程序员如何做「接口设计」：不只是功能，是契约

接口是系统之间对话的契约。

接口设计得好，系统之间的集成就顺畅；设计得不好，后患无穷。

---

一、好的接口设计的目标

1. 清晰易懂

调用方看了文档就知道怎么用。

2. 稳定

不改就不变，改也要向前兼容。

3. 安全

权限控制、参数校验、防攻击。

4. 高效

性能足够，不会成为系统瓶颈。

---

二、RESTful 接口设计原则

1. 用名词，不用动词

GET /users ✓ GET /getUsers ✗

2. 用 HTTP 方法表示动作

• GET：查
• POST：增
• PUT：改
• DELETE：删

3. 版本控制

/api/v1/ /api/v2/

4. 统一的错误格式

{
  "code": 400,
  "message": "参数错误",
  "data": null
}

---

三、接口设计要注意的事

1. 幂等性

PUT 和 DELETE 要设计成幂等的。

重复调用和调用一次结果一样。

2. 参数校验

不要相信调用方的输入。

所有输入都要校验。

3. 分页

列表接口一定要分页。

不要返回所有数据。

4. 文档

接口必须有文档。

代码即文档不够，需要专门的 API 文档。

---

四、常见错误

❌ 返回数据过于随意

有时候返回 data，有时候返回 list。

格式要统一。

❌ 不做版本控制

一个接口改来改去，调用方不知道用什么版本。

❌ 错误信息不明确

"系统错误"——调用方根本不知道发生了什么。

---

五、一句话总结

接口设计 = 清晰易懂 + 稳定兼容 + 安全校验 + 文档完善。