使用Sequelize+CLS记录MySQL查询时丢失Request-Id上下文求助

架构老林

2026-5-19

问题分析

你遇到的Request-Id上下文丢失问题，核心原因是旧版本的Sequelize与CLS（cls-hooked）的绑定逻辑没做对，加上异步操作中上下文传播不完整，导致日志模块无法正确获取当前请求的Request-Id。结合你使用的Node.js 8.9.4、Sequelize 4.33.4、cls-hooked 4.2.2版本，我们需要针对性修复几个关键环节。

分步解决方案

1. 正确初始化CLS命名空间并绑定Sequelize

Sequelize 4.x需要在创建实例前手动绑定CLS命名空间，否则后续数据库查询无法继承上下文。在mysql.js中按以下顺序编写代码：

const cls = require('cls-hooked');
const Sequelize = require('sequelize');

// 1. 创建全局唯一的CLS命名空间（不要重复创建）
const requestNamespace = cls.createNamespace('request-context');

// 2. 必须在创建Sequelize实例前，绑定命名空间到Sequelize
Sequelize.useCLS(requestNamespace);

// 3. 初始化Sequelize实例
const sequelize = new Sequelize('your-db-name', 'user', 'password', {
  host: 'localhost',
  dialect: 'mysql',
  // 其他配置...
});

// 导出命名空间和Sequelize实例，方便其他文件使用
module.exports = { sequelize, requestNamespace };

2. 在请求入口注入Request-Id到CLS上下文

在你的请求中间件（比如Express中间件）里，确保每个请求都在CLS上下文里执行，并且注入Request-Id：

const { requestNamespace } = require('./mysql.js');
const uuid = require('uuid/v4'); // 用uuid生成默认Request-Id

app.use((req, res, next) => {
  // 从请求头获取或生成Request-Id
  const requestId = req.headers['x-request-id'] || uuid();
  
  // 用namespace.run包裹请求处理，确保后续异步操作继承上下文
  requestNamespace.run(() => {
    requestNamespace.set('requestId', requestId);
    next();
  });
});

3. 修复日志模块的上下文获取逻辑

在logger.js中，直接从CLS命名空间获取Request-Id，不要依赖全局变量或其他非上下文方式：

const cls = require('cls-hooked');

// 获取之前创建的命名空间
const requestNamespace = cls.getNamespace('request-context');

const logger = {
  info(message) {
    // 容错：如果不在请求上下文里，返回默认值
    const requestId = requestNamespace ? requestNamespace.get('requestId') : 'unknown-request-id';
    console.log(`[INFO] [${requestId}] ${message}`);
  },
  error(message) {
    const requestId = requestNamespace ? requestNamespace.get('requestId') : 'unknown-request-id';
    console.error(`[ERROR] [${requestId}] ${message}`);
  }
};

module.exports = logger;

4. 验证上下文传播是否正常

可以在Sequelize的查询钩子中检查Request-Id是否存在，确认绑定生效：

const { sequelize, requestNamespace } = require('./mysql.js');

sequelize.addHook('beforeQuery', (options) => {
  const reqId = requestNamespace.get('requestId');
  console.log(`[Before Query] Request-Id: ${reqId}`);
  // 如果这里能正确打印当前请求的Request-Id，说明Sequelize与CLS绑定成功
});

针对你版本的特殊注意事项

Sequelize 4.x的绑定顺序：Sequelize.useCLS()必须在创建任何Sequelize实例前调用，否则绑定完全无效，这是很多开发者踩坑的点。
Node.js 8.x的AsyncHooks限制：cls-hooked依赖Node.js的AsyncHooks API，8.x版本存在少量上下文泄漏的已知问题，尽量避免在请求上下文外执行数据库查询（比如定时任务），如果必须执行，需要手动重新注入上下文。
避免重复创建命名空间：所有文件都通过cls.getNamespace()获取同一个命名空间，不要重复调用createNamespace()。

内容的提问来源于stack exchange，提问作者rajat12a