API安全日志与可观测性（Trace-ID与脱敏）最佳实践

一、Trace-ID注入与传播type Req = { headers: Record<string, string | undefined> } type Res = { setHeader: (k: string, v: string) => void } function randId(): string { return Math.random().toString(36).slice(2) + Math.random().toString(36).slice(2) } function attachTrace(req: Req, res: Res): string { const id = req.headers['x-trace-id'] || randId() res.setHeader('X-Trace-Id', id) return id } 二、采样与速率限制class RateGate { windowMs: number max: number hits = new Map<string, number[]>() constructor(windowMs: number, max: number) { this.windowMs = windowMs; this.max = max } allow(key: string): boolean { const now = Date.now() const arr = (this.hits.get(key) || []).filter(t => now - t < this.windowMs) if (arr.length >= this.max) return false arr.push(now); this.hits.set(key, arr); return true } } function sample(p: number): boolean { return Math.random() < p } 三、脱敏与Schematype LogItem = { traceId: string; level: 'info' | 'warn' | 'error'; route: string; method: string; status?: number; userId?: string; payload?: Record<string, any>; timestamp: string } function redactPII(obj: Record<string, any>): Record<string, any> { const out: Record<string, any> = {} for (const [k, v] of Object.entries(obj)) { const key = k.toLowerCase() if (key.includes('password') || key.includes('secret') || key.includes('token')) out[k] = '***' else if (key.includes('email')) out[k] = String(v).replace(/^[^@]+/, '***') else out[k] = v } return out } 四、日志输出与审计function nowIso(): string { return new Date().toISOString() } function makeLog(traceId: string, route: string, method: string, level: 'info' | 'warn' | 'error', payload?: Record<string, any>, status?: number, userId?: string): LogItem { const p = payload ? redactPII(payload) : undefined return { traceId, level, route, method, status, userId, payload: p, timestamp: nowIso() } } function serializeLog(item: LogItem): string { return JSON.stringify(item) } 五、整合中间件type Ctx = { req: Req; res: Res; route: string; method: string; userId?: string } function loggingMiddleware(ctx: Ctx, gate: RateGate, p: number, emit: (line: string) => void) { const traceId = attachTrace(ctx.req, ctx.res) const ok = gate.allow(traceId) if (!ok) return if (sample(p)) emit(serializeLog(makeLog(traceId, ctx.route, ctx.method, 'info', undefined, undefined, ctx.userId))) } 六、验收清单`X-Trace-Id`注入与传播一致；采样概率与速率限制生效。PII字段脱敏覆盖密码/Secret/Token与邮箱前缀；日志Schema统一且JSON输出。审计记录包含`traceId/route/method/status/userId/timestamp`并可关联上下游。