接口设计三大原则：RESTful规范落地时这些细节最容易踩坑

RESTful规范看起来简单但真正落地时十个团队有九个踩坑。不是把GET换成POST就叫REST也不是URL里加个/api/v1就完事。下面这三大原则每一条都藏着容易被忽视的细节。原则一资源导向而不是动作导向REST的核心是“资源”URL应该表示名词HTTP方法表示动作。但很多团队写着写着就变成了RPC风格/getUserById、/deleteOrder、/updateProduct。这种写法不是REST只是用HTTP当传输协议的远程调用。正确的做法是URL只保留资源动作交给HTTP方法。查用户用GET /users/{id}删用户用DELETE /users/{id}更新用PUT /users/{id}。但这里有个坑PUT和PATCH怎么选PUT是全量替换PATCH是局部更新。如果你只改一个字段却用PUT客户端必须传完整对象否则没传的字段会被置空。很多团队为了省事全用PUT结果前端漏传字段导致数据丢失。正确做法全量更新用PUT局部更新用PATCH或者干脆统一用POST加/updates子资源。另一个坑是资源嵌套过深。/users/{id}/orders/{orderId}/items/{itemId}/reviews这种URL看起来符合REST但实际维护起来很痛苦。层级超过两层就应该考虑把子资源提升为顶级资源用查询参数关联/reviews?orderIdxxxitemIdyyy。原则二HTTP方法和状态码要用对别糊弄很多团队所有接口都返回200然后在body里写{code: 500, msg: 失败}。这是最典型的RESTful踩坑。HTTP状态码本身就是语义的一部分用对了客户端、网关、监控系统都能自动识别。常见错误对照创建成功应该返回201 Created而不是200删除成功返回204 No Content而不是200带个空body参数校验失败返回400 Bad Request未登录返回401 Unauthorized无权限返回403 Forbidden资源不存在返回404 Not Found服务器异常返回500。但注意404不要滥用。如果查询列表返回空数组应该是200不是404。404只表示“这个资源不存在”不表示“查询结果为空”。另一个高频坑是POST和PUT的幂等性。POST不幂等PUT幂等。如果你用POST做更新网络超时后客户端重试可能产生重复更新。正确做法创建用POST全量更新用PUT局部更新用PATCH删除用DELETE。幂等性设计是RESTful的底线别为了省事全用POST。原则三URL设计要一致版本管理要克制URL是接口的门面一致性比“好看”更重要。常见坑包括大小写混用/Users和/users并存、单复数混用/user和/orders、连字符和下划线混用/user-orders和/user_orders。统一规则全小写、用连字符、资源用复数。/users、/order-items、/payment-records。版本管理是另一个重灾区。很多团队上来就/api/v1/users结果v1还没稳定就出了v2维护两套代码苦不堪言。正确做法版本号只在破坏性变更时引入。新增字段、新增接口不需要升版本删除字段、修改字段类型、改变语义才需要。而且版本号不要放在每个URL里可以放在域名或Header中api.example.com/v1/users或Accept: application/vnd.example.v1json。URL里的版本号越少越好否则每个接口都要改。还有一个隐藏坑分页、排序、过滤的参数不统一。有的接口用page和size有的用offset和limit有的用pageNum和pageSize。客户端每调一个接口都要查文档体验极差。统一规范?page1size20sortcreatedAt,descstatusactive。所有列表接口都遵守同一套参数命名这才是RESTful落地的细节功力。总结RESTful不是宗教不必死守每一个字母。但既然选择了这套规范就要把资源导向、HTTP语义、URL一致性这三大原则贯彻到底。落地时最怕两种极端一种是全用POST把REST当RPC另一种是过度设计嵌套五层资源、每个接口都带版本号。好的接口设计是让调用方不看文档也能猜出七八分。记住URL给资源方法给动作状态码给结果一致性给体验。这四点做到你的接口就超过了80%的团队。