Node-CheatSheet

本文节选自 Node.js CheatSheet | Node.js 语法基础、框架使用与实践技巧，也可以阅读 JavaScript CheatSheet 或者现代 Web 全栈开发与工程架构了解更多 JavaScript/Node.js 的实际应用。

Node.js CheatSheet | Node.js 语法基础、框架使用与实践技巧

Node.js 的包管理，或者说依赖管理使用了语义化版本的规范，版本的发布分为四个不同的层次：使用 1.0.0 表示新发布，使用 1.0.1 这样第三位数字表示错误修复等小版本更新；使用 1.1.0 这样的第二位数字表示新特性等兼容性更新；使用 2.0.0 这样第一位数字表示大版本的更新。相对应地，在 package.json 声明依赖版本时，我们也可以指定不同的兼容范围：

Patch releases：1.0 或者 1.0.x 或者 ~1.0.4
Minor releases: 1 或者 1.x 或者 ^1.0.4
Major releases: * 或者 x

基础语法

开发实践

调试

在 VSCode 中，我们也能够方便地进行断点调试，首先我们需要在 package.json 中添加 debug 指令：

  "scripts": {
    "debug": "node --nolazy --inspect-brk=9229 myProgram.js"
  },

然后在 ./vscode/launch.json 中添加启动配置项：

{
  "name": "Launch via NPM",
  "type": "node",
  "request": "launch",
  "cwd": "${workspaceFolder}",
  "runtimeExecutable": "npm",
  "runtimeArgs": ["run-script", "debug"],
  "port": 9229
}

如果我们希望包含较多的环境变量，还可以指定环境变量：

   //...
   "envFile": "${workspaceFolder}/.env",
   "env": { "USER": "john doe" }
   //...

或者指定加载外部的环境变量文件：

USER=doe
PASSWORD=abc123

IO

异步循环

Node 的异步语法比浏览器更复杂，因为它可以跟内核对话，不得不搞了一个专门的库 libuv 做这件事。这个库负责各种回调函数的执行时间，毕竟异步任务最后还是要回到主线程，一个个排队执行。

事件循环会无限次地执行，一轮又一轮。只有异步任务的回调函数队列清空了，才会停止执行。

每一轮的事件循环，分成六个阶段。这些阶段会依次执行。

timers IO callbacks idle, prepare poll check close callbacks

每个阶段都有一个先进先出的回调函数队列。只有一个阶段的回调函数队列清空了，该执行的回调函数都执行了，事件循环才会进入下一个阶段。

下面简单介绍一下每个阶段的含义，详细介绍可以看官方文档，也可以参考 libuv 的源码解读。

（1）timers

这个是定时器阶段，处理 setTimeout()和 setInterval()的回调函数。进入这个阶段后，主线程会检查一下当前时间，是否满足定时器的条件。如果满足就执行回调函数，否则就离开这个阶段。

（2）IO callbacks

除了以下操作的回调函数，其他的回调函数都在这个阶段执行。

setTimeout()和 setInterval()的回调函数 setImmediate()的回调函数用于关闭请求的回调函数，比如 socket.on(‘close’, …)

（3）idle, prepare

该阶段只供 libuv 内部调用，这里可以忽略。

（4）Poll

这个阶段是轮询时间，用于等待还未返回的 IO 事件，比如服务器的回应、用户移动鼠标等等。

这个阶段的时间会比较长。如果没有其他异步任务要处理（比如到期的定时器），会一直停留在这个阶段，等待 IO 请求返回结果。

（5）check

该阶段执行 setImmediate()的回调函数。

（6）close callbacks

该阶段执行关闭请求的回调函数，比如 socket.on(‘close’, …)。

const fs = require("fs");

const timeoutScheduled = Date.now();

// 异步任务一：100ms 后执行的定时器
setTimeout(() => {
  const delay = Date.now() - timeoutScheduled;
  console.log(`${delay}ms`);
}, 100);

// 异步任务二：至少需要 200ms 的文件读取
fs.readFile("test.js", () => {
  const startCallback = Date.now();
  while (Date.now() - startCallback < 200) {
    // 什么也不做
  }
});

