写在前面

为满足爱奇艺RND框架的JS批量绑定需求，在调研和借鉴了现有流行开源框架成功经验的基础上，我们开发设计了一套新的JS自动绑定工具，并且定义了弹性化的绑定规则，探索解决了多继承绑定、Wrapped指针转换、多JS引擎支持等问题，特别是将Mate API与Node-Addon-API进行了融合，形成了隔离底层JS引擎的具有ABI稳定性的JS Common API层，并将为其实现JavaScriptCore Port。所有这些工作为RND框架打造了低耦合、易维护的底层JS引擎环境，同时也提供了坚实通用的JS自动绑定支持。

本文将介绍RND中的JS自动绑定工具的功能和实现原理。

确定技术方案之前，要对WebKit和Cocos Creator中的JS自动绑定技术进行调研。WebKit使用Web IDL对绑定需求进行描述，然后通过Perl脚本解析这些IDL，为不同的JS引擎分别生成对应的绑定代码。但总是避免不了会存在一些需要手动编写的绑定代码，在这种情况下就需要为每个JS引擎都手写一份绑定代码。Cocos Creator则为不同的JS引擎抽象出了一套通用接口，通过libclang解析待绑定的C类库后生成基于通用接口的绑定代码。Cocos Creator的方案不存在WebKit的问题，抽象出通用JS接口的设计既避免了手动绑定代码时为多个JS引擎重复编写的麻烦，又为扩展支持新的JS引擎提供了便利。

尽管如此，仍然存在一些无法满足我们需求的地方。首先，Cocos Creator的绑定规则的描述粒度不如Web IDL精细，比如不能针对某个特定的待绑定方法或属性设置其PropertyDescriptor。其次，绑定层函数原型必须是统一的形式，在其实现中绝大部分代码都是调用JS与C类型转换的代码，手写绑定代码时会比较繁琐。最后，Cocos Creator不支持绑定C++中的多继承。为解决上述问题，我们决定重新开发一套适合RND框架的JS自动绑定工具。

我们知道JS程序的运行依赖于宿主环境，不同宿主环境下的JS程序可调用的API集合也是不同的。这些API分为三部分：

1）由JS引擎实现的ECMAScript标准API；

2）由宿主实现并通过JS引擎提供的Native接口向JS Context直接提供的API，例如浏览器中的DOM、Node.js中的内部实现中通过process.binding获取的模块、RND中的_setTimeout等；

3）在前两者基础上实现的API，例如React框架、Node.js中通过require获取的的模块、RND中的setTimeout等。狭义上的JS绑定指的是第2类API的实现方式，广义上的JS绑定还包括由宿主基于第2类API来实现第3类API这种方式。本文中的JS绑定指的是狭义上的JS绑定。

下面来看一个简单的例子，以便更具体地了解JS绑定，顺便也能了解RND中JS自动绑定工具的输入和输出是什么。

假设存在一个待绑定的C++类Foo，如下：

下面是一个绑定规则文件foo.yaml，表示要绑定Foo类及其ToBind方法。

自动绑定工具根据输入的foo.yaml和foo.hpp生成的绑定代码片断如下：

JS调用代码如下：

可以看到，自动绑定工具为Foo类生成了一个FooWrappable类，这个类拥有一个Foo*类型的成员变量，构造函数、析构函数以及用户在绑定规则文件foo.yaml中所指定的ToBind函数。当JS代码调用new Foo()时会调用到FooWrappable的构造函数，进而创建出Foo对象实例。同样的，当调用toBind函数时，也会先调用到FooWrappable这一层，再委托给Foo对象实例的ToBind函数。当Foo对象实例被JS引擎垃圾回收时，析构函数以同样的方式被层层调用。FooWrappable层就是连接JS与C的桥梁 - JS绑定层。JS与C类库之间的相互调用都会经过JS绑定层，虽然例子中仅展示了JS调用C的情形，其实反过来当C调用JS Callback也一样，例如RND中setTimeout的实现就是先由native调用到绑定层，然后再调用到JS Callback。

