做过一段时间后端你会发现团队里最容易被忽略但又天天被吐槽的往往就是接口设计。我见过不少项目接口数量不多但风格千奇百怪有的 URL 里带着动词有的所有请求都返回 200有的状态码含义全靠前端猜RESTful API 设计规范与实践这个话题其实说的就是把这些“猜”变成“共识”。写这篇东西的起因是有个同事接手老项目后跑来问我为什么/getUserInfo这种接口越加越多加到最后自己都分不清哪些能复用原因是团队从一开始就没有把接口当作“资源”来设计而是当作“函数”来命名。今天我把这些年沉淀下来的一套 RESTful API 设计方法整理出来包括资源建模、URL 规范、方法语义、状态码选型、分页过滤、版本管理、安全认证以及团队落地时容易踩的坑尽量讲得能直接用。1. REST 到底在约束什么先把接口当资源而不是函数1.1 资源抽象是最基础的一步REST 的全称是 REpresentational State Transfer翻译过来是“表现层状态转移”。很多人听到这个概念就头大我换个说法REST 的核心是把服务器上的数据和功能都抽象成“资源”每个资源用 URL 唯一标识客户端通过 HTTP 方法对资源做操作。拿博客系统举例。传统的函数式接口风格可能是这样POST /createUser POST /getUserById POST /deleteUser你看这像不像在调用一个函数RESTful 风格则完全不同它把“用户”抽象成一个资源路径永远指向资源本身GET /users/{id} 查询某个用户 POST /users 创建一个用户 DELETE /users/{id} 删除某个用户区别在哪里前者关注“我要做什么”后者关注“我要操作哪个资源”。一旦你习惯了资源视角整个接口的扩展性会好很多。比如今天要增加一个“获取所有用户”的接口RESTful 风格就是GET /users而不是再新造一个/getAllUsers。用生活中的例子类比URL 是资源门牌号HTTP 方法是动作。你到一栋楼办事门牌号告诉你去哪动作决定了你进去是提交材料、查看材料还是搬走材料。而不是每办一件事都要给那扇门换一个新门牌。1.2 六个约束条件该守的守该灵活的灵活REST 严格来说是一组架构约束不是协议标准。它包含六大约束客户端-服务端分离前后端各自演进服务端不关心页面展示。无状态服务端不在请求之间保存客户端上下文每次请求自带完整信息。可缓存通过 HTTP 缓存机制减轻服务端压力。统一接口URL、方法、状态码等有稳定语义。分层系统网关、代理、负载均衡对客户端透明。按需代码服务端可以把逻辑下发给客户端实践中极少使用。实际项目里我认为最有价值的是“无状态”和“统一接口”。无状态让服务可以水平扩容因为每个请求不依赖之前的会话统一接口让前后端协作成本降低因为大家都用同一套语义。至于“按需代码”我在真实项目中基本没见人做它对大多数业务系统没有实际收益不必为了严格而严格设计规范是给人用的不是用来供奉的。1.3 不是所有场景都必须硬套 REST虽然这篇文章讲 RESTful但我还是想说REST 不是万能药。有些场景硬套 REST 反而别扭内部服务间的高性能 RPC比如用 gRPC基于 HTTP/2 多路复用二进制序列化性能比 JSON 高不少更适合链路复杂、对耗时敏感的内部调用。复杂聚合查询比如 BI 报表接口一次要聚合十几个数据源REST 资源模型表达起来很吃力GraphQL 反而更灵活。高频小数据量同步WebSocket 长连接或消息推送本身就不适合请求-响应模型。所以我的建议是对外 API、需要跨团队协作的接口优先 REST纯内部、性能敏感的场景按需选 gRPC 或消息队列。规范和信条之间选务实。2. URL 与资源设计先把接口当资源目录来规划2.1 名词优先集合用复数资源层级不过三URL 设计第一原则用名词不用动词。/users是资源/getUsers是行为资源可以被查询、创建、修改、删除行为只能被调用。当你开始把行为往 URL 里塞早晚会陷入接口爆炸的困境。具体到命名规范我统一遵循这几个约定集合资源用复数名词例如/books、/orders。单个资源用/books/{id}{id}是路径参数。子资源用嵌套关系表达例如/books/{id}/reviews表示某本书的评论。嵌套层级不要超过两层。超过两层说明资源边界没有划清楚。一律小写字母单词之间用连字符-不要用下划线也不要驼峰。举个例子获取“某用户在某店铺下的订单”可以设计成GET /customers/{customerId}/orders GET /customers/{customerId}/orders/{orderId}这看起来清晰但如果我们再往下嵌套一层GET /customers/{customerId}/orders/{orderId}/items/{itemId}/supplier/{supplierId}这就是个灾难。路径过长不仅难读还意味着服务端做了过多的关联查询性能和维护成本都会上来。遇到这种三到四层的“深嵌套”我更倾向于把它拆成独立资源GET /orders/{orderId}/items GET /suppliers/{supplierId}用户信息可以从 Token 或上下文里拿不要让 URL 把整个实体关系图都画出来。2.2 操作型接口的处理尽量用状态流转而不是动词命名业务中总有些动作天然带着“行为”色彩比如发布文章、审核订单、封禁用户。很多人下意识就会写POST /publishArticle POST /reviewOrder POST /banUser这种写法的问题在于每个动作都是一个新端点半成品前端很难归纳规律。我的处理方式分三种第一能用资源状态表达的就用状态。发布文章本质上是把文章的status从draft改成published那可以PATCH /articles/{id} Body: { status: published }第二状态表达不直观的用子资源动作。比如审核流程可能包含通过、驳回、撤回等多种动作都塞进PATCH会让 Body 变得不可预测这时可以POST /articles/{id}/publish POST /reviews/{id}/approve POST /reviews/{id}/reject这类端点本质上还是一个“动作资源”不算完全符合教条但可读性极强团队协作成本低。第三一定要上动词的关键操作建议把它归属到明确的资源之下例如POST /orders/{id}/cancel而不是裸的POST /cancelOrder。归属关系能让 URL 自己解释清楚“这个取消动作是针对哪个订单的”。2.3 参数放路径还是查询串看它是不是资源的标识新手最容易纠结的是参数到底放/books/{id}里还是放/books?id123里我的判断标准很简单你描述的是不是“资源的唯一标识”如果是放路径如果只是筛选条件、补充信息放查询串。/books/{isbn}isbn 唯一确定一本书放路径。/books?author张三category编程作者和分类是筛选条件放查询串。/books/{id}/reviews?page1page 是分页控制信息不属于资源标识放查询串。路径参数描述“是什么资源”查询参数描述“怎么筛选或控制返回结果”这样分界清楚了文档也好写。3. HTTP 方法与状态码语义一致前端才能少写分支3.1 方法语义你可能一直在误解 GET 和 POSTHTTP 方法不是随便用的每个方法都有严格的语义约束方法含义典型场景是否幂等GET查询资源不应该修改服务器状态获取文章列表是POST创建资源或触发复杂操作创建文章否PUT全量替换资源更新整篇文章是PATCH部分更新资源修改文章标题否实际可设计为幂等DELETE删除资源删除某篇文章是继续说幂等性因为这块特别容易被忽略。幂等指同一个请求执行一次和执行一百次结果是一致的。GET 执行一百次结果一样所以可靠DELETE 第一次删了资源第二次再删返回 404但从系统状态看资源已经不存在了也算幂等PUT 无论执行几次最终资源状态都一样算是幂等。POST 不幂等因为它每次都可能创建一个新资源。如果你点击“提交订单”按钮网络超时前端自动重试结果用户就收到了两张一样的订单。为了补救有两种常规方案一是服务端对频繁重复的 POST 做去重比如根据订单号或设备标识做唯一约束二是客户端生成幂等键放在Idempotency-Key请求头里服务端根据这个键缓存响应结果。支付、下单、消息发送这类敏感操作幂等设计是必须的。很多人习惯把所有操作都丢给 POST短时间内方便但前端缓存、代理重试、服务器日志排查都会变得很困难。方法语义选对后面很多问题就自动消失了。3.2 状态码选型别让前端靠“猜”来处理错误状态码是 HTTP 层面的“结论”它不该为业务细节负责但应该表达清楚结果类型。我见过最头疼的接口就是无论成功失败都返回 200然后业务错误全放在响应体的字符串里。这样前端每次请求都要先拆 JSON 看 code再判断是否真的成功遇到网络层错误和业务错误混在一起排查问题难度翻倍。正确做法很简单用 HTTP 状态码表达请求结果的大类用响应体表达业务细节。常用选型如下状态码含义使用场景200OK查询、更新成功201Created资源创建成功返回 Location 头指向新资源204No Content删除成功或无需返回资源体400Bad Request请求参数有误语义错误401Unauthorized未认证缺少登录态403Forbidden已认证但无权限404Not Found资源不存在405Method Not Allowed方法用错例如只支持 POST 的路径收到 GET409Conflict与现状冲突例如更新了已被他人修改的资源422Unprocessable Entity参数格式正确但业务校验不通过429Too Many Requests触发限流500Internal Server Error服务端异常503Service Unavailable服务不可用通常伴随维护或过载我特别想提醒一个容易被混淆的点401 和 403 的区别。401 表示“你是谁我需要先知道你”对应未登录、Token 缺失或过期403 表示“我已经知道你是谁但你不被允许做这件事”对应权限不足。如果登录了但没权限返回 401就会让前端错误地触发“跳登录页”的逻辑。3.3 响应体结构成功和失败要区分但不要层层包装响应体的结构我不建议搞“万能包装”。比如所有响应都包一层{ code: 0, message: success, data: { ... } }短期内看起来统一长期维护会很麻烦不同类型的数据被封进 data 里后类型信息变淡文档和类型定义都更难维护。我的偏好是成功响应直接返回资源本身错误响应统一格式。成功返回示例{ id: 123, title: RESTful API 设计实战, status: published, createdAt: 2025-01-15T10:00:00Z }错误响应统一格式{ error: { code: ARTICLE_NOT_FOUND, message: 文章不存在或已被删除, requestId: abcd1234 } }code是业务错误码message是给人读的描述requestId是关联日志用的链路标识。前端判断错误时先看 HTTP 状态码确定大类再看error.code决定展示逻辑层级少心智负担小。4. 分页、过滤、排序、版本细节决定协作体验4.1 分页选型分页风格要匹配数据规模分页是最容易被“随便设计”的细节也是影响性能最大的细节之一。我更愿意把分页分成两类来选第一类是页数分页适合后台管理、数据量在十万级以内、用户需要跳页的场景。常用参数是page和page_size响应里带上总数{ items: [ ... ], pagination: { page: 1, pageSize: 20, total: 834, totalPages: 42 } }这种方案对用户友好可以快速跳到任意一页。但数据量大时total查询和深翻页比如 page10000会拖垮数据库因为后端需要跳过很多偏移量。第二类是游标分页适合 C 端业务、数据量大、持续增长的场景。参数是cursor和limit响应用nextCursor指向下一批{ items: [ ... ], nextCursor: eyJpZCI6MTIzNCwidGltZSI6IjIwMjQtMDItMDFUMTg6MDA6MDBaIn0 }游标分页不做“跳过多少行”的动作性能稳定但我个人觉得它有三个小代价不能直接跳到任意页游标如果被篡改可能产生边界问题前端展示“共多少页”时需要额外接口。所以我的选择标准一直是后台表格用页数前台信息流用游标。4.2 过滤与排序统一查询参数约定过滤条件我推荐全部放查询串推荐统一风格GET /articles?statuspublishedcategorytechtagjavacreatedAfter2024-01-01字段命名统一用一个小写风格要么全camelCase要么全snake_case不要混。排序建议用sort参数字段前加负号表示倒序GET /articles?sortcreatedAt,-views这条查询的意思是按createdAt升序再按views降序。相比在查询串里写order_bycreated_at_desc这种风格更紧凑也好在代码里解析。4.3 版本管理路径版本最省心但要想好弃用策略接口一定会变所以版本管理要一开始就定下来。目前业界常用三种URL 路径版本/v1/articles最直观。媒体类型版本Accept: application/vnd.myapp.v1json请求头复杂调试要额外配置。查询参数版本/articles?version1不透明容易被忽略。我强烈推荐路径版本/v1/...原因只有一句话直观得不需要任何文档解释。浏览器、抓包工具、调用方代码里一眼就能看清当前用的是哪个版本。配合网关做流量切分也简单。版本策略上还要定两个规则小版本兼容扩展只新增字段不修改已有字段语义大版本破坏性升级旧版本要给出废弃时间表建议至少保留半年到一年同时在响应头加Deprecation: true提示调用方提前迁移。5. 安全与合规认证、授权与限流不能临时补5.1 认证按调用方类型选方案认证方案的选择我一般先看“谁在调用”服务端到服务端的内部调用用 API Key 或 mTLS。API Key 简单服务端可以限制 IP、前缀、有效期mTLS 更安全但运维复杂度高适合银行、政务系统。第三方应用授权场景按客户端标识和用户授权需求用 OAuth 2.0。它支持授权码模式、客户端凭证模式等多种流程能让用户不暴露密码给第三方应用。纯前后端分离、由自己控制登录态的 Web 应用用 JWT 是最常见的做法。JWT 带来的主要好处是无状态服务端不用保存会话。但 JWT 有几个细节要特别注意过期时间不要设置太长建议 15 分钟到 1 小时配合刷新令牌延长会话。不要把敏感个人数据放进 tokenJWT 默认只是 Base64 编码不是加密。签名密钥要独立管理服务端环境变量或密钥系统统一管理不能提交到代码库。注销是一个弱项真正的立即失效很难做到需要结合黑名单或短过期时间。5.2 授权越权是比漏认证更容易犯的问题有认证还不够越权防护是 API 安全的高频重灾区。我把越权分两类水平越权和垂直越权。水平越权是指普通用户 A 通过修改 URL 里的 ID拿到了普通用户 B 的数据比如GET /users/12345/orders服务端如果只做了“是否登录”判断没判断“当前用户是否是 12345”那这个接口就是裸奔的。垂直越权则是普通用户访问了管理员接口比如访问/admin/users。水平越权比垂直越权更容易被忽略因为团队往往只测“登录用户能做什么”没测“用户是否只能操作自己的资源”。解决思路很简单在所有访问用户私有资源的接口里从上下文拿到当前用户的身份再做所有权校验。可以用一个基础的资源所有权检查层把“资源归属身份”和“当前身份”比对逻辑统一封装。5.3 参数校验、限流与传输安全参数校验看似基础却是防止脏数据进入系统的第一道门。每个入参都要定类型、长度、枚举值、格式。不要指望前端帮你校验后端必须全部重新校验一遍。比如status字段形如published、draft、archived枚举外的一个值就该返回 422而不是静默降级。限流方面对外 API 如果完全不做某个异常客户端的一次死循环就可能把服务打挂。业界常见算法有固定窗口、滑动窗口、令牌桶。我建议网关或中间件统一做直接返回 429并带上Retry-After头告诉调用方多久后重试。传输安全上线上环境必须 HTTPS这是底线。CORS 白名单要收紧不能随便配*尤其是携带 Cookie 或认证头的请求。日志里不能打明文密码、Token、手机号等敏感字段脱敏逻辑要在打印前统一过滤。6. 完整实操设计一套内容管理 API示例全过程6.1 业务场景与资源梳理这一节我用一个虚构的“内容管理平台”来演示完整过程。平台里有作者、文章、文章分类、标签、评论。现实中这个场景很典型核心实体关系算不上复杂但足以覆盖 RESTful 设计的主要决策点。资源清单/v1/articles文章/v1/users用户作者/v1/categories分类/v1/tags标签/v1/articles/{id}/comments评论我把“用户”和“文章”设计为主资源评论作为文章的子资源这样 URL 层级刚好是两层结构清晰。6.2 端点清单方法路径说明结果GET/v1/articles文章列表支持筛选排序分页200POST/v1/articles创建文章草稿201GET/v1/articles/{id}文章详情200PUT/v1/articles/{id}全量更新200PATCH/v1/articles/{id}部分更新200DELETE/v1/articles/{id}删除文章软删除204POST/v1/articles/{id}/publish发布文章200GET/v1/articles/{id}/comments评论列表200POST/v1/articles/{id}/comments发表评论201DELETE/v1/comments/{id}删除评论204GET/v1/categories分类列表200GET/v1/tags标签列表200组合起来这套端点基本能覆盖内容平台的日常需求。注意这里我把“发布”做成了动作型端点而不是用 PATCH 修改状态原因是发布这个动作还伴随状态校验、生成摘要、更新计数等副作用独立成动作更清晰。6.3 关键接口细节与代码示例创建文章的请求和响应POST /v1/articles Content-Type: application/json { title: RESTful 设计实践, categoryId: 3, tagIds: [1, 5], content: # 文章正文... }响应201 Created Location: /v1/articles/1024 { id: 1024, title: RESTful 设计实践, status: draft, categoryId: 3, tagIds: [1, 5], createdAt: 2025-03-01T10:00:00Z, updatedAt: 2025-03-01T10:00:00Z }查询文章列表带筛选分页排序GET /v1/articles?statuspublishedcategoryId3sort-publishedAtpage1pageSize20删除文章这里用软删除实现。为什么不用硬删除因为文章被删除后评论、统计引用还可能存在硬删除会引发关联数据断裂。软删除只是把deletedAt字段置为当前时间查询时默认过滤掉代价低且容易恢复。发布文章POST /v1/articles/1024/publish响应返回200文章状态变为published同时带上发布时间{ id: 1024, status: published, publishedAt: 2025-03-02T08:30:00Z }评论资源的设计我建议保持它和文章的子资源关系因为评论天然从属于文章查询入口也常从文章进入。但删除评论可以走/v1/comments/{id}因为评论一旦创建它有自己的全局 ID 更方便直接定位。6.4 错误响应示例例如请求了一个不存在的文章HTTP/1.1 404 Not Found { error: { code: ARTICLE_NOT_FOUND, message: 文章不存在或已被删除, requestId: 8ab7f3c2 } }如果文章创建失败因为分类不存在HTTP/1.1 422 Unprocessable Entity { error: { code: CATEGORY_NOT_FOUND, message: 指定分类不存在, requestId: 91d2e5ba } }这里的关键思路是状态码说明请求结果足够清晰具体业务问题由code给到前端精确判断。7. 团队协作把规范从文档变成可执行的共识7.1 用 OpenAPI 描述接口别让文档落后于代码接口规范只存在口头和 wiki 里很快就会被绕过。我强烈建议团队用 OpenAPI 3.0 写接口描述文档第一次就把它作为接口的唯一事实来源。下面是一个简单的 OpenAPI 片段paths: /v1/articles: get: summary: 查询文章列表 parameters: - name: status in: query schema: type: string enum: [draft, published, archived] - name: page in: query schema: type: integer default: 1 responses: 200: description: 文章列表 content: application/json: schema: type: object properties: items: type: array items: $ref: #/components/schemas/Article pagination: $ref: #/components/schemas/Pagination有了这个文件可以自动生成在线文档、Mock 服务前端团队也可以在接口未完成时就按约定并行开发。工具链上展示用 Swagger UI联调用 Apifox 或 Postman 都是可以的关键不是工具选择而是所有人都以 OpenAPI 文件为基准。7.2 在评审和 CI 里卡规范规范要落地一定得有“卡点”。我所在的团队曾试过完全靠人工评审结果接口风格逐渐漂移后来在 CI 里加了规范检查情况才好起来。有两个实用的卡点第一代码评审检查清单固定化。评审接口变更时必须核对 URL 命名是否名词复数、方法语义是否正确、状态码是否选型合理、错误码是否在字典里注册、分页参数是否统一、是否做了越权校验。把清单贴在 PR 模板里比口头提醒可靠得多。第二用规则引擎检查 OpenAPI 文件。可以用开源规则工具对文档做自动 lint比如要求所有路径以/v1/开头所有路径不许出现动词所有响应必须定义错误结构等。CI 不过就不合代码强制约束会自动纠正团队习惯。7.3 变更流程兼容优先废弃要有时间表接口变更最怕“突然改”。字段改名、删除参数、修改枚举值对调用方都是破坏。我给团队定的流程是新增字段完全兼容直接加不需要大版本。新增接口没影响按规范加。修改字段语义破坏性必须升大版本不能偷改。废弃接口保留旧版本至少 6 到 12 个月提前在响应头加Deprecation: true并在文档中明示迁移方案。8. 常见问题与踩坑实录这些坑我基本都掉过8.1 错误码和 HTTP 状态码到底怎么分工这是我被问到最多的问题也是很多团队设计混乱的根源。我建议把握一个原则HTTP 状态码描述“请求的分类结果”业务错误码描述“具体业务原因”。比如用户余额不足返回 422 加业务码INSUFFICIENT_BALANCE前端可以精确提示而不要返回 200 加code: 50001然后前端去查表那是把 HTTP 语义白白浪费掉。8.2 关于“接口是否要统一包一层”的争论这个问题业界吵了很多年。我的最终选择上面已经说过成功不包装错误统一包装。成功返回直接是数据调用方拿到的就是类型干净的资源错误响应自带结构前端可以统一拦截。中间态没有了data.message那层冗余实际联调中非常省心。8.3 嵌套资源深了以后接口会变得难维护我踩过把资源嵌套设计到三层的坑。后来发现一旦订单、用户、商品形成三层嵌套接口路径又长又绕还逼着服务端做大量级联查询。现在我的规则很明确嵌套最多两层。再深的关系要么把中间资源提升为独立资源要么通过查询参数关联不要硬凹层级。8.4 超时重试一定要考虑幂等压测时发现过一个高频问题客户端因为网络抖动发起了重试结果重复创建了多条评论。归根结底所有“提交型”接口都要考虑幂等。方案追加一条带业务幂等键的 POST重试不会重复创建不带幂等键的 POST则在业务字段上做唯一约束比如订单号、手机号加校验。这个设计越早做越好等数据脏了再清理成本高得多。8.5 一个小习惯写接口前先问自己三个问题最近几年我总结了一个小习惯开写任何接口前先问三个问题这个 URL 是不是明确指向一个或多个资源别人只看方法名和状态码能不能理解发生了什么如果用户恶意篡改参数会不会导致越权或脏数据三个问题都通过这个接口大概率是合格的。如果有一个回答不上来说明设计还没想透。最后再分享一个从教训里换来的经验接口规范这件事最怕的不是定不好而是不定。哪怕开始只有几条朴素的约定也比没有强。RESTful API 设计的本质是让团队在沟通接口时少说废话、少猜意图。尽早定一套属于自己的规范然后坚持下去你会发现前后端协作的摩擦小得多。