上面代码有两个异步任务，一个是 100ms 后执行的定时器，一个是至少需要 200ms 的文件读取。请问运行结果是什么？

脚本进入第一轮事件循环以后，没有到期的定时器，也没有已经可以执行的 IO 回调函数，所以会进入 Poll 阶段，等待内核返回文件读取的结果。由于读取小文件一般不会超过 100ms，所以在定时器到期之前，Poll 阶段就会得到结果，因此就会继续往下执行。

第二轮事件循环，依然没有到期的定时器，但是已经有了可以执行的 IO 回调函数，所以会进入 IO callbacks 阶段，执行 fs.readFile 的回调函数。这个回调函数需要 200ms，也就是说，在它执行到一半的时候，100ms 的定时器就会到期。但是，必须等到这个回调函数执行完，才会离开这个阶段。

第三轮事件循环，已经有了到期的定时器，所以会在 timers 阶段执行定时器。最后输出结果大概是 200 多毫秒。

八、setTimeout 和 setImmediate

由于 setTimeout 在 timers 阶段执行，而 setImmediate 在 check 阶段执行。所以，setTimeout 会早于 setImmediate 完成。

setTimeout(() => console.log(1)); setImmediate(() => console.log(2));

上面代码应该先输出 1，再输出 2，但是实际执行的时候，结果却是不确定，有时还会先输出 2，再输出 1。

这是因为 setTimeout 的第二个参数默认为 0。但是实际上，Node 做不到 0 毫秒，最少也需要 1 毫秒，根据官方文档，第二个参数的取值范围在 1 毫秒到 2147483647 毫秒之间。也就是说，setTimeout(f, 0)等同于 setTimeout(f, 1)。

实际执行的时候，进入事件循环以后，有可能到了 1 毫秒，也可能还没到 1 毫秒，取决于系统当时的状况。如果没到 1 毫秒，那么 timers 阶段就会跳过，进入 check 阶段，先执行 setImmediate 的回调函数。

但是，下面的代码一定是先输出 2，再输出 1。

const fs = require("fs");

fs.readFile("test.js", () => {
  setTimeout(() => console.log(1));
  setImmediate(() => console.log(2));
});

上面代码会先进入 IO callbacks 阶段，然后是 check 阶段，最后才是 timers 阶段。因此，setImmediate 才会早于 setTimeout 执行。

Stream

Stream 是 Node.js 中的基础概念，类似于 EventEmitter，专注于 IO 管道中事件驱动的数据处理方式；类比于数组或者映射，Stream 也是数据的集合，只不过其代表了不一定正在内存中的数据。。Node.js 的 Stream 分为以下类型：

Readable Stream: 可读流，数据的产生者，譬如 process.stdin
Writable Stream: 可写流，数据的消费者，譬如 process.stdout 或者 process.stderr
Duplex Stream: 双向流，即可读也可写
Transform Stream: 转化流，数据的转化者

Stream 本身提供了一套接口规范，很多 Node.js 中的内建模块都遵循了该规范，譬如著名的 fs 模块，即是使用 Stream 接口来进行文件读写；同样的，每个 HTTP 请求是可读流，而 HTTP 响应则是可写流。

文件读写

__dirname 指向当前文件所在目录。我们可以使用 join 与 resolve 两个辅助函数来进行路径构造，区别在于 join 只是进行简单连接，而 resolve 会进行根路径重置：

path.join('/a', '/b'); // Outputs '/a/b'
path.resolve('/a', '/b'); // Outputs '/b'

// 获取文件状态
fs.statSync(path[, options])
stats.isBlockDevice()
stats.isDirectory()
stats.isFIFO()
stats.isFile()
stats.isSocket()

// 同步读取
const contents = fs.readFileSync("DATA", "utf8");

// 异步读取
const { promisify } = require("util");
const fs = require("fs");
const readFileAsync = promisify(fs.readFile); // (A)
const filePath = process.argv[2];

readFileAsync(filePath, { encoding: "utf8" })
  .then((text) => {
    console.log("CONTENT:", text);
  })
  .catch((err) => {
    console.log("ERROR:", err);
  });

// fs-extra

HTTP Server

WebSocket

Production | 部署