现在自动绑定工具的使命已经明确了，就是以尽可能低的人工成本生成JS绑定层代码。

那么绑定工具是如何根据绑定规则和待绑定类库的头文件自动生成JS绑定层代码的呢？工作流程如下：

C++ Library --libclang--> AST --ast parser--> wrapped class map --rule parser--> target class map --refiner--> wrappable class map --template--> binding code即：

1. 使用libclang解析待绑定的C++库的头文件后得到AST。

2. 遍历上一步生成的AST，得到所有的C++类信息，例如类名、方法名、属性名、参数名、参数类型等。

3. 解析用户定义的绑定规则，对上一步的C类信息进行匹配，过滤不需要绑定的C类，得到目标C++类。

4. 对目标C类信息进一步处理，例如合并C重载函数、合并父/子类方法和属性、检查冲突等，得到可用于模板渲染的数据。

5. 基于绑定层框架编写模板，并将上一步的数据feed给这些模板，渲染出最终的绑定代码。

正如前面例子中foo.yaml所展示的，我们自定义了一套绑定规则，大致如下：

# classes: 由待绑定的class组成的list
# class分三种绑定类型interface， object， class，通过bind_type指定。某些属性只对特定类型有效。
# - interface: 表示在JS中无法通过new实例化此类，相当于C++中的抽象类，只能作为JS原型链上的一环。
# - object: 表示向JS绑定一个对象，相当于C++中的单例对象。
# - class: 表示向JS绑定一个可动态实例化的类，即可通过new构造出对象实例。
#
classes:
# wrapped_class_name: 通用字段，必选，支持正则表达式。表示需要绑定的c++类名。
  - wrapped_class_name: SampleClass
# bind_type: 通用字段，可选。表示绑定类型，共三种，分别是interface，object，class。若省略此项，则使用默认值class。
    bind_type: class
# js_class_name: 通用字段，可选。表示JS中对应的类名。若省略此项，则表示与wrapped_class_name一致。
    js_class_name: SampleClass
# wrapped_decl: 通用字段，可选。表示待绑定的C++对象在生成的绑定层类的头文件中的变量声明语句，一般为祼指针或智能指针。
# 若省略此项，则默认为祼指针，即wrapped_class_name* impl_; 注意变量名必须是impl_，下同
    wrapped_decl: |
SampleClass* impl_;
#
    # methods: 通用字段，可选。指定除构造和析构函数之外需要绑定的方法。
    methods:
# wrapped_method_proto: 必选，支持正则表达式。指定待绑定的方法原型，请复制粘贴待绑定的C++类头文件中的方法原型。
# 采用这种方式时绑定工具会自动生成绑定代码的声明和实现。
      - wrapped_method_proto: |
virtual int GetWidth() const;
        # js_method_name: 可选。指定JS方法名称。若省略此项，则使用wrapped_method_proto函数名的首字母小写形式，下同。
        js_method_name: getWidth
# wrappable_method_proto: 必选。允许用户不依赖待绑定C++类头文件中的方法，而是完全自定义绑定层函数。
      - wrappable_method_proto: |
          Mate::SafeString GetName();
        js_method_name: getName
# static: 可选。指定此方法是否为static。若省略此项，则使用默认值false。
        static: true
#
# properties: 通用字段，可选。指定需要绑定的属性。
    properties:
# wrapped_property_name: 必选，支持正则表达式。指定待绑定的属性名。
# 采用这种方式时系统会自动生成绑定代码的声明和实现。
      - wrapped_property_name: m_Width
# js_property_name: 可选。指定JS属性名称。若省略此项，则使用去除前缀且将首字母改为小写形式的wrapped_property_name，下同。
        js_property_name: width
# accessor_descriptor: 可选。指定JS属性的访问器描述符。
# 若此项省略，则采用默认值。各项默认值分别是:configurable-false，enumerable-false，set-true
        accessor_descriptor: {configurable: false, enumerable: false, set: false}
