微服务接口定义规范标准[详]

1、. . . . 接口定义规范研发部2018/01参考.资料1 URI命名规范32 使用HTTP方法表示动作行为43 使用HTTP内容协商处理资源表示内容44 使用HTTP响应状态码标识处理结果状态55 使用 HAL(Hypertext Application Language)作为响应数据格式66 各HTTP方法成功处理后的返回数据97 不要对返回结果进行封装98 支持资源的字段裁剪，减少响应中返回的字段数量109 使用 OAuth2 来确保 API 的安全性1010 确保GET，PUT，DELETE 请求是幂等的1011 API版本10微服务

2、接口设计采用Restful风格的接口规范，下面是基于Restful风格要求制订的接口设计规范。1 URI命名规范Ø 不用大写；Ø 用中杠-不用下杠_；Ø 参数列表要encode；Ø 使用名词作为资源名称 (例如，不要在网址中使用动词)；Ø 使用资源集合的概念；v 每种资源有两类URI（接口）：u 资源集合（例如，/orders）；u 集合中的单个资源（例如，/orders/orderId）。v 使用复数形式 (使用 orders 而不是 order)；v 资源名称和 ID 组合可以作为一个网址的节点；例如，/orders/orderId/ite

3、ms/itemId；v 尽可能的让网址越短越好，单个网址最好不超过三个节点。可以使用查询参数代替路径中的节点组合Ø 对Composite资源的访问服务器端的组合实体必须在uri中通过父实体的id导航访问。GET /orders/12/itemsØ 使用有意义的资源描述；v “禁止单纯的使用 ID!” 响应信息中不应该存在单纯的 ID，应使用链接或是引用的对象；v 设计资源的表述信息，而不是简简单单的做数据库表的映射；v 合并表述信息，不要通过两个 ID 直接表示两个表的关系；Ø 资源的集合应支持过滤，排序和分页；过滤、排序、分页应出现在参数列表中而不是Path中。

4、例如：GET /currencies?page=1&size=10过滤条件应该合并到一个参数里：GET poobah” 排序字段也应该合并到一个参数里,使用-代表倒序GET Ø 经常使用的、复杂的查询标签化，降低维护成本。如：GET /trades?status=closed&sort=created desc快捷方式：GET /trades/recently-closed2 使用HTTP方法表示动作行为v POST - 创建资源，非幂等性操作；v PUT - 更新资源；v PATCH - 部分更新资源；v GET - 获取单个资源或资源集合；v DELETE - 删

5、除单个资源或资源集合；原则上URI中不应该出现动词，当出现复杂操作超出上述HTTP方法描述的行为时，可以考虑通过URL参数来指定动作。如 PUT /books/1?action=like 标注ID为1的图书为喜爱图书使用其他动作时，HTTP方法仍然根据实际操作属于那种类型设定，比如属于资源的更新操作，那么就使用PUT方法。3 使用HTTP内容协商处理资源表示内容 通过请求头/响应头中的Content-Type判断请求提中的数据类型，然后根据数据类型做出相应处理。v 请求Body内容格式采用JSON格式，其格式通过HTTP Header Content-Type:application/json

6、表示。v 或From表单格式，其格式通过HTTP Header：Content-Type: application/x-www-form-urlencodedv 响应内容格式为JSON，响应头Content-Type:application/jsonv 或HAL+JSON，响应头为Content-Type:application/hal+jsonv 或XML格式，响应头为Content-Type:text/xml4 使用HTTP响应状态码标识处理结果状态v 不要发生了错误但给2xx响应，客户端可能会缓存成功的http请求；v 正确设置http状态码，不要自定义； 下面是常用状态码及其意义： 响

7、应码说明200 OK请求处理正常，通常用于GET操作时内容正常返回201 CreatedPost或PUT操作时对象被正常创建，通常在Body中返回对象内容。204 No content处理成功，但没返回值。如delete操作，没有内容可返回。301 Moved permanently 资源被移动到其它位置，需要客户端重定向。400 Bad request请求有问题，可能是缺少参数或参数不正确，需要客户端修正请求内容。可以在请求体中返回错误提示信息。401 Unauthorized 指定资源需要授权，用户未认证身份所以不能访问资源。403 Forbidden 用户已登录但是没有指定资源的访问权限

