程序员如何做「接口设计」：不是定格式，是契约

接口是系统之间交互的契约。

好的接口稳定、清晰、易用；不好的接口是集成噩梦的开始。

一、接口设计的原则

1. 简单

接口要简单明了，容易理解。

不要过度设计，一个接口只做一件事。

2. 一致

命名、参数、返回值风格要一致。

团队内有统一的接口规范。

3. 稳定

接口一旦发布，不要轻易 breaking change。

破坏性变更要走版本管理。

4. 安全

• 参数校验
• 权限控制
• 防止注入
• 敏感数据脱敏

二、RESTful 接口设计

1. 资源命名

• 名词复数：/users
• 不要用动词：/getUser ❌

2. HTTP 方法

• GET：查询
• POST：创建
• PUT：全量更新
• PATCH：部分更新
• DELETE：删除

3. 状态码

• 200：成功
• 201：创建成功
• 400：参数错误
• 401：未认证
• 403：权限不足
• 404：资源不存在
• 500：服务器错误

4. 统一响应格式

{
  "code": 0,
  "message": "success",
  "data": {}
}

三、接口文档

1. 必含信息

• 接口地址
• 请求方法
• 请求参数（含类型、说明、是否必填）
• 响应格式（含示例）
• 错误码说明

2. 维护方式

• Swagger/OpenAPI
• YAPI
• 飞书文档

四、常见错误

❌ 接口返回数据随意

一会儿返回数组，一会儿返回对象。

❌ 错误信息模糊

"error": "failed" —— 什么失败？为什么？

❌ 不做参数校验

后端不做校验，靠前端保证。

❌ 省略版本号

v1 改版没有 v2，旧版本用户全挂。

五、一句话总结

接口设计 = 简单 + 一致 + 稳定 + 安全，核心是清晰的契约和完整的文档。