服务端请求防重与幂等键设计最佳实践

一、幂等键与约束function validKey(k: string): boolean { return /^[A-Za-z0-9_\-\.]{8,128}$/.test(k) } 二、请求哈希与存储import crypto from 'crypto' function requestHash(path: string, body: any): string { const s = path + ':' + JSON.stringify(body) return crypto.createHash('sha256').update(s).digest('hex') } type Entry = { key: string; hash: string; status: number; body: string; expireAt: number } class Store { map = new Map<string, Entry>() ttlSec: number constructor(ttlSec: number) { this.ttlSec = ttlSec } get(k: string): Entry | undefined { const e = this.map.get(k) if (!e) return undefined if (Date.now() > e.expireAt) { this.map.delete(k); return undefined } return e } set(k: string, e: Entry) { this.map.set(k, e) } } 三、并发锁与防重放class Lock { locks = new Set<string>() acquire(k: string): boolean { if (this.locks.has(k)) return false; this.locks.add(k); return true } release(k: string) { this.locks.delete(k) } } 四、路由中间件type Req = { headers: Record<string, string | undefined>; path: string; body: any } type Res = { status: (n: number) => Res; end: (b?: string) => void; setHeader: (k: string, v: string) => void } function idempotencyGuard(store: Store, lock: Lock) { return async function handler(req: Req, res: Res, next: Function) { const key = req.headers['idempotency-key'] || '' if (!validKey(key)) return res.status(400).end('invalid_idempotency_key') const h = requestHash(req.path, req.body) const cached = store.get(key) if (cached) { if (cached.hash !== h) return res.status(409).end('key_conflict') res.setHeader('Idempotency-Replayed', 'true') return res.status(cached.status).end(cached.body) } if (!lock.acquire(key)) return res.status(409).end('in_progress') try { ;(req as any).idemKey = key ;(req as any).idemHash = h next() } finally { lock.release(key) } } } function recordResponse(store: Store, req: Req, status: number, body: string) { const key = (req as any).idemKey as string const hash = (req as any).idemHash as string const ttlSec = 900 const expireAt = Date.now() + ttlSec * 1000 store.set(key, { key, hash, status, body, expireAt }) } 五、示例与验收键格式长度与字符约束通过；TTL≤900秒；冲突返回`409`。重复请求响应复用并带`Idempotency-Replayed`；并发锁避免重复执行。存储包含状态与响应体，过期后自动清理并拒绝旧键复用。