Анатомия Node-API-проекта

Прежде чем нырять в код, полезно понять файлы и структуру, общие для каждого проекта на node-addon-api. Все примеры N-API в этих руководствах следуют одной и той же структуре, поэтому эта страница объясняет её один раз, чтобы те туториалы могли сосредоточиться на том, что делает каждый из них уникальным.

Node-API работает на двух уровнях:

• C API встроен непосредственно в Node.js и полностью задокументирован на страницах API Node.js. Даёт максимальный контроль без лишних зависимостей.
• C++-обёртка (node-addon-api) — npm-пакет, оборачивающий C API в идиоматичную объектную модель C++. Рекомендуется для большинства проектов: устраняет значительный объём шаблонного кода, сохраняя полную гарантию ABI-стабильности Node-API.

Туториалы в этом разделе используют node-addon-api.

Node-API стабилен во всех поддерживаемых в настоящее время релизах Node.js. Для лучшего опыта используйте релиз Active LTS или Maintenance LTS. Проверить, какую версию Node.js вы используете, можно командой node -v.

.
├── binding.gyp        # говорит node-gyp, как компилировать C/C++-исходники
├── build/             # скомпилированный вывод (генерируется)
├── lib/
│   └── binding.js     # JavaScript-слой, загружающий скомпилированный бинарник
├── node_modules/
├── src/
│   └── *.cc / *.h     # ваша C/C++-реализация
├── test/
│   └── *.js           # тестовый код
├── package.json
└── package-lock.json

Две записи в package.json специфичны для нативных аддонов.

"dependencies": {
  "node-addon-api": "^8.0.0"
}

node-addon-api добавляет C++-обёртку к C API, встроенному в Node.js. Он делает создание и манипуляцию JavaScript-объектами в C++ прямолинейными и полезен даже когда нижележащая библиотека, которую вы оборачиваете, написана на C.

"gypfile": true

Это говорит npm, что пакет требует шага нативной компиляции. Когда npm видит эту запись, он автоматически вызывает свою встроенную копию node-gyp, которая читает binding.gyp, чтобы собрать бинарник.

binding.gyp — это файл GYP, описывающий, как компилировать и линковать ваш C/C++-код. Он должен называться в точности binding.gyp.

GYP (Generate Your Projects) позволяет написать единое описание сборки, работающее на Windows, macOS и Linux. node-gyp читает этот файл и производит подходящие для платформы файлы сборки (MSVC-проект на Windows, Makefile на Linux, Xcode-проект на macOS), а затем вызывает компилятор.

Минимальный binding.gyp для проекта на node-addon-api выглядит так:

{
  "targets": [
    {
      "target_name": "my_addon",
      "sources": ["src/my_addon.cc"],
      "include_dirs": ["<!@(node -p \"require('node-addon-api').include\")"],
      "dependencies": ["<!(node -p \"require('node-addon-api').gyp\")"]
    }
  ]
}

Полный формат GYP задокументирован в пользовательской документации GYP.

Директория lib/ содержит тонкую JavaScript-обёртку, которая загружает скомпилированный бинарник и реэкспортирует его. Этот слой держит логику загрузки бинарника в одном месте и даёт естественное место для добавления валидации на стороне JavaScript или удобных методов.

Типичный binding.js использует пакет bindings, чтобы разрешить путь к файлу .node независимо от платформы:

'use strict';
const addon = require('bindings')('my_addon');
module.exports = addon;

Если вы устанавливаете пакеты глобально через npm и сталкиваетесь с Error: EACCES: permission denied, используйте nvm для управления вашей установкой Node.js. С nvm глобальные установки попадают в вашу домашнюю директорию и никогда не требуют sudo.