分布式 API 设计之上：REST 背景、对比、实践及例外情况全解析

【没时间看记住这3点】各位如果没时间看记住3点一是 REST 以资源为中心设计的 API数据架构和数据模型设计对 REST 接口质量有很大影响二是遇事不决就用 POST三是参考业界的 REST API如 githubelasticsearch。【REST 背景】2000 年互联网兴起数年企业系统广泛流行通过 HTTP 实现远程调用代替 EJB当时基于 HTTP 远程调用无论 URL 的设计参数命名以及响应都没有统一的规范。Roy Fielding 针对此问题提出了表示状态转移Representational State Transfer简称 REST作为一种设计 web 服务的体系结构方法。REST 是目前最流行的 HTTP API 设计规范用于 Web 接口的设计。REST 的核心思想就是客户端发出的指令都是“标准动词 操作资源”的结构。比如GET /orders/1 这个命令GET 是动词/orders/1 是宾语这里的 1 是指订单编号为 1 的订单。如下是一个 REST 请求GET https://xxxx/orders/1 HTTP/1.1 Accept: application/json响应HTTP/1.1 200 OK { code:SUCCESS messsage:成功 data:{orderId:1,orderValue:99.90,productId:1,quantity:1} }这里的标准动词是 HTTP 规范提供的标准如上面的 get其他动作还有 post、delete将会在后面描述。相比于 HTTP 远程调用REST 是以资源作中心构建的远程调用服务这里的资源指的是业务实体业务实体来自于数据架构。一个良好的 REST API 设计离不开良好的数据架构。以 GIT 提供的服务为例子资源包括了仓库、用户、Issues、Release、Team。以物联网为例子资源包括了设备、用户、家庭、属性、告警、OTA、命令。【REST 和其他协议对比】在上一节比较过二进制协议和 HTTP 的区别建立在 HTTP 之上的 REST具备 HTTP 的优点一是语言独立所有语言都支持 HTTP 协议也提供 REST 风格的客户端接口二是平台独立所有的系统都支持 HTTP三是可观测性强通过 HTTP 代理服务器以及良好的 REST 接口定义可以让系统之间调用可观测可统计。基于 HTTP 协议的除了 REST 外还有非常流行的 SOAP简单区分俩种的区别RESTSOAP核心资源服务方法像传统分布式调用 CorbaEJB 的的 HTTP 版本量级轻便可选约束重量级必须约束适用范围任何系统服务之间终端和系统之间系统之间如人力系统和财务系统【REST 最佳实践】本节介绍 REST 的设计最佳实践它除了上一节的分布式 API 通用的最佳实践外REST API 还有特定的设计原则总结为下表内容和表后的重点说明设计原则描述URLURL 必须定义了资源比如 /books/1978命名规范驼峰命名方法蛇形命名法烤肉串命名法。比如对于显示名称 display name。分别对应了 displayNamedisplay_namedispaly - name。REST 的 URL 通常使用烤肉串命名法入参和出参数使用 Java 常用的驼峰命名法资源名称API 的核心是操作是 WEB 资源或者业务实体因此需要在这之前定义好这些名称这些名称在数据架构或者更早的数据架构前已经定好。比如用户中心提供的 REST 接口查询用户的绑定设备 GET /users/devices 。如果缺少标准名称另外一个接口查询设备状态 GET /devs/customer 。这让 API 使用者有困惑他可能认为 devices 和 devs 可能是物联网的俩种设备资源名称通常以复数形式体现资源层级当资源必须通过层级获取的时候可以用 / 表达层级比如 /orders/{orderId}/items建议层级不超过 3 层。标准字段定义常见的标准字段如 requestIdtokencreateTimeorderBydisplayNamestartDateendDate 等。其他行业特定的字段应该基于数据架构的概念模型来定义比如物联网中的 deviceshadow电商中的 couponordersku开闭区间表示范围需要统一规定是否包含临界值Java 通常使用[、)起始值闭区间结束值为开区间推荐使用这种约定使用单位后缀比如优先使用 maxByte 代替 max除非有上下文指示返回的单位。关于时间精确到秒应该使用 time精确到天应该使用 date 后缀。名字缩写软件开发者常用的缩写可以用在 API 上如 idconfig电商中的 Sku。属性class 是 java 的关键字因此在设计 API 的时候需要避免参数中使用此关键字这主要考虑到序列化和反序列化时候这类关键字无法被实现is 开头的属性有可能在反序列化中失败isCreate有的序列化成 isCreate有的序列化成 create 需要明确属性不存在和属性值为 null 是同一个含义 明确空集合和 null 是同一个含义 客户端是否支持浮点数以 JS 为例子[不支持 Java 返回的过长的数字](https://blog.csdn.net/u010028869/article/details/86563382)版本号通常使用 version 表示 api 的版本比如 /gms/v1.0/devices建议 REST URL 总是包含 version。另外可选的是在 HTTP Header 中包含 version。比如 github api 推荐把 version 放到 header 里下表列出了 Github REST APIREST 接口说明/user/repos获取当前用户的所有仓库/repos/{owner}/查询一个仓库信息/repos/{owner}/{repo}/releases来自 github api返回代码库的所有 release/repos/{owner}/{repo}/releases/来自 github api返回代码库的指定的 release 信息下列情况是错误的 URL 例子REST 接口正确错误分析/book/books通常使用复数除非查询单个对象/user/create/userURL 不应该包含动词/users/{id}/books.json/users/{id}/books无需指定返回的格式通常默认是 json如果需要其他格式可以通过媒体类型来指定比如 **application/xml**思考查看你系统的的 REST API看看有没有不符合 RESTAPI 设计原则的。【标准方法命名】HTTP 提供了标准的动作 GET、PUT、POST、DELETE 等GET 表示读取POST 表示新建PUT 表示创建或者更新PATCH 表示更新Update通常是部分更新DELETE 表示删除Delete。URL动作含义/usersGET查询所有用户/users/1GET查询 id 为 1 的用户/usersPOST创建新的用户/users/1PUT创建或者更新用户id 为 1/users/1DELETE删除用户 1/usersDELETE删除所有用户【范围查询】规定使用 offset 和 limt 作为查询参数如果数据来源是大数据通常使用 cusor 方式查询翻页范围使用 cusor 和 limit 参数俩个这里的 cusor 通常是递增主键 id。【HTTP Stauts】在开发 API 时候对于 REST 的响应结果还需要进一步规范如下 API 说明通常用如下200 表示成功400 表示客户端错误 其中 400 服务器不理解请求如参数错误401 未通过身份验证403 未授权的访问资源404 访问资源不存在500 表示服务端错误。关于 HTTP Status 定义参考[HTTP 响应状态](https://developer.mozilla.org/zh - CN/docs/Web/HTTP/Status)。如果这些 Status Code 不足以表达更明确的含义建议在响应体的 JSON 里包含 code 进一步明确错误含义比如 code 为 PARAMETER_ERROR 表示参数校验错误。message 通常用于补充 code 含义。HTTP/1.1 200 OK Content - Type: application/json { code:SUCCESS messsage:库存查询成功 data:{ } }错误响应对于基于 HTTP 协议的 API可以充分利用 HTTP STATUS 来表示 API 是否成功STATUS 304 表示授权错STATUS 500 表示内部失败等等使用 HTTP STATUS 也有利于其他系统如网关或者监控系统对错误进行观测。HTTP/1.1 500 Content - Type: application/json { code:PARAMETER_ERROR messsage:操作失败 data:{ } }使用 HTTP Status还是使用响应的 Body 中的 code 来指示 REST 的响应结果屈居于俩个因素一是 HTTP Status 仍然能粗略的表达 REST 响应状态屈居于客户端是否对状态更详细的要求比如 HTTP 500 表示服务器内不错误对于大多数电商和企业应用系统是不足以表达的二是可观测性如果已经搭建好的有可观测系统且 REST 返回结果能被客观性系统收集到则可以使用 CODE 来指示结果。 如果此时搭建的有 NGINX 的日志监控HTTP Status 也能粗略的统计到 REST 请求结果。如果 API 实现异步调用需要通过文档向调用者说明从哪里可以获取异步执行结果。或者提供一个新的 API用户可以通过 reqeust_id查询异步调用结果。或者服务端返回一个查询 ID用户可以用此 ID 查询结果。或者对于 REST 请求也可以在响应中包含一个 URL供用户查询。如下一个成功响应HTTP/1.1 200 OK Content - Type: application/json { code:ASYNC - SUCCESS messsage:成功 data:{ url:/device/ECD0017R1/status/344fer55656563 } }无论是成功或者失败都应该包含 code 和 messagecode 是成功或者错误的 CODE 定义message 是用户可阅读的的消息。对于响应的 JSON还有如下设计建议一是需要明确的区分其属性是否为 null或者不存在二是返回的空集合使用[]而不是 null或者不存在三是返回的浮点数或者长整形如果客户端是 JS需要注意到有可能 JS 不支持这情况下改成字符串。【总有例外】本节包含了通常 REST API 最佳实践有其他资料对 API 最佳实践有更严格的规定架构师需要衡量是否采用这些严格规定本文列举了几个需要衡量的点一是充分使用 HTTP Status Code有些 REST 规范要求使用更多的 HTTP Status Code 表示比如对于客户端错误采用 403 表示权限不足404 表示访问资源不存在使用。参考 rfc9110 了解更多 status 含义。本书建议使用 200400以及 500 即可更详细的错误信息放在 code 里二是 REST API 的 GET 查询不推荐携带 Body。允许 GET with Body即允许 GET 查询携带 Body。这是因为可能查询参数结构较为复杂比如 ES 提供的 /_search 其 body 就是一个 JSON 格式。再比如通常客户端 JS 框架会把页面查询条件的表单序列化成 JSON。因此通常建议使用 POST 请求且 URL 路径上增加查询动作比如 /books/search三是删除通常是用 DELETE如果是按照条件删除可以使用 POST比如 ES 中的按照查询条件删除 POST /my - index - 000001/_delete_by_query四是 REST API 大部分实践都要求参数是蛇行命名。本书建议蛇行命名以可以像 Java 那样驼峰命名。通常基于 GET 请求的 REST意味着通过 URL 分享此 REST 接口其结果易于被客户端或者代理缓存支持重定向等功能如果 GET 支持 BODY那必须确认 HTTP 代理或者是 WEB 框架是否支持。【REST 服务成熟度模型】个人觉得比较扯淡也不建议企业按照 REST 成熟度模型构建服务。【引用】如何定义 REST 接口还可以参考业内的一些实践比如 Github REST APIElasticSerch REST API。作者博客 [Blog | 闲大赋]原始文章Github REST 实践GitHub 例子Elastic Search 例子推荐阮一峰RESTful API 最佳实践推荐: **Zalando RESTful API and Event Guidelines**推荐 微软 [RESTful web API design ]博客 [API Design Patterns for REST]。