接口设计规范：命名、版本与错误码

接口层面反复返工，通常不是因为技术难，而是因为"每个接口长得都不一样"：有的用驼峰有的用下划线、有的返回 code 有的返回 status、分页参数三种写法。统一规范这件事，一次投入长期受益。

一、命名统一，不只是风格问题

• 字段命名统一风格（推荐小写下划线或小驼峰，选一种就别改）
• 资源用名词复数，动作用 HTTP 方法表达，避免 /getUserList 这类命名
• 同一含义用同一个词：不要一会儿 user 一会儿 member
• 布尔字段用 is/has 前缀，便于理解

二、版本策略：什么时候升版本

版本放在路径或请求头都行，关键是写进规范并保持一致。

三、错误码要有结构

1. HTTP 状态码表达大类（200/400/401/403/404/500）
2. 业务错误码表达具体原因，且全局唯一、可查表
3. 错误信息面向调用方，说明"哪里错了、怎么改"
4. 不要用统一的一个错误码应付所有情况

四、分页、时间与空值

• 分页参数统一（如 page/size 或 offset/limit），返回结构统一包含总数
• 时间统一使用带时区的标准格式，不使用本地化字符串
• 空值约定明确：null、空数组、缺字段三者含义不能混

五、规范要能落地

写进文档只是第一步，还要做到：提供公共封装（统一响应结构、统一异常处理）、在代码评审中检查、把规范附在一页纸的速查表里。能被随手查到的规范，才会被真正执行。