我们也可以将 Node.js 应用部署为 Systemd 服务，首先创建 /etc/systemd/system/node-sample.service 文件：

[Unit]
Description=node-sample - making your environment variables rad
Documentation=https://example.com
After=network.target

[Service]
ExecStart=[node binary] /home/srv-node-sample/[main file]
Restart=always
StandardOutput=syslog
StandardError=syslog
SyslogIdentifier=node-sample
User=srv-node-sample
Group=srv-node-sample
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

然后使用 systemctl 命令启动与控制服务：

$ systemctl enable node-sample
$ systemctl start node-sample

# 查看应用状态
$ systemctl status node-sample

# 查看日志
$ journalctl -u node-sample

Cluster | 集群模式

const cluster = require("cluster");
const http = require("http");
const numCPUs = require("os").cpus().length;

if (cluster.isMaster) {
  console.log(`Master ${process.pid} is running`);

  // Fork workers.
  for (let i = 0; i < numCPUs; i++) {
    cluster.fork();
  }

  cluster.on("exit", (worker, code, signal) => {
    console.log(`worker ${worker.process.pid} died`);
  });
} else {
  // Workers can share any TCP connection
  // In this case it is an HTTP server
  http
    .createServer((req, res) => {
      res.writeHead(200);
      res.end("hello world\n");
    })
    .listen(8000);

  console.log(`Worker ${process.pid} started`);
}

系统功能

数据存储

Knex

当我们使用 leftJoin 查询单条数据时，可以通过 nestTables 选项将扁平结构转化为嵌套结构：

knex
  .from('users')
  .leftJoin('user_address', 'users.id', '=', 'user_address.user_id')
  .options({ nestTables: true })
  .then(results => {
    // do something with results ...
  });

// result 结果如下
{
  users: {
    id: 3,
    username: 'somename',
    email:
  },
  user_address: {
    id: 1, // or whatever format your id is in
    user_id: 3,
    street: 'somestreet',
    postcode: 'somepostcode'
  }
}

当我们使用 innerJoin 查询多个关联项时，可以使用 knexnest:

const knexnest = require("knexnest");

const sql = knex
  .select(
    "c.id    AS _id",
    "c.title AS _title",
    "t.id    AS _teacher_id",
    "t.name  AS _teacher_name",
    "l.id    AS _lesson__id",
    "l.title AS _lesson__title"
  )
  .from("course AS c")
  .innerJoin("teacher AS t", "t.id", "c.teacher_id")
  .innerJoin("course_lesson AS cl", "cl.course_id", "c.id")
  .innerJoin("lesson AS l", "l.id", "cl.lesson_id");
knexnest(sql).then(function (data) {
  result = data;
});
/* result should be like:
[
	{id: '1', title: 'Tabular to Objects', teacher: {id: '1', name: 'David'}, lesson: [
		{id: '1', title: 'Defintions'},
		{id: '2', title: 'Table Data'},
		{id: '3', title: 'Objects'}
	]},
]
*/

Kenx 同样支持子查询，我们可以将某个查询语句当做源表或者计算列处理：

// 源表
const subQuery = this.app.knex
  .select("asset_id as asset_id_1")
  .count("_id as component_num")
  .from("asset_component")
  .groupBy("asset_id")
  .as("ac");

const assets = await this.app
  .knex("asset")
  .select("*")
  .leftJoin(subQuery, "asset.asset_id", "ac.asset_id_1")
  .orderBy("updated_at", "desc");

// 计算列
const components = await knexCamel("component").select(
  "*",
  knexCamel.raw(
    "(SELECT count(*) from vuln where vuln.c_id = component.c_id) as vuln_count"
  )
);

在我们进行插入操作时，常常需要在存在时更新；在 MySQL 数据库中，我们可以自行封装如下函数：

function upsert(table, data, updateData?) {
  if (!updateData) {
    updateData = data;
  }

  const insert = this.knex(table).insert(data).toString();

  const updateSql = this.knex(table)
    .update(updateData)
    .toString()
    .replace(/^update .* set /i, "");

  return this.knex.raw(insert + " on duplicate key update " + updateSql);
}

