REST API 设计规范整理一下我自己写接口踩过的坑前言最近在整理自己项目里的后端代码翻到几个月前写的接口发现问题挺多的。比如接口路径长这样GET /getUserList GET /getUserById?id1 POST /updateUser POST /delUser然后所有接口不管成功失败都返回 200错误信息全塞在一个 code 字段里。结果就是前端调接口经常来问我这个 code 是什么意思我这边每加一个接口还得重新解释一遍联调效率挺低的。后来参考了一些资料把接口重新设计了一下前后端沟通顺畅了很多。这里把我整理出来的 REST API 设计规范记录一下都是我自己在用的可能不全面但至少把我踩过的坑避开了。一、REST 的核心思路REST 这个名词听着挺唬人其实核心就是一句话用 URL 定位资源用 HTTP 方法表示动作用状态码表达结果。一个接口拆成这三部分语义就清楚了调用方看 URL 和状态码基本能猜到接口是干什么的。一个 HTTP 请求URL 定位资源HTTP 方法表达动作状态码表达结果/api/v1/todos —— 我要操作待办/api/v1/todos/123 —— 具体某一条GET 查询 / POST 新建 / PUT 整体更新 / PATCH 局部更新 / DELETE 删除2xx 成功 / 4xx 客户端问题 / 5xx 服务端问题二、URL 怎么设计2.1 资源用名词动词交给 HTTP 方法我之前喜欢把动词写进 URL比如/getUser、/updateUser。正确做法是资源用名词动作由 HTTP 方法表示我原来写的改成GET /getUserListGET /api/v1/usersPOST /updateUserPUT /api/v1/users/{id}POST /delUserDELETE /api/v1/users/{id}两个注意点集合资源用复数users单个资源用users/123不要user、users混着用容易让前端混乱2.2 用层级表达资源关系有从属关系的资源可以嵌套GET /api/v1/users/123/orders # 查某用户的所有订单 GET /api/v1/users/123/orders/5 # 查某用户的某个订单不过嵌套别超过三层太深了说明资源拆得有问题或者应该用查询参数。比如查某用户已支付的订单GET /api/v1/users/123/orders?statuspaid而不是/api/v1/users/123/orders/paid把状态当子资源不太合适。2.3 建议加上版本号接口大概率会改一改前端就可能崩。比较省事的方式是在 URL 里带版本/api/v1/users /api/v2/users就算第一版只有一个版本写上/v1成本也很低后面要升级直接加个/v2就行不用动旧接口。三、HTTP 方法的使用我见过有人把增删改查全写成 POST这样接口语义就乱了。用对方法会清晰很多方法作用幂等性场景GET查询幂等查列表、查详情POST新增不幂等创建资源PUT整体更新幂等更新整个资源PATCH局部更新不幂等只改某个字段DELETE删除幂等删除资源幂等的含义同一个请求执行一次和执行一百次结果一样。GET、PUT、DELETE 应该幂等POST 不幂等每次都会新建一条。我之前踩过的一个坑用 POST 做更新订单状态前端网络重发了一次状态被改了两次数据就乱了。改成 PUT 之后重发也没问题。四、状态码的选择这个改完收益比较大。之前错误全靠 code 字段猜现在看 HTTP 状态码就行状态码含义什么时候用200成功查询、更新成功201已创建POST 新建资源成功204无内容删除成功无返回体400参数错误参数缺失 / 格式不对401未认证没登录或 token 失效403无权限登录了但没权限404资源不存在URL 或资源找不着409冲突比如用户名已存在422语义错误参数合法但业务上不通过500服务器错误后端异常选状态码可以按这个流程判断不能参数缺失/格式错没登录/token失效登录了但没权限资源不存在业务规则不通过后端异常能新建资源更新/查询删除收到一个请求能正常处理吗?是哪类问题?400 参数错误401 未认证403 无权限404 资源不存在422 语义错误500 服务器错误做了什么操作?201 已创建 Location200 成功204 无内容错误信息统一格式状态码能说明是哪类问题但具体哪里错了还得靠返回体。我统一成这种格式{code:40001,message:手机号格式不正确,details:phone 字段不合法应为 11 位数字}code业务错误码前后端约定好message给用户看的提示details给前端调试用的细节前端捕获到非 2xx 响应直接解析 body 里的 message 弹给用户基本不用再问后端。五、列表接口的参数列表接口一般都有分页、过滤、排序的需求参数规约好会省事很多参数说明示例page/page_size分页?page1page_size20过滤字段查询参数表达?statuspaidcategoryphonesort/order排序?sortcreated_atorderdescfields字段裁剪?fieldsid,name,price分页响应我一般这样返回{items:[],total:137,page:1,page_size:20,has_more:true}has_more让前端判断是否还有下一页比前端自己算当前页 × 页大小 total省心一些也少踩边界 bug。六、一个完整的例子以 Todo 接口为例需求接口获取待办列表GET /api/v1/todos?page1page_size20获取单个待办GET /api/v1/todos/123新建待办POST /api/v1/todos更新标题PATCH /api/v1/todos/123整体替换PUT /api/v1/todos/123删除待办DELETE /api/v1/todos/123一次新建待办的完整调用流程数据库后端服务网关/鉴权前端数据库后端服务网关/鉴权前端POST /api/v1/todos带 Token校验 Token转发请求参数校验INSERT 一条待办返回新记录201 Created 完整资源 Location请求POST /api/v1/todos Content-Type: application/json { title: 给接口写文档, done: false }响应HTTP/1.1 201 Created Location: /api/v1/todos/123 { id: 123, title: 给接口写文档, done: false, created_at: 2026-09-02T10:00:0008:00 }几个小细节新建成功返回 201 Location告诉前端新资源的地址直接返回完整的资源对象前端不用再发一次 GET 去拿时间用 ISO 8601 带时区前端解析比较友好Go 后端实现gin 框架typeTodostruct{IDint64json:idTitlestringjson:titleDonebooljson:doneCreatedAt time.Timejson:created_at}// 新建待办funcCreateTodo(c*gin.Context){varreqstruct{Titlestringjson:titleDonebooljson:done}// 参数解析失败400iferr:c.ShouldBindJSON(req);err!nil{c.JSON(400,gin.H{code:40000,message:参数错误,details:err.Error()})return}// 业务规则不通过422ifreq.Title{c.JSON(422,gin.H{code:40001,message:标题不能为空})return}// ... 落库成功返回 201 完整资源c.JSON(201,todo)}七、小结把我踩过的坑总结成几条URL 里只放资源名词动词交给 HTTP 方法别写/getUser这种版本号建议从第一天就加上/api/v1/成本很低状态码不要永远 200让调用方看状态码就能定位问题错误返回统一格式业务码 用户提示 调试信息幂等的操作用幂等的方法POST 别用来做更新分页响应带上 total 和 has_more前端用起来方便新建返回 201 Location 完整资源省一次往返以上是我自己整理的 REST API 设计经验不一定全对写出来记录一下。如果你有更好的做法或者哪里说得不对欢迎指出来正好我也学习一下。