xadillax (機巧死月不會碼代碼)

从暴力到 NAN 再到 NAPI——Node.js 原生模块开发方式变迁

xadillax — Sat, 01 Jul 2017 17:05:26 +0800

本文由我首发于 GitChat 中。

前言

在 Node.js 开发领域中，原生 C++ 模块的开发一直是一个被人冷落的角落。但是实际上在必要的时候，用 C++ 进行 Node.js 的原生模块开发能有意想不到的好处。

性能提升。很多情况下，使用 C++ 进行 Node.js 原生模块开发的性能会比纯 Node.js 开发要高，少数情况除外。
开发成本节约。在一些即有的 C++ 代码上做封装，开发成本远远低于从零开始写 Node.js 代码。
Node.js 无法完成的工作。个别情况，开发者只能得到一个库的静态连接库或者动态链接库以及一堆 C++ 头文件，其余都是黑盒的，这种情况就不得不使用 C++ 进行模块开发了。

本文将从早期的 Node.js 开始，逐渐披露 Node.js 原生 C++ 模块开发方式的变迁。一直到最后，会比较详细地对 Node.js v8.x 新出的原生模块开发接口 N-API 做一次初步的尝试和解析，使得大家对 Node.js 原生 C++ 模块开发的固有印象（认为特别麻烦）有一个比较好的改观，让大家都来尝试一下 Node.js 原生 C++ 模块的开发。

不变应万变

虽然 Node.js 原生 C++ 模块开发方式有了很大的改变，但是有一些内容是不变的，至少到现在来说都是基本上没什么 Breaking 的变化。

原生模块本质

这就要从 Node.js 最本质的 C++ 模块开发讲起了。举个例子，我们在 Linux 下有一个合法的原生模块 ons.node，它其实是一个二进制文件，使用文本编辑器无法正常地看出什么鬼，直到我们遇到了二进制文件查看器。

眼尖的同学会看到它的 Magic Number[^1] 是 0x7F454C46，其按位的 ASCII 码代表的字符串是 ELF。于是答案呼之欲出，这就是一个 Linux 下的动态链接库文件。

事实上，不只是在 Linux 中。当一个 Node.js 的 C++ 模块在 OSX 下编译会得到一个后缀是 *.node 本质上是 *.dylib 的动态链接库；而在 Windows 下则会得到一个后缀是 *.node 本质上是 *.dll 的动态链接库。

这么一个模块在 Node.js 中被 require 的时候，是通过 process.dlopen() 对其进行引入的。我们来看一下 Node.js v6.9.4 的 DLOpen[^2] 函数吧：

void DLOpen(const FunctionCallbackInfo<Value>& args) {
  Environment* env = Environment::GetCurrent(args);
  uv_lib_t lib;

  ...

  Local<Object> module = args[0]->ToObject(env->isolate());
  node::Utf8Value filename(env->isolate(), args[1]);

  // 使用 uv_dlopen 加载链接库
  const bool is_dlopen_error = uv_dlopen(*filename, &lib);
  node_module* const mp = modpending;
  modpending = nullptr;

  ...

  // 将加载的链接库句柄转移到 mp 上
  mp->nm_dso_handle = lib.handle;
  mp->nm_link = modlist_addon;
  modlist_addon = mp;

  Local<String> exports_string = env->exports_string();

  // exports_string 其实就是 `"exports"`
  // 这句的意思是 `exports = module.exports`
  Local<Object> exports = module->Get(exports_string)->ToObject(env->isolate());

  if (mp->nm_context_register_func != nullptr) {
    mp->nm_context_register_func(exports, module, env->context(), mp->nm_priv);
  } else if (mp->nm_register_func != nullptr) {
    mp->nm_register_func(exports, module, mp->nm_priv);
  } else {
    uv_dlclose(&lib);
    env->ThrowError("Module has no declared entry point.");
    return;
  }
}

按照逻辑来讲，这个加载过程其实就是下面这样的。

通过 uv_dlopen 加载链接库。
将加载的链接库挂到原生模块链表中去。
通过 mp->nm_register_func() 初始化这个模块，并得到该有的 module 和 module.exports。

流程走下来就跟这个流程图差不多。

node-gyp

这货是 Node.js 中编译原生模块用的。自从 Node.js v0.8 之后，它就跟 Node.js 黏上了，在此之前它的默认编译帮助包是 node-waf[^3]，对于老 Noder 来说应该不会陌生的。

GYP

node-gyp 是基于 GYP[^4] 的。它会识别包或者项目中的 binding.gyp[^5] 文件，然后根据该配置文件生成各系统下能进行编译的项目，如 Windows 下生成 Visual Studio 项目文件（*.sln 等），Unix 下生成 Makefile。在生成这些项目文件之后，node-gyp 还能调用各系统的编译工具（如 GCC）来将项目进行编译，得到最后的动态链接库 *.node 文件。

从上面的描述中大家可以看到，Windows 下编译 C++ 原生模块是依赖 Visual Studio 的，这就是为什么大家在安装一些 Node.js 包的时候会需要你事先安装好 Vusual Studio 了。

事实上，对于并没有 Visual Studio 需求的同学们来说，它不是必须的，毕竟 node-gyp 只依赖它的编译器，而不是 IDE。想要精简化安装的同学可以直接访问 http://landinghub.visualstudio.com/visual-cpp-build-tools 下载 Visual CPP Build Tools 安装，或者通过 $ npm install --global --production windows-build-tools 命令行的方式安装，就能得到你该得到的编译工具了。

说了那么多，让大家见识一下 binding.gyp 的基本结构吧。

# binding.gyp

{
  "targets": [{
    "target_name": "addon1",
    "sources": [ "1/addon.cc", "1/myobject.cc" ]
  }, {
    "target_name": "addon2",
    "sources": [ "2/addon.cc", "2/myobject.cc" ]
  }, {
    "target_name": "addon3",
    "sources": [ "3/addon.cc", "3/myobject.cc" ]
  }, {
    "target_name": "addon4",
    "sources": [ "4/addon.cc", "4/myobject.cc" ]
  }]
}

这段配置讲述了这么一个故事：

定义了 4 个 C++ 原生模块。
每个模块的源码分别是 */addon.cc 和 */myobject.cc。
4 个模块名分别是 addon1 至 addon4。
隐藏故事：通过正规途径编译好后，这些模块存在于 build/Release/addon*.node 中。

关于 GYP 配置文件的更多内容，大家可自行去官方文档观摩，在脚注中有 GYP 的链接。

做的事情

node-gyp 除了自身是基于 GYP 的之外，它还做了一些额外的事情。首先，在我们编译一个 C++ 原生扩展的时候，它会去指定目录下（通常是 ~/.node-gyp 目录下）搜我们当前 Node.js 版本的头文件和静态连接库文件，若不存在，它就会火急火燎跑去 Node.js 官网下载。

这是一个 Windows 下 node-gyp 下载的指定版本 Node.js 头文件和库文件的目录结构。

这个头文件目录会在 node-gyp 进行编译时，以 "include_dirs" 字段的形式合并进我们事先写好的 binding.gyp 中，总而言之，这里面的所有头文件能被直接 #include <>。

子命令

node-gyp 是一个命令行的程序，在安装好后能通过 $ node-gyp 直接运行它。它有一些子命令供大家使用。

$ node-gyp configure：通过当前目录的 binding.gyp 生成项目文件，如 Makefile 等；
$ node-gyp build：将当前项目进行构建编译，前置操作必须先 configure；
$ node-gyp clean：清理生成的构建文件以及输出目录，说白了就是把目录清理了；
$ node-gyp rebuild：相当于依次执行了 clean、configure 和 build；
$ node-gyp install：手动下载当前版本的 Node.js 的头文件和库文件到对应目录。

时代在召唤

第 N 套国际 Node.js 开发者原生 C++ 模块开发方式，时代在召唤。

除去前文中讲的一些不变的内容，还有很多内容是一直在变化的，虽然说用老旧的开发方式也是可以开发出能用的 C++ 原生模块，但是旧不如新。

而且，其实目前来说 node-gyp 的地位也有可能在未来进行变化。因为当年 Chromium 是通过 GYP 来管理它的构建配置的，现如今已经步入了 GN[^6] 的殿堂，是否也意味着 node-gyp 有一天也会被可能叫做 node-gn 的东西给取代呢？

话不多说，先来看看沧海桑田的故事吧。

黑暗时代：node-waf

在 Node.js 0.8 之前，通常在开发 C++ 原生模块的时候，是通过 node-waf 构建的。当然彼 node-waf 不是现在在 NPM 仓库上能搜到的 node-waf 了，当年那个 node-waf 早就年久失修了。

这个东西使用一种叫 wscript 的文件来配置。自 Node.js 升上 0.8 之后，就自带了 node-gyp 的支持，从此就不再需要 wscript 了。

不过就是因为有这个青黄交接的时候，那段时间的各种使用 C++ 来开发 Node.js 原生扩展的包为了兼容 0.8 前后版本的 Node.js，通常都是 binding.gyp 和 wscript 共存的。

大家可以来看一下 node-mysql-libmysqlclient 这个包在当年相应时间段的时候的仓库文件。为了支持 node-gyp，有一个 binding.gyp 文件，然后还存留着 wscript 配置文件。

封建时代：暴力！暴力！暴力！

在早期的时候，Node.js 原生 C++ 模块开发方式是非常暴力的，直接使用其提供的原生模块开发头文件。

开发者直接深入到 Node.js 的各种 API，以及 Google V8 的 API。

举个最简单的例子，在几年前，你的 Node.js C++ 原生扩展代码可能是长这样的。

Handle<Value> Echo(const Arguments& args)
{
    HandleScope scope;

    if(args.Length() < 1)
    {
        ThrowException(
            Exception::TypeError(
                String::New("Wrong number of arguments.")));
        return scope.Close(Undefined());
    }

    return scope.Close(args[0]);
}

void Init(Handle<Object> exports)
{
    exports->Set(String::NewSymbol("echo"),
        FunctionTemplate::New(Echo)->GetFunction());
}

这是一个最简单的 echo 函数，返回传进来的参数。写作 JavaScript 相当于是这样的。

exports.echo = function() {
    if(arguments.length < 1)
        throw new Error("Wrong number of arguments.");
    return arguments[0];
};

遗憾的是，这样的代码如果发成一个包，你现在是无论如何无法安装的，除非你用的是 0.10.x 的 Node.js 版本。

为什么这么说呢，这段代码的确是在 Node.js 0.10.x 的时候可以用的。但是再往上升 Google V8 的大版本，这段代码就无法适用了，讲粗暴点就是没办法再编译通过了。

就拿 Node.js 6.x 版本的 Google V8 来说，函数声明的对比是这样的：

Handle<Value> Echo(const Arguments& args);    // 0.10.x
void Echo(FunctionCallbackInfo<Value>& args); // 6.x

事实上，根本不需要等到 6.x。上面的代码到 0.12 就已经无法再编译通过了。不只是函数声明的变化，连句柄作用域 [^7] 的声明方式都变了。

如果要让它在 Node.js 6.x 下能编译，就需要改代码，就像这样。

void Echo(const FunctionCallbackInfo<Value>& args)
{
    Isolate* isolate = args.GetIsolate();
    if(args.Length() < 1)
    {
        isolate->ThrowException(
            Exception::TypeError(
                String::NewFromUtf8(isolate, "Wrong number of arguments.")));
        return;
    }

    args.GetReturnValue().Set(args[0]);
}

void Init(Local<Object> exports)
{
    NODE_SET_METHOD(exports, "echo", Echo);
}

也就是说，以黑暗时代的方式进行 Node.js 原生模块开发的时候，一个版本只能支持特定几个版本的 Node.js，一旦 Node.js 的底层 API 以及 Google V8 的 API 发生变化，而这些原生模块又依赖了变化了的 API 的话，包就作废了。除非包的维护者去支持新版的 API，不过这样依赖，老版 Node.js 下就又无法编译通过新版的包了。

