环境变量、配置管理、日志与统一异常处理

在启动时校验配置,并用请求编号关联访问日志与错误响应

🎯 引言

学完这篇文章,你能通过环境变量配置端口,自动记录接口访问日志,并按请求编号排查异常。

⚙️ 启动时读取配置

新建 config.mjs,读取端口并检查范围:

config.mjs
const port = Number(process.env.PORT ?? 3000);
if (!Number.isInteger(port) || port < 1 || port > 65535) {
    throw new Error('PORT 必须是 1 到 65535 的整数');
}
export const config = { port };

缺少 PORT 时使用 3000,写成 abc 会停止启动。数据库地址和密钥等必需配置应检查缺失,不能随意设置可公开的默认秘密值。

本地 .env 可以写入:

.env
PORT=3000

使用 node --env-file=.env 启动时加载它,真实凭据不提交仓库。部署平台也可以直接注入环境变量。


📝 用日志中间件记录请求

pino-http 是请求日志中间件,会记录响应状态和耗时:

npm install pino-http@11.0.0

新建 logging-app.mjs:

logging-app.mjs
import express from 'express';
import pinoHttp from 'pino-http';
import { randomUUID } from 'node:crypto';

export const app = express();

在路由前挂载日志中间件:

logging-app.mjs
app.use(pinoHttp({
    genReqId: () => randomUUID(),
    redact: ['req.headers', 'req.url', 'req.query', 'req.params', 'res.headers'],
    customProps: req => ({ path: req.path })
}));

genReqId 为请求生成编号。redact 隐去完整头部、URL 和参数,避免记录 Cookie、Authorization 或 Query 中的秘密;path 单独记录不含查询参数的路径。默认不会记录请求正文,不要自行把密码表单写进日志。


🏷 把请求编号返回客户端

继续添加:

logging-app.mjs
app.use((req, res, next) => {
    res.setHeader('X-Request-Id', req.id);
    next();
});

前端报告问题时可以提供响应头中的编号,服务端按相同编号查日志。跨域页面若要通过脚本读取这个头,还需要在 cors 的 exposedHeaders 配置中允许 X-Request-Id。


🧯 记录异常并返回有限信息

先添加两个接口,一个成功,一个用于检查失败路径:

logging-app.mjs
app.get('/health', (req, res) => res.json({ status: 'ok' }));
app.get('/failure', async (req, res) => {
    throw new Error('模拟内部操作失败');
});

在它们后面配置错误处理中间件:

logging-app.mjs
app.use((error, req, res, next) => {
    if (res.headersSent) return next(error);
    req.log.error({ err: error }, '请求处理失败');
    res.status(500).json({ error: '服务暂时无法处理请求' });
});

req.log 自动关联当前请求,客户端只收到通用提示,服务端可以查看内部错误。需要同时处理 JSON 等输入错误时,把这条日志调用放进统一异常篇对应的错误分支,不要重复挂载多个会发送响应的错误处理器。


🚀 用配置启动并核对日志

新建 logging-server.mjs:

logging-server.mjs
import { app } from './logging-app.mjs';
import { config } from './config.mjs';

app.listen(config.port, '127.0.0.1');

运行:

node --env-file=.env logging-server.mjs

请求 /health 得到 200,终端打印访问日志,其中包含状态与耗时。请求 /failure 得到 500,响应头编号与错误日志中的请求编号一致。日志耗时描述服务端处理时间,不是页面从点击到渲染结束的总时间。


❓ 知识问答

Q1:把全部请求内容记下来更方便吗?

可能泄露密码和令牌。记录排查必需的字段,并控制日志访问权限与保留期限。

Q2:每个业务函数都要记录一次错误吗?

不必。同一异常在最终处理位置记录,避免重复。

Q3:生产环境必须保存 .env 文件吗?

不必,部署平台注入的环境变量也能通过 process.env 读取。


🧪 小练习

将 PORT 改成 abc,确认启动失败;恢复后请求 /failure,核对响应编号和错误日志。

// 请在这里记录结果