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

刚做后端那会儿，我对 API 的态度很简单——能调通就完事了。后来被坑多了才明白，API 设计这东西，前期省的事后期全得还回来。

先说命名这事。我最开始的接口长这样：

GET /getUserInfo
POST /createOrder
GET /fetchProducts

单个看都挺清楚，但团队一扩，每个人都有自己的命名习惯。有人用 get_，有人用 fetch，有人驼峰有人下划线。接口文档越来越厚，新来的同事问"查用户到底调哪个接口"，我得翻半天才说得清。

后来统一改成 RESTful 风格，资源用名词复数，操作用 HTTP 方法表达：

GET /users/{id}
POST /orders
GET /products

刚开始觉得别扭，多写了几个接口就习惯了。半年后回头看，接口路径看一眼就知道在干嘛，不用再翻文档了。

版本控制也吃过亏。有次改一个用户接口的返回字段，想着小改动直接上了。结果移动端的旧版本还在用，一改前端直接崩。那次之后所有接口都带了版本号：

GET /v1/users/{id}
GET /v2/users/{id}

新功能放 v2，老版本继续跑。多一层路径而已，升级的时候不用提心吊胆。

错误处理这块我以前特别敷衍，接口挂了就返回 {"code": 1, "msg": "error"}。前端同事跑来问"error 是什么意思"，我就去翻代码。后来改成 HTTP 状态码加具体错误信息：

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "手机号格式不对",
    "details": { "field": "phone", "value": "123" }
  }
}

前端拿到就能直接给用户提示，不用再来找我了。

文档这事我也栽过。接手过一个项目，接口参数全靠猜，返回值全靠试。有个支付接口调了十几次才试对签名规则。后来养成的习惯：写完接口就写文档，用 Swagger 或者 Apifox 生成基础结构，再补业务说明。这玩意儿不是给别人看的——三个月后的自己才是最大的受益者。

性能这块早期完全没概念。一个列表接口不加分页不加字段过滤，数据量一上来就超时。后来学乖了，接口默认支持分页和字段选择：

GET /products?page=1&size=20&fields=id,name,price

响应时间从 2 秒降到 200 毫秒，改动其实不大。

干这行几年下来，觉得 API 设计没有什么一步到位的秘诀。命名统一、带版本、错误说人话、写文档、提前想性能——这些都不是什么高深的东西，只是踩过坑之后自然就会注意了。