这就很尴尬了。

城堡时代：Native Abstractions for Node.js

在经历了黑暗时代的尴尬局面之后，2013 年年中，一个救世主突然现世。

它的名字叫作 NAN，全称 Native Abstractions for Node.js，即 Node.js 原生模块抽象接口。

NAN 由 Rod Vagg 和 Benjamin Byholm 两手带大，记名在 GitHub 的 Rod Vagg 账号下。并且在 Node.js 与 io.js 黑历史的年代，这个在 GitHub 上面项目移到了 io.js 的组织下面；后来由于两家又重归于好，NAN 最终归属到了 nodejs 这个组织下面。

总之在 NAN 出现之后，Node.js 的原生开发方式进入了城堡时代，并且一直持续到现在，甚至可能会持续到好久之后。

说 NAN 是 Node.js 原生模块抽象接口可能还是有点抽象，那么讲明白点，它就是一堆宏判断。比如声明一个函数的时候，只需要通过下面的一个宏就可以了：

NAN_METHOD(Echo)
{
}

NAN 的宏会判断当前编译时候的 Node.js 版本，根据不同版本的 Node.js 来展开不同的结果。这会儿就又会提到先前的两个函数声明对比了。

Handle<Value> Echo(const Arguments& args);    // 0.10.x
void Echo(FunctionCallbackInfo<Value>& args); // 6.x

NAN_METHOD 将会在不同版本的 Node.js 下被 NAN 展开成上面两个这样。

而且 NAN 可不只是提供了 NAN_METHOD 一个宏，它还有一坨一坨数不清的宏供开发者使用。

比如声明句柄作用域的 Nan::HandleScope、能黑盒调起 libuv[^8] 进行事件循环上的异步操作的 Nan::AsyncWorker 等。

于是，在城堡时代，大家的 C++ 原生模块代码都差不多长这样。

NAN_METHOD(Echo)
{
    if(info.Length() < 1)
    {
        Nan::ThrowError("Wrong number of arguments.");
        return info.GetReturnValue().Set(Nan::Undefined());
    }

    info.GetReturnValue().Set(info[0]);
}

NAN_MODULE_INIT(InitAll)
{
    Nan::Set(
        target,
        Nan::New<String>("echo").ToLocalChecked(),
        Nan::GetFunction(Nan::New<v8::FunctionTemplate>(Echo)).ToLocalChecked());
}

这样做的好处就是，代码只需要随着 NAN 的升级做改变就好，它会帮你兼容各不同 Node.js 版本，使其在任意版本都能被编译使用。

即使是 NAN 这样的好物，也有自己的一个使命，使命之外的东西会被逐渐剥离。比如 0.10.x 和 0.12.x 等版本就应该要退出历史舞台了，NAN 会逐渐放弃对它们的兼容和支持。

帝国时代：符合 ABI 的 N-API

自从前几天 Node.js v8.0.0 发布之后，Node.js 推出了全新的用于开发 C++ 原生模块的接口，N-API。

据官方文档所述，它的发音就是一个单独的 N，加上 API，即四个英文字母单独发音。

这东西相较于先前三个时代有什么不同呢？为什么会是更进一步的帝国时代呢？

首先，我们知道，即使是在 NAN 的开发方式下，一次编写好的代码在不同版本的 Node.js 下也需要重新编译，否则版本不符的话 Node.js 无法正常载入一个 C++ 扩展。即一次编写，到处编译。

而 N-API 相较于 NAPI 来说，它把 Node.js 的所有底层数据结构全部黑盒化，抽象成 N-API 当中的接口。

不同版本的 Node.js 使用同样的接口，这些接口是稳定地 ABI 化的，即应用二进制接口（Application Binary Interface）。这使得在不同 Node.js 下，只要 ABI 的版本号一致，编译好的 C++ 扩展就可以直接使用，而不需要重新编译。事实上，在支持 N-API 接口的 Node.js 中，的确就指定了当前 Node.js 所使用的 ABI 版本。

为了使得以后的 C++ 扩展开发、维护更方便，N-API 致力于以下的几个目标：

以 C 的风格提供稳定 ABI 接口；
消除 Node.js 版本的差异；
消除 JavaScript 引擎的差异（如 Google V8、Microsoft ChakraCore 等）。

而这些 API 主要就是用来创建和操作 JavaScript 的值了，我们就再也不用直接使用 Google V8 提供的数据类型了。毕竟在 NAN 中，就算我们有时候看不到 Google V8 的影子，实际上在宏展开后还是无数的 Google V8 数据结构。

为了达成上述隐藏的目标，N-API 的姿势就变成了这样：

提供头文件 node_api.h；
任何 N-API 调用都返回一个 napi_status 枚举，来表示这次调用成功与否；
N-API 的返回值由于被 napi_status 占坑了，所以真实返回值由传入的参数来继承，如传入一个指针让函数操作；
所有 JavaScript 数据类型都被黑盒类型 napi_value 封装，不再是类似于 v8::Object、v8::Number 等类型；
如果函数调用不成功，可以通过 napi_get_last_error_info 函数来获取最后一次出错的信息。

注意：哪怕是现在的 Node.js v8.x 版本，N-API 仍处于一个实验状态，个人认为还有非常长的一段路要走，所以大家在生产环境中还不必太过于激进，不过 N-API 依然是大势所趋；不过对于使用老版本的 Node.js 开发者来说，大家也不要着急，即使 N-API 是在 v8.x 才正式集成进 Node.js，在其它旧版本的 Node.js 中依然可以将 N-API 作为外挂式的头文件 9 中使用，只不过无法做到跨版本的特性，这只是它做的向后兼容的一个事情而已。

关于 N-API 一系列的函数可以访问它的文档了解更多详情，现在我们来点料儿让大家对 N-API 的印象不是那么抽象。

模块初始化

在封建时代和 NAN 所处的，模块的初始化是交给 Node.js 提供的宏来实现的。

NODE_MODULE(addon, Init)

而到了当前的 N-API，它就变成了 N-API 的一个宏了。

NAPI_MODULE(addon, Init)

相应地，这个初始化函数 Init 的写法也会有所改变。比如这是封建时代和 NAN 时代的两种不同写法：

// 暴力写法
void Init(Local<Object> exports) {
    NODE_SET_METHOD(exports, "echo", Echo);
}

// NAN 写法
NAN_MODULE_INIT(Init)
{
    Nan::Set(
        target,
        Nan::New<String>("echo").ToLocalChecked(),
        Nan::GetFunction(Nan::New<v8::FunctionTemplate>(Echo)).ToLocalChecked());
}

而到了 N-API 的时候，这个 Init 函数就该是这样的了。

void Init(napi_env env, napi_value exports, napi_value module, void* priv)
{
    napi_status status;

    // 用于设置 exports 对象的描述结构体
    napi_property_descriptor desc =
        { "echo", 0, Echo, 0, 0, 0, napi_default, 0 };

    // 把 "echo" 设置到 exports 去
    status = napi_define_properties(env, exports, 1, &desc);
}

napi_property_descriptor 是用于设置对象属性的描述结构体，它的声明如下：
typedef struct {
  const char* utf8name;

  napi_callback method;
  napi_callback getter;
  napi_callback setter;
  napi_value value;

  napi_property_attributes attributes;
  void* data;
} napi_property_descriptor;
那么上面 Init 函数中的 desc 意思就是，即将被挂在的对象下会挂一个叫 "echo" 的东西，它的函数是 Echo，其它的 getter、setter 等全是空指针，而属性则是 napi_default。

napi_property_attributes 除了 napi_default 之外，还有诸如只读、是否可枚举等属性。

函数声明

还记得之前的两种函数声明吗？第三次再搬过来。

Handle<Value> Echo(const Arguments& args);    // 0.10.x
void Echo(FunctionCallbackInfo<Value>& args); // 6.x

在 N-API 中，你不用再被告知需要有 C++ 基础，C 即可。因为在 N-API 里面，声明一个 Echo 是这样的：

napi_value Echo(napi_env env, napi_callback_info info)
{
    napi_status status;

    size_t argc = 1;
    napi_value argv[1];
    status = napi_get_cb_info(env, info, &argc, argv, 0, 0);
    if(status != napi_ok || argc < 1)
    {
        napi_throw_type_error(env, "Wrong number of arguments");
        return 0; // napi_value 实际上是一个指针，返回空指针表示无返回值
    }

    return argv[0];
}

重要：目前 8.0.0 和 8.1.0 版本的 Node.js 官方文档中，关于 N-API 的各种接口文档错误颇多，所以还是要以能使用的接口为准。

