API错误码与可观测性统一规范最佳实践

一、错误Schema与映射type ErrorPayload = { code: string; message: string; traceId: string; hint?: string } const statusByCode: Record<string, number> = { 'bad_request': 400, 'unauthorized': 401, 'forbidden': 403, 'not_found': 404, 'rate_limited': 429, 'server_error': 500 } function toStatus(code: string): number { return statusByCode[code] || 500 } 二、Trace-ID与头字段type Req = { headers: Record<string, string | undefined> } type Res = { setHeader: (k: string, v: string) => void; status: (n: number) => Res; end: (b?: string) => void } function traceId(req: Req): string { return req.headers['x-trace-id'] || Math.random().toString(36).slice(2) } function setCommonHeaders(res: Res, id: string) { res.setHeader('Content-Type', 'application/json; charset=utf-8') res.setHeader('X-Content-Type-Options', 'nosniff') res.setHeader('X-Trace-Id', id) } 三、错误封装与输出function makeError(code: string, message: string, traceId: string, hint?: string): ErrorPayload { return { code, message, traceId, hint } } function sendError(req: Req, res: Res, code: string, message: string, hint?: string) { const id = traceId(req) setCommonHeaders(res, id) const payload = makeError(code, message, id, hint) res.status(toStatus(code)).end(JSON.stringify(payload)) } 四、指标与采样class Metrics { counts = new Map<string, number>() inc(key: string) { const n = (this.counts.get(key) || 0) + 1; this.counts.set(key, n) } } function sample(p: number): boolean { return Math.random() < p } function record(metrics: Metrics, code: string, p = 0.1) { if (sample(p)) metrics.inc(code) } 五、整合中间件function guardExample(req: Req, res: Res, metrics: Metrics) { const ok = (req.headers['authorization'] || '').startsWith('Bearer ') if (!ok) { record(metrics, 'unauthorized'); return sendError(req, res, 'unauthorized', '缺少或无效授权', '检查令牌') } } 六、验收清单错误码与状态码映射统一；错误Schema包含`code/message/traceId/hint`。`X-Trace-Id`传播一致；头字段包含`Content-Type`与`nosniff`；重试建议通过`hint`提供。指标采样与统计可用；日志与错误输出遵循统一格式并可脱敏。