全链路溯源的核心目标是让每个异步环节的调用路径与上下文（如traceId、服务名、参数）随异常透出，从而清晰还原“谁、在哪个环节、因何失败”；需在async入口注入traceId、封装异步操作为带上下文的AppError、顶层结构化记录并透传错误。
明确“全链路溯源”的核心目标
所谓“全链路溯源”，不是单纯捕获错误，而是让每个异步环节的调用路径、上下文信息（如请求 ID、服务名、关键参数）能随异常一起透出，最终在日志或监控中清晰还原“谁、在哪个环节、因何失败”。async/await + try...catch 本身不自动提供溯源能力，必须主动注入上下文并统一错误构造逻辑。
在 async 函数入口注入唯一追踪标识
每次发起异步调用前，生成或透传一个贯穿整个调用链的 traceId（例如使用 uuidv4 或从上游 HTTP Header 中提取）。把它作为参数显式传入所有 async 函数，并在函数内部通过闭包或上下文对象保留。
- 避免依赖全局变量或 Zone.js —— Node.js 环境无原生 Zone，且全局状态易污染
- 推荐方式：将 traceId 封装进 request context 对象，作为第一个参数传给业务 async 函数，例如
await handleOrder({ traceId: 'abc123', userId, orderId }) - 若使用 Express/Koa，可在中间件中解析 traceId 并挂载到
req.context，后续 async 处理函数直接读取
统一包装异步操作并重抛带上下文的错误
不要裸写 await fetch(...) 或 await db.query(...)。所有外部异步调用应被封装成具备错误增强能力的工具函数。
AI舌诊面诊问诊医疗系统+诊疗商城系统源码
下载
AI 舌诊面诊问诊医疗系统 + 诊疗商城系统源码是一套结合 AI 辅助诊断与商品转化的健康类程序，基于浩创云、ThinkPHP（PHP）开发，支持微信服务号与 H5 端，适合做中医舌诊面诊问答、健康建议推送以及配套诊疗商品的运营。
- 示例封装：
async function safeFetch(url, options = {}, context) { try { return await fetch(url, options); } catch (err) { throw new AppError('FETCH_FAILED', { url, ...context }, err); } } -
AppError是自定义错误类，构造时合并 traceId、服务名、操作类型、原始 error.stack 和 cause - 关键点：原始 error 的 stack 不要丢失，同时叠加当前层的调用位置和 context —— 可用
err.stack + '\nCaused by: ' + new Error().stack粗粒度拼接，或用err.cause = originalErr（Node.js 16.9+）
顶层 try...catch 中结构化记录与透传
在最外层 async 入口（如 API 路由处理函数）使用 try...catch，但不做静默吞错，而是做三件事：记录完整错误对象、设置响应状态码、必要时向下游透传 traceId 和错误摘要。
- 日志记录必须包含：
traceId、error.code（业务码）、error.message、error.stack、context中的关键字段（如userId、orderId） - 避免只打印
err.toString()—— 会丢失堆栈和属性 - 若调用下游服务，可在响应 header 中返回
X-Error-Trace: abc123，方便前端或网关关联排查
不复杂但容易忽略
async/await 的错误捕获天然扁平，真正实现可溯源，靠的是每层都主动携带 traceId、每层都用 AppError 包装、每层都不丢原始 error。没有魔法，只有约定和坚持。