而且现在大家也有很多人正在帮忙一起修复文档。例如现在的 JavaScript 函数声明返回值其实是 napi_value，而官方文档上还是老旧的 void。又比如 `napi_property_descriptor_desc 结构体中，在 utf8name 之后还有一个 napi_value 的变量，而文档中却是没有的。

这也是为什么我前面强调目前来说 N-API 还处于试验阶段。毕竟 API 并没有完全稳定下来，还处于一个快速迭代的步伐中，文档的更新并未跟上代码的更新。至少在笔者写作的当前是这样的（现在日期 2017 年 6 月 9 日）。

上面代码分步解析。

通过 napi_get_cb_info 获取当次函数请求的参数信息，包括参数数量和参数体（参数体以 napi_value 的数组形式体现）；
看看解析有无出错（status 不等于 napi_ok）或者看看参数数量是否小于 1；
- 若解析出错或者参数数量小于 1，通过 napi_throw_type_error 在 JavaScript 层抛出一个错误对象，并返回；
- 若无错则继续进行；
返回 argv[0]，即第一个参数。

Demo 完整代码

这里放上这个 Echo 样例的完整代码，大家可以拿回家试试看。

binding.gyp

{
  "targets": [{
    "target_name": "addon",
    "sources": [ "addon.cc" ],
    "cflags!": [ "-fno-exceptions" ],
    "cflags_cc!": [ "-fno-exceptions" ],
    "xcode_settings": {
      "GCC_ENABLE_CPP_EXCEPTIONS": "YES",
      "CLANG_CXX_LIBRARY": "libc++",
      "MACOSX_DEPLOYMENT_TARGET": "10.7"
    },
    "msvs_settings": {
      "VCCLCompilerTool": { "ExceptionHandling": 1 }
    }
  }]
}

addon.cc

#include <node_api.h>

napi_value Echo(napi_env env, napi_callback_info info)
{
    napi_status status;

    size_t argc = 1;
    napi_value argv[1];
    status = napi_get_cb_info(env, info, &argc, argv, 0, 0);
    if(status != napi_ok || argc < 1)
    {
        napi_throw_type_error(env, "Wrong number of arguments");
        status = napi_get_undefined(env, argv);
    }

    return argv[0];
}

void Init(napi_env env, napi_value exports, napi_value module, void* priv)
{
    napi_status status;
    napi_property_descriptor desc =
        { "echo", 0, Echo, 0, 0, 0, napi_default, 0 };
    status = napi_define_properties(env, exports, 1, &desc);
}

NAPI_MODULE(addon, Init)

乘风破浪

在完成了代码之后，大家赶紧试一下代码吧。

首先在 Node.js v8.x 下进行试验，把这两段代码分别放到同一个目录下，命名好后，执行这样的终端命令：

$ node-gyp rebuild
...
$ node --napi-modules
(node:52264) Warning: N-API is an experimental feature and could change at any time
> const addon = require("./build/Release/addon");
undefined
> addon.echo("2333");
'2333'
> addon.echo("蛋花汤🐶", "南瓜饼🐱");
'蛋花汤🐶'
> addon.echo();
TypeError: Wrong number of arguments
    at repl:1:7
    at ContextifyScript.Script.runInThisContext (vm.js:44:33)
    at REPLServer.defaultEval (repl.js:239:29)
    at bound (domain.js:301:14)
    at REPLServer.runBound [as eval] (domain.js:314:12)
    at REPLServer.onLine (repl.js:433:10)
    at emitOne (events.js:120:20)
    at REPLServer.emit (events.js:210:7)
    at REPLServer.Interface._onLine (readline.js:278:10)
    at REPLServer.Interface._line (readline.js:625:8)

注意：还是因为试验特性，目前在 Node.js v8.x 要加载和执行 N-API 的 C++ 扩展的话，在启动 node 的时候需要加上 --napi-modules 参数，表示这次执行要启用 N-API 特性。

效果显而易见，在刚启动 Node.js REPL 的时候，你会得到一个警告。

(node:52264) Warning: N-API is an experimental feature and could change at any time

表示它目前还不是特别稳定，但是值得我们展望未来。然后在我们 require() 扩展的时候，我们就得到了一个拥有 echo 函数的对象了。

我们尝试了三种调用方式。第一次是规规矩矩传入一个参数，echo 如期返回我们传入的参数 "2333"；第二次传入两个参数，echo 返回了第一个参数 "蛋花汤🐶"；最后一次我们没传任何参数，这个时候就走到了 C++ 扩展中判断函数参数数量失败的条件分支，就抛出了一个 Wrong number of arguments 的错误对象。

总之，它按照我们的预期跑起来了。并且代码里面并没有任何 Node.js 非 N-API 所暴露出来的数据结构和 V8 的数据结构——版本差异消除了。

接下来激动人心的时刻到了，如果读者是使用 nvm 来管理自己的 Node.js 版本的话，可以尝试着安装一个 8.1.0 的 Node.js 版本。

$ nvm install 8.1.0

在安装成功切换版本成功后，尝试着直接打开 Node.js RELP，忘掉再次编译刚才编译好的扩展这一步。（不过别忘了 --napi-module 参数）

把刚才用于测试的几句 JavaScript 代码再重复地输入——N-API 诚不我欺，居然还是能输出结果。这对于以前的暴力做法和 NAN 做法来说，无疑是非常大的一个进步。

向下兼容

至此，我希望大家还没有忘记 N-API 是自 Node.js 8.0 之后出的特性。所以之前 Demo 的代码并不能在 Node.js 8.0 之前的版本如期编译和运行。

辛辛苦苦写好的包，居然不能在 Node.js 6.x 下面跑，搞什么。

先别急着摔。文中之前也说了，有一个外挂式头文件的包，其包名是 node-addon-api。

我们就试着通过它来进行向下兼容吧。首先在我们刚才的源码目录把这个包给安装上。

$ npm install --save node-addon-api

还是由于快速迭代的原因，我不能保证这个包当前版本的时效性，不过我相信大家都有探索精神，在未来版本不符导致的 API 不符的问题应该都能解决。

然后，给我们的 binding.gyp 函数加点料，加两个字段，里面是两个指令展开。

"include_dirs": [ "<!@(node -p \"require('node-addon-api').include\")" ],
"dependencies": [ "<!(node -p \"require('node-addon-api').gyp\")" ]

<!@ 和 <! 开头的字符串在 GYP 中代表指令，表示它的值是后面的指令的执行结果。上面两条指令的返回结果分别是外挂式头文件的头文件搜索路径，以及外挂式 N-API 这个包编译成静态连接库供我们自己的包使用的依赖声明。

有了这两个字段后，就表示我们依赖了外挂式 N-API 头文件。而且它内部自带判断，如果版本已经达到了有 N-API 的要求，它的依赖就会是一个空依赖，即不依赖外挂式 N-API 编译的静态连接库。

也就是说，用了外挂式的 N-API，能自动适配 Node.js 8.x 和低版本。

于是这个 binding.gyp 现在看起来是这样子的。

{
  "targets": [{
    "target_name": "addon",
    "sources": [ "addon.cc" ],
    "cflags!": [ "-fno-exceptions" ],
    "cflags_cc!": [ "-fno-exceptions" ],
    "xcode_settings": {
      "GCC_ENABLE_CPP_EXCEPTIONS": "YES",
      "CLANG_CXX_LIBRARY": "libc++",
      "MACOSX_DEPLOYMENT_TARGET": "10.7"
    },
    "msvs_settings": {
      "VCCLCompilerTool": { "ExceptionHandling": 1 }
    },
    "include_dirs": [ "<!@(node -p \"require('node-addon-api').include\")" ],
    "dependencies": [ "<!(node -p \"require('node-addon-api').gyp\")" ]
  }]
}

至于源码层面，我们就不需要作任何修改。在 Node.js v6.x 下面试试看吧。同样是使用 node-gyp rebuild 进行编译。然后通过 Node.js REPL 进去测试。

具体的终端输出这里就不放出来了，相信经过实验的大家都得到了自己想要的结果。

小结

本次内容主要讲解了在 Node.js 领域中原生 C++ 模块开发的方式变迁。

从 node-waf 到 node-gyp，这是构建工具的一个变迁，未来说不定会是 GN 或者其它的构建工具。
从暴力写码，到 NAN 的出现，见证了 Node.js 社区的各种爱恨情仇，一直到现在的新生儿 N-API，为原生 C++ 模块的开发输送了新鲜的血液。

目前的中坚力量仍然是 NAN 的开发方式，甚至我猜测是否未来有可能 NAN 会提供关于 N-API 的各种宏封装，使其彻底消除版本差异，包括 ABI 版本上的差异。当然这种 ABI 版本差异导致的需要多次编译问题应该还是存在的，这里指的是一次编码的差异。

在大家跟着本文对 N-API 进行了一次浅尝辄止的尝试之后，希望能对当下仍然处于实验状态的 N-API 充满了希冀，并对现在存在的各种坑处以包容的心态。

毕竟，Node.js loves you all。

参考资料

「Consider moving from gyp to gn」：https://github.com/nodejs/node/issues/6089
「Getting Started with Embedding · v8/v8 Wiki」：https://github.com/v8/v8/wiki/Getting-Started-with-Embedding
「Drop support for v0.10 and v0.12?」：https://github.com/nodejs/nan/issues/676
「Node Loves Rust」：https://cnodejs.org/topic/593353775b07c1b24afa0638
「N-API | Node.js v8.0.0 Documentation」：https://nodejs.org/docs/v8.0.0/api/n-api.html
「doc: fix out of date sections in n-api doc」：https://github.com/nodejs/node/pull/13508

[^1]: 用于定义某种文件类型的特殊标识，详见 https://en.wikipedia.org/wiki/Magic_number_programming)( [^2]: 代码参见 https://github.com/nodejs/node/blob/v6.9.4/src/node.cc#L2427-L2502 [^3]: 年久失修，当前 NPM 上搜索到的 node-waf 已经不是当年的了，不过这个是 Waf 的官方仓库 https://github.com/waf-project/waf。 [^4]: 全称 Generate Your Projects，是谷歌开发的一套构建系统，未尽事宜详询 https://gyp.gsrc.io。 [^5]: GYP 的配置文件的后缀就是 *.gyp 或者 *.gypi 等，是个类 JSON 文件。 [^6]: GN 是谷歌开发的相较于 GYP 更新更快的一套构建工具，可以参考 https://chromium.googlesource.com/chromium/src/tools/gn/+/HEAD/docs/quick_start.md [^7]: 让垃圾回收机制来管理 JavaScript 对象生命周期的一种类，即 HandleScope，在我的新书中将会有详解。 [^8]: Node.js 的异步事件循环支撑者，详询 http://www.libuv.org/ [^9]: 详情请查看 node-api 这个包，https://github.com/nodejs/node-api

开场 Live，分享点干货——「深入了解 Node.js 包与模块机制」

xadillax — Wed, 03 May 2017 18:06:08 +0800

先放上 Live 地址： https://www.zhihu.com/lives/842742839304667136

本次 Live 将深入剖析 Node.js 包与模块机制，包括且不限于解析 Node.js 源码、社区规范等。本人认为这是作为一个合格 Node.js 开发者哪怕是不深入也要了解的姿势之一。

本次 Live 主要包括以下内容：

CommonJs 模块规范
CommonJs 包规范
Node.js 模块规范
Node.js 包规范
Node.js 四种模块本质和加载原理
Node.js 入口模块
最后带一笔 Node.js 包（如包管理器，通样等）

当然在 Live 过程中，可能略有出入。

Byakuren：一个 C 实现的主题色提取库

xadillax — Fri, 03 Mar 2017 19:08:55 +0800

原文地址： https://xcoder.in/2017/03/03/byakuren/

好久没发文章了，借着 Byakuren 开源的档口炒炒冷饭吧。

先上 Repo 地址：https://github.com/XadillaX/byakuren。

主题色

图像主题色是从一张图像中提取出来最能代表这张图片主色调的多种颜色。也就是说在一幅色彩斑斓的图片里面，各种不同颜色的数量就对应着该颜色在图片中的比例，程序可以通过计算图片中不同颜色的像素数来算出主题色。

主题色提取算法

提取的算法在我之前的博客中有说明。在 Byakuren 中其实用的就是之前博客中讲的一些算法。

除去上面两种算法，Byakuren 还提供了将这两种算法结合起来的 Mix 算法。

Byakuren

Byakuren 是我前两年写的一个主题色提取库，也是继 thmclrx 之后的 C 版实现，个人认为代码质量比旧版的 thmclrx 要高。并且它实际上经过了企业级的验证，在某相关的公司已经欢快跑了有些年头了。

在经过相关人员的同意下，我也算把这雪藏了好久的代码给开源出来了。

伪·Byakuren 是什么？

聖白蓮（ひじりびゃくれん，Hiziri Byakuren）是系列作品《东方 project》中的角色，首次登场于《东方星莲船》。

种族：魔法使

能力：使用魔法程度的能力（酣畅增强身体能力的）

危险度：不明

人类友好度：中

主要活动场所：命莲寺之类

命莲寺的住持。虽然原本是人类，不过由于常年的修行已经完全超越了人类。现在已经属于人们常说的魔法使了。

虽然已经入了佛门，但是不知道什么原因却被妖怪敬仰着。她从来没有像童话故事中的魔法使那样，念诵着咒语治退妖怪。使用的力量完全是邪恶的，一点都不像是圣人，虽然并没有人目击到她与人类为敌，但其实已彻底成为妖怪的同伴了。

好吧，总之本人是个东方控，所以基本上项目名都跟东方有关。

真·Byakuren 是什么？

如文章题目所说，它是一个 C 实现的开源主题色提取的库，大家可以把它编译成链接库使用。

不过目前暂时只支持 Makefile 的形式来编译，大家如果有兴趣也可以自己建个 Windows 下的 Visual Studio 项目等，也欢迎提类似于 CMake 之类的 PR。

使用

其实详细的使用方法在文档中就有说明。

不过这里还是简单介绍一下吧。

Clone

先把代码给下下来，你也可以把它 Clone 下来。总之仓库地址是：https://github.com/XadillaX/byakuren。

make

然后跑到目录下执行 make。

$ make byakuren

你将得到一个 byakuren.a 的静态链接库。

这个时候你只要拿着这个静态链接库，然后顺便在你的项目中把头文件引进来就可以了。

#include "byakuren.h"

API

我们假设你有 bkr_rgb* rgb 的图片像素信息，以及 uint32_t color_count 的图片像素总数两个变量，下面分别给出三个样例。具体的 API 解析还请去文档观摩。

Octree

bkr_color_stats stats[256];
bkr_octree_node* root = bkr_build_octree(rgb, color_count, 256);
int colors = bkr_octree_calculate_color_stats(root, stats);
bkr_release_octree(root);

colors 就是主题色数量了，传进去的 stats 就会接收到主题色的具体信息了。

Min-diff

bkr_color_stats stats[256];
bkr_mindiff_parameter param;
param.gray_offset = 5;
param.palette = NULL;
int colors = bkr_mindiff_calculate_color_stats(rgb, color_count, stats, &param);

colors 和 stats 如上所述。

Mix

bkr_color_stats stats[256];
bkr_mindiff_parameter param;
param.gray_offset = -1;
param.palette = NULL;
int colors = bkr_mix_calculate_color_stats(rgb, color_count, 256, &param, stats);

colors 和 stats 如上所述。

预览一下

可能有人想看看效果，我这里就放个效果图给大家看看吧。

其中 Octree 和 Mix 两个算法的主题色最大数量参数传的都是 16。

能做什么？

你可以拿它来写一些主题色提取的东西。

你也可以拿它来完成其它语言的主题色提取库的封装，如 Python、Lua 等等。欢迎反馈给我。

结束语

把一份自己觉得还不错的代码开源出来的感觉特爽，尤其是这种重见天日的感觉。ﾍ|･∀･|ﾉ*~●

跟我一起部署和定制 CNPM——基础部署

xadillax — Tue, 12 Jul 2016 20:10:12 +0800

原文链接：https://xcoder.in/2016/07/09/lets-cnpm-base-deploy/

本章会介绍 CNPM 的基础部署方法。

该文章所对应的 cnpm 目标版本为 v2.12.2，上下浮动一些兼容的版本问题也都不是特别大。

准备

想要部署 CNPM，你需要做以下的一些准备。

部署的宿体，如服务器、云主机、自己的电脑等；
数据库，支持 MySQL、PostgreSQL、MariaDB，如果使用 SQLite 则无需准备；
Git 客户端（推荐）。

开始部署

克隆 CNPM

首先在本地选择一个目录，比如我将它选择在 /usr/app，然后预想 CNPM 的目录为 /usr/app/cnpm，那么需要在终端 $ cd /usr/app。

接下去执行 Git 指令将 CNPM 克隆到相应目录。

$ git clone https://github.com/cnpm/cnpmjs.org.git

Windows 用户

Windows 用户也可以用类似 Cygwin、MinGW、Powershell 甚至直接是 Command 等来运行 Git。

当然也可以直接下载一些 GUI 工具来克隆，如 SourceTree。

非 Git 用户

跑到 CNPM 的 Release 页面，选择相应的版本下载，比如这里会选择 v2.12.2 版。

下载完毕后将文件夹解压到相应目录即可。

安装依赖

安装依赖其实就是一个 npm install，不过 CNPM 把该指令已经写到 Makefile 里面了，所以直接执行下面的命令就好了。

$ make install

当然万一你是 Windows 用户或者不会 make，那么还是要用 npm install。

$ npm install --build-from-source --registry=https://registry.npm.taobao.org --disturl=https://npm.taobao.org/mirrors/node

修改配置文件

新建一份 config/config.js 文件，并且写入如下的骨架：

'use strict';

module.exports = {
};

在这里面输入你需要的键值对。

这里将会列举一些常用的配置项，其余的一些配置项请自行参考 config/index.js 文件。

配置字段参考

enableCluster：是否启用 cluster-worker 模式启动服务，默认 false，生产环节推荐为 true;
registryPort：API 专用的 registry 服务端口，默认 7001；
webPort：Web 服务端口，默认 7002；
bindingHost：监听绑定的 Host，默认为 127.0.0.1，如果外面架了一层本地的 Nginx 反向代理或者 Apache 反向代理的话推荐不用改；
sessionSecret：session 用的盐；
logdir：日志目录；
uploadDir：临时上传文件目录；
viewCache：视图模板缓存是否开启，默认为 false；
enableCompress：是否开启 gzip 压缩，默认为 false；
admins：管理员们，这是一个 JSON Object，对应各键名为各管理员的用户名，键值为其邮箱，默认为 { fengmk2: 'fengmk2@gmail.com', admin: 'admin@cnpmjs.org', dead_horse: 'dead_horse@qq.com' }；
logoURL：Logo 地址，不过对于我这个已经把 CNPM 前端改得面目全非的人来说已经忽略了这个配置了；
adBanner：广告 Banner 的地址；
customReadmeFile：实际上我们看到的 cnpmjs.org 首页中间一大堆冗长的介绍是一个 Markdown 文件转化而成的，你可以设置该项来自行替换这个文件；
customFooter：自定义页脚模板；
npmClientName：默认为 cnpm，如果你有自己开发或者 fork 的 npm 客户端的话请改成自己的 CLI 命令，这个应该会在一些页面的说明处替换成你所写的；
backupFilePrefix：备份目录；
database：数据库相关配置，为一个对象，默认如果不配置将会是一个 ~/.cnpmjs.org/data.sqlite 的 SQLite；
- db：数据的库名；
- username：数据库用户名；
- password：数据库密码；
- dialect：数据库适配器，可选 "mysql"、"sqlite"、"postgres"、"mariadb"，默认为 "sqlite"；
- hsot：数据库地址；
- port：数据库端口；
- pool：数据库连接池相关配置，为一个对象；
- maxConnections：最大连接数，默认为 10；
- minConnections：最小连接数，默认为 0；
- maxIdleTime：单条链接最大空闲时间，默认为 30000 毫秒；
- storege：仅对 SQLite 配置有效，数据库地址，默认为 ~/.cnpmjs/data.sqlite；
nfs：包文件系统处理对象，为一个 Node.js 对象，默认是 fs-cnpm 这个包，并且配置在 ~/.cnpmjs/nfs 目录下，也就是说默认所有同步的包都会被放在这个目录下；开发者可以使用别的一些文件系统插件（如上传到又拍云等）,又或者自己去按接口开发一个逻辑层，这些都是后话了；
registryHost：暂时还未试过，我猜是用于 Web 页面显示用的，默认为 r.cnpmjs.org；
enablePrivate：是否开启私有模式，默认为 false；
- 如果是私有模式则只有管理员能发布包，其它人只能从源站同步包；
- 如果是非私有模式则所有登录用户都能发布包；
scopes：非管理员发布包的时候只能用以 scopes 里面列举的命名空间为前缀来发布，如果没设置则无法发布，也就是说这是一个必填项，默认为 [ '@cnpm', '@cnpmtest', '@cnpm-test' ]，据苏千大大解释是为了便于管理以及让公司的员工自觉按需发布；更多关于 NPM scope 的说明请参见 npm-scope；
privatePackages：就如该配置项的注释所述，出于历史包袱的原因，有些已经存在的私有包（可能之前是用 Git 的方式安装的）并没有以命名空间的形式来命名，而这种包本来是无法上传到 CNPM 的，这个配置项数组就是用来加这些例外白名单的，默认为一个空数组；
sourceNpmRegistry：更新源 NPM 的 registry 地址，默认为 https://registry.npm.taobao.org；
sourceNpmRegistryIsCNpm：源 registry 是否为 CNPM，默认为 true，如果你使用的源是官方 NPM 源，请将其设为 false；
syncByInstall：如果安装包的时候发现包不存在，则尝试从更新源同步，默认为 true；
syncModel：更新模式（不过我觉得是个 typo），有下面几种模式可以选择，默认为 "none";
- "none"：永不同步，只管理私有用户上传的包，其它源包会直接从源站获取；
- "exist"：定时同步已经存在于数据库的包；
- "all"：定时同步所有源站的包；
syncInterval：同步间隔，默认为 "10m" 即十分钟；
syncDevDependencies：是否同步每个包里面的 devDependencies 包们，默认为 false；
badgeSubject：包的 badge 显示的名字，默认为 cnpm；
userService：用户验证接口，默认为 null，即无用户相关功能也就是无法有用户去上传包，该部分需要自己实现接口功能并配置，如与公司的 Gitlab 相对接，这也是后话了；
alwaysAuth：是否始终需要用户验证，即便是 $ cnpm install 等命令；
httpProxy：代理地址设置，用于你在墙内源站在墙外的情况。

一个可能的配置

下面给出一个样例配置：

module.exports = {
    enableCluster: true,
    database: {
        db: "snpm",
        username: "username",
        password: "password",

        dialect: "mysql",
        host: "127.0.0.1",
        port: 3306
    },
    enablePrivate: false,
    admins: {
        xadillax: "i@2333.moe"
    },
    syncModel: "exist",
    nfs: require('upyun-cnpm').create({
        bucket: "your bucket",
        oprator: "your id",
        password: "your secret"
    }),
    scopes: [ '@cheniu', '@souche', '@souche-f2e' ],
    badgeSubject: 'snpm',
    privatePackages: [ 'snpm' ]
};

上面的配置包文件系统层用的是 upyun-cnpm 插件，需要在 CNPM 源码根目录执行
$ npm install --save -d upyun-cnpm
这个时候你的 package.json 就有更改与源 Repo 不一致了，如果是 Git 克隆的用户在以后升级更新系统的时候稍稍注意一下可能的冲突即可。

官方 NFS 插件

下面给出几个官方的 NFS 插件：

upyun-cnpm：包本体存在又拍云的插件；
fs-cnpm：包本体存在本地的插件；
sfs-client：包本体存在 SFS（Simple FIle Store）插件；
qn-cnpm：包本体存在七牛的插件；
oss-cnpm：包本体存在阿里云 OSS 的插件。

以后官方如果有一些新的插件进来，这里可能不会更新了，请自行去 NFS Storage Wrappers 获取最新的 NFS 插件们。

初始化数据库

如果你使用的是 SQLite 的话，数据库是自动就好了的，可以忽略该步。

其它数据库需要自行导入初始数据库结构。

初始数据库脚本在 docs/db.sql 里面，你可以用一些 GUI 工具将数据导入，也可以直接进入命令行导入。

比如你用的是 MySQL，就可以在本机操作 MySQL。

$ mysql -u yourname -p
mysql> use cnpmjs;
mysql> source docs/db.sql

启动服务

搞好配置之后就可以直接启动服务了。

简单启动

最简单的办法也是我现在正在用的方法就是直接用 node 执行一下入口文件就好了。

$ node dispatch.js

其实我是在 tmux 里面执行上面的指令的。

官方脚本启动

官方的其它一些指令，比如你可以用 NPM 的 script 来运行。

$ npm run start

在 CNPM 里面，npm script 还有下面几种指令

npm run dev：调试模式启动；

npm run test：跑测试；

npm run start：启动 CNPM；

npm run status：查看 CNPM 启动状态；

npm run stop：停止 CNPM。

让我们一起来起花名吧

xadillax — Wed, 24 Feb 2016 16:03:35 +0800

原文：https://xcoder.in/2016/02/24/lets-hua/

起因

起因是我一个叫『小龙』的好基友由于某些原因离职去了一家跟阿里一样有着『花名文化』的公司，于是开始为花名犯愁。

结合之前妹纸『弍纾』在起花名的时候也遇到了同样的困扰，于是决定用 Node.js 写个『一本正经乱起花名』的程序。

准备

Chinese Random Name

首先起花名的原理就是胡乱随机一串字出来胡乱拼。

于是准备应该有 chinese-random-name，一个随机生成中文名的包。

使用它很简单，先把它 require 进来：

const randomName = require("chinese-random-name");

基本用法

如果你需要随机生成一个名字只需要 randomName.generate() 就可以了；如果你要随机一个姓那么就 randomName.surnames.getOne()；如果你只需要获得名字，这里面就有点门道了。

高级用法

你可以随机生成一个名（不带姓的） randomName.names.get()；你也可以指定名字的字数，一二三：

randomName.names.get1();
randomName.names.get2();
randomName.names.get3();

或者！

又或者！

然后或者！

你可以指定每个字的五行哦！

什么意思呢？比如你想给孩子起个名，然后孩子命里五行缺金，那么就可以：

randomName.names.get2("金金");

然后你就可能得到一个『紫铨』，两个字都是属金的。那么如果你孩子姓李，就叫李紫铨；如果孩子姓王，就叫王紫铨；如果姓爱新觉罗，那么就叫爱新觉罗·紫铨。

有木有想给我装得这个逼打个 82 分呢？剩下的就交给 666 吧。(ง •̀_•́)ง

Nomnom

这个包是用来解析命令行参数的。虽然市面上有挺多别的的，比如 commander 等，不过我还是最习惯 nomnom，用称手了就不想换了。

虽然它的 GitHub Repo 下面有这么一段话。

Nomnom is deprecated. Check out https://github.com/tj/commander.js, which should have most, if not all of the capability that nomnom had. Thank you!

不过再怎么说 nomnom 也是当年 substack 大神推荐的啊。(ಡωಡ)

Colorful

这个包是用来上色的。

毕竟五行是有颜色的哇。

const color = require("colorful");
console.log(color.red("（*/∇＼*）"));

那么在你的终端就好看到一个红色的 （*/∇＼*）。

Is Chinese

用来判断是不是中文的包。

作为一个起名的命令行程序，你总得好好传参才行吧，总不能你随便传个咸鸭蛋🐣我也好好处理吧。

于是就用 is-chinese 来判断某个字符串是不是纯中文。

这个包是由前阿里小伙伴，CNode 站长唐少写的。

用起来也很简单，只要 isChinese("什么你要判断什么") 就可以了。

集合

$ npm install --save -d chinese-random-name
$ npm install --save -d nomnom
$ npm install --save -d colorful
$ npm install --save -d is-chinese

chinese-random-name: https://github.com/XadillaX/chinese-random-name
nomnom: https://github.com/harthur/nomnom
colorful: https://github.com/lepture/colorful
is-chinese: https://github.com/alsotang/is-chinese

开工

其结果在这里。

解析命令行参数

首先效果是这样的：

$ hua --help

Usage: hua [options]

Options:
-p PREFIX, --prefix PREFIX          to specify a prefix.
-s SUFFIX, --suffix SUFFIX          to specify a suffix.
-5 WUXING, --five-elements WUXING   the file elements (Wuxing) of huaming.
-c COUNT, --count COUNT             the count of huaming  [10]

使用者可以自己想一个前缀或者后缀，然后自定义（或者也可以不指定）两个字的五行，以及指定一次性生成多少个花名。

比如想要生成以 龙 字为前缀的花名，就可以 $ hua --prefix 龙，得到结果可以是这样的：

* 龙幼
* 龙巡
* 龙躬
* 龙仇
* 龙锤
* 龙镒
* 龙拾
* 龙央
* 龙些
* 龙悠

如果想两个字分别所属金和谁，就可以 $ hua --five-elements 金水 来起花名：

* 倩娥
* 雀效
* 黍棓
* 姹溶
* 馨沙
* 宫闲
* 裕混
* 俗封
* 绸娥
* 瑞淦

想要得到这样一个命令行参数，我们可以用 nomnom 来解决。

var opts = require("nomnom")
    .script("hua")
    .option("prefix", {
        abbr: "p",
        help: "to specify a prefix.",
        metavar: "PREFIX"
    })
    .option("suffix", {
        abbr: "s",
        help: "to specify a suffix.",
        metavar: "SUFFIX"
    })
    .option("five-elements", {
        abbr: "5",
        help: "the file elements (Wuxing) of huaming.",
        metavar: "WUXING"
    })
    .option("count", {
        abbr: "c",
        help: "the count of huaming",
        metavar: "COUNT",
        default: 10
    })
    .parse();

上面的这段代码分别指定了脚本名为 hua，然后指定了 prefix / suffix / five-elements 和 count 四个参数，并把解析好的参数赋值给 opts 变量。

由于我希望这个包在通常的 Node.js 下都可以跑，所以没有用 let 之类的东西。

花名类

接下去要写一个花名类，这个类不只是可以在 CLI 之中使用，也可以让别人作为一个包来引入。然后实际上这个类就是要对 chinese-random-name 进行一个封装。

构造函数

var Hua = function(options) {
    this.options = options;

    // Do something...
};

首先这个 options 就是之前由 nomnom 解析出来的参数，当然有些参数是可选的。

接下去我们要在构造函数也就是 Hua 里面格式化前缀或者后缀（如果有的话），将他们弄成只有一个汉字的格式。

if(options.prefix) {
    options.prefix = options.prefix[0];
    if(!isChinese(options.prefix)) delete options.prefix;
}

if(options.suffix) {
    options.suffix = options.suffix[0];
    if(!isChinese(options.suffix)) delete options.suffix;
}

前后缀弄好之后要对五行进行分析了。

如果有前后缀那么忽略五行参数。

if(options.prefix && options.suffix) {
    delete options["file-elements"];
}

如果有前缀，那么忽略传进来的五行的第一个五行；如果有后缀那么忽略第二个字的五行。

var wuxing = "金木水火土";

.
.
.

} else if(options.prefix) {
    options["five-elements"] = options["five-elements"].substr(1, 1);
    if(-1 === wuxing.indexOf(options["five-elements"])) {
        delete options["five-elements"];
    }
} else if(options.suffix) {
    options["five-elements"] = options["five-elements"].substr(0, 1);
    if(-1 === wuxing.indexOf(options["five-elements"])) {
        delete options["five-elements"];
    }
}

如果前后缀都没有，那么要格式化一下该参数，使其仅剩两个有效的五行汉字。

} else {
    options["five-elements"] = options["five-elements"].substr(0, 2).split("");
    for(var i = 0; i < options["five-elements"].length; i++) {
        // 如果是无效五行或者冰没有这个字的话，随机一个五行出来
        if(-1 === wuxing.indexOf(options["five-elements"][i])) {
            options["five-elements"][i] = wuxing[Math.floor(Math.random() * 5)];
        }
    }

    // 字数不够，随机来凑
    while(options["five-elements"].length < 2) {
        options["five-elements"].push(wuxing[Math.floor(Math.random() * 5)]);
    }

    options["five-elements"] = options["five-elements"].join("");
}

以上的这些逻辑都写在构造函数里面，如果想要完整的构造函数可以看 hua 的 hua.js 文件。

生成一个花名

生成一个花名其实就是调用 randomName.names.get 系列函数们了。

有前后缀：直接返回前缀加后缀。
有前缀：返回前缀加 get1。
有后缀：返回 get1 加后缀。
没有前后缀：直接返回 get2。

注意：以上情况都会传进（哪怕是 undefined）五行参数。

所以 generateOne 函数长这样：

Hua.prototype.generateOne = function() {
    if(this.options.prefix && this.options.suffix) {
        return this.options.prefix + this.options.suffix;
    }

    if(this.options.prefix) {
        debug(this.options["five-elements"]);
        return this.options.prefix + randomName.names.get1(this.options["five-elements"]);
    }

    if(this.options.suffix) {
        debug(this.options["five-elements"]);
        return randomName.names.get1(this.options["five-elements"]) + this.options.suffix;
    }

    return randomName.names.get2(this.options["five-elements"]);
};

生成 Count 个花名

还记得 CLI 的 count 参数么？因为为了方便，我们可以批量生成花名，所以就需要生成 Count 个花名的函数了。

实际上就是一个循环调用 generateOne 的函数而已。

Hua.prototype.generate = function(count) {
    if(!count) count = this.options.count || 10;

    var result = [];
    for(var i = 0; i < count; i++) {
        result.push(this.generateOne());
    }
    return result;
};

CLI 文件

刚刚那个 nomnom 解析就在这个文件里面，然后接下去就是实例化一个 Hua 对象，然后生成 count 个花名。

var hua = new Hua(opts);
var result = hua.generate();

最后把花名输出来就好了。

for(var i = 0; i < result.length; i++) {
    console.log(" * " + result[i]);
}

桥豆麻袋！

说好的五行颜色呢？！

好像是的哦，我们要在输出之前给 result 上个色儿。

遍历 result 里面的花名每个字，获取它的五行属性，然后涮上色儿。

chinese-random-name 暴露了字典中每个字的五行属性，只需要赋值一下就好了。

var dict = require("chinese-random-name").names.dict;

然后逐一对比。最后对应金木水火土的颜色值分别为：

var definedColors = [
    220, 83, 26, 197, 59
];

220 为黄色，代表金；83 为绿色，代表木；26 蓝色代表水；197 红色代表火；59 灰色代表土。

如果那个字无法找到属性，则不上色，保持默认。

result = result.map(function(name) {
    var withColor = "";

    for(var i = 0; i < 2; i++) {
        for(var j = 0; j < wuxing.length; j++) {
            var wx = wuxing[j];
            if(wx === " ") {
                withColor += name[i];
                break;
            }

            if(dict[wx].indexOf(name[i]) !== -1) {
                var color = new Color(name[i]);
                color.fgcolor = definedColors[j];
                withColor += color.toString();
                break;
            }
        }
    }

    return withColor;
});

至此我们的 CLI 就写好了，最后别忘了在 hua 这个 CLI 文件顶部加上一句话。

#!/usr/bin/env node

这代表到时候如果要 ./hua 的时候这个脚本是用 Node.js 来跑的。

收拾

本来想好好写篇起花名的牢骚，结果不知不觉写成了给初心者看的初级教程了，泪目 ( •̥́ ˍ •̀ू )

不嫌弃的就这么看看吧。

最后这里给出我写好的这个 hua 程序。

$ [sudo] npm install -g huaming

然后就能在命令行下面跑了，跑法上面几章有介绍过。它的 Repo 在这里。

最后希望这个包在你们起花名的时候还真有那么一丢丢的用处。

Node.js 启动方式：一道关于全局变量的题目引发的思考·续

xadillax — Fri, 27 Nov 2015 15:13:14 +0800

原文地址：https://xcoder.in/2015/11/27/a-js-problem-about-global-continued/

本文是上文《Node.js 启动方式：一道关于全局变量的题目引发的思考》的续章。

原题回顾

我们还是先回顾下原题吧。

var a = 2;  
function foo(){  
    console.log(this.a);
}

foo();

上题由我们亲爱的小龙童鞋发现并在我们的 901 群里提问的。

不过在上面一篇文章中，我们讲的是在 REPL 和 vm 中有什么事情，但是并没有解释为什么在文件模块的载入形式下，var 并不会挂载到全局变量去。

其实原因很简单，大家应该也都明白，在 Node.js 中，每个文件相当于是一个闭包，在 require 的时候被编译包了起来。

但是具体是怎么样的呢？虽然网上也有很多答案，我还是决定在这里按上一篇文章的尿性稍微解释一下。

分析

首先我们还是回到上一篇文章的《Node REPL 启动的沙箱》一节，里面说了当启动 Node.js 的时候是以 src/node.js 为入口的。

如果以 REPL 为途径启动的话是直接启动一个 vm，而此时的所有根级变量都在最顶级的作用域下，所以一个 var 自然会绑定到 global 下面了。

而如果是以文件，即 $ node foo.js 形式启动的话，它就会执行 src/node.js 里面的另一坨条件分支了。

  // ...
} else if (process.argv[1]) {
  // make process.argv[1] into a full path
  var path = NativeModule.require('path');
  process.argv[1] = path.resolve(process.argv[1]);

  var Module = NativeModule.require('module');

  // ...

  startup.preloadModules();
  if (global.v8debug &&
      process.execArgv.some(function(arg) {
        return arg.match(/^--debug-brk(=[0-9]*)?$/);
      })) {

    var debugTimeout = +process.env.NODE_DEBUG_TIMEOUT || 50;
    setTimeout(Module.runMain, debugTimeout);
  } else {
    // Main entry point into most programs:
    Module.runMain();
  }
} else {
  // ...

从上面的代码看出，只要是以 $ node foo.js 形式启动的，都会经历 startup.preloadModules() 和 Module.runMain() 两个函数。

startup.preloadModules()

我们来看看这个函数。

startup.preloadModules = function() {
  if (process._preload_modules) {
    NativeModule.require('module')._preloadModules(process._preload_modules);
  }
};

实际上就是执行的 lib/module.js 里面的 _preloadModules 函数，并且把这个 process._preload_modules 给传进去。当然，前提是有这个 process._preload_modules。

process._preload_modules

这个 process._preload_modules 指的就是当你在使用 Node.js 的时候，命令行里面的 --require 参数。

-r, --require         module to preload (option can be repeated)

代码在 src/node.cc 里面可考。

// ...
} else if (strcmp(arg, "--require") == 0 ||
           strcmp(arg, "-r") == 0) {
  const char* module = argv[index + 1];
  if (module == nullptr) {
    fprintf(stderr, "%s: %s requires an argument\n", argv[0], arg);
    exit(9);
  }
  args_consumed += 1;
  local_preload_modules[preload_module_count++] = module;
} else if
// ...

如果遇到了 --require 这个参数，则对静态变量 local_preload_modules 和 preload_module_count 做处理，把这个预加载模块路径加进去。

待到要生成 process 这个变量的时候，再把预加载模块的信息放到 process._preload_modules 里面去。

void SetupProcessObject(Environment* env,
                        int argc,
                        const char* const* argv,
                        int exec_argc,
                        const char* const* exec_argv) {
  // ...

  if (preload_module_count) {
    CHECK(preload_modules);
    Local<Array> array = Array::New(env->isolate());
    for (unsigned int i = 0; i < preload_module_count; ++i) {
      Local<String> module = String::NewFromUtf8(env->isolate(),
                                                 preload_modules[i]);
      array->Set(i, module);
    }
    READONLY_PROPERTY(process,
                      "_preload_modules",
                      array);

    delete[] preload_modules;
    preload_modules = nullptr;
    preload_module_count = 0;
  }

  // ...
}

最重要的就是这句

READONLY_PROPERTY(process,
                  "_preload_modules",
                  array);

require('module')._preloadModules

上面我们讲了这个 process._preload_modules，然后现在我们说说是如何把 $ node --require bar.js foo.js 给预加载进去的。

接下去我们就要移步到 lib/module.js 文件里面去了。

在第 496 行左右的地方有这个函数。

Module._preloadModules = function(requests) {
  if (!Array.isArray(requests))
    return;

  // Preloaded modules have a dummy parent module which is deemed to exist
  // in the current working directory. This seeds the search path for
  // preloaded modules.
  var parent = new Module('internal/preload', null);
  try {
    parent.paths = Module._nodeModulePaths(process.cwd());
  }
  catch (e) {
    if (e.code !== 'ENOENT') {
      throw e;
    }
  }
  requests.forEach(function(request) {
    parent.require(request);
  });
};

大概我们能看到，就是以 internal/preload 为 ID 的 Module 对象来载入这些预加载模块。

var parent = new Module('internal/preload', null);
requests.forEach(function(request) {
  parent.require(request);
});

根据这个函数的注释说明，这个 Module 对象是一个虚拟的 Module 对象，主要是跟非预加载的那些模块给隔离或者区别开来，并且提供一个模块搜索路径。

Module.runMain()

看完上面的说明，我们接下去看看 Module.runMain() 函数。

这个函数还是位于 lib/module.js 文件里面。

Module.runMain = function() {
  // Load the main module--the command line argument.
  Module._load(process.argv[1], null, true);
  // Handle any nextTicks added in the first tick of the program
  process._tickCallback();
};

我们看到了就是在这句话中，Module 载入了 process.argv[1] 也就是文件名，自此一发不可收拾。

Module._load

这个函数相信很多人都知道它的用处了，无非就是载入文件，并加载到一个闭包里面。

这样一来在文件里面 var 出来的变量就不在根作用域下面了，所以不会粘到 global 里面去。它的 this 就是包起来的这个闭包了。

Module._load = function(request, parent, isMain) {
  // ...

  var filename = Module._resolveFilename(request, parent);

  // ...
  var cachedModule = Module._cache[filename];
  if (cachedModule) {
    return cachedModule.exports;
  }

  if (NativeModule.nonInternalExists(filename)) {
    debug('load native module %s', request);
    return NativeModule.require(filename);
  }

  var module = new Module(filename, parent);

  if (isMain) {
    process.mainModule = module;
    module.id = '.';
  }

  Module._cache[filename] = module;

  module.load(filename);
  return module.exports;
}

上面的代码首先是根据传入的文件名找到真的文件地址，就是所谓的搜索路径了。比如 require("foo") 就会分别从 node_modules 路径等依次查找下来。

我经常 Hack 这个 _resolveFilename 函数来简化 require 函数，比如我希望我用 require("controller/foo") 就能直接拿到 ./src/controller/foo.js 文件。有兴趣讨论一下这个用法的童鞋可以转到我的 Gist 上查看 Hack 的一个 Demo。

第二步就是我们常说的缓存了。如果这个模块之前加载过，那么在 Module._cache 下面会有个缓存，直接去取就是了。

第三步就是看看是不是 NativeModule。

if (NativeModule.nonInternalExists(filename)) {
  debug('load native module %s', request);
  return NativeModule.require(filename);
}

NativeModule

之前的代码里面其实也没少出现这个 NativeModule。那这个 NativeModule 到底是个 shenmegui 呢？

其实它还是在 Node.js 的入口 src/node.js 里面。

它主要用来加载 Node.js 的一些原生模块，比如说 NativeModule.require("child_process") 等，也用于一些 internal 模块的载入，比如 NativeModule.require("internal/repl")。

之前代码的这个判断就是说如果判断要载入的文件是一个原生模块，那么就使用 NativeModule.require 来载入。

NativeModule.require

NativeModule.require = function(id) {
  if (id == 'native_module') {
    return NativeModule;
  }

  var cached = NativeModule.getCached(id);
  if (cached) {
    return cached.exports;
  }

  if (!NativeModule.exists(id)) {
    throw new Error('No such native module ' + id);
  }

  process.moduleLoadList.push('NativeModule ' + id);

  var nativeModule = new NativeModule(id);

  nativeModule.cache();
  nativeModule.compile();

  return nativeModule.exports;
};

先看看是否是本身，再看看是否被缓存，然后看看是否合法。接下去就是填充 process.moduleLoadList，最后载入这个原生模块、缓存、编译并返回。

有兴趣的同学可以在 Node.js 中输出 process.moduleLoadList 看看。

这个 compile 很重要。

NativeModule.prototype.compile

在 NativeModule 编译的过程中，大概的步骤是获取代码、包裹（Wrap）代码，把包裹的代码 runInContext 一遍得到包裹好的函数，然后执行一遍就算载入好了。

NativeModule.prototype.compile = function() {
  var source = NativeModule.getSource(this.id);
  source = NativeModule.wrap(source);

  var fn = runInThisContext(source, { filename: this.filename });
  fn(this.exports, NativeModule.require, this, this.filename);

  this.loaded = true;
};

我们往这个 src/node.js 文件这个函数的上面几行看一下，就知道包裹代码是怎么回事了。

NativeModule.wrap = function(script) {
  return NativeModule.wrapper[0] + script + NativeModule.wrapper[1];
};

NativeModule.wrapper = [
  '(function (exports, require, module, __filename, __dirname) {\n',
  '\n});'
];

根据上面的代码，我们能知道的就是比如我们一个内置模块的代码是：

var foo = require("foo");
module.exports = 1;

那么包裹好的代码将会是这样子的：

(function (exports, require, module, __filename, __dirname) {
var foo = require("foo");
module.exports = 1;
});

这样一看就明白了这些 require、module、exports、__filename 和 __dirname 是怎么来了吧。

当我们通过 var fn = runInThisContext(source, { filename: this.filename }); 得到了这个包裹好的函数之后，我们就把相应的参数传进这个闭包函数去执行。

fn(this.exports, NativeModule.require, this, this.filename);

这个 this 就是对应的这个 module，自然这个 module 里面就有它的 exports；require 函数就是 NativeModule.require。

所以我们看到的在 lib/*.js 文件里面的那些 require 函数，实际上就是包裹好之后的代码的 NativeModule.require 了。

所以说实际上这些内置模块内部的根作用域下的 var 再怎么样高级也都是在包裹好的闭包里面 var，怎么的也跟 global 搭不着边。

内部原生模块

通过上面的追溯我们知道了，如果我们在代码里面使用 require 的话，会先看看这个模块是不是原生模块。

不过回过头看一下它的这个判断条件：

if (NativeModule.nonInternalExists(filename)) {
  // ...
}

如果是原生模块并且不是原生内部模块的话。

那是怎么区分原生模块和内部原生模块呢？

我们再来看看这个 NativeModule.nonInternalExists(filename) 函数。

NativeModule.nonInternalExists = function(id) {
  return NativeModule.exists(id) && !NativeModule.isInternal(id);
};

NativeModule.isInternal = function(id) {
  return id.startsWith('internal/');
};

上面的代码是去除各种杂七杂八的条件之后的一种情况，别的情况还请各位童鞋自行看 Node.js 源码。

也就是说我们在我们自己的代码里面是请求不到 Node.js 源码里面 lib/internal/*.js 这些文件的——因为它们被上面的这个条件分支给过滤了。（比如 require("internal/module") 在自己的代码里面是无法运行的）

注意： 不过有一个例外，那就是 require("internal/repl")。详情可以参考这个 Issue 和这段代码。

Module.prototype.load

解释完了上面的 NativeModule 之后，我们要就上面 Module._load 里面的下一步 module.load 也就是 Module.prototype.load 做解析了。

Module.prototype.load = function(filename) {
  // ...

  var extension = path.extname(filename) || '.js';
  if (!Module._extensions[extension]) extension = '.js';
  Module._extensions[extension](this, filename);
  this.loaded = true;
};

做了一系列操作之后得到了真·文件名，然后判断一下后缀。如果是 ".js" 的话执行 Module._extensions[".js"] 这个函数去编译代码，如果是 ".json" 则是 Module._extensions[".json"]。

这里我们略过 JSON 和 C++ Addon，直奔 Module._extensions[".js"]。

Module._extensions['.js'] = function(module, filename) {
  var content = fs.readFileSync(filename, 'utf8');
  module._compile(internalModule.stripBOM(content), filename);
};

它也很简单，就是奔着 _compile 去的。

Module.prototype._compile

先上代码。

Module.prototype._compile = function(content, filename) {
  var self = this;
  // remove shebang
  content = content.replace(shebangRe, '');

  function require(path) {
    return self.require(path);
  }

  require.resolve = function(request) {
    return Module._resolveFilename(request, self);
  };

  require.main = process.mainModule;

  // Enable support to add extra extension types
  require.extensions = Module._extensions;

  require.cache = Module._cache;

  var dirname = path.dirname(filename);

  // create wrapper function
  var wrapper = Module.wrap(content);

  var compiledWrapper = runInThisContext(wrapper,
                                      { filename: filename, lineOffset: -1 });

  // ...

  var args = [self.exports, require, self, filename, dirname];
  return compiledWrapper.apply(self.exports, args);
};

感觉流程上跟 NativeModule 的编译相似，不过这里是事先准备好要在载入的文件里面用的 require 函数，以及一些 require 的周边。

接下去就是用 Module.wrap 来包裹代码了，包裹完之后把得到的函数用参数 self.exports, require, self, filename, dirname 去执行一遍，就算是文件载入完毕了。

最后回到之前载入代码的那一刻，把载入完毕得到的 module.exports 再 return 出去就好了。

Module.wrap

这个就不用说了。

在 lib/module.js 的最顶端附近有这么几行代码。

Module.wrapper = NativeModule.wrapper;
Module.wrap = NativeModule.wrap;
Module._debug = util.debuglog('module');

一切豁然开朗了吧。

连 NativeModule 的代码都逃不开被之前说的闭包所包裹，那么你自己写的 JS 文件当然也会被 NativeModule.wrap 所包裹。

那么你在代码根作用域申明的函数实际上在运行时里面已经被一个闭包给包住了。

以前可能很多同学只知道是被闭包包住了，但是包的方法、流程今天算是解析了一遍了。

(function (exports, require, module, __filename, __dirname) {
var a = 2;
function foo(){  
    console.log(this.a);
}

foo();
});

这个 var a 怎么也不可能绑到 global 去啊。

Module.prototype.require

虽然我们上面讲得差不多了，可能很多童鞋也厌烦了。

不过该讲完的还是得讲完。

我们在我们自己文件中用的 require 在上一节里面有提到过，传到我们闭包里面的 require 实际上是长这样的：

function require(path) {
  return self.require(path);
}

所以实际上就是个 Module.prototype.require。

我们再看看这个函数。

Module.prototype.require = function(path) {
  assert(path, 'missing path');
  assert(typeof path === 'string', 'path must be a string');
  return Module._load(path, this);
};

一下子又绕回到了我们一开始的 Module._load。

所以基本上就差不多到这过了。

REPL vs 文件启动

最后我们再点一下，或者说回顾一下吧。

REPL 启动的时候 Node.js 是开了个 vm 直接让你跑，并没有把代码包在一个闭包里面，所以再根作用域下的变量会 Biu 一下贴到 global 中去。

而文件启动的时候，会做本文中说的一系列事情，然后就会把各文件都包到一个闭包去，所以变量就无法通过这种方式来贴到 global 去了。

不过这种二义性会在 "use strict"; 中戛然而止。

珍爱生命，use strict。

小结

本文可能很多童鞋看完后悔觉得很坑——JS 为什么有那么多二义性那么坑呢。

其实不然，主要是可能很多人对 Node.js 执行的机制不是很了解。

本文从小龙抛出的一个简单问题进入，然后浅入浅出 Node.js 的一些执行机制什么的，希望对大家还是有点帮助，更何况我在意的不是问题本身，而是分析的这个过程。

番外

以下均为臆想。

小龙： 喂喂喂，我就问一个简单的小破题目，你至于嘛！

Node.js 启动方式：一道关于全局变量的题目引发的思考

xadillax — Thu, 26 Nov 2015 22:44:52 +0800

原文链接：https://xcoder.in/2015/11/26/a-js-problem-about-global/

本人是作者。

原题

题目是这样的。

var a = 2;
function foo(){
    console.log(this.a);
}

foo();

上题由我们亲爱的小龙童鞋发现并在我们的 901 群里提问的。

经过

然后有下面的小对话。

小龙：你们猜这个输出什么？

弍纾：2

力叔：2 啊

死月·絲卡蕾特：2

力叔：有什么问题么？

小龙：输出 undefind。

死月·絲卡蕾特：你确定？

小龙：是不是我电脑坏了

力叔：你确定？

弍纾：你确定？

小龙：为什么我 node 文件名跑出来的是 undefined？

郑昱：-.- 一样阿。undefined

以上就是刚见到这个题目的时候群里的一个小讨论。

分析

后来我就觉得奇怪，既然小龙验证过了，说明他也不是随地大小便，无的放矢什么的。

于是我也验证了一下，不过由于偷懒，没有跟他们一样写在文件里面，而是直接 node 开了个 REPL 来输入上述代码。

结果是 2！

结果是 2！

结果是 2！

于是这就出现了一个很奇怪的问题。

尼玛为毛我是 2 他们俩是 undefined 啊！

不过马上我就反应过来了——我们几个的环境不同，他们是 $ node foo.js 而我是直接 node 开了个 REPL，所以有一定的区别。

而力叔本身就是前端大神，我估计是以 Chrome 的调试工具下为基础出的答案。

REPL vs 文件执行

其实上述的问题，需要解释的问题大概就是 a 到底挂在哪了。

因为细细一想，在 function 当中，this 指向的目标是 global 或者 window。

还无法理解上面这句话的童鞋需要先补一下基础。

那么最终需要解释的就是 a 到底有没有挂在全局变量上面。

这么一想就有点细思恐极的味道了——如果在 node 线上运行环境里面的源代码文件里面随便 var 一个变量就挂到了全局变量里面那是有多恐怖！

于是就有些释然了。

但究竟是什么原因导致 REPL 和文件执行方式不一样的呢？

全局对象的属性

首先是弍纾找出了阮老师 ES6 系列文章中的全局对象属性一节。

全局对象是最顶层的对象，在浏览器环境指的是 window 象，在 Node.js 指的是 global 对象。ES5 之中，全局对象的属性与全局变量是等价的。
window.a = 1;
a // 1

a = 2;
window.a // 2
上面代码中，全局对象的属性赋值与全局变量的赋值，是同一件事。（对于 Node 来说，这一条只对 REPL 环境适用，模块环境之中，全局变量必须显式声明成 global 对象的属性。）

有了阮老师的文章验证了这个猜想，我可以放心大胆继续看下去了。

repl.js

知道了上文的内容之后，感觉首要查看的就是 Node.js 源码中的 repl.js 了。

先是结合了一下自己以前用自定义 REPL 的情况，一般的步骤先是获取 REPL 的上下文，然后在上下文里面贴上各种自己需要的东西。

var r = relp.start(" ➜ ");
var c = r.context;

// 在 c 里面贴上各种上下文
c.foo = bar;
// ...

关于自定义 REPL 的一些使用方式可以参考下老雷写的《Node.js 定制 REPL 的妙用》。

有了之前写 REPL 的经验，大致明白了 REPL 里面有个上下文的东西，那么在 repl.js 里面我们也找到了类似的代码。

REPLServer.prototype.createContext = function() {
  var context;
  if (this.useGlobal) {
    context = global;
  } else {
    context = vm.createContext();
    for (var i in global) context[i] = global[i];
    context.console = new Console(this.outputStream);
    context.global = context;
    context.global.global = context;
  }

  context.module = module;
  context.require = require;

  this.lines = [];
  this.lines.level = [];

  // make built-in modules available directly
  // (loaded lazily)
  exports._builtinLibs.forEach(function(name) {
    Object.defineProperty(context, name, {
      get: function() {
        var lib = require(name);
        context._ = context[name] = lib;
        return lib;
      },
      // allow the creation of other globals with this name
      set: function(val) {
        delete context[name];
        context[name] = val;
      },
      configurable: true
    });
  });

  return context;
};

看到了关键字 vm。我们暂时先不管 vm，光从上面的代码可以看出，context 要么等于 global，要么就是把 global 上面的所有东西都粘过来。

然后顺带着把必须的两个不在 global 里的两个东西 require 和 module 给弄过来。

下面的东西就不需要那么关心了。

VM

接下去我们来讲讲 vm。

VM 是 node 中的一个内置模块，可以在文档中看到说明和使用方法。

大致就是将代码运行在一个沙箱之内，并且事先赋予其一些 global 变量。

而真正起到上述 var 和 global 区别的就是这个 vm 了。

vm 之中在根作用域（也就是最外层作用域）中使用 var 应该是跟在浏览器中一样，会把变量粘到 global（浏览器中是 window）中去。

我们可以试试这样的代码：

var vm = require('vm');
var localVar = 'initial value';

vm.runInThisContext('var localVar = "vm";');
console.log('localVar: ', localVar);
console.log('global.localVar: ', global.localVar);

其输出结果是：

localVar: initial value
global.localVar: vm

如文档中所说，vm 的一系列函数中跑脚本都无法对当前的局部变量进行访问。各函数能访问自己的 global，而 runInThisContext 的 global 与当前上下文的 global 是一样的，所以能访问当前的全局变量。

所以出现上述结果也是理所当然的了。

所以在 vm 中跑我们一开始抛出的问题，答案自然就是 2 了。

var vm = require("vm");
var sandbox = {
    console: console
};

vm.createContext(sandbox);
vm.runInContext("var a = 2;function foo(){console.log(this.a);}foo();", sandbox);

Node REPL 启动的沙箱

最后我们再只需要验证一件事就能真相大白了。

平时我们自定义一个 repl.js 然后执行 $ node repl.js 的话是会启动一个 REPL，而这个 REPL 会去调 vm，所以会出现 2 的答案；或者我们自己在代码里面写一个 vm 然后跑之前的代码，也是理所当然出现 2。

那么我们就输入 $ node 来进入的 REPL 跟我们之前讲的 REPL 是不是同一个东西呢？

如果是的话，一切就释然了。

首先我们进入到 Node 的入口文件——C++ 的 int main()。

它在 Node.js 源码 src/node_main.cc 之中。

int main(int argc, char *argv[]) {
  setvbuf(stderr, NULL, _IOLBF, 1024);
  return node::Start(argc, argv);
}

就在主函数中执行了 node::Start。而这个 node::Start 又存在 src/node.cc 里面。

然后在 node::Start 里面又调用 StartNodeInstance，在这里面是 LoadEnvironment 函数。

最后在 LoadEnvironment 中看到了几句关键的语句：

Local<String> script_name = FIXED_ONE_BYTE_STRING(env->isolate(), "node.js");
Local<Value> f_value = ExecuteString(env, MainSource(env), script_name);

//...

Local<Function> f = Local<Function>::Cast(f_value);

//...
Local<Object> global = env->context()->Global();

//...
Local<Value> arg = env->process_object();
f->Call(global, 1, &arg);

还有这么一段关键的注释。

// Now we call 'f' with the 'process' variable that we've built up with
// all our bindings. Inside node.js we'll take care of assigning things to
// their places.

// We start the process this way in order to be more modular. Developers
// who do not like how 'src/node.js' setups the module system but do like
// Node's I/O bindings may want to replace 'f' with their own function.

也就是说，启动 node 的时候，在做了一些准备之后是开始载入执行 src 文件夹下面的 node.js 文件。

在 92 行附近有针对 $ node foo.js 和 $ node 的判断启动不同的逻辑。

  // ...
} else if (process.argv[1]) {
  // make process.argv[1] into a full path
  var path = NativeModule.require('path');
  process.argv[1] = path.resolve(process.argv[1]);

  var Module = NativeModule.require('module');

  // ...

  startup.preloadModules();
  if (global.v8debug &&
      process.execArgv.some(function(arg) {
        return arg.match(/^--debug-brk(=[0-9]*)?$/);
      })) {
    var debugTimeout = +process.env.NODE_DEBUG_TIMEOUT || 50;
    setTimeout(Module.runMain, debugTimeout);
  } else {
    // Main entry point into most programs:
    Module.runMain();
  }
} else {
  var Module = NativeModule.require('module');

  if (process._forceRepl || NativeModule.require('tty').isatty(0)) {
    // REPL
    var cliRepl = Module.requireRepl();
    cliRepl.createInternalRepl(process.env, function(err, repl) {
      // ...
    });
  } else {
    // ...
  }
}

在上述节选代码的第一个 else if 中，就是对 $ node foo.js 这种情况进行处理了，再做完各种初始化之后，使用 Module.runMain(); 来运行入口代码。

第二个 else if 里面就是 $ node 这种情况了。

我们在终端中打开 $ node 的时候，TTY 通常是关连着的，所以 require('tty').isatty(0) 为 true，也就是说会进到条件分支并且执行里面的 cliRepl 相关代码。

我们进入到 lib/module.js 看看这个 Module.requireRepl 是什么东西。

Module.requireRepl = function() {
  return Module._load('internal/repl', '.');
}

所以我们还是得转入 lib/internal/repl.js 来一探究竟。

上面在 node.js 里面我们看到它执行了这个 cliRepl 的 createInternalRepl 函数，它的实现大概是这样的：

function createRepl(env, opts, cb) {
  // ...

  opts = opts || {
    ignoreUndefined: false,
    terminal: process.stdout.isTTY,
    useGlobal: true
  };

  // ...

  opts.replMode = {
    'strict': REPL.REPL_MODE_STRICT,
    'sloppy': REPL.REPL_MODE_SLOPPY,
    'magic': REPL.REPL_MODE_MAGIC
  }[String(env.NODE_REPL_MODE).toLowerCase().trim()];

  // ...

  const repl = REPL.start(opts);

  // ...
}

转头一看这个 lib/internal/repl.js 顶端的模块引入，赫然看到一句话：

const REPL = require('repl');

真相大白。

小结

最后再梳理一遍。

在于 Node.js 的 vm 里面，顶级作用域下的 var 会把变量贴到 global 下面。而 REPL 使用了 vm。然后 $ node 进入的一个模式就是一个特定参数下面启动的一个 REPL。

所以我们一开始提出的问题里面在 $ node foo.js 模式下执行是 undefined，因为不在全局变量上，但是启用 $ node 这种 REPL 模式的时候得到的结果是 2。

番外

小龙：我用 node test.js 跑出来是 a: undefined；那我应该怎么修改“环境”，来让他跑出：a: 2 呢？

于是有了上面写的那段代码。

var vm = require("vm");
var sandbox = {
    console: console
};

vm.createContext(sandbox);
vm.runInContext("var a = 2;function foo(){console.log(this.a);}foo();", sandbox);

我为什么要使用哈希

xadillax — Fri, 16 Oct 2015 15:06:03 +0800

原文（我是作者）：https://xcoder.in/2015/10/16/why-i-use-hash/

什么是哈希（Hash）

本来这里不应该出现这一节的，因为实际上大家应该都知道什么是哈希。不过有时候为了文章的完整性，我这里就稍微教条性地说明一下吧。ヽ (́◕◞౪◟◕‵) ﾉ

散列（英语：Hashing），通常音译作哈希，是电脑科学中一种对资料的处理方法，通过某种特定的函数、算法将要检索的项与用来检索的索引关联起来，生成一种便于搜索的数据结构。也译为散列。

-- From 散列, Wikipedia

实际上通俗的说法就是把某种状态或者资料给映射到某个值上的操作。

本酱大概就解释到这里了，至于哈希的进一步认知包括冲突的产生和解决等，如果米娜桑不了解的话还请自行学习咕。థ౪థ

引子——子树问题

这个不是我在实践中遇到的问题，而是当年去某不作恶的大厂面试时候遇到的问题，觉得比较经典，所以就拿出来了。ᕙ༼ຈل͜ຈ༽ᕗ

问题描述

给定一棵二叉树，假设每个节点的数据只有左右子节点，自身并不存储数据。请找出两两完全相等的子树们。

有兴趣的童鞋可以自己先思考一下。₍₍◝(･'ω'･)◟⁾⁾

我的做法

实际上我也不知道自己的做法是不是正确做法，不过既然通过了那一轮面试，想来也不会偏差到哪去喵。ლ（╹ε╹ლ）

做法大概如下：

后序遍历一遍整棵树。
对于遍历到每一个节点，都获取到左右子节点的哈希值，然后将其拼接重新计算出自身的哈希值，并返回给父亲节点。

至于哈希值怎么算，方法有很多。最简单的就是设叶子节点一个哈希值，比如是 md5("")，然后每次非叶子节点的哈希值就用 md5(LEFT_HASH + RIGHT_HASH) 来计算。大家也可以自己随便想一种方法来做就好了。

很多人可能不解了，明明是用 md5，这篇文章是讲哈希，有毛线关系。(╯°O°)╯┻━┻

实际上 md5 就是一种哈希算法，而且是非常经典的哈希算法。

典型的哈希算法包括 MD2、MD4、MD5 和 SHA-1 等。当然不局限于这些，对于数字来说，取模也算是哈希算法，对于字符串状态转整数状态哈希来说还有诸如 BKDR、ELF 等等。

如果大家想多了解一些字符串转数字哈希的算法，可以参考一下 BYVoid 的这篇《各种字符串 Hash 函数比较》，或者想直接在 Node.js 里面使用的小伙伴们可以光顾下这个包——bling-hashes。

初步的轮廓已经明晰了，说白了就是将每个节点的哈希全算出来，如果是父亲节点就用子节点的哈希拼接起来再哈希一遍。σ`∀´)σ