Bookshelf 则是基于 Knex 的 ORM 框架，其能够自动地从数据库中抓取表结构信息，并且支持事务、多态以及 One-to-One, One-to-Many, Many-to-Mant 等多种关系映射。

const knex = require("knex")({
  client: "mysql",
  connection: process.env.MYSQL_DATABASE_CONNECTION,
});
const bookshelf = require("bookshelf")(knex);

const User = bookshelf.Model.extend({
  tableName: "users",
  posts: function () {
    return this.hasMany(Posts);
  },
});

const Posts = bookshelf.Model.extend({
  tableName: "messages",
  tags: function () {
    return this.belongsToMany(Tag);
  },
});

const Tag = bookshelf.Model.extend({
  tableName: "tags",
});

User.where("id", 1)
  .fetch({ withRelated: ["posts.tags"] })
  .then(function (user) {
    console.log(user.related("posts").toJSON());
  })
  .catch(function (err) {
    console.error(err);
  });

日志

const env = process.env.NODE_ENV || "development";
const logDir = "log";

// Create the log directory if it does not exist
if (!fs.existsSync(logDir)) {
  fs.mkdirSync(logDir);
}

const filename = path.join(logDir, "results.log");

const logger = createLogger({
  // change level if in dev environment versus production
  level: env === "production" ? "info" : "debug",
  format: format.combine(
    format.label({ label: path.basename(module.parent.filename) }),
    format.timestamp({ format: "YYYY-MM-DD HH:mm:ss" })
  ),
  transports: [
    new transports.Console({
      format: format.combine(
        format.colorize(),
        format.printf(
          (info) =>
            `${info.timestamp} ${info.level} [${info.label}]: ${info.message}`
        )
      ),
    }),
    new transports.File({
      filename,
      format: format.combine(
        format.printf(
          (info) =>
            `${info.timestamp} ${info.level} [${info.label}]: ${info.message}`
        )
      ),
    }),
  ],
});

DevOps

Deploy

Pandora.js 阿里巴巴产出的一个 Node.js 应用监控管理器，可以让您对自己的 Node.js 应用了若指掌，我们的目标就是让应用可管理、可度量、可追踪。

$ npm i pandora pandora-dashboard -g

# 输出 Pandora.js dashboard 的目录，然后 Pandora.js 会把它当成一个普通的项目来启动
$ pandora start --name dashboard `pandora-dashboard-dir`

# 主入口为 server.js，在项目根目录运行下面的命令来初始化
$ pandora init server.js
? Which type do you like to generate ? (Use arrow keys)
  fork  # Fork 简单拉起 server.js
❯ cluster  # Cluster 则用 Node.js 的 Cluster 模块启动 server.js（即 Master / Worker 模型）

$ pandora start
Starting rest-crud at /xx/xxx/rest-crud
rest-crud started successfully! Run command [ pandora log rest-crud ] to get more information

如果需要在 Egg.js 中使用，则添加自定义的 server.js 入口文件：

const egg = require('egg');

const workers = Number(process.argv[2] || require('os').cpus().length);
egg.startCluster({
  workers,
  baseDir: __dirname,
});

Web 框架

基础框架除了应用最广泛的主流 Web 框架 Koa 外，Fastify 也是一直劲敌，作者 Matteo Collina 是 Node.js 核心开发，Stream 掌门，性能优化专家。Fastify 基于 Schema 优化，对性能提升极其明显。当然，最值得说明的，我认为是企业级 Web 开发，这里简单介绍 3 个知名框架。

b1）Egg.js

阿里开源的企业级 Node.js 框架 Egg 发布 2.0，基于 Koa 2.x，异步解决方案直接基于 Async Function。框架层优化不含 Node 8 带来的提升外，带来 30% 左右的性能提升。

Egg 采用的是微内核 + 插件 + 上层框架模式，对于定制，生态，快速开发有明显提升，另外值得关注的是稳定性和安全上，也是极为出色的。

b2）Nest

Nest 是基于 TypeScript 和 Express 的企业级 Web 框架。

很多人开玩笑说，Nest 是最像 Java 开发方式的，确实，Nest 采用 TypeScript 作为底层语言，TypeScript 是 ES6 超集，对类型支持，面向对象，Decorator（类似于 Java 里注解 Annotation）等支持。在写法上，保持 Java 开发者的习惯，能够吸引更多人快速上手。