8、。404 Not found 指定的资源不存在。405 Method not allowed资源不支持访问方法，如对只读资源使用PUT进行更新409 Conflict将出现重复的数据或是无效的数据状态。500 Internal server error服务器发生非预期错误，此时需要在响应体中返回错误的具体信息。对于400、409、500这种需要进一步说明原因的错误码，可以在响应体中返回对应的错误信息，格式如下：code:500,message:'服务暂不可用，请稍后重试或与管理员联系' 5 使用 HAL(Hypertext Application&

9、#160;Language)作为响应数据格式v 简单资源对象： "_links": "self": "href": "/api/user/matthew" , "id": "matthew", "name": "Matthew Weier O'Phinney" v 复杂资源对象： "_links": "self": "href": &q

10、uot;/api/user/matthew" , "id": "matthew", "name": "Matthew Weier O'Phinney", "_embedded": "contacts": "_links": "self": "href": "/api/user/mac_nibblet" , &qu

11、ot;id": "mac_nibblet", "name": "Antoine Hedgecock" , "_links": "self": "href": "/api/user/spiffyjr" , "id": "spiffyjr", "name": "Kyle Spraggs" , "website": &q

12、uot;_links": "self": "href": "/api/locations/mwop" , "id": "mwop", "url": "" , v 带有分页的结果： "_embedded" : "currencyLogs" : "uid" : "quot;, "type" : 1, &q

13、uot;coin" : 0.50, "usercoin" : 5.50, "add_time" : "1504228164", "expressid" : 0 , "uid" : "quot;, "type" : 1, "coin" : 0.50, "usercoin" : 6.00, "add_time" : "1504228187", "e

14、xpressid" : 0,. "uid" : "quot;, "type" : 1, "coin" : 0.50, "usercoin" : 10.00, "add_time" : "1504228349", "expressid" : 0 , "_links" : "first" : "href" : "http:/localhost:80

15、11/userscurrencylogs/group-by-day?page=0&size=10" , "prev" : "href" : "http:/localhost:8011/userscurrencylogs/group-by-day?page=0&size=10" , "self" : "href" : "http:/localhost:8011/userscurrenc

16、ylogs/group-by-day?page=1&size=10" , "next" : "href" : "http:/localhost:8011/userscurrencylogs/group-by-day?page=2&size=10" , "last" : "href" : "http:/localhost:8011/userscurrencylogs/group-by-day?page=5345

17、&size=10" , "page" : "size" : 10, "totalElements" : 53454, "totalPages" : 5346, "number" : 1 6 各HTTP方法成功处理后的返回数据HTTP方法response 格式GET单个对象、集合POST新增成功的对象、或URIPUT/PATCH更新成功的对象或URIDELETE空7 不要对返回结果进行封装response 的 body 直接就是数据，不要做多余的包装。 "uid&quo

18、t; : "quot;, "type" : 1, "coin" : 24991.50, "expressid" : 0, "_links" : "self" : "href" : "http:/localhost:8011/currencies/270" 8 支持资源的字段裁剪，减少响应中返回的字段数量9 使用 OAuth2 来确保 API 的安全性v 使用 Bearer Token 进行身份验证；v OAuth2 的 Bearer token 要求必须通过 HTTPS / TLS / SSL 来访问你的 API。通过 HTTP 进行的未加密通信将导致窃听和重放。10 确保GET，PUT，DELETE 请求是幂等的 幂等性：执行1次和执行N次，对资源状态改变的效果是等价的。11 API版本使用HEADER传递版本信息。# RequestGET Accept: application/jsonContent-Type: application/json; version=1 1. 若不给自己设限，则人生中就没有限制你发挥的藩篱。2. 若不是心宽似海