把这些哈希算出来之后放在一个散列表里面待查。如果一个算出来的哈希跟之前已有的哈希值相等，那么就是说这个节点跟那个节点为根节点的子树有可能完全相等。

注意：有可能完全相等。

注意：只是有可能完全相等。

注意：重要的事情说三遍，只是有可能完全相等。

哈希是存在着一定的冲突概率的，所以说两个相等的哈希所检索到的源不一定一样，所以我们根据这些计算到的哈希建立哈希表，然后把表中同哈希值的子树再两两同时遍历一遍以检验是否相等。

同时递归，取两个子树的根节点。
后序遍历，看看每个节点是不是都一样存在（或者不存在）左子节点以及存在（或者不存在）右子节点。
循环往复一直到两两遍历完整棵树得到验证结果。如果半路有一个节点的左右子节点状态不一样就可以直接跳出递归返回 false。

至此为止，我们可以看出大概是两大步——计算各子树的哈希值和验证各同哈希子树的相等性。不过稍微变通一下，我们就可以在计算出哈希值的时候就去跟以前的对比了。

剪枝

实际上上面的做法还有一个优化的方案，不过跟哈希相关性已经基本上很小了。不过还是跟解决冲突有一丢丢的关系的，没兴趣的童鞋也可以直接跳过了。(๑•́ ₃ •̀๑)

