REST的6大指导原则

1. 前言REST 全称为 ：Resource Representational State Transfer. 是一种分布式超媒体系统（ distributed hypermedia systems ）架构风格。

由Roy Fielding 提出REST API 也称RESTful API， 其遵循REST架构规范的应用编程接口， 支持与RESTful WEB服务进行交互简单来讲就是：符合REST架构风格的 WEB API 或WEB 服务就是 REST API。

2. REST 的6大指导原则REST 定义了6个原则，这些原则使得一个WEB API 成为真正的RESTful API统一接口（Uniform interface）开发者一旦熟悉了你的其中一个API，那么他就可以遵循类似的结构去使用其他API.。

客户端服务器（Client-server） 只要不改变他们之间的接口，服务端和客户端可以相互替换或独立开发无状态（Stateless） 客户端上下文状态不应该存储在服务端，而应该有客户端去管理程序的状态。

可缓存（Cacheable） 优秀的缓存可以部分或者完全消除客户端和服务端的交互，最终提高应用的伸缩性和性能分层系统（Layered System） REST可以允许你使用分层架构，让你在服务器A上部署API， 服务器B上存储数据，服务器C上进行权限验证，客户端不知道它实际连接的是哪个服务器。

按需编码（Code on demand （optional）） 这些规则可以帮组你构建真正的RESTful API ，所以尽量遵循着些规则如果因为某些原因违反这些规则，事实上你还是在构建RESTful API ，只是不算真正的RESTful。

3. 最佳实践3.1 API名称API的名称应该出现在URL中，API的标题也应该和名称一致，所以起名子也是比较重要的一点，这决定了你的API是否容易让人读懂！3.2 API的版本API的版本应该遵循, MAJOR.MINOR.PATCH的结构，即主要.次要.补丁 。

如果有重大的改动，导致前后的版本不兼容应该升级主要版本， 比如从1.0 升级到2.0如果只是增加了一些特性，前后的版本都是兼容话，可以升级次要版本， 比如从1.0 升级到1.1.如果有一些小的bug修改的话，可以在补丁版本的上升级，比如从 1.0 升级到1.0.1。

例如：复制https://mysite.com/v1/... https://mysite.com/v2/...3.3提供准确的API文档开发完成一个API之后，你需要让API的使用者可以正确的使用它，那么就需要一份漂亮的API文档了。

API文档需要提供准确的请求路径， 请求示例， 以及各种error时的状态码等 可以使用Swagger等工具3.4资源路径命名资源名称使用名词，而不要使用动词 比如 POST : /cars 表示创建cars , GET: /cars 表示查询cars 而不应该写成/createCars ， /getCars 等等。

获取集合资源与获取特定资源,统一使用复数来表示资源 复制#获取资源集合时使用复数名词 例如 /schools #获取特定资源 例如 /schools/{school-id} /schools/5

#获取特定资源的子资源 例如 /schools/{school-id}/grades /schools/5/grades 3.5资源操作RESTful API 使用HTTP 方法来对资源进行操作，相对应的一些常用操作如下：

HTTP method资源操作类型GET查询集合，查询单个资源POSTCreate 创建某个资源PUTupdate 更新资源PATCH局部更新资源DELETE删除资源创建资源 POST 使用POST方法 创建资源，此处可以创建单个资源或者资源集合。

创建成功应该立马返回HTTP 201， 二接受到resource并未立即添加资源则返回 HTTP 202 复制例如： 使用POST: /schools 添加多个school资源， /schools/

{school-id}/grades 添加某个school资源的grade， 查询集合资源 及单个资源复制例如： 使用 GET: /schools?type=PRIMARY 查询所有的小学 使用 GET :

/schools/{school-id}/grades 查询某个学校的所有年级 GET :/schools/{school-id}/grades/{grade-id} 查询某个学校某个年级

更新及修改资源 PUT/PATCH 更新个修改资源包含多种情况： 一种是完全更新，使用新的资源完全替换旧的资源复制例如：PUT: /schools/{school-id}/address 更新某个客户学校的地址。

信息一种是修改局部更新，根据需求去更新修改原有的资源复制例如：PATCH: /schools/{school-id}/teachers 调整某个学校的老师 举个例子原有的资源如下：复制{ "a"

:"A", "b":{ "c":"C", "d":"D" } } 当PATAH请求 如下：复制PATCH HTTP/1.1 Content-Type: appl

ication/merge-patch+json { "a":"Z", "b":{ "d":null } } 修改后的resource如下复制{ "a":

"Z", "b":{ "c":"C" } } 删除资源 删除资源使用DELETE方法，删除的方法有直接删除，或者使资源不可见3.6请求参数其余不是资源的参数应该出现在请求参数中。

而且查询参数应该出现在GET请求中，不应该出现在PUT，POST请求中请求参数应该使用驼峰命名法 复制例如：GET /orders?startDate=2022-01-03&endDate=2022-02

-03DELETE /orders?status=EXPIRED 使用唯一查询参数进行过滤 复制GET /orders?orderType=PAID GET /orders?amount >100.00

分页查询 复制API 使用offset={resultOffset}&limit={resultsPerPage} 进行分页查询， 并且以第0条数据为起始 另外也可以使用 page={pageNumber}&。

limit={resultPerPage} 此时起始页为第1页 使用index={pageIndex}&limit={resultPerPage}, 每一页可以返回上一页或者下一页的link 可以看如下例子：

GET /orders?page=1&limit=15 第一页的15条数据 GET /orders?offset=0&limit=15 第一页的15条数据 GET /orders?page=

5&limit=10 第五页的10条数据 第51-60条 GET /orders?offset=50&limit=10 第51到60条数据 GET /orders?index=xxxxxxx&

limit=10 同样也可以表示第51-60条数据， 只不过对客户端来说可能不知道第几页，response中应该包含有上一页和下一页的index排序 API的排序功能是API非常重要的一个功能，可以使用sort，sort-by 即使没有指出要排序，那么而应该给一个默认的排序。

复制例如： GET /orders?sort=asc(date) /orders?sort=desc(date) GET /orders?sort=+date /orders?sort=-

dateGET /orders?sort=date.asc /orders?sort=date.descGET /orders?sort=date&order-by=asc /orders?sort=-

date&order-by=desc 多字段排序示例： GET /orders?sort=desc(date),asc(amount) GET /orders?sort=-date

,+amount 3.7使用HTTP状态码处理错误Http状态码有很多，这里列举一些常见的http status描述2XXSUCCESS200OK201Create202Accepted204No Content。

4XXClient Error400Bad Request401Unauthorized403Forbidden404Not Found429Too Many Request5xxServer Errors

500Internal Server Error总结本篇介绍了一些REST API的一些食用方式，我们工作中可以根据一些各自的条件，作为参考。欢迎留言讲讲自己的一些实践经验！

版权声明：本文内容由网络用户投稿，版权归原作者所有，本站不拥有其著作权，亦不承担相应法律责任。如果您发现本站中有涉嫌抄袭或描述失实的内容，请联系我们jiasou666@gmail.com 处理，核实后本网站将在24小时内删除侵权内容。