API 设计踩坑实录：我用 RESTful 做了三年后总结的 5 个关键原则

我刚做后端开发的时候，觉得 API 设计不就是定义几个接口嘛，能跑通就行。结果三年下来，踩的坑比写的代码还多。今天把我踩过的坑和现在的做法分享出来，希望能帮到刚入行的朋友。

1. 资源命名混乱，接口变成迷宫

最早我设计的接口是这样的：
```
GET /getUserInfo
POST /createOrder
GET /fetchProducts
```
看起来挺直观对吧？但问题来了：团队扩大后，每个人都有自己的命名习惯。有的人用动词，有的人用名词，有的人用驼峰，有的人用下划线。接口文档变成了字典，新人根本看不懂。

后来我强制统一用 RESTful 风格：
```
GET /users/{id}
POST /orders
GET /products
```
资源用名词复数，操作用 HTTP 方法。刚开始有点不习惯，但半年后维护成本直接降了一半。

2. 版本控制缺失，升级接口像拆炸弹

有一次我要改一个用户接口的返回字段，结果前端直接崩了。因为老版本的移动端还在用，我一改全挂。那次事故让我意识到版本控制的重要性。

现在我的接口都带版本号：
```
GET /v1/users/{id}
GET /v2/users/{id}
```
新功能在 v2 加，老版本继续维护。虽然多了一层路径，但升级的时候心里踏实多了。

3. 错误处理不规范，前端猜谜游戏

以前我的错误返回是这样的：
```json
{"code": 1, "msg": "error"}
```
前端同事天天问我："这个 error 是什么意思？" 我只能翻代码查。

现在我用标准的 HTTP 状态码 + 详细错误信息：
```json
{
"error": {
"code": "INVALID_PARAMETER",
"message": "手机号格式不正确",
"details": {
"field": "phone",
"value": "123"
}
}
}
```
前端拿到错误码就能直接提示用户，不用再找我了。

4. 文档缺失，接口变黑盒

我最怕接手没有文档的项目。接口参数全靠猜，返回值全靠试。有一次我调一个支付接口，试了十几次才搞明白签名规则。

现在我的习惯是：接口写完立刻写文档。用 Swagger 或者 Apifox 自动生成，再手动补充业务逻辑。文档不是给别人看的，是给三个月后的自己看的。

5. 性能优化不足，接口慢如蜗牛

早期我写接口从来不考虑性能。一个列表接口返回所有字段，数据量大了直接超时。后来学了分页、字段过滤、缓存，才明白接口设计要提前考虑性能。

比如列表接口：
```
GET /products?page=1&size=20&fields=id,name,price
```
支持分页和字段选择，响应时间从 2 秒降到 200 毫秒。

总结

API 设计不是一蹴而就的，需要在实践中不断优化。我踩过的这些坑，希望你不用再踩。记住：统一命名、版本控制、规范错误、及时文档、性能优先。做到这五点，你的接口至少能及格。

这些都是我实实在在踩过的坑，希望对你有帮助。