由于子树哈希值是存在一定的冲突概率的，所以两个同哈希的子树不一定相同。那么我们如果能一眼看出这样的两棵子树是不相等的，就可以省略验证这一个递归的步骤了。

这里有一种最显而易见的情况我们是可以忽略省略步骤的，那就是深度。

如果两棵子树两两完全相等，那么说明这俩基佬的深度（或者说高度）是一样的，如果连深度都不一样了还如何愉快搞基——所以说如果有两个相等哈希值的子树的深度不一样的话可以直接略过验证步骤了。

那么就可以这么做：

设所有叶子节点的深度为 0，然后每往上一层加一。
遇到左右子节点深度不一样的父节点时，取深度大的那个子节点深度去加一。

以上步骤在遍历计算哈希的时候顺便也做了，这样就多了一个验证标记了。

所以差不多就这样了，浅尝辄止。( ˘･з･)

引子的小结

就上述的场景来说，哈希非常好地将一个非常复杂的状态转化成一个可以检索的状态。本来毫无头绪的一个问题使用了哈希之后就完全变成了一个检索加验证的过程了。

报告图问题

这个问题就是我在大搜车中确实遇到的场景了。大家也不需要知道什么是报告图，就当它是一个代号了。

问题描述

要做的事情大概就是说给定一个报告，我们根据报告的各个细节选定各种图层然后揉成一团叠加在一起形成最后一个结果图。

