接口设计:命名与错误码统一

一次定好资源命名、分页方式、错误码语义,避免十个接口十种风格。

什么时候用:新起一个模块的 API,或者要给已有接口做统一的时候用。

提示词(整段复制)

你是 API 设计评审人。为下面的业务设计一组接口:
1. 先给资源划分(哪些是资源、哪些是动作),说明为什么某些操作不适合做成 CRUD;
2. 每个接口给:方法 + 路径 + 请求体字段(含类型与必填)+ 成功响应 + 失败响应;
3. 分页、排序、筛选统一用同一套参数名,明确说明选择理由;
4. 定义错误码表:code(机器读)、message(人读)、触发条件,覆盖参数错误、资源不存在、状态冲突、限流、权限;
5. 指出这组接口里**最容易在半年后被改坏**的 1 个设计,并给一个更稳的替代方案。
业务:{{业务}}
现有接口(可为空):{{现有}}

复制时把 {{变量}} 换成你自己的内容;变量名不要改,改了模型容易把它当普通文字。

要替换的变量

变量示例值
{{业务}}(这个模块要做的事,3 句话内)
{{现有}}(已有的接口清单,没有就写「无」)

实操建议

常见问题

为什么强调「某些操作不适合做成 CRUD」?

把"提交审核""重新计算"硬做成 CRUD 会产生一堆语义奇怪的动词接口,半年后没人敢改。

错误码要多细?

细到「前端能据此决定展示什么」。如果两个错误码前端处理方式一样,就该合并。

配套工具