大家好，我是北军。RESTfulHTTP方法包括POST、GET、PUT、DELETE、PATCH等。那么我们在开发的时候应该如何写出优雅的RESTful接口呢？本文为大家带来RESTfulAPI实践阶段。一、前言REST的全称是：ResourceRepresentationalStateTransfer。它是分布式超媒体系统的一种架构风格。由RoyFielding推荐。RESTAPI，又称RESTfulAPI，遵循REST架构规范的应用程序编程接口，支持与RESTfulWEB服务交互。简单来说：符合REST架构风格的WEBAPI或WEB服务就是RESTAPI。2.REST的6条指导原则REST定义了6条原则，使WEBAPI成为真正的RESTfulAPI。一旦统一接口开发人员熟悉了您的一个API，他就可以按照类似的结构来使用其他API。只要客户端-服务器端（Client-server）不改变它们之间的接口，服务器端和客户端可以相互替代或独立开发。无状态（Stateless）客户端上下文状态不应该存储在服务器上，而应该由客户端管理程序的状态应用程序性能可扩展性和性能。分层系统（LayeredSystem）REST允许你使用分层架构，允许你在服务器A上部署API，在服务器B上存储数据，在服务器C上进行权限验证。客户端不知道它实际连接的是哪个服务器.按需代码（可选）这些规则可以帮助您构建真正的RESTfulAPI，因此请尽量遵循这些规则。如果您出于某种原因违反了这些规则，您仍在构建RESTfulAPI，它只是不是真正的RESTful。3.最佳实践3.1API名称API的名称应该出现在URL中，API的标题也应该和名称保持一致，所以命名也是很重要的一点，它决定了你的API是否容易被人接受理解！3.2APIAPI版本应遵循MAJOR.MINOR.PATCH结构，即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文档需要提供准确的请求路径、请求示例以及各种错误的状态码。可以使用Swagger等工具。3.4资源路径命名资源名称使用名词，而不是动词。比如POST:/cars表示创建汽车，GET:/cars表示查询汽车，而不是/createCars、/getCars等。获取集体资源和获取特定资源，统一使用复数来表示资源。#获取资源集合时使用复数名词如/schools#获取具体资源如/schools/{school-id}/schools/5#获取具体资源的子资源如/schools/{school-id}/grades/schools/5/grades3.5资源操作RESTfulAPI使用HTTP方法对资源进行操作，对应的常用操作如下：HTTP方法资源操作类型GET查询集合，查询单个资源POSTCreate创建资源PUTupdate部分更新资源PATCHupdateresourceDELETE删除资源CreateresourcePOST使用POST方法创建资源，这里可以创建单个资源或资源集合。如果创建成功，应该立即返回HTTP201，如果收到资源后没有立即添加资源，则应该返回HTTP202。例如：使用POST:/schools添加多个学校资源，/schools/{school-id}/grades添加一个学校资源的年级，查询集合资源和单个资源例如：使用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请求如下：PATCHHTTP/1.1Content-Type:application/merge-patch+json{"a":"Z","b":{"d":null}}修改后的资源如下：{"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=PAIDGET/orders?amount>100.00分页查询API使用offset={resultOffset}&limit={resultsPerPage}进行分页查询，从第0条数据开始。另外，也可以使用page={pageNumber}&limit={resultPerPage}，此时起始页为第1页。使用index={pageIndex}&limit={resultPerPage}，每页都可以返回到第1页的链接上一页或下一页。看下面的例子：GET/orders?page=1&limit=15第一页15条数据GET/orders?offset=0&limit=15第一页15条数据GET/orders?page=5&limit=1010条第五页第51-60条数据GET/orders?offset=50&limit=10第51到60条数据GET/orders?index=xxxxxxx&limit=10也可以代表51-60的数据，但是对于客户端不知道是哪个页面，响应中应该包含上一页和下一页的索引。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,+amount3.7使用HTTP状态码处理错误http状态描述2XXSUCCESS200OK201Create202Accepted204NoContent4XXClientError400BadRequest401Unauthorized403Forbidden404NotFound429TooManyRequest5xxServerErrors500InternalServerError根据本文的一些工作方法，我们总结了一些API可以吃参考。