其实本来就有个系统在做这件事情的——每来一个报告就生成一张图，然后存储好之后给前端使用。

我做的事情是将逻辑迁移到另一套计算密集型任务集中处理系统中去。(´艸`)

其实生成这样一张图片的逻辑是 CPU 计算密集型的逻辑，所以比较耗费资源和时间的，那么我们就能在这上面做点手脚优化一下。

优化方法

首先我们要知道的是，有哪些图层是固定的，所以其实这算半个排列组合的问题了。

不过我们也知道排列组合的增长性非常快，更何况我这里有约 100 个图层选择，所以可能性非常多，一下子全生成好不可能。

那么就可以用哈希和懒惰的思想来实现了。(ˇωˇ人)

虽然报告是有无限种可能的，但是把报告转成图层数据之后，拥有完全一样的图层数据的报告就可以用同一张图片了，这样就可以大大节省空间和时间了。

其实大概的步骤非常简单：

把图层数据计算成哈希。（比如把所有图层文件路径用某种符号拼接，再用 md5 计算一下）
去数据库查找这个哈希主键存不存在。
- 如果存在则验证源图层数据域当前图层数据是否吻合。
  - 如果不吻合则按某种算法重新计算哈希，继续步骤 2。
  - 如果吻合则可以直接拿着这个数据返回了，跳出计算。
- 如果不存在就说明当前数据库还没有这个图层情况的报告图生成，那么就执行生成报告图逻辑。
报告图生成之后，将其存入数据库中。
- 计算出这个报告图图层数据的哈希，去数据库查存不存在。
  - 如果不存在则说明哈希不冲突，能用，直接用这个哈希存进去。
  - 如果存在则说明哈希冲突，那么按某种算法重新计算哈希，继续上面的步骤直到不冲突为止。

如果大家想知道“按某种算法重新生成哈希”里面“某种算法”的话可以看看下面的瞎狗眼的说明了。(ﾉ◕ヮ◕) ﾉ*:･ﾟ✧

其实很简单，把图层数据的这个字符串加某个固定字符当小尾巴，如果哈希还是冲突则继续加这个小尾巴，直到计算出来的哈希不冲突为止。

比如我就用了这字符当小尾巴——🀣（麻将牌中的蘭）。(♛‿♛)

报告图的小结

在这种场景中，我把哈希拿来作检索某种报告图是否已经生成的用途。如果没有生成则生成一张，如果已经生成则直接拿已有的报告图去用。

至少比原来的来一张报告就生成一张图片来得快，并且省空间——相当于作冗余处理了。

事实上在很多的网盘系统中也有作冗余处理的。你以为你有多少多少 T 的空间，实际上相同的文件最终在网盘系统里面只存一份（不过排除备份的那些），而我相信做这些冗余判断的原理就是哈希了，SHA-1 也好 MD5 也好，反正就是这样。

上面网盘的冗余处理原理也只是我的猜测，我没在那些厂子里面工作过所以不能说就是就是这样子的。欢迎指正。｡ﾟヽ (ﾟ´Д`) ﾉﾟ｡

