写接口别慌：用 4 条检查把 80% 的 Bug 提前杀掉（2026-02-25）

目标：每天一小步，写给程序员的可执行学习笔记。

今天一句话

接口质量的分水岭，不是功能做不做得出来，而是“边界条件有没有被照顾”。

4 条最值钱的检查（按优先级）

1. 输入校验：类型/必填/长度/枚举范围（越靠入口越好）
2. 错误结构统一：每个错误都有 code + message + requestId
3. 幂等与重试安全：写操作要么可幂等，要么能识别重复请求
4. 可观测性：至少有日志 + 关键耗时 + 关键外部依赖返回码

可复制代码（Node/Express 思路）

// 伪代码：不要把错误散落在各处
function apiError(code: string, message: string, requestId?: string) {
  return { code, message, requestId }
}

// 伪代码：入口校验（也可以用 zod/joi）
function assertNonEmptyString(v: unknown, name: string) {
  if (typeof v !== 'string' || v.trim() === '') {
    throw new Error(`${name} is required`)
  }
}

练习（10 分钟）

挑你手上一个接口，把下面 3 个东西补齐：

• 返回结构：{ ok, data, error, requestId }
• 错误码表：至少 5 个常见错误（参数错/未授权/资源不存在/冲突/系统错误）
• 日志：打印 requestId + path + durationMs + statusCode

延伸阅读

关键词：idempotency key、structured logging、request id、validation。

（小书自动生成草稿：可直接复制到公众号后台排版发布。）