当遇到 bug、测试失败、报错或"本来是好的现在坏了"时使用…

# Node.js 电商下单接口 500 错误：系统性排查与修复指南

一、先定位：明确错误特征（别急着改代码）

1. 收集日志与监控

• 查看错误日志：确认 500 的具体堆栈（app.use((err, req, res, next)) 是否有全局错误中间件，日志是否带 request id 可串联）
• 统计 3-5/50 = 6%~10% 的错误率，属于“偶发但高频”，常见于并发竞态、资源池耗尽、超时、未捕获异常
• 检查是否集中在特定时间点、特定商品、特定支付方式（可归因性分析）

2. 区分错误类型

• 同步抛错：堆栈里有明确的文件行号
• Promise rejection 未捕获：UnhandledPromiseRejection，常见于 async 中间件未 try-catch（Express 4 不会自动捕获 async 错误）
• 超时/连接类：数据库连接池耗尽、Redis 断连、下游支付接口超时

二、高概率根因清单（按电商下单场景）

1. async 错误未捕获：Express/Koa 中间件漏 try-catch，偶发 reject 直接打穿

2. 库存扣减竞态：并发下单时 check-then-update 非原子操作，或乐观锁冲突未处理返回 500

3. 数据库连接池耗尽：下单涉及事务 + 锁等待，高峰期 connection timeout

4. 事务死锁：同时更新订单表 + 库存表，锁顺序不一致

5. 下游服务超时：优惠券、支付预下单、风控接口抖动，超时未降级

6. Node 内存/事件循环阻塞：大促时序列化大对象、同步 CPU 操作阻塞导致请求堆积超时

三、定位手段

• 用 clinic doctor / 0x 做 CPU profile，看事件循环阻塞
• APM 接入（如自建 tracer 或商用 APM）追踪慢查询和下游调用
• 对比错误请求与成功请求的参数差异：是否同一 SKU、同一用户重复点击、同一优惠券

四、修复策略（按定位结果对症下药）

• 未捕获异常：中间件统一包 async wrapper；进程级兜底 process.on('uncaughtException') 记录后优雅重启
• 库存竞态：改为原子扣减（UPDATE stock SET n=n-1 WHERE sku=? AND n>0）或 Redis Lua + MQ 异步落库
• 连接池：确认池大小与 DB 配置匹配，事务设置合理超时，失败快速返回而非堆积
• 死锁：统一多表更新顺序，缩短事务持有锁时间
• 下游超时：设置超时 + 重试（幂等前提下）+ 熔断降级

五、验证闭环

• 修复后压测复现场景（并发下单同一 SKU），观察错误率降至接近 0
• 加告警：500 率 >1% 触发通知
• 上线采用灰度/金丝雀，对比新旧版本错误率

核心原则：先让日志能说清“哪一行、什么错误”，再改代码；竞态和未捕获异常是这个错误率区间最常见的两类根因。