唯一主键问题

这是我来这边工作后的另一个小插曲了，遇到一个主键生成的小需求。

问题描述

有一个数据要插入到数据库，所以要给它生成一个主键，但是需求比较奇葩，可能是历史遗留问题吧。(눈‸눈)

非自增。
是一个全是数字的字符串。
不同类型的这个表的数据用不同的前缀，比如 10、11、12 等。
位数在十几位左右（不过在我这里就固定了）。

解决方案

如果是 前缀 + 随机数 的冲突概率会比较大的，所以还是用哈希来搞。

非常简单。首先前缀是固定的，我们就不管了，然后我根据这次进来的数据拼接成字符串（数据不会完全一样的），加上一点随机盐，然后用字符串哈希计算一遍，加上前导零，加上当前时间戳的后几位拼接起来，最后接上前缀就好了。

这个 generate 函数看起来就像这样子：

var bling = require("bling-hashes");
function generate(type, bodyParamStr) {
    var basePrefix;
    switch(type) {
        case 'foo': basePrefix = '10'; break;
        case 'bar': basePrefix = '11'; break;
        default: base_prefix = '00';
    }

    var date = moment();
    var hash = bling.bkdr(bodyParamStr + date.valueOf()).pad(10);
    hash = date.millisecond().pad(3) + hash;

    return basePrefix + hash;
};

