Node.js如何优雅的传递traceId（请求唯一标识）-JXin的博客

手动传参（不推荐）
async_hooks
cls-hooked（推荐）
- 使用 cls-hooked

背景

自己写的Node.js服务中，经常会出现数据库查询超时、第三方接口请求异常等问题，虽然有记录错误日志，但是缺少上下文，导致很多问题都不好解决，甚至都不知道哪里出的问题，最近研究了一下如何生成一个traceId（请求唯一标识），来记录上下文，本文主要记录一下如何在不影响历史代码的前提下，给每一个报错信息增加一个traceId，来关联请求的接口，记录上下文，快速定位问题发生的位置

手动传参（不推荐）

在请求入口中生成 traceId 并存储在 req 中：

app.use((err, req, res, next) => {
  const traceId = generateTraceId(); // 生成 traceId
  res.traceId = traceId; // 将 traceId 存储 在req 中传递下去
  next();
});

1
2
3
4
5

最简单的方法就是手动传参，不需要什么理解的成本，简单直接，但它的侵入性强，难以维护，而且如果当前的系统已经有一定规模，想再用这个方法也比较不现实，所以本文也不推荐使用这种方法

async_hooks

Node.js 提供了 async_hooks 模块来实现 异步上下文跟踪，它允许开发者监控 异步操作 的创建、执行和销毁过程

生命周期钩子

async_hooks 提供了几个关键的 生命周期钩子函数 ，可以在异步资源的不同阶段执行回调：

init: 异步资源初始化时调用
before: 异步回调即将执行前调用
after: 异步回调执行完成后调用
destroy: 异步资源销毁时调用
promiseResolve: Promise 被 resolve 时调用

async_hooks 核心API

async_hooks.createHook(callbacks)：创建并返回一个 AsyncHook 实例
asyncHook.enable()：启用该 AsyncHook 实例的钩子回调
asyncHook.disable()：禁用该 AsyncHook 实例的钩子回调
async_hooks.executionAsyncId()：返回当前执行上下文的 asyncId
async_hooks.triggerAsyncId()：返回触发当前执行上下文的 asyncId（即父 asyncId）
async_hooks.asyncResourceSymbol：用于创建 AsyncResource 实例的符号

每个异步资源都会获得一个唯一的 asyncId，数字从 1 开始递增分配，同时也是通过这个 asyncId 来记录和关联对应信息的

例子

来看一个简单的例子：

const async_hooks = require("async_hooks");
const fs = require("fs");

// 创建一个 AsyncHook 实例
const asyncHook = async_hooks.createHook({
  init(asyncId, type, triggerAsyncId, resource) {
    fs.writeSync(
      1,
      `Init: ${type}(${asyncId}), triggered by ${triggerAsyncId}\n`
    );
  },
  before(asyncId) {
    fs.writeSync(1, `Before: ${asyncId}\n`);
  },
  after(asyncId) {
    fs.writeSync(1, `After: ${asyncId}\n`);
  },
  destroy(asyncId) {
    fs.writeSync(1, `Destroy: ${asyncId}\n`);
  },
  promiseResolve(asyncId) {
    fs.writeSync(1, `Promise resolved: ${asyncId}\n`);
  },
});

// 启用钩子
asyncHook.enable();

// 示例异步操作
setTimeout(() => {
  console.log("Timeout executed");
}, 100);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

以下是代码执行后返回的结果

// 创建了一个 setTimeout 异步资源，asyncId 为 2
// triggered 为 1，是因为 Node.js 进程启动时已经有一个默认的异步上下文，其 asyncId 为 1
Init: Timeout(2), triggered by 1

// setTimeout 的回调函数即将执行 asyncId 为 2
Before: 2

// 创建了与终端输出相关的资源（因为回调中有 console.log） asyncId 为 3
// triggered 为 setTimeout（asyncId 为 2）
Init: TTYWRAP(3), triggered by 2

// 创建了信号处理相关的资源 asyncId 为 4
// triggered 为 setTimeout（asyncId 为 2）
Init: SIGNALWRAP(4), triggered by 2

// 实际执行了 setTimeout 的回调函数，输出 "Timeout executed"
Timeout executed