...

绑定规则使用YAML语法进行描述。之所以选择YAML是因为它可读性高，支持注释功能，提供层次化的描述能力，且可以将C代码以文本形式嵌入，而不会对*，#，&等特殊字符进行转义。为保持一定程度的灵活性，绑定规则考虑了待绑定的C库可能存在的内存管理机制，例如C++对象可能是祼指针/智能指针，祼指针的话可能还有引用计数机制等。最后，也允许用户在一些特殊情况下手动实现绑定层代码。

前面例子中的绑定层FooWrappable类继承自Mate::WrappableObject，后者是我们的绑定层框架Mate。

上面这幅图以爱奇艺客户端中的UI引擎Lyra的绑定为例，描述了绑定层次结构。首先，QyClient作为一个Embedder嵌入了JS引擎V8和UI引擎Lyra，JS绑定层LyraWrappable是通过自动绑定工具生成的，它依赖于绑定层框架Mate、UI引擎和JS引擎。

Mate是Electron对Chromium Gin的fork，它基于V8 API进行了适配，内置了一些用于转换C和JS基本数据类型的Converter模板，并利用Chromium的base::callback将待绑定的C函数自动wrap成V8 callback。对于可序列化为字符串的C类或结构体，例如SIZE、POINT、RECT等，用户也可通过扩展Converter模板来对这些数据结构的C/JS类型转换进行支持。得益于C模板参数推导机制，所有的Converter都能被Mate框架自动调用，因此数据类型转换工作得以在Mate框架层自动进行，用户只需要按照与待绑定C库函数一致的方式定义绑定层函数原型即可。这些特点使得基于Mate手写无法自动绑定的代码时非常方便和简洁，避免了直接使用较为晦涩的V8 API。下面是与Cocos Creator绑定层代码的一个简单对比：

Cocos Creator绑定函数实现:

static bool JS_box2dclasses_b2Draw_AppendFlags(se::State& s)
{
b2Draw* cobj = (b2Draw*)s.nativeThisObject();
SE_PRECONDITION2(cobj, false, "JS_box2dclasses_b2Draw_AppendFlags : Invalid Native Object");
const auto& args = s.args();
size_t argc = args.size();
CC_UNUSED bool ok = true;
if (argc == 1) {
unsigned int arg0 = 0;
ok &= seval_to_uint32(args[0], (uint32_t*)&arg0);
SE_PRECONDITION2(ok, false, "JS_box2dclasses_b2Draw_AppendFlags : Error processing arguments");
cobj->AppendFlags(arg0);
return true;
}
SE_REPORT_ERROR("wrong number of arguments: %d, was expecting %d", (int)argc, 1);
return false;
}

RND等价实现：

上面两段代码都实现了绑定b2Draw::AppendFlags方法的功能，相比之下可以看出RND绑定层函数实现非常简单，绝大部分情况下函数原型可以与待绑定的C++库函数原型保持一致。这是因为Mate框架会自动调用Converter进行参数转换，并处理此过程中可能出现的错误。若转换顺利完成，则会以转换后的参数调用绑定层函数。上例中调用了Mate内置的uint32_t类型Converter，代码示例如下：

只需要为某个类型定义一次Converter，即可自动处理同类型参数的C++/JS类型转换，而不必在每个函数实现中重复编写类型转换代码。

目前仍存在一些无法自动绑定的情况，包括：

▪ 待绑定的C++库中并不存在相应的方法。

▪ C调用JS callback的情况。这种情况下JS callback需要先被转换成base::Callback，然后再适配成C库函数中定义的Callback原型。目前需要手动编写这部分代码。

▪ 由于指针本身语义模糊的问题，对于通过Converter方式绑定的C类型以及C基本类型（例如int,bool,float等）来说，如果它们作为函数参数和返回值时是以指针或非const引用形式出现，则需要手写绑定函数。

▪ 由于对象生命周期同步问题，对于通过非Converter方式绑定的C++类型（例如前面的lyra::CControlUI）来说，如果它们作为函数参数和返回值时不是以指针和引用形式出现，则无法绑定。