TypeScript 支持几乎是目前所有 Node Web 框架都要做的头等大事，在 2017 年 Nest 算首个知名项目，值得一提。

b3）ThinkJS

ThinkJS 是一款拥抱未来的 Node.js Web 框架，致力于集成项目最佳实践，规范项目让企业级团队开发变得更加简单，更加高效。秉承简洁易用的设计原则，在保持出色的性能和至简的代码同时，注重开发体验和易用性，为 WEB 应用开发提供强有力的支持。

ThinkJS 是国产老牌 Web 框架，在 2017 年 10 月发布 v3 版本，基于 Koa 内核，在性能和开发体验上有更好的提升。

整体来看，Node.js 在企业 Web 开发领域日渐成熟，无论微服务，还是 Api 中间层都得到了非常好的落地。在 2017 年唯一遗憾的是 Node.js 在 servless 上表现的不太好，相关框架实践偏少。

c）不可不见的 Api 中间层

前端越来越复杂，后端服务化，今日的前端要面临更多的挑战。一个典型的场景就是在服务化架构里，前端面临的最头痛的问题是异构 API，前后端联调的时候，多个后端互相推诿，要么拖慢上线进度，要么让前端性能变得极其慢。进度慢找前端，性能差也找前端，但这个锅真的该前端来背么？

Node.js 的 Api 中间层应用很好的解决了这个问题。后端不想改的时候，实在不行就前端自己做，更灵活，更能应变。

透传接口，对于内网或者非安全接口，可以采用中间层透传。聚合接口，对异构 API 处理非常方便，如果能够梳理 model，应变更容易。 Mock 接口，通过 Mock 接口，提供前端开发效率，对流程优化效果极其明显，比如去哪儿开发的 yapi 就是专门解决这个问题的。除此之外，前端如果想做一些技术驱动的事儿，SSR（服务器端渲染）和 PWA（渐进式 Web 应用）也是非常不错的选择。

if _, err := net.ListenUDP(“udp”, addr); err != nil { log.Fatal(“error making udp socket”, err) }

Express

Koa

Koa 中最著名即其洋葱圈模型，其任何的处理流都是以中间件方式进行：

基础的 Koa 用法如下：

const Koa = require('koa');

const app = new Koa();
const PORT = 3000;

app.use(async (ctx, next)=>{
    console.log(1)
    ctx.body = ...
    await next();
    console.log(1)
});

...

Koa 洋葱模型的两个核心设计点即是 context 的保存和传递以及中间件的管理和 next 的实现，从 Koa 入口 Server 开始：

listen(...args) {
    debug('listen');
    const server = http.createServer(this.callback());
    return server.listen(...args);
}

在 callback 函数中，会执行中间件的聚合与使用：

callback() {
    const fn = compose(this.middleware);
    ...
    const handleRequest = (req, res) => {
      const ctx = this.createContext(req, res);
      return this.handleRequest(ctx, fn);
    };

    return handleRequest;
}

compose 函数在 koa-compose 中定义，其会包含某个 dispatch 函数，该函数等于会递归执行数组后的中间件函数：

function compose (middleware) {
  ...
  return function (context, next) {
    // last called middleware #
    let index = -1
    return dispatch(0)
    function dispatch (i) {
      if (i <= index) return Promise.reject(new Error('next() called multiple times'))
      index = i
      let fn = middleware[i]
      // 如果中间件执行完毕，则调用传入的函数
      if (i === middleware.length) fn = next
      if (!fn) return Promise.resolve()

      try {
      	// 递归执行下一个函数，传入的 next 函数即是包装的 dispatch 的下一个函数的调用
        return Promise.resolve(fn(context, dispatch.bind(null, i + 1)));
      } catch (err) {
        return Promise.reject(err)
      }
    }
  }
}

而 handleRequest 函数中只是会简单地初始化调用中间件聚合函数：

  handleRequest(ctx, fnMiddleware) {
    ...
    return fnMiddleware(ctx).then(handleResponse).catch(onerror);
  }

最近更新于 0001-01-01