为什么需要清单

同一个项目里，接口改了三次：第一次少了分页，第二次错误码不统一，第三次字段命名前后矛盾。每次都是联调时才被发现，返工成本远高于设计时多想十分钟。

动工前的检查项

数据结构

• 列表接口必须带分页，哪怕现在数据量只有十条
• 时间字段统一用 ISO 8601 字符串，不要混用时间戳
• 布尔字段否定式命名要慎用，is_not_ready 是双重否定

错误处理

• 错误码分段管理：客户端错误、服务端错误、业务错误各占一段
• 错误信息分两层：给机器看的 code，给人看的 message
• 4xx 不记 error 日志，5xx 必须带 trace id

兼容性

• 新增字段默认可选，删除字段先标记废弃
• 枚举值只增不减，前端才能安全缓存

{
  "code": "INVALID_PARAM",
  "message": "page_size 必须在 1 到 100 之间",
  "trace_id": "b3f1..."
}

用法

清单不长，打印贴在显示器旁边。每次设计新接口过一遍，能挡掉大部分"当时没想到"。