// console.log 内部可能使用了 process.nextTick，创建了新的 tick 对象  asyncId 为 5
// triggered 为 setTimeout（asyncId 为 2）
Init: TickObject(5), triggered by 2

// setTimeout 的回调执行完成 asyncId 为 2
After: 2

// TickObject 的回调即将执行 asyncId 为 5
Before: 5

// TickObject 的回调执行完成 asyncId 为 5
After: 5

// setTimeout 资源被销毁 asyncId 为 2
Destroy: 2

// TickObject 资源被销毁 asyncId 为 5
Destroy: 5

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

Node.js 的 I/O 操作通常涉及多个内部资源协同工作，一个简单的 console.log 实际上会触发多个底层异步操作

在这段代码有一个疑问，就是 TTYWRAP 和 SIGNALWRAP 被初始化了，但却没有看到它的 before/after/destroy？这可能是因为这些资源由底层管理，生命周期不完全暴露

如何使用 async_hooks 来存储 traceId？

接下来就讲讲如何使用 async_hooks 来存储 traceId，首先封装一个存储和查询traceId 的方法

// asyncContext.js
const async_hooks = require("async_hooks");

// 存储上下文的 Map
const contexts = new Map();

const asyncHook = async_hooks.createHook({
  init(asyncId, type, triggerAsyncId) {
    // 当有新的异步资源创建时，如果父异步资源有上下文，则继承
    if (contexts.has(triggerAsyncId)) {
      contexts.set(asyncId, contexts.get(triggerAsyncId));
    }
  },
  destroy(asyncId) {
    // 异步资源销毁时清理上下文
    contexts.delete(asyncId);
  },
});

// 启用 AsyncHook 实例
asyncHook.enable();

// 存储当前上下文的 traceId
function setTraceId(traceId) {
  const asyncId = async_hooks.executionAsyncId();
  contexts.set(asyncId, { traceId });
}

// 获取当前上下文的 traceId
function getTraceId() {
  const asyncId = async_hooks.executionAsyncId();
  return contexts.get(asyncId)?.traceId;
}

module.exports = { setTraceId, getTraceId };

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

在请求入口中生成 traceId 并存储

const { setTraceId } = require('./asyncContext');

app.use((err, req, res, next) => {
  const traceId = generateTraceId(); // 生成 traceId
  setTraceId(traceId); // 存储 traceId
  next();
});

1
2
3
4
5
6
7

之后就可以在需要的地方获取到traceId了，例如：在 SQL 执行方法中获取 traceId

const { getTraceId } = require('./asyncContext');

module.exports = async (query, params = []) => {
  const traceId = getTraceId(); // 获取当前上下文的 traceId
  const pool = db();
  const promisePool = pool.promise();
  try {
    const [rows] = await promisePool.query(query, params);
    pool.end();
    return rows;
  } catch (error) {
    logger.error({ traceId, error }); // 记录 错误日志和traceId
    throw error;
  }
};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

cls-hooked（推荐）

cls-hooked 是基于 async_hooks 封装的，它使用简单，且自动上下文管理，不需要像 async_hooks 那样需手动管理生命周期

使用 cls-hooked

// clsContext.js
const cls = require('cls-hooked');
const namespace = cls.createNamespace('custom-name'); // 创建一个命名空间，名字自定义

module.exports = namespace;

1
2
3
4
5

在请求入口中存储 traceId

const namespace = require('./clsContext');

app.use((req, res, next) => {
  namespace.run(() => {
    const traceId = generateTraceId(); // 生成 traceId
    namespace.set('traceId', traceId); // 存储 traceId
    next(); // 后续所有中间件/路由都能访问 traceId
  });
});

1
2
3
4
5
6
7
8
9

在 SQL 执行方法中获取 traceId

const namespace = require('./clsContext');

module.exports = async (query, params = []) => {
  const traceId = namespace.get('traceId'); // 获取当前上下文的 traceId
  const pool = db();
  const promisePool = pool.promise();
  try {
    const [rows] = await promisePool.query(query, params);
    pool.end();
    return rows;
  } catch (error) {
    logger.error({ traceId, error }); // 记录 错误日志和traceId
    throw error;
  }
};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15