▪ 以Converter方式进行绑定的情况。

▪ 非类函数和变量的绑定。目前暂未实现。

自定义Converter

前面例子中的C类Foo和b2Draw被绑定到JS运行时后，JS可通过new运算符创建出JS对象实例，同时在C端一个对应的C对象也被创建出来，JS对象仅仅是一个壳，在它上面的所有操作都会调用到C对象上。但对于C中一些仅用于数据传递目的，且这些数据可序列化为字符串形式的数据结构来说，并不需要这么重量级的绑定方式，只需像C基本数据类型一样，定义相应的Converter来完成C与JS之间的类型转换即可。这样的C数据结构在JS中对应对象字面量，例如JS中的{cx:100,cy:100}等同于下例中C++ SIZE对象。

上面代码中，ConvertFromV8和Dictionary（对应JS中的对象）都会在内部调用现有Converter。具体来说，分别调用了Mate内置的v8::Local<v8::Object>和long的Converter。例子中没有展示出来还有ConverToV8，实际上Dictionary的Set函数内部会调用ConverToV8，Get函数内部调用的则是ConvertFromV8。使用这几个API函数来实现自定义类型Converter还是比较方便的。

绑定层提供了很大的灵活性,允许用户自定义实现一些特殊情况，例如希望在现有C++库函数基础上封装新的函数给JS使用。

对应的JS调用代码如下：

上面的例子中，假设C++类Foo存在SetWidth和SetHeight方法，并想将两个方法组合成一个setKeyValue方法绑定到JS运行时，因为Foo类中本不存在这样一个方法，自然无法自动生成绑定代码，因此需要在绑定层，也就是FooWrappable类中手动实现这个方法。这就需要先在绑定规则文件中使用wrappable_method_proto项写好函数原型，然后在手动创建的一个源文件中include自动生成的绑定层的类头文件，手动实现该函数。

• 多继承绑定
  

Mate框架的一个问题在于不支持继承关系的绑定，更别说多继承了。虽然待绑定的C++类之间存在继承关系，但绑定层的各个类之间是不存在继承关系的。如果非要利用JS原型链来实现继承，则在函数调用过程中有可能发生错误的指针转换。

先来看函数调用过程中指针经历了怎样的转换。

JS对象上绑定的是一个void指针。当调用JS对象的SayHello方法时，Mate会将void指针通过static_cast转成绑定层的Wrappable指针，然后调用Wrappable::SayHello函数，进而调用impl_对象的SayHello方法。在这背后，编译器实际上是通过Wrappable指针值加上impl_变量的偏移得到impl_变量的地址。

再来看使用JS原型链实现继承时子类对象调用自身方法和父类方法时的情形。

请注意子类对象上绑定的指针是WrappableS指针，当子类对象调用自身方法SayWorld时，指针获取和转换如前所述，没什么问题。但当子类对象调用父类方法SayHello时，则会调用到父类的绑定层函数，也就是WrappableB::SayHello中。Mate框架会通过static_cast将事实上的WrappableS指针误转成WrappableB指针（这种转换是在编译时就已经确定了的）。然后按照WrappableB的内存布局和偏移去获取WrappedB指针，这时实际上获取到的是WrappedS指针。

最后把WrappedS指针当成WrappedB指针去调用SayHello方法。在单继承且保证impl_变量总是位于内存布局起始位置的情况下，这种调用过程歪打正着最终还是可以正确调用到父类函数。但如果是多继承且Wrappable类中存在自定义变量时，即使能保证各个Wrappable类中impl_变量的地址偏移都为0，但是自定义变量的偏移无法保证是一致的，如果Wrappable类自定义函数实现中使用了这些自定义变量，就可能导致崩溃。因此RND只能采用在子类上重复绑定父类方法的做法来实现多继承，这样的话父类方法就变成子类上的方法，子类对象调用父类方法就是调用自身方法，因此不会调用到父类的Wrappable，从而避免上述问题。值得一提的是，采用这种方法实现继承后，我们将自定义绑定层方法的实现模板化，这样就避免了在子类上重复编写自定义代码。

在子类上重复绑定父类方法只解决了多继承的一半问题，另一半问题是，当需要将子类对象传递给父类方法时，或者，父类方法返回指向子类对象的父类指针时，同样的指针转换和误用问题会发生。

C++中的Base::link函数要求传入Base指针，当JS中传入一个子类对象时，实际的子类的Wrappable指针被当成父类的Wrappable指针在使用，然后按照父类的Wrappable内存布局和偏移取得的是子类Wrapped指针变量impl_，却被当成父类的Wrapped指针传给了link函数。只要保证父类和子类的Wrappable的内存布局和impl_变量偏移是一致的，那么在单继承情况下，子类和父类的Wrapped指针地址也是相等的，不会存在问题。在多继承情况下必须对wrapped指针impl_进行转换，但impl_指针真实类型只有在运行时才能知道，且是动态可变的，因此只能通过在直接父/子类之间构建起指针转换MAP，通过查询转换来完成运行时期impl_指针的动态转换。

由于Mate仅支持V8 API，因此需要对绑定层框架进行适当修改，以便支持其他JS引擎，例如JavaScriptCore。存在三种可选方案，如下所示：

按照与V8绑定相似的思路，实现一个基于JSC的Mate。此方案问题在于，对那些不得不手动绑定的代码来说，仍要为各个JS引擎分别实现。

github上有一个开始于2018年9月的Node-JSC，旨在让Node.js运行在JavaScriptCore引擎上。它的做法与微软的Node-ChakraCore相同，都是使用其它JS引擎API去适配V8 API，由于事实上很难实现所有v8.h中的API，且没有必要，因为只要满足Node.js需要即可，所以实现的只是部分V8 API。此方案问题在于，一方面此项目并不成熟，另一方面其实现过程中需要修改JavaScriptCore源码，而不是使用JavaScriptCore官方接口。

前面两种方案因其所存在的问题被排除在外。JS Common API方案抽象出一层很薄的中间层JS common API，当然这也需要修改Mate框架进行适配。第二种方案也可看成是这种方案的特例，即选择V8 API作为Js Common API。

如上图所示，RND在JS Common API方面选用了Node.js中的Node-Addon-API，并对其进行了裁剪和修改。Node-Addon-API是N-API的C++接口，由于它只是以inline方式实现的头文件，所以仍保有N-API的ABI稳定性。Mate原本是为了提供相较于V8 API更简单方便的接口而存在的，既然现在Mate已不直接基于V8 API了，所以干脆将Mate的功能融合进Node-Addon-API，即只保留JS Common API层即可。所以方案最终变为：

目前正在开发JavaScriptCore Port，完成后将达到同时支持V8和JavaScriptCore的目的。事实上，Node.js已将N-API代码拆成了node_api和js_native_api两部分，前者是与Node.js本身特性相关的部分，后者则是仅与ECMAScript标准相关的部分，这种拆分为Node.js之外的N-API实现提供了便利。

▪ 开发JS Common API的JavaScriptCore Port。

▪ 简单Converter的自动生成。一些简单类型的Converter其实也可通过绑定工具自动生成。

▪ 可视化工具。提供一个可视化工具，用户可使用此工具指定绑定需求，而不是直接手写绑定规则文件。

▪ C++祼指针、智能指针、引用计数机制的选项化。用户只需要根据实际情况选择相应的选项，而不是在绑定规则文件中写C代码。

▪ 非类函数和变量的绑定。

未来我们还将持续改进。如果您想了解更多关于RND的信息，请参阅爱奇艺RND框架系列的其他文章。

end

也许你还想看

干货|格物致知—机器学习应用性能调优

干货|爱奇艺直播 - 春晚直播业务API架构

扫一扫下方二维码，更多精彩内容陪伴你！

爱奇艺技术产品团队

简单想，简单做