RESTful API 接口设计规范：资源导向、HTTP 语义、统一返回格式、避坑指南

RESTful 是 Web API 主流架构风格核心思想是以资源为中心使用 HTTP 方法表达动作。很多项目伪 RESTURL 写大量动词方法滥用 GET/POST。本文系统讲解 REST 核心原则、URL 命名、HTTP 方法语义、状态码使用、统一返回体、分页、排序、嵌套资源、版本控制附带正反案例、开发踩坑清单适合团队接口规范制定、复习。前言REST 全称 Representational State Transfer表述性状态转移由 Roy Fielding 提出。REST 不是一个协议是一套架构设计风格基于 HTTP 协议特性。 REST 核心思想一切皆资源URL 代表资源HTTP 方法代表对资源的操作动作。反模式/getUser、/deleteOrderURL 里面带动词这不是 REST 风格。一、REST 核心设计原则资源使用名词推荐复数URL 描述资源集合不要描述动作。推荐 GET /users 获取用户列表 GET /users/100 获取id100单个用户 POST /users 创建用户 PUT /users/100 全量更新用户 PATCH /users/100 局部更新用户字段 DELETE /users/100 删除用户 错误示范 GET /getUserList POST /createUser DELETE /deleteUser正确使用 HTTP 方法遵守语义、幂等、安全特性方法含义幂等安全适用场景GET查询资源是是只读查询不修改数据POST新建资源否否新增记录PUT全量替换资源是否完整覆盖更新不存在则新建PATCH局部更新否否只更新部分字段DELETE删除资源是否删除资源无状态 每个请求包含全部信息服务端不保存客户端会话状态认证信息Token放在请求头。资源可以嵌套父子资源GET /users/100/orders 获取用户100的订单列表 POST /users/100/orders 为用户100创建订单嵌套层级建议最多 2 层不要无限嵌套。二、URL 规范细节全部小写横线-分隔单词禁止下划线、驼峰/user-address而不是/userAddress、/user_address根路径增加 api 前缀区分业务接口/api/users查询参数放 queryString用于过滤、分页、排序GET /api/users?page1size10status1sortcreateTime,desc三、HTTP 状态码合理使用不要全部接口统一返回 200业务错误放在 code 字段这是很多项目的伪 REST。查询成功200 OK创建资源成功201 Created响应头 Location 返回资源地址删除成功无返回体204 No Content参数错误400 Bad Request未登录 / Token 无效401 Unauthorized权限不足403 Forbidden资源不存在404 Not Found请求方法不支持405 Method Not Allowed参数校验失败422 Unprocessable Entity服务异常500 Internal Server Error现实开发折中方案很多团队仍然统一返回 200业务自定义 code。面试时区分标准 REST和企业落地折中方案。四、统一返回体设计企业落地最常用标准 REST 推荐直接返回资源实体国内项目为方便前端一般封装统一 JSON 结构。{ code: 200, msg: success, data: { id: 100, name: 张三 } }code业务码200 成功4xxx 客户端业务错误5xxx 服务异常msg可读提示信息data业务数据查询返回实体 / 数组删除成功可以为 null分页返回示例{ code:200, msg:success, data:{ records:[], total:100, current:1, size:10 } }五、附加规范版本控制、排序、过滤、搜索API 版本控制推荐路径版本/api/v1/users新增不兼容接口升级 v2。不推荐 Header 放版本。过滤query 参数?status1gender0排序?sortfield,asc?sortcreateTime,desc字段裁剪按需返回字段?fieldsid,name六、REST 常见误区 踩坑所有接口只用 GET 和 POSTPUT/DELETE 不使用URL 大量动词/api/updateUserGET 请求做数据修改操作违反安全原则缓存会误触发幂等接口没有保证幂等重试产生脏数据状态码滥用全部返回 200业务异常全部用自定义 code嵌套层级太深可读性变差。七、问答Q1RESTful 是什么核心原则AREST 是基于 HTTP 的资源导向架构风格。核心一切是资源URL 标识资源HTTP 方法代表动作无状态合理使用状态码。Q2PUT 和 PATCH 区别APUT 全量替换资源PATCH 局部更新部分字段。Q3幂等性是什么哪些 HTTP 方法天然幂等A多次请求服务端结果和一次请求相同。GET、PUT、DELETE 天然幂等POST 非幂等。Q4如何做 API 版本管理A路径版本/api/v1/usersHeader 版本参数版本项目推荐路径版本简单直观。结语RESTful 接口设计的本质是充分利用 HTTP 原生语义让接口语义自描述。实际开发不必追求完全严格 RESTRichardson 成熟度模型 Level3优先保证团队统一、前后端沟通简单。合理的接口规范降低对接成本方便使用 Apifox/Postman 调试。