注意：这里的 bling 就是上面提到过的那个 bling-hashes，采用了 BKDR 算法来计算哈希。以及 Number.prototype.pad 函数是我邪恶得使用了 SugarJs 里面的函数，就是加上前导零的意思。如果受“千万不要修改原型链”影响较深地童鞋别学我哦。bodyParamStr 是前端传过来的 Raw Form Data，它看起来像 "data1=1&data2=2&..."。

最后得到的这个字符串是我们所要的主键了。｡:.ﾟヽ (*´∀`) ﾉﾟ.:｡

不过要注意的是，这个主键仍然又冲突的可能性，所以一旦冲突了（无论是自己检测到的还是插入数据库的时候疼了）就需要再生产一遍。就目前来说再生成的时候毫秒时间戳后三位会不一样，所以问题不大，允许存在的误差——毕竟不是那种分分钟集千万条的数据，肯定在 int 范围内。如果到时候真出问题了再改进。

主键的小结

这里的哈希是用在生成基本上没有碰撞的主键身上，感觉效果也是非常不错的——前提是你也有这种奇葩需求。

真·小结

本文大致介绍了哈希的几种用途，有可能是大家熟知的用途，也有可能是巧用，总之就是说了为什么我要用哈希。

在编程中，无论是实际用途还是自己玩玩的题目，多动动脑子就会出来一些“奇技淫巧”。哈希也好，别的东西也罢，反正都是为了解决问题的——千万别因为实际开发中通常性的“并没有什么卵用”而去忽视它们，虽然哈希已经是够常用的了。(๑•ૅω•´๑)