接手一个老项目的时候我看了下接口文档心里凉了半截。文档里齐刷刷地写着/api/getUserList、/api/doUpdateUser、/api/delOrder动作写满了路径一眼望去像是给服务号写开放接口而不是在做一个前后端分离的产品。我叹了口气把项目组成员叫到会议室第一句话就是“我们先聊聊什么是真正的REST风格。”这大概是很多团队的真实写照大家嘴上都在说RESTful简历上都写着常年使用REST风格设计接口但真正拿出来的东西十个里有八个只是“长得像REST”。URL换成了名词、把POST换成PUT就算完成了却完全没有理解REST作为一种架构风格背后的原则。这篇文章我不打算再给你复述一遍教科书定义我想从一名一线开发者的角度把REST风格的来龙去脉、设计取舍、实际落地经验以及那些最容易踩的坑都拆开讲清楚。不管你是刚接触接口设计的新人还是正在为团队推行API规范的老手应该都能在里面找到点用得上的东西。1. 很多人理解的REST其实只是“长得像REST”1.1 动词型URL与REST之间的鸿沟先说说“长得像REST”是什么感觉。一个团队说自己会REST实际做的却是把/api/getUser改成/api/user把/api/deleteUser改成DELETE /api/user?id1。路径里确实没有动词了HTTP动词也换成了对应的语义看起来挺像那么回事。但真正的REST不是URL风格而是一套约束下的架构风格。REST这个缩写来自“表征状态转移”Representational State Transfer它讨论的是在分布式系统中客户端和服务端之间如何通过资源的概念互相交互。URL只是其中一个很表面、很小的组成部分。如果把REST比作一套交通规则URL命名充其量只是路牌上的字体真正管用的是红绿灯设置、车道划分和行人优先这些底层的制度安排。实际开发里动词型URL带来的问题远不只是“不优雅”。它破坏了资源的可预测性。一个接口叫/api/getUserList另一个叫/api/userList还有一个叫/api/queryUsers前端对接时要反复翻文档才能弄明白每个接口到底是干嘛的。而当所有接口都统一成“名词HTTP方法”的格式后调用方天然就能猜出接口的行为这种可预测性在前后端并行开发时价值极高。1.2 所谓“REST风格”里常见的三处遗漏很多团队在推行REST风格时只把精力放在了路径命名上却忽略了另外三件更重要的事情。第一是HTTP方法语义的完整性。不少项目无论什么操作都用POST创建用POST、更新用POST、删除也用POST。这导致接口的语义信息完全丢失。REST风格要求尽量利用HTTP本身提供的动词与语义GET负责查询、POST负责创建、PUT负责整体替换、PATCH负责局部修改、DELETE负责删除。这样做的价值不仅在于“规范”更在于让网关、缓存、监控这些基础组件也能理解接口的行为。比如网关可以天然识别出GET请求是可以缓存、可以重试的而对POST请求要做特殊处理。第二是状态码的语义化。很多后端工程师无论成功失败都返回HTTP 200然后把业务码放在响应体的code字段里。从REST的角度看状态码本身就是响应的一部分它应该用来表达本次请求的处理结果。错误有错误的码权限有权限的码资源不存在有不存在的码。如果所有情况下都返回200意味着协议层面的信息完全被浪费了调用方只能层层剥开body才知道发生了什么。第三是超媒体与自描述性。REST的完整定义里有一个常被忽略的约束HATEOAS也就是超媒体作为应用状态的引擎。简单说服务端返回用户数据时可以顺带返回相关的链接告诉客户端接下来可以去哪里。比如订单资源返回后附带cancel、pay这些操作的链接。这个理念在市面上绝大多数业务系统里都没有落实因为确实会增加不少工作量。但至少设计接口时应该知道这件事的存在而不是完全没听过。1.3 为什么“长得像REST”反而更危险如果完全不懂REST倒是无所谓接口写错了也会有人指出。最怕的是那种“半桶水”式的REST路径从动词改成了名词HTTP方法也用对了看起来已经“达标”了但内部设计仍然是RPC思维。这种项目在外人面前有模有样实际维护的时候同样会陷入混乱。举个例子。一个订单系统为了兼容“查询待支付订单”和“查询已发货订单”两个场景接口设计成/api/order/pending和/api/order/shipped。路径是名词了却没有意识到这两个接口其实是一个资源订单集合在不同过滤条件下的两种视图。正确做法应该是一个/api/orders?statuspending把参数交给查询条件处理。前者导致每增加一种订单状态就要新增一个接口接口数量会随着业务状态膨胀后者只需要在参数层面做扩展后端增加一个枚举判断即可。这就是我想说的核心问题REST风格的重要价值之一是收敛接口数量用统一的方式表达一类操作。如果只学了皮毛而没有理解背后的资源抽象就会在表面的合规之下保留着RPC的放荡不羁最后接口越写越多、越写越乱大家还都觉得自己的设计挺REST。2. 回到源头一篇博士论文和六个约束2.1 从论文到互联网主流API风格REST这个词最早出现在Roy Fielding在2000年发表的博士论文《架构风格与基于网络的软件架构设计》里。那时候可没有什么前后端分离更没有移动端App要对接后端API的概念。Fielding是HTTP协议的主要作者之一也是后来Apache基金会的重要人物。他研究的是互联网这种大规模分布式系统到底应该遵循什么样的架构风格才能保证它能够持续演进、承受住Web规模的并发压力。这篇论文里Fielding基于对早期Web架构的分析抽象出了一组约束称其为REST。这组约束并不是拍脑袋想出来的而是从互联网的实践中反推出来的架构原则。有意思的是这篇论文诞生后很长一段时间里真正理解它的人并不多。REST开始大规模流行是在2007年前后Rails框架把RESTful Routes作为默认路由方式写进了框架之后。后来各种框架纷纷跟进前后端分离成为主流REST风格的接口设计才真正变成工程师的必修课。这里可以打个比方。REST就像城市规划里的分区制度它规定了住宅区、商业区、工业区应该分开道路应该按等级划分。至于每个小区里种什么树、刷什么墙是细节问题。很多人只学到了“道路刷成淡黄色”这种表面特征却没有理解分区制度是为了解决城市蔓延、交通拥堵这些问题。2.2 六大约束和它们各自解决什么问题REST架构风格由六个约束组成我来逐个说一下它们的内涵。第一个是客户端-服务器分离。客户端只管展示与交互服务端只管数据存储与业务处理两者独立演化。这是分布式系统最基本的解耦方式也是Web能发展出这么多前端框架、移动端技术栈的前提。很多团队当初推行前后端分离本质上就是在落实这个约束。第二个是无状态。服务器不能在请求之间保存任何上下文信息。每一次HTTP请求都应该携带足够的信息让服务器能够独立处理。有人会觉得这很别扭因为有状态的设计写起来更自然比如登录状态存在服务端session里多方便。但无状态约束保证了服务器的可伸缩性。如果一个服务器挂掉了另一台服务器可以直接接管请求不会因为“这台机器上有用户登录状态”而服务不了。它在牺牲一点点开发便利性的同时把水平扩展这个能力拿到了手。现代系统通常用Token、JWT这些方式配合无状态约束让认证信息随请求头携带而不是存在服务端的session里。第三个是缓存。服务器返回的数据可以标记为可缓存客户端拿到响应后可以在一段时间内不用再发请求直接用缓存的副本。这个约束对Web性能优化意义重大。在实际API设计中GET请求默认就是可以被缓存的而POST、PUT这些非安全方法则会穿透缓存系统。理解了这点就不会在业务里滥用POST来替代所有请求了。第四个是统一接口。这是REST最核心的一个约束也是被理解得最浅的一个。统一接口可以拆成四个子约束资源识别、通过表示对资源进行操作、自描述消息、超媒体作为应用状态的引擎。翻译成大白话客户端不直接操作数据库而是操作资源的表示通常就是JSON请求与响应里携带着足够描述自己意图的信息客户端基于资源状态和超媒体链接来推进应用流程。这四个子约束是REST与普通RPC接口最大的区别。第五个是分层系统。允许系统由多个层级组成客户端不需要关心它访问的到底是直接提供数据的服务还是中间层的代理、网关或负载均衡器。这个约束给了系统极大的灵活性比如加一层CDN缓存静态资源加一层API网关做鉴权和限流客户端完全不知情。第六个是按需代码。服务器可以通过返回可执行代码比如JavaScript、Flash插件扩展客户端的功能。这是REST里唯一一个可选约束在实际业务API中几乎用不上。2.3 约束不是束缚是取舍的依据很多人谈到REST的约束就头疼觉得“这也限制那也限制”不如直接想怎么写就怎么写。但约束恰恰提供了决策依据。举个现实中的例子。很多公司内部服务之间直接使用HTTPJSON接口路径写得很随意根本没有统一接口的约束。这种做法的代价是什么一旦服务数量变多每一个接口的调用规则都需要额外文档记录前端的对接成本高后端改动也容易被上游调用方偷偷破坏。REST约束就是在逼你把“资源的表述方式”稳定下来让接口变成一种可以被理解、被信任的契约。它当然有局限如果一个操作本质上就不是资源操作硬套REST就会很别扭。此时应该选择更合适的RPC框架而不是非要在一棵树上吊死。这一点我在后面专门用一章来说。3. 资源思维先分清“名词”和“动词”再谈设计3.1 资源为什么要用名词而不是动词把接口设计成REST风格的第一课是学会用名词定义一切。订单是资源用户是资源商品是资源。而支付、取消、发货这些在REST风格里不是资源而是“对资源施加的操作”。但为什么资源和名词绑定而不是和操作绑定因为资源是稳定的分类操作是易变的行为。一个业务系统里核心资源往往就那么十几个用户、订单、商品、优惠券……而围绕资源展开的操作可能有几十上百个注册、登录、下单、付款、退款、发货、退货……。如果接口按操作来组织接口数量就会失去控制。按资源组织操作再多也可以收敛到几种标准的HTTP行为上。打个比方。如果你把图书馆的管理规则设计成“每本书附带一本说明书说明怎么借、怎么还、怎么预约”那每本书的说明书都不一样读者每借一本新书都要重新学习一道流程。而如果图书馆规定“所有书都遵循同一个借阅流程”读者只需要学一次换任何书都会操作。资源就是那本“被统一操作的书”HTTP方法就是那套“所有人都遵守的流程”两者结合接口自然收敛。3.2 路径设计的核心是层级与从属关系既然用名词表示资源路径自然就是一个个层层嵌套的名词组合。这里有两条设计原则需要掌握。第一路径的全部职责是定位资源不是传递行为。查询、创建、修改等行为交给HTTP方法过滤、排序、分页等条件交给查询参数不要把行为和动作塞进路径。这是最基础的一步。把/api/order/pay改为/api/orders/{id}/pay并没有解决本质问题“pay”仍然是动词。正确的做法要么是提供一个资源化的“支付单”来建模POST /api/payments带订单ID要么在刚引入REST风格时先用一个自定义方法过渡但明确这只是演进过程中的妥协代码里要做好隔离。总之路径设计要能体现出“这是一组资源操作方式由方法决定”的气息。第二路径有层级关系但层级关系应该表达“从属”而不是“路径”本身。最常见的子资源场景是“某个用户下的订单”/api/users/123/orders。这个设计告诉你“订单从属于用户”。但如果订单本身已是独立重要资源直接写/api/orders?userId123更合理。什么时候用嵌套、什么时候用平铺看资源和父资源之间的耦合度。订单即使离开用户也存在自己的生命周期通常用平铺评论如果不属于某篇文章就没有存在意义通常用嵌套。这是我设计接口时的一条实用判断标准。3.3 集合与单体一条URI对应一种资源粒度资源还可以进一步分为“集合资源”和“单体资源”。/api/users是用户集合/api/users/123是单个用户。这两个URI虽然是同一类资源的不同粒度但对应的HTTP操作组合完全不同。集合资源通常支持GET列出、POST创建单体资源通常支持GET获取、PUT整体替换、PATCH局部更新、DELETE删除。理解了这个粒度区分就不会出现“用POST /api/users/update”这种四不像的写法了。集合资源承载“批量”与“新增”语义单体资源承载“操作单个对象”语义权限控制、缓存策略、参数校验规则都可以依据粒度来设置。比如单体资源接口一般可以做细粒度的缓存集合资源接口的缓存会更复杂需要结合过滤条件考虑缓存失效的问题。这条规则还可以扩展到“容器类资源”的设计。例如公司有多个项目每个项目有多个成员/api/projects?orgId1或/api/orgs/1/projects再往下/api/orgs/1/projects/22这种路径虽然长但语义清晰。设计路径时只要始终问自己“这个资源是属于哪个父资源底下的”层级就会自然推出来。4. HTTP方法不是动词库是语义契约4.1 五个核心方法的语义映射REST风格中最容易出问题的地方之一是HTTP方法的使用。很多团队对方法的理解就停留在“GET用于查询POST用于新增DELETE用于删除”这是对的但远远不够。我给团队成员做培训时会把五个核心方法用一张表格列出来让大家每次写接口前先过一遍这张表。方法语义是否安全是否幂等典型场景GET获取资源的表示是是查询用户信息、获取订单详情POST创建资源或触发特定操作否否创建订单、注册用户PUT整体替换资源否是更新用户全部字段PATCH局部更新资源否否修改用户昵称DELETE删除资源否是删除订单、下架商品“安全”意味着这个请求不会修改服务器上的任何状态也因此可以被缓存、被预取。“幂等”意味着同一个请求执行一次和执行十次最终结果是一样的。这两个概念很多人分不清但它们在实际系统中影响很大。比如网络超时后自动重试如果请求方法是幂等的重试就是安全的如果不是幂等的重试可能产生重复订单那就必须靠业务层的唯一键去兜底。4.2 PUT与PATCH的差别比你想象的更重要更新接口是REST风格里争议最多的地方。有人习惯把所有更新都设计成PUT也有人喜欢全部用PATCH。我从实践中得出的结论是PUT代表“整体替换”PATCH代表“局部更新”两者适用的场景完全不同。什么时候用PUT当客户端有能力提供资源的完整表示时。比如修改一个用户资料前端把表单里的所有字段都提交上来服务端拿这份完整数据整体覆盖旧数据。这种情况下用PUT客户端和服务端的语义非常明确客户端说了算缺省字段就是置空服务端不用猜。什么时候用PATCH当客户端只需要提交变化的部分时。比如用户只修改了手机号提交的数据里只有phone字段其他字段服务端保持原样。这就是PATCH的用法。它的好处是数据量小服务端逻辑也简单只更新传入字段。但PATCH的代价是非幂等的因为服务端的当前状态会影响最终结果。比如同一份PATCH请求第一次执行时把数量从3改成5执行两次就变成7了。实际开发中PUT和PATCH的误用很常见。一个订单更新接口客户端想改一下收货地址却用PUT把整个订单都提交上来服务端要是没有做“空字段不更新”的保护这个设计就会吞掉订单里的其他字段数据。我的建议是除非接口明确要求客户端提交完整资源否则更新操作一律优先考虑PATCH。这样既省流量也避免覆盖风险。如果把PUT用于局部更新必须把所有可能缺失的字段都考虑成“不更新”这本身就是反直觉的。4.3 POST不止是“创建”还有“动作资源化”的艺术POST在REST风格里除了创建资源还有一个更微妙的用法表达“非CRUD操作”。类似“发货”“取消订单”“支付”“确认收货”这种操作它们本质是业务动作不是资源状态本身。强行用PUT或PATCH去表达要么语义不对要么参数很尴尬。最典型的是“取消订单”PATCH /api/orders/123传{status: cancelled}技术上说得通却不直观。业务上真正发生的是一系列动作取消库存、触发退款、发通知不是一个简单的状态变更。这种情况下业界有两种常见思路。一种是“动作资源化”把“取消”这个动作建模成一个子资源POST /api/orders/123/cancellation。这看起来很REST也确实是最贴近REST理念的做法因为动作被转化成了“资源状态的转移过程”。另一种思路是保留RPC式动作接口POST /api/orders/123/cancel路径里带了动词但因为是POST调用逻辑上排除在“资源定位”规则之外实践上也能接受。从我带团队的经验来看内部系统用第二种更省事对外API想追求风格的纯度可以用第一种。但无论选哪种都要守住一条底线只有POST可以承载语义不那么标准的动作接口GET、PUT、DELETE这些方法都应该严格对应它们的标准语义。5. 状态码选不对接口再准确也是半成品5.1 状态码是按协议说话不是业务码的备胎很多后端工程师是从零设计接口的没有系统学过HTTP语义。他们习惯把业务码放在JSON里{code: 10001, message: 用户不存在}然后让前端根据body里的code来写逻辑。这种做法从REST风格的角度看是把协议层的表达能力白白浪费了。HTTP状态码本身就是这次请求的结果摘要。它有三类信息量结果大类2xx成功、3xx重定向、4xx客户端错误、5xx服务端错误、具体语义200成功、201创建成功、204无内容、400参数错误、401未认证、403无权限、404不存在、409冲突、422无法处理、500服务器内部错误以及可缓存性2xx里有一些可缓存4xx一般不可缓存。接口设计者不利用这些信息前端就只能猜、只能把所有请求都当成200来处理再根据code做一次二次分发。这等于把网关、日志、监控系统本来就该具备的“按状态码告警”能力全部绕过了。5.2 按场景选状态码一张常用清单我整理了一张在业务API里最常用的状态码清单适合大多数RESTful接口场景。你不用背全部状态码记住这张清单基本上就够用了。场景状态码说明查询成功200返回资源列表或详情创建成功201必须在响应头里带Location指向新资源更新成功200 或 204返回完整新数据用200纯成功无内容用204删除成功204无响应体表示删除已完成参数错误400 或 422参数格式不对用400语义不对用422未认证401没带Token或Token失效禁止访问403认证了但没有权限资源不存在404路径错了或资源被删除状态冲突409例如订单已支付不能再次提交支付服务端错误500未捕获异常伴随错误日志服务不可用503依赖的下游服务挂了或服务在重启这里容易出问题的是401和403的区分。401表示“我根本不知道你是谁”403表示“我知道你是谁但你没有权限”。前者是认证问题后者是授权问题。很多前端工程师会把这两个混为一谈看到401就跳登录页导致403场景里用户被反复弹登录。接口设计时应该在错误响应体里写清楚原因便于排查。另一个容易忽略的是400和422的区别。400类状态码里最常用的是“参数格式错误”比如id传的不是数字。422则更适合表达“我的参数格式没问题但按照业务规则无法处理”比如仓库里库存不足下单失败。这两个状态码的区分能直接提升接口错误信息的可读性。5.3 错误响应体用统一结构封装问题细节光有状态码还不够错误响应体也需要统一设计。我不建议把错误信息只放在一个message字符串里因为前端既要展示给用户看也要根据错误类型做不同处理一个纯文本消息的能力非常弱。推荐的结构是这样的{ error: { code: ORDER_STATUS_CONFLICT, message: 订单已支付无法取消, fieldErrors: [ { field: status, message: 当前订单状态为PAID期望状态为PENDING } ], requestId: a1b2c3d4 } }code是机器可读的错误码前端可以用它做分支处理message是给用户看的友好提示fieldErrors是字段级别的错误详情适用于参数校验requestId用于关联日志排查问题。这套结构与HTTP状态码配合起来一层是协议层面的粗粒度一层是业务层面的细粒度既不浪费状态码又保留了灵活性。这里要强调一点HTTP状态码不要和业务错误码做成一一映射。比如所有业务错误都返回400然后在body里用code区分这等于又回到“一切皆200”的糟糕体验。状态码给大类业务码给细节两者各司其职配合最舒服。6. 查询参数分页、过滤、排序和搜索的成熟姿势6.1 分页设计offset/limit与cursor的本质区别列表接口最核心的设计就是分页。REST风格在分页这件事上并没有一套唯一的标准我见过三种主要方案每一种都有合适的应用场景。?page1pageSize20是最常见的适合数据量不大、跳页需求强的场景比如管理后台的表格。它的缺点有两个一是深翻页时性能差MySQL里LIMIT 100000, 20意味着要扫描前10万行再丢掉效率很低二是并发写入下数据会漂移翻页过程中可能出现重复或遗漏。?offset20limit20在语义上更贴近数据库操作适合内部工具类接口但问题跟page/pageSize基本一致。?cursoreyJzdGF0dXMiOi...是基于游标的分页方式。服务端返回一页数据的同时返回一个不透明的游标客户端拿这个游标请求下一页。它的核心思路是通过“排序列上的位置”来定位下一批数据天然支持数据的实时变化而且深翻页性能非常稳定。缺点是跳页困难只能一页一页往后翻。内容流、动态列表、IM消息列表这些页面最适合cursor分页。我倾向于在对外API里默认用cursor分页只有在管理后台场景才提供page/pageSize。游标字符串建议Base64编码带上排序键值和时间戳服务端解析后进行条件查询。响应体里可以把下一页游标放在nextCursor字段中最后一页返回null。6.2 过滤、排序、搜索的参数规范列表接口的资源量一大必然需要过滤、排序和搜索。这方面的设计乱象不亚于方法误用最常见的写法是把过滤条件揉进路径/api/orders/pending。我这里给出一个更统一的规范。过滤条件放在查询参数里字段名直接映射/api/orders?statuspaidchannelapp。如果某个过滤字段有多值需求可以用逗号分隔?statuspaid,shipped服务端按集合处理。范围过滤可以用操作符前缀?price_gte100price_lte500尤其是需要做区间查询的时候前缀法比JSON嵌套参数更直观。排序可以用sort参数表达格式是字段名方向多个排序条件用逗号分隔?sort-created_at,id。负号表示倒序正号表示正序通常省略。服务端要对sort字段做白名单校验不然用户传一个?sortpassword;drop table进来拼接SQL时就是个灾难。搜索关键词则统一放在keyword或q参数里。接口文档要明确说明搜索的作用范围比如只搜索订单号、商品名称避免前端以为所有字段都会被模糊匹配结果搜了手机号却什么都没有来回对需求。6.3 版本控制URI版本与Header版本之争REST服务上线后接口的结构不可能一成不变。但修改总是会破坏已有的调用方所以版本控制是每个对外API都要想的。常见方案有两类。URI版本是最直观的做法/api/v1/orders、/api/v2/orders。优点是调用方明确接口文档也好归类缺点是会让接口的URL变长也不利于对旧版本资源的复用和整理。很多大厂的开放平台倾向于用这种方案因为它语义清晰。Header版本则是通过Accept头比如Accept: application/vnd.example.v2json或自定义头比如X-API-Version: 2来指定版本。优点是URI保持干净缺点是版本信息透明性差调用方很容易忽略。如果团队没有强制的API文档管理工具不建议用这种方式。我的建议是对外部公开API用URI版本内部微服务之间用Header版本。内部服务调用方是自家团队愿意配合升级外部调用方则要给足够显眼的版本标识减少升级踩坑的概率。另外无论哪种方式版本升级时都要在老版本上保留足够长的过渡期而不是一刀切下线。7. 什么时候别用REST和RPC的边界7.1 RPC是动作导向REST是资源导向REST风格不是什么万能银弹。不少场景里它的资源抽象并不适合。典型就是RPC远程过程调用风格的接口。RPC的本质是“调用一个远端函数”路径写的是动作/api/userService/getUserById、/api/orderService/createOrder。这种风格面向“方法调用”非常直接我要创建一个订单就调用创建订单的方法。它省去了资源建模的过程也更符合程序员的直觉。REST风格则要求把一切抽象成资源POST /api/orders创建订单GET /api/orders/{id}获取订单。如果业务场景里“动作”占据主导资源建模就很费劲。比如一个推荐系统客户端核心操作就是“喂一条行为数据”和“拿一批推荐结果”前者是提交行为后者是获取结果虽然可以用“行为”和“推荐结果”建模成资源但经常感觉多此一举直接定义两个RPC方法反而更简洁。7.2 内部服务用RPC外部API用REST我参与过的不少项目都是这样一种分工外部开放接口、前后端交互接口用REST风格服务与服务之间用RPC框架gRPC、Thrift、Dubbo直接调用。为什么会有这种分工因为内部服务之间有更严格的技术栈约束和性能要求。gRPC基于HTTP/2支持双向流式传输序列化用Protobuf数据量小、性能高。服务治理上还内置了负载均衡、重试、熔断等能力。这些好处集中在内部服务间体现得最充分因为双方是同一边的契约由代码生成维护成本低。对外API则不同调用方多种多样可能是网页端、App、第三方合作伙伴还有可能不是我们自己的程序员。REST依赖HTTP协议本身的可理解性一个只懂基础Web知识的人也能根据“动词名词”猜出接口的大致行为这种低门槛优势是Protobuf这类契约机制给不了的。所以我的判断清单很简单同一个公司内部优先用成熟RPC框架对外公开接口优先用REST风格的HTTP接口。不要拿REST风格去硬套内部RPC场景那只会平白增加建模成本也不会带来太多收益。7.3 一个判断工具对资源模型问五个问题如果不确定某个业务场景到底适不适合REST设计可以问自己五个问题。第一业务里有稳定的核心资源吗一个外卖系统“商家、订单、骑手、用户”是稳定的资源一个计算引擎“把任务提交上去然后轮询拿结果”则没有稳定的资源。第二操作是不是可以归约为CRUD能归约REST的收益就大操作之间跳跃性强、经常需要串联执行多个步骤RPC的表达更直接。第三接口调用方是外部还是内部外部用REST便于理解内部用RPC效率更高。第四是否需要利用HTTP的缓存、网关、监控生态REST可以直接吃这些红利。第五团队对REST的掌握程度如何一个没有资源设计经验的团队硬推行REST风格很可能只是把路径改成名词而已不如先上RPC等有了建模能力再切REST。这个工具不是什么官方标准是我自己带团队时整理的用来在答辩和技术评审时快速对齐大家的预期。它能帮你避免那种最尴尬的局面花大力气设计了一个“理论完善”的RESTful接口开发三个月后发现客户端根本不需要那么丰富的资源语义反而被资源抽象限制住了手脚。8. 落地实操从混乱接口到一套可执行的REST API章程8.1 一个真实项目的接口改造动作与思想同步替换前面讲了不少理论这章分享一个我实际推动的接口改造。流程是先梳理出当前系统里所有对外接口按“路径里是否带动词、HTTP方法是否对应语义、是否返回了合理状态码”三个维度打了一遍分。结果触目惊心120个接口里超过三分之二的路径自带动词HTTP方法基本都是POST所有响应HTTP码都是200。改造分三步走。第一步把路径里的动词去掉。系统里四大核心资源user、order、product、review先建立好然后把所有动词搬出去。比如/api/getUserInfo改成GET /api/users/{id}/api/updateUserAddress改成PATCH /api/users/{id}。这一步不涉及任何业务逻辑变化纯路径迁移风险可控。第二步再把方法语义矫正过来。此前“创建操作”都被POST统一取代这一步要把创建改成POST、更新改成PATCH或PUT、删除改成DELETE。注意这里有个兼容问题老接口的调用方还在用POST。处理方法是给老接口留一条兼容路由路由内部转发到新接口但返回Deprecated头提示调用方尽快升级。第三步才是真正复杂的把业务逻辑和资源状态解耦。比如取消订单以前有一个/api/order/cancel接口直接操作订单状态。改造后核心动作仍然是修改订单状态但对外暴露的形态变成了POST /api/orders/{id}/cancel或POST /api/orders/{id}/cancellation后端逻辑负责校验状态、触发库存回补、创建退款单。这一步不改变底层代码组织但会逼着团队思考“操作一个资源”和“修改一个资源字段”之间的边界。8.2 一套REST API章程的骨架可以直接抄改造完接口后我又把这些规则整理成了一份团队内部章程大家可以照着这个骨架搭自己的版本。第一路径命名一律复数名词一律小写用连字符而非下划线。/api/orders/{id}为一等奖设计/api/order/{id}只会带来混乱。子资源只有在从属关系强烈时才嵌套否则平铺。第二方法选择新建用POST全部字段更新用PUT单字段更新用PATCH删除用DELETE纯查询用GET。任何情况下都不允许用GET去触发状态变更这是底线中的底线。第三响应结构统一封一层data字段避免客户端直接读裸数组。列表接口额外提供pagination信息。错误响应按前面说的code/message/requestId结构。成功响应不要随便包装一层“resultCode0”式的业务包裹层用HTTP状态码就已经能表达结果大类。第四查询参数分页默认page_size20、cursor或page两种模式按场景切换过滤字段直接使用资源字段名排序字段白名单校验搜索统一叫keyword。第五安全性非公开接口全部要求Bearer Token认证敏感操作删除、变更金额要求二次校验比如短信验证码或操作人身份确认所有写操作记录审计日志带上发起者ID、来源IP、请求体和变更前后快照。第六文档化接口文档至少包含请求路径、方法、参数、响应示例、错误码列表、变更历史。文档更新与代码合并绑定不允许只写代码不写文档。这套章程不是一夜之间形成的而是踩了无数坑之后总结出来的。它的作用不是束缚创造力而是把所有人在接口设计上的脑洞收敛到同一套语言体系里减少协作成本。8.3 用契约测试守住REST风格的底线章程定下来只是开始真正难的是让每个开发都严格遵守。契约测试是一个很好用的工具。在接口的代码仓库里维护一套“契约测试用例”每次接口变更都必须跑这些用例测试内容包括路径语义、方法语义、响应状态码、必填参数、错误格式。测试不过代码不允许合并。这种做法相当于给REST风格套上了一道自动化的护栏。曾经有个开发把删除用户接口写成了POST /api/users/1/delete测试用例里明确写着“路径不得包含动词”和“删除操作必须使用DELETE方法”CI跑挂之后他别无选择只能改成DELETE /api/users/1。这就是自动化规则的价值它可以把纸面上的规范变成代码里的硬约束而不是靠review时的口舌之争。移动端和前端也可以通过契约测试来联调。只要后端接口的契约测试通过了前端就可以依据契约文档做Mock不需要等后端联调环境完全就绪。这在大型团队里的效率提升非常明显。8.4 从老接口到微服务REST风格如何演进来收尾REST风格不是一套死板的规则它在演进。微服务时代服务拆分变细了接口数量和调用链路都变得复杂。此时REST风格依然适用但需要配合网关、服务发现和统一的流量治理机制使用。例如网关可以对REST接口做统一的认证、限流和缓存让服务本身只关注业务逻辑。这正是REST“分层系统”约束带来的扩展性红利。云原生时代Kubernetes的Ingress、Service Mesh也都天然理解HTTP语义GET/POST/PUT/DELETE这些方法被基础设施吸收为标准流量特征。这意味着维护一套REST风格的接口整个技术栈的通用组件都能直接为你服务。相反如果接口设计成非标准形态这些基础设施的便利就会打折扣。对团队来说推行REST风格最难的不是学会规则而是改变思维方式。从“我写一个接口帮你做一件事”到“我暴露一批资源你用标准动作去操作它们”这中间隔着一道很深的坎。跨过去了后面的维护和演进会顺滑很多。我的体会是刚开始推行的时候可以允许一部分接口“长得不完全像REST”但必须明确哪些位置允许妥协、为什么妥协、后续怎么演进。保持方向一致比一步到位更重要。
接手一个老项目的时候我看了下接口文档心里凉了半截。文档里齐刷刷地写着/api/getUserList、/api/doUpdateUser、/api/delOrder动作写满了路径一眼望去像是给服务号写开放接口而不是在做一个前后端分离的产品。我叹了口气把项目组成员叫到会议室第一句话就是“我们先聊聊什么是真正的REST风格。”这大概是很多团队的真实写照大家嘴上都在说RESTful简历上都写着常年使用REST风格设计接口但真正拿出来的东西十个里有八个只是“长得像REST”。URL换成了名词、把POST换成PUT就算完成了却完全没有理解REST作为一种架构风格背后的原则。这篇文章我不打算再给你复述一遍教科书定义我想从一名一线开发者的角度把REST风格的来龙去脉、设计取舍、实际落地经验以及那些最容易踩的坑都拆开讲清楚。不管你是刚接触接口设计的新人还是正在为团队推行API规范的老手应该都能在里面找到点用得上的东西。1. 很多人理解的REST其实只是“长得像REST”1.1 动词型URL与REST之间的鸿沟先说说“长得像REST”是什么感觉。一个团队说自己会REST实际做的却是把/api/getUser改成/api/user把/api/deleteUser改成DELETE /api/user?id1。路径里确实没有动词了HTTP动词也换成了对应的语义看起来挺像那么回事。但真正的REST不是URL风格而是一套约束下的架构风格。REST这个缩写来自“表征状态转移”Representational State Transfer它讨论的是在分布式系统中客户端和服务端之间如何通过资源的概念互相交互。URL只是其中一个很表面、很小的组成部分。如果把REST比作一套交通规则URL命名充其量只是路牌上的字体真正管用的是红绿灯设置、车道划分和行人优先这些底层的制度安排。实际开发里动词型URL带来的问题远不只是“不优雅”。它破坏了资源的可预测性。一个接口叫/api/getUserList另一个叫/api/userList还有一个叫/api/queryUsers前端对接时要反复翻文档才能弄明白每个接口到底是干嘛的。而当所有接口都统一成“名词HTTP方法”的格式后调用方天然就能猜出接口的行为这种可预测性在前后端并行开发时价值极高。1.2 所谓“REST风格”里常见的三处遗漏很多团队在推行REST风格时只把精力放在了路径命名上却忽略了另外三件更重要的事情。第一是HTTP方法语义的完整性。不少项目无论什么操作都用POST创建用POST、更新用POST、删除也用POST。这导致接口的语义信息完全丢失。REST风格要求尽量利用HTTP本身提供的动词与语义GET负责查询、POST负责创建、PUT负责整体替换、PATCH负责局部修改、DELETE负责删除。这样做的价值不仅在于“规范”更在于让网关、缓存、监控这些基础组件也能理解接口的行为。比如网关可以天然识别出GET请求是可以缓存、可以重试的而对POST请求要做特殊处理。第二是状态码的语义化。很多后端工程师无论成功失败都返回HTTP 200然后把业务码放在响应体的code字段里。从REST的角度看状态码本身就是响应的一部分它应该用来表达本次请求的处理结果。错误有错误的码权限有权限的码资源不存在有不存在的码。如果所有情况下都返回200意味着协议层面的信息完全被浪费了调用方只能层层剥开body才知道发生了什么。第三是超媒体与自描述性。REST的完整定义里有一个常被忽略的约束HATEOAS也就是超媒体作为应用状态的引擎。简单说服务端返回用户数据时可以顺带返回相关的链接告诉客户端接下来可以去哪里。比如订单资源返回后附带cancel、pay这些操作的链接。这个理念在市面上绝大多数业务系统里都没有落实因为确实会增加不少工作量。但至少设计接口时应该知道这件事的存在而不是完全没听过。1.3 为什么“长得像REST”反而更危险如果完全不懂REST倒是无所谓接口写错了也会有人指出。最怕的是那种“半桶水”式的REST路径从动词改成了名词HTTP方法也用对了看起来已经“达标”了但内部设计仍然是RPC思维。这种项目在外人面前有模有样实际维护的时候同样会陷入混乱。举个例子。一个订单系统为了兼容“查询待支付订单”和“查询已发货订单”两个场景接口设计成/api/order/pending和/api/order/shipped。路径是名词了却没有意识到这两个接口其实是一个资源订单集合在不同过滤条件下的两种视图。正确做法应该是一个/api/orders?statuspending把参数交给查询条件处理。前者导致每增加一种订单状态就要新增一个接口接口数量会随着业务状态膨胀后者只需要在参数层面做扩展后端增加一个枚举判断即可。这就是我想说的核心问题REST风格的重要价值之一是收敛接口数量用统一的方式表达一类操作。如果只学了皮毛而没有理解背后的资源抽象就会在表面的合规之下保留着RPC的放荡不羁最后接口越写越多、越写越乱大家还都觉得自己的设计挺REST。2. 回到源头一篇博士论文和六个约束2.1 从论文到互联网主流API风格REST这个词最早出现在Roy Fielding在2000年发表的博士论文《架构风格与基于网络的软件架构设计》里。那时候可没有什么前后端分离更没有移动端App要对接后端API的概念。Fielding是HTTP协议的主要作者之一也是后来Apache基金会的重要人物。他研究的是互联网这种大规模分布式系统到底应该遵循什么样的架构风格才能保证它能够持续演进、承受住Web规模的并发压力。这篇论文里Fielding基于对早期Web架构的分析抽象出了一组约束称其为REST。这组约束并不是拍脑袋想出来的而是从互联网的实践中反推出来的架构原则。有意思的是这篇论文诞生后很长一段时间里真正理解它的人并不多。REST开始大规模流行是在2007年前后Rails框架把RESTful Routes作为默认路由方式写进了框架之后。后来各种框架纷纷跟进前后端分离成为主流REST风格的接口设计才真正变成工程师的必修课。这里可以打个比方。REST就像城市规划里的分区制度它规定了住宅区、商业区、工业区应该分开道路应该按等级划分。至于每个小区里种什么树、刷什么墙是细节问题。很多人只学到了“道路刷成淡黄色”这种表面特征却没有理解分区制度是为了解决城市蔓延、交通拥堵这些问题。2.2 六大约束和它们各自解决什么问题REST架构风格由六个约束组成我来逐个说一下它们的内涵。第一个是客户端-服务器分离。客户端只管展示与交互服务端只管数据存储与业务处理两者独立演化。这是分布式系统最基本的解耦方式也是Web能发展出这么多前端框架、移动端技术栈的前提。很多团队当初推行前后端分离本质上就是在落实这个约束。第二个是无状态。服务器不能在请求之间保存任何上下文信息。每一次HTTP请求都应该携带足够的信息让服务器能够独立处理。有人会觉得这很别扭因为有状态的设计写起来更自然比如登录状态存在服务端session里多方便。但无状态约束保证了服务器的可伸缩性。如果一个服务器挂掉了另一台服务器可以直接接管请求不会因为“这台机器上有用户登录状态”而服务不了。它在牺牲一点点开发便利性的同时把水平扩展这个能力拿到了手。现代系统通常用Token、JWT这些方式配合无状态约束让认证信息随请求头携带而不是存在服务端的session里。第三个是缓存。服务器返回的数据可以标记为可缓存客户端拿到响应后可以在一段时间内不用再发请求直接用缓存的副本。这个约束对Web性能优化意义重大。在实际API设计中GET请求默认就是可以被缓存的而POST、PUT这些非安全方法则会穿透缓存系统。理解了这点就不会在业务里滥用POST来替代所有请求了。第四个是统一接口。这是REST最核心的一个约束也是被理解得最浅的一个。统一接口可以拆成四个子约束资源识别、通过表示对资源进行操作、自描述消息、超媒体作为应用状态的引擎。翻译成大白话客户端不直接操作数据库而是操作资源的表示通常就是JSON请求与响应里携带着足够描述自己意图的信息客户端基于资源状态和超媒体链接来推进应用流程。这四个子约束是REST与普通RPC接口最大的区别。第五个是分层系统。允许系统由多个层级组成客户端不需要关心它访问的到底是直接提供数据的服务还是中间层的代理、网关或负载均衡器。这个约束给了系统极大的灵活性比如加一层CDN缓存静态资源加一层API网关做鉴权和限流客户端完全不知情。第六个是按需代码。服务器可以通过返回可执行代码比如JavaScript、Flash插件扩展客户端的功能。这是REST里唯一一个可选约束在实际业务API中几乎用不上。2.3 约束不是束缚是取舍的依据很多人谈到REST的约束就头疼觉得“这也限制那也限制”不如直接想怎么写就怎么写。但约束恰恰提供了决策依据。举个现实中的例子。很多公司内部服务之间直接使用HTTPJSON接口路径写得很随意根本没有统一接口的约束。这种做法的代价是什么一旦服务数量变多每一个接口的调用规则都需要额外文档记录前端的对接成本高后端改动也容易被上游调用方偷偷破坏。REST约束就是在逼你把“资源的表述方式”稳定下来让接口变成一种可以被理解、被信任的契约。它当然有局限如果一个操作本质上就不是资源操作硬套REST就会很别扭。此时应该选择更合适的RPC框架而不是非要在一棵树上吊死。这一点我在后面专门用一章来说。3. 资源思维先分清“名词”和“动词”再谈设计3.1 资源为什么要用名词而不是动词把接口设计成REST风格的第一课是学会用名词定义一切。订单是资源用户是资源商品是资源。而支付、取消、发货这些在REST风格里不是资源而是“对资源施加的操作”。但为什么资源和名词绑定而不是和操作绑定因为资源是稳定的分类操作是易变的行为。一个业务系统里核心资源往往就那么十几个用户、订单、商品、优惠券……而围绕资源展开的操作可能有几十上百个注册、登录、下单、付款、退款、发货、退货……。如果接口按操作来组织接口数量就会失去控制。按资源组织操作再多也可以收敛到几种标准的HTTP行为上。打个比方。如果你把图书馆的管理规则设计成“每本书附带一本说明书说明怎么借、怎么还、怎么预约”那每本书的说明书都不一样读者每借一本新书都要重新学习一道流程。而如果图书馆规定“所有书都遵循同一个借阅流程”读者只需要学一次换任何书都会操作。资源就是那本“被统一操作的书”HTTP方法就是那套“所有人都遵守的流程”两者结合接口自然收敛。3.2 路径设计的核心是层级与从属关系既然用名词表示资源路径自然就是一个个层层嵌套的名词组合。这里有两条设计原则需要掌握。第一路径的全部职责是定位资源不是传递行为。查询、创建、修改等行为交给HTTP方法过滤、排序、分页等条件交给查询参数不要把行为和动作塞进路径。这是最基础的一步。把/api/order/pay改为/api/orders/{id}/pay并没有解决本质问题“pay”仍然是动词。正确的做法要么是提供一个资源化的“支付单”来建模POST /api/payments带订单ID要么在刚引入REST风格时先用一个自定义方法过渡但明确这只是演进过程中的妥协代码里要做好隔离。总之路径设计要能体现出“这是一组资源操作方式由方法决定”的气息。第二路径有层级关系但层级关系应该表达“从属”而不是“路径”本身。最常见的子资源场景是“某个用户下的订单”/api/users/123/orders。这个设计告诉你“订单从属于用户”。但如果订单本身已是独立重要资源直接写/api/orders?userId123更合理。什么时候用嵌套、什么时候用平铺看资源和父资源之间的耦合度。订单即使离开用户也存在自己的生命周期通常用平铺评论如果不属于某篇文章就没有存在意义通常用嵌套。这是我设计接口时的一条实用判断标准。3.3 集合与单体一条URI对应一种资源粒度资源还可以进一步分为“集合资源”和“单体资源”。/api/users是用户集合/api/users/123是单个用户。这两个URI虽然是同一类资源的不同粒度但对应的HTTP操作组合完全不同。集合资源通常支持GET列出、POST创建单体资源通常支持GET获取、PUT整体替换、PATCH局部更新、DELETE删除。理解了这个粒度区分就不会出现“用POST /api/users/update”这种四不像的写法了。集合资源承载“批量”与“新增”语义单体资源承载“操作单个对象”语义权限控制、缓存策略、参数校验规则都可以依据粒度来设置。比如单体资源接口一般可以做细粒度的缓存集合资源接口的缓存会更复杂需要结合过滤条件考虑缓存失效的问题。这条规则还可以扩展到“容器类资源”的设计。例如公司有多个项目每个项目有多个成员/api/projects?orgId1或/api/orgs/1/projects再往下/api/orgs/1/projects/22这种路径虽然长但语义清晰。设计路径时只要始终问自己“这个资源是属于哪个父资源底下的”层级就会自然推出来。4. HTTP方法不是动词库是语义契约4.1 五个核心方法的语义映射REST风格中最容易出问题的地方之一是HTTP方法的使用。很多团队对方法的理解就停留在“GET用于查询POST用于新增DELETE用于删除”这是对的但远远不够。我给团队成员做培训时会把五个核心方法用一张表格列出来让大家每次写接口前先过一遍这张表。方法语义是否安全是否幂等典型场景GET获取资源的表示是是查询用户信息、获取订单详情POST创建资源或触发特定操作否否创建订单、注册用户PUT整体替换资源否是更新用户全部字段PATCH局部更新资源否否修改用户昵称DELETE删除资源否是删除订单、下架商品“安全”意味着这个请求不会修改服务器上的任何状态也因此可以被缓存、被预取。“幂等”意味着同一个请求执行一次和执行十次最终结果是一样的。这两个概念很多人分不清但它们在实际系统中影响很大。比如网络超时后自动重试如果请求方法是幂等的重试就是安全的如果不是幂等的重试可能产生重复订单那就必须靠业务层的唯一键去兜底。4.2 PUT与PATCH的差别比你想象的更重要更新接口是REST风格里争议最多的地方。有人习惯把所有更新都设计成PUT也有人喜欢全部用PATCH。我从实践中得出的结论是PUT代表“整体替换”PATCH代表“局部更新”两者适用的场景完全不同。什么时候用PUT当客户端有能力提供资源的完整表示时。比如修改一个用户资料前端把表单里的所有字段都提交上来服务端拿这份完整数据整体覆盖旧数据。这种情况下用PUT客户端和服务端的语义非常明确客户端说了算缺省字段就是置空服务端不用猜。什么时候用PATCH当客户端只需要提交变化的部分时。比如用户只修改了手机号提交的数据里只有phone字段其他字段服务端保持原样。这就是PATCH的用法。它的好处是数据量小服务端逻辑也简单只更新传入字段。但PATCH的代价是非幂等的因为服务端的当前状态会影响最终结果。比如同一份PATCH请求第一次执行时把数量从3改成5执行两次就变成7了。实际开发中PUT和PATCH的误用很常见。一个订单更新接口客户端想改一下收货地址却用PUT把整个订单都提交上来服务端要是没有做“空字段不更新”的保护这个设计就会吞掉订单里的其他字段数据。我的建议是除非接口明确要求客户端提交完整资源否则更新操作一律优先考虑PATCH。这样既省流量也避免覆盖风险。如果把PUT用于局部更新必须把所有可能缺失的字段都考虑成“不更新”这本身就是反直觉的。4.3 POST不止是“创建”还有“动作资源化”的艺术POST在REST风格里除了创建资源还有一个更微妙的用法表达“非CRUD操作”。类似“发货”“取消订单”“支付”“确认收货”这种操作它们本质是业务动作不是资源状态本身。强行用PUT或PATCH去表达要么语义不对要么参数很尴尬。最典型的是“取消订单”PATCH /api/orders/123传{status: cancelled}技术上说得通却不直观。业务上真正发生的是一系列动作取消库存、触发退款、发通知不是一个简单的状态变更。这种情况下业界有两种常见思路。一种是“动作资源化”把“取消”这个动作建模成一个子资源POST /api/orders/123/cancellation。这看起来很REST也确实是最贴近REST理念的做法因为动作被转化成了“资源状态的转移过程”。另一种思路是保留RPC式动作接口POST /api/orders/123/cancel路径里带了动词但因为是POST调用逻辑上排除在“资源定位”规则之外实践上也能接受。从我带团队的经验来看内部系统用第二种更省事对外API想追求风格的纯度可以用第一种。但无论选哪种都要守住一条底线只有POST可以承载语义不那么标准的动作接口GET、PUT、DELETE这些方法都应该严格对应它们的标准语义。5. 状态码选不对接口再准确也是半成品5.1 状态码是按协议说话不是业务码的备胎很多后端工程师是从零设计接口的没有系统学过HTTP语义。他们习惯把业务码放在JSON里{code: 10001, message: 用户不存在}然后让前端根据body里的code来写逻辑。这种做法从REST风格的角度看是把协议层的表达能力白白浪费了。HTTP状态码本身就是这次请求的结果摘要。它有三类信息量结果大类2xx成功、3xx重定向、4xx客户端错误、5xx服务端错误、具体语义200成功、201创建成功、204无内容、400参数错误、401未认证、403无权限、404不存在、409冲突、422无法处理、500服务器内部错误以及可缓存性2xx里有一些可缓存4xx一般不可缓存。接口设计者不利用这些信息前端就只能猜、只能把所有请求都当成200来处理再根据code做一次二次分发。这等于把网关、日志、监控系统本来就该具备的“按状态码告警”能力全部绕过了。5.2 按场景选状态码一张常用清单我整理了一张在业务API里最常用的状态码清单适合大多数RESTful接口场景。你不用背全部状态码记住这张清单基本上就够用了。场景状态码说明查询成功200返回资源列表或详情创建成功201必须在响应头里带Location指向新资源更新成功200 或 204返回完整新数据用200纯成功无内容用204删除成功204无响应体表示删除已完成参数错误400 或 422参数格式不对用400语义不对用422未认证401没带Token或Token失效禁止访问403认证了但没有权限资源不存在404路径错了或资源被删除状态冲突409例如订单已支付不能再次提交支付服务端错误500未捕获异常伴随错误日志服务不可用503依赖的下游服务挂了或服务在重启这里容易出问题的是401和403的区分。401表示“我根本不知道你是谁”403表示“我知道你是谁但你没有权限”。前者是认证问题后者是授权问题。很多前端工程师会把这两个混为一谈看到401就跳登录页导致403场景里用户被反复弹登录。接口设计时应该在错误响应体里写清楚原因便于排查。另一个容易忽略的是400和422的区别。400类状态码里最常用的是“参数格式错误”比如id传的不是数字。422则更适合表达“我的参数格式没问题但按照业务规则无法处理”比如仓库里库存不足下单失败。这两个状态码的区分能直接提升接口错误信息的可读性。5.3 错误响应体用统一结构封装问题细节光有状态码还不够错误响应体也需要统一设计。我不建议把错误信息只放在一个message字符串里因为前端既要展示给用户看也要根据错误类型做不同处理一个纯文本消息的能力非常弱。推荐的结构是这样的{ error: { code: ORDER_STATUS_CONFLICT, message: 订单已支付无法取消, fieldErrors: [ { field: status, message: 当前订单状态为PAID期望状态为PENDING } ], requestId: a1b2c3d4 } }code是机器可读的错误码前端可以用它做分支处理message是给用户看的友好提示fieldErrors是字段级别的错误详情适用于参数校验requestId用于关联日志排查问题。这套结构与HTTP状态码配合起来一层是协议层面的粗粒度一层是业务层面的细粒度既不浪费状态码又保留了灵活性。这里要强调一点HTTP状态码不要和业务错误码做成一一映射。比如所有业务错误都返回400然后在body里用code区分这等于又回到“一切皆200”的糟糕体验。状态码给大类业务码给细节两者各司其职配合最舒服。6. 查询参数分页、过滤、排序和搜索的成熟姿势6.1 分页设计offset/limit与cursor的本质区别列表接口最核心的设计就是分页。REST风格在分页这件事上并没有一套唯一的标准我见过三种主要方案每一种都有合适的应用场景。?page1pageSize20是最常见的适合数据量不大、跳页需求强的场景比如管理后台的表格。它的缺点有两个一是深翻页时性能差MySQL里LIMIT 100000, 20意味着要扫描前10万行再丢掉效率很低二是并发写入下数据会漂移翻页过程中可能出现重复或遗漏。?offset20limit20在语义上更贴近数据库操作适合内部工具类接口但问题跟page/pageSize基本一致。?cursoreyJzdGF0dXMiOi...是基于游标的分页方式。服务端返回一页数据的同时返回一个不透明的游标客户端拿这个游标请求下一页。它的核心思路是通过“排序列上的位置”来定位下一批数据天然支持数据的实时变化而且深翻页性能非常稳定。缺点是跳页困难只能一页一页往后翻。内容流、动态列表、IM消息列表这些页面最适合cursor分页。我倾向于在对外API里默认用cursor分页只有在管理后台场景才提供page/pageSize。游标字符串建议Base64编码带上排序键值和时间戳服务端解析后进行条件查询。响应体里可以把下一页游标放在nextCursor字段中最后一页返回null。6.2 过滤、排序、搜索的参数规范列表接口的资源量一大必然需要过滤、排序和搜索。这方面的设计乱象不亚于方法误用最常见的写法是把过滤条件揉进路径/api/orders/pending。我这里给出一个更统一的规范。过滤条件放在查询参数里字段名直接映射/api/orders?statuspaidchannelapp。如果某个过滤字段有多值需求可以用逗号分隔?statuspaid,shipped服务端按集合处理。范围过滤可以用操作符前缀?price_gte100price_lte500尤其是需要做区间查询的时候前缀法比JSON嵌套参数更直观。排序可以用sort参数表达格式是字段名方向多个排序条件用逗号分隔?sort-created_at,id。负号表示倒序正号表示正序通常省略。服务端要对sort字段做白名单校验不然用户传一个?sortpassword;drop table进来拼接SQL时就是个灾难。搜索关键词则统一放在keyword或q参数里。接口文档要明确说明搜索的作用范围比如只搜索订单号、商品名称避免前端以为所有字段都会被模糊匹配结果搜了手机号却什么都没有来回对需求。6.3 版本控制URI版本与Header版本之争REST服务上线后接口的结构不可能一成不变。但修改总是会破坏已有的调用方所以版本控制是每个对外API都要想的。常见方案有两类。URI版本是最直观的做法/api/v1/orders、/api/v2/orders。优点是调用方明确接口文档也好归类缺点是会让接口的URL变长也不利于对旧版本资源的复用和整理。很多大厂的开放平台倾向于用这种方案因为它语义清晰。Header版本则是通过Accept头比如Accept: application/vnd.example.v2json或自定义头比如X-API-Version: 2来指定版本。优点是URI保持干净缺点是版本信息透明性差调用方很容易忽略。如果团队没有强制的API文档管理工具不建议用这种方式。我的建议是对外部公开API用URI版本内部微服务之间用Header版本。内部服务调用方是自家团队愿意配合升级外部调用方则要给足够显眼的版本标识减少升级踩坑的概率。另外无论哪种方式版本升级时都要在老版本上保留足够长的过渡期而不是一刀切下线。7. 什么时候别用REST和RPC的边界7.1 RPC是动作导向REST是资源导向REST风格不是什么万能银弹。不少场景里它的资源抽象并不适合。典型就是RPC远程过程调用风格的接口。RPC的本质是“调用一个远端函数”路径写的是动作/api/userService/getUserById、/api/orderService/createOrder。这种风格面向“方法调用”非常直接我要创建一个订单就调用创建订单的方法。它省去了资源建模的过程也更符合程序员的直觉。REST风格则要求把一切抽象成资源POST /api/orders创建订单GET /api/orders/{id}获取订单。如果业务场景里“动作”占据主导资源建模就很费劲。比如一个推荐系统客户端核心操作就是“喂一条行为数据”和“拿一批推荐结果”前者是提交行为后者是获取结果虽然可以用“行为”和“推荐结果”建模成资源但经常感觉多此一举直接定义两个RPC方法反而更简洁。7.2 内部服务用RPC外部API用REST我参与过的不少项目都是这样一种分工外部开放接口、前后端交互接口用REST风格服务与服务之间用RPC框架gRPC、Thrift、Dubbo直接调用。为什么会有这种分工因为内部服务之间有更严格的技术栈约束和性能要求。gRPC基于HTTP/2支持双向流式传输序列化用Protobuf数据量小、性能高。服务治理上还内置了负载均衡、重试、熔断等能力。这些好处集中在内部服务间体现得最充分因为双方是同一边的契约由代码生成维护成本低。对外API则不同调用方多种多样可能是网页端、App、第三方合作伙伴还有可能不是我们自己的程序员。REST依赖HTTP协议本身的可理解性一个只懂基础Web知识的人也能根据“动词名词”猜出接口的大致行为这种低门槛优势是Protobuf这类契约机制给不了的。所以我的判断清单很简单同一个公司内部优先用成熟RPC框架对外公开接口优先用REST风格的HTTP接口。不要拿REST风格去硬套内部RPC场景那只会平白增加建模成本也不会带来太多收益。7.3 一个判断工具对资源模型问五个问题如果不确定某个业务场景到底适不适合REST设计可以问自己五个问题。第一业务里有稳定的核心资源吗一个外卖系统“商家、订单、骑手、用户”是稳定的资源一个计算引擎“把任务提交上去然后轮询拿结果”则没有稳定的资源。第二操作是不是可以归约为CRUD能归约REST的收益就大操作之间跳跃性强、经常需要串联执行多个步骤RPC的表达更直接。第三接口调用方是外部还是内部外部用REST便于理解内部用RPC效率更高。第四是否需要利用HTTP的缓存、网关、监控生态REST可以直接吃这些红利。第五团队对REST的掌握程度如何一个没有资源设计经验的团队硬推行REST风格很可能只是把路径改成名词而已不如先上RPC等有了建模能力再切REST。这个工具不是什么官方标准是我自己带团队时整理的用来在答辩和技术评审时快速对齐大家的预期。它能帮你避免那种最尴尬的局面花大力气设计了一个“理论完善”的RESTful接口开发三个月后发现客户端根本不需要那么丰富的资源语义反而被资源抽象限制住了手脚。8. 落地实操从混乱接口到一套可执行的REST API章程8.1 一个真实项目的接口改造动作与思想同步替换前面讲了不少理论这章分享一个我实际推动的接口改造。流程是先梳理出当前系统里所有对外接口按“路径里是否带动词、HTTP方法是否对应语义、是否返回了合理状态码”三个维度打了一遍分。结果触目惊心120个接口里超过三分之二的路径自带动词HTTP方法基本都是POST所有响应HTTP码都是200。改造分三步走。第一步把路径里的动词去掉。系统里四大核心资源user、order、product、review先建立好然后把所有动词搬出去。比如/api/getUserInfo改成GET /api/users/{id}/api/updateUserAddress改成PATCH /api/users/{id}。这一步不涉及任何业务逻辑变化纯路径迁移风险可控。第二步再把方法语义矫正过来。此前“创建操作”都被POST统一取代这一步要把创建改成POST、更新改成PATCH或PUT、删除改成DELETE。注意这里有个兼容问题老接口的调用方还在用POST。处理方法是给老接口留一条兼容路由路由内部转发到新接口但返回Deprecated头提示调用方尽快升级。第三步才是真正复杂的把业务逻辑和资源状态解耦。比如取消订单以前有一个/api/order/cancel接口直接操作订单状态。改造后核心动作仍然是修改订单状态但对外暴露的形态变成了POST /api/orders/{id}/cancel或POST /api/orders/{id}/cancellation后端逻辑负责校验状态、触发库存回补、创建退款单。这一步不改变底层代码组织但会逼着团队思考“操作一个资源”和“修改一个资源字段”之间的边界。8.2 一套REST API章程的骨架可以直接抄改造完接口后我又把这些规则整理成了一份团队内部章程大家可以照着这个骨架搭自己的版本。第一路径命名一律复数名词一律小写用连字符而非下划线。/api/orders/{id}为一等奖设计/api/order/{id}只会带来混乱。子资源只有在从属关系强烈时才嵌套否则平铺。第二方法选择新建用POST全部字段更新用PUT单字段更新用PATCH删除用DELETE纯查询用GET。任何情况下都不允许用GET去触发状态变更这是底线中的底线。第三响应结构统一封一层data字段避免客户端直接读裸数组。列表接口额外提供pagination信息。错误响应按前面说的code/message/requestId结构。成功响应不要随便包装一层“resultCode0”式的业务包裹层用HTTP状态码就已经能表达结果大类。第四查询参数分页默认page_size20、cursor或page两种模式按场景切换过滤字段直接使用资源字段名排序字段白名单校验搜索统一叫keyword。第五安全性非公开接口全部要求Bearer Token认证敏感操作删除、变更金额要求二次校验比如短信验证码或操作人身份确认所有写操作记录审计日志带上发起者ID、来源IP、请求体和变更前后快照。第六文档化接口文档至少包含请求路径、方法、参数、响应示例、错误码列表、变更历史。文档更新与代码合并绑定不允许只写代码不写文档。这套章程不是一夜之间形成的而是踩了无数坑之后总结出来的。它的作用不是束缚创造力而是把所有人在接口设计上的脑洞收敛到同一套语言体系里减少协作成本。8.3 用契约测试守住REST风格的底线章程定下来只是开始真正难的是让每个开发都严格遵守。契约测试是一个很好用的工具。在接口的代码仓库里维护一套“契约测试用例”每次接口变更都必须跑这些用例测试内容包括路径语义、方法语义、响应状态码、必填参数、错误格式。测试不过代码不允许合并。这种做法相当于给REST风格套上了一道自动化的护栏。曾经有个开发把删除用户接口写成了POST /api/users/1/delete测试用例里明确写着“路径不得包含动词”和“删除操作必须使用DELETE方法”CI跑挂之后他别无选择只能改成DELETE /api/users/1。这就是自动化规则的价值它可以把纸面上的规范变成代码里的硬约束而不是靠review时的口舌之争。移动端和前端也可以通过契约测试来联调。只要后端接口的契约测试通过了前端就可以依据契约文档做Mock不需要等后端联调环境完全就绪。这在大型团队里的效率提升非常明显。8.4 从老接口到微服务REST风格如何演进来收尾REST风格不是一套死板的规则它在演进。微服务时代服务拆分变细了接口数量和调用链路都变得复杂。此时REST风格依然适用但需要配合网关、服务发现和统一的流量治理机制使用。例如网关可以对REST接口做统一的认证、限流和缓存让服务本身只关注业务逻辑。这正是REST“分层系统”约束带来的扩展性红利。云原生时代Kubernetes的Ingress、Service Mesh也都天然理解HTTP语义GET/POST/PUT/DELETE这些方法被基础设施吸收为标准流量特征。这意味着维护一套REST风格的接口整个技术栈的通用组件都能直接为你服务。相反如果接口设计成非标准形态这些基础设施的便利就会打折扣。对团队来说推行REST风格最难的不是学会规则而是改变思维方式。从“我写一个接口帮你做一件事”到“我暴露一批资源你用标准动作去操作它们”这中间隔着一道很深的坎。跨过去了后面的维护和演进会顺滑很多。我的体会是刚开始推行的时候可以允许一部分接口“长得不完全像REST”但必须明确哪些位置允许妥协、为什么妥协、后续怎么演进。保持方向一致比一步到位更重要。
