API 与 ABI 的区别

[xiaoxiaojx]

背景

Node-API 的基本概念里面提到了 ABI, 前端开发的同学对这个词语可能就比较陌生，和平时经常提到的 API 有什么区别？

Node-API（以前称为 N-API）是用于构建原生插件的 API。它独立于底层 JavaScript 运行时（例如，V8）并作为 Node.js 本身的一部分进行维护。此 API 将在 Node.js 的各个版本中保持稳定的应用程序二进制接口 (ABI)。它旨在将插件与底层 JavaScript 引擎中的更改隔离开来，并允许为一个主要版本编译的模块无需重新编译即可在 Node.js 的后续主要版本上运行

API 与 ABI

API 应用程序接口

这是从应用程序/库公开的一组公共类型/变量/函数。 在 C/C++ 中，这是应用程序附带的头文件中公开的内容。

ABI 二进制接口

这就是编译器构建应用程序的方式。 它定义了事物（但不限于）：

• 如何将参数传递给函数（寄存器/堆栈）
• 谁从堆栈中清除参数（调用者/被调用者）
• 返回值放置的位置以供返回
• 异常如何传播

举个例子

下面的 main.c 程序依赖了 mylib 这个库, mylib 这个库对外暴露了 mylib_init 这个接口, 该接口的出参与入参可以看 mylib.h 中的类型定义。

// main.c

#include <assert.h>
#include <stdlib.h>

#include "mylib.h"

int main(void) {
    mylib_mystruct *myobject = mylib_init(1);
    assert(myobject->old_field == 1);
    free(myobject);
    return EXIT_SUCCESS;
}

// mylib.c

#include <stdlib.h>

#include "mylib.h"

mylib_mystruct* mylib_init(int old_field) {
    mylib_mystruct *myobject;
    myobject = malloc(sizeof(mylib_mystruct));
    myobject->old_field = old_field;
    return myobject;
}

// mylib.h

#ifndef MYLIB_H
#define MYLIB_H

typedef struct {
    int old_field;
} mylib_mystruct;

mylib_mystruct* mylib_init(int old_field);

#endif

现在 mylib 这个库进行了 v2 版本的升级。v2 版本修改了 mylib_mystruct 的定义, 新增加了 new_field 字段，新的定义如下

// mylib.h

typedef struct {
    int new_field;
    int old_field;
} mylib_mystruct;

此时我们只重新编译 mylib, 不重新编译 main.c 主程序。然后运行 main.out, 发现 main 函数里面的 assert 错误了...

// main.c

assert(myobject->old_field == 1);

因为 myobject 还是访问的第一个字段, 但是现在第一个字段为 new_field 了，程序中并没有为它赋值。此时对于用户来说 API 没有造成 break change, 可以不用修改代码来适配。但是由于 ABI 的 break change 导致需要重新编译主程序，所以 ABI 的稳定性的维持是高于 API 的。

如果把新增 new_field 放在 old_field 之后了，发现程序运行是没有问题的。mylib 通过后者的方式去升级 v2 版本，即使新增了字段，ABI 依然是稳定的。

// mylib.h

typedef struct {
    int old_field;
    int new_field;
} mylib_mystruct;

扩展阅读

下面所示的使用 Node-API 开发的 c++ 插件的代码例子, 对于我来说就比较好奇 napi_value 的定义

// demo

napi_status status;
napi_value object, string;
status = napi_create_object(env, &object);
if (status != napi_ok) {
  napi_throw_error(env, ...);
  return;
}

status = napi_create_string_utf8(env, "bar", NAPI_AUTO_LENGTH, &string);
if (status != napi_ok) {
  napi_throw_error(env, ...);
  return;
}

status = napi_set_named_property(env, object, "foo", string);
if (status != napi_ok) {
  napi_throw_error(env, ...);
  return;
}

最后我们在 js_native_api_types.h 文件找到了 napi_value 的定义。napi_value 是 struct napi_value__ 类型的指针，其实 napi_value__ 是未定义的。从源码中的注释可知， 编译时 undefined structs 会比 void* 更加安全。

// src/js_native_api_types.h

// JSVM API types are all opaque pointers for ABI stability
// typedef undefined structs instead of void* for compile time type safety
typedef struct napi_value__* napi_value;

实测上面的 napi_value__ 是 undefined 编译是会通过的，实际使用的时候强制类型转换为目标类型即可。

参考

• Difference between API and ABI