微服务接口定义规范.docx

1、西安景兆科技有限公司西安景兆科技有限公司接口定义规范研发部西安景兆科技有限公司西安景兆科技有限公司2018/01西安景兆科技有限公司西安景兆科技有限公司1 URI 命名规范 .32 使用 HTTP 方法表示动作行为 .43 使用 HTTP 内容协商处理资源表示内容 .44 使用 HTTP 响应状态码标识处理结果状态 .55 使用 HAL(Hypertext Application Language)作为响应数据格式 .66 各 HTTP 方法成功处理后的返回数据 .97 不要对返回结果进行封装 .98 支持资源的字段裁剪，减少响应中返回的字段数量 .109 使用 OAuth2 来确保 API

2、的安全性 .1010 确保 GET，PUT，DELETE 请求是幂等的 .1011 API 版本 .10西安景兆科技有限公司西安景兆科技有限公司微服务接口设计采用 Restful 风格的接口规范，下面是基于 Restful 风格要求制订的接口设计规范。1URI 命名规范 不用大写； 用中杠-不用下杠_； 参数列表要 encode； 使用名词作为资源名称 (例如，不要在网址中使用动词)； 使用资源集合的概念； 每种资源有两类 URI（接口）： 资源集合（例如，/orders）； 集合中的单个资源（例如，/orders/orderId）。 使用复数形式 (使用 orders 而不是 order)；

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

4、序和分页；西安景兆科技有限公司西安景兆科技有限公司过滤、排序、分页应出现在参数列表中而不是 Path 中。例如：GET /currencies?page=1&size=10过滤条件应该合并到一个参数里：GET http:/ poobah”排序字段也应该合并到一个参数里,使用-代表倒序GET http:/ 经常使用的、复杂的查询标签化，降低维护成本。如：GET /trades?status=closed&sort=created desc快捷方式：GET /trades/recently-closed2使用 HTTP 方法表示动作行为 POST - 创建资源，非幂等性操作； PUT - 更新资源

5、； PATCH - 部分更新资源； GET - 获取单个资源或资源集合； DELETE - 删除单个资源或资源集合；原则上 URI 中不应该出现动词，当出现复杂操作超出上述 HTTP 方法描述的行为时，可以考虑通过 URL 参数来指定动作。如 PUT /books/1?action=like 标注 ID 为 1 的图书为喜爱图书使用其他动作时，HTTP 方法仍然根据实际操作属于那种类型设定，比如属于资源的更新操作，那么就使用 PUT 方法。西安景兆科技有限公司西安景兆科技有限公司3使用 HTTP 内容协商处理资源表示内容通过请求头/响应头中的 Content-Type 判断请求提中的数据类型，

6、然后根据数据类型做出相应处理。 请求 Body 内容格式采用 JSON 格式，其格式通过 HTTP Header Content-Type:application/json 表示。 或 From 表单格式，其格式通过 HTTP Header：Content-Type: application/x-www-form-urlencoded 响应内容格式为 JSON，响应头 Content-Type:application/json 或 HAL+JSON，响应头为 Content-Type:application/hal+json 或 XML 格式，响应头为 Content-Type:text/xm

7、l4使用 HTTP 响应状态码标识处理结果状态 不要发生了错误但给 2xx 响应，客户端可能会缓存成功的 http 请求； 正确设置 http 状态码，不要自定义；下面是常用状态码及其意义：响应码 说明200 OK 请求处理正常，通常用于 GET 操作时内容正常返回201 Created Post 或 PUT 操作时对象被正常创建，通常在 Body中返回对象内容。204 No content 处理成功，但没返回值。如 delete 操作，没有内容可返回。西安景兆科技有限公司西安景兆科技有限公司对于 400、409、500 这种需要进一步说明原因的错误码，可以在响应体中返回对应的错误信息，格式如

8、下：code:500,message:服务暂不可用，请稍后重试或与管理员联系 5使用 HAL(Hypertext Application Language)作为响应数据格式 简单资源对象： “_links“: “self“: “href“: “http:/example.org/api/user/matthew“ , “id“: “matthew“, “name“: “Matthew Weier OPhinney“ 301 Moved permanently 资源被移动到其它位置，需要客户端重定向。400 Bad request 请求有问题，可能是缺少参数或参数不正确，需要客户端修正请求内容。

9、可以在请求体中返回错误提示信息。401 Unauthorized 指定资源需要授权，用户未认证身份所以不能访问资源。403 Forbidden 用户已登录但是没有指定资源的访问权限。404 Not found 指定的资源不存在。405 Method not allowed 资源不支持访问方法，如对只读资源使用 PUT 进行更新409 Conflict 将出现重复的数据或是无效的数据状态。500 Internal server error 服务器发生非预期错误，此时需要在响应体中返回错误的具体信息。西安景兆科技有限公司西安景兆科技有限公司 复杂资源对象： “_links“: “self“: “h

10、ref“: “http:/example.org/api/user/matthew“ , “id“: “matthew“, “name“: “Matthew Weier OPhinney“, “_embedded“: “contacts“: “_links“: “self“: “href“: “http:/example.org/api/user/mac_nibblet“ , “id“: “mac_nibblet“, “name“: “Antoine Hedgecock“ , “_links“: “self“: “href“: “http:/example.org/api/user/spiff

11、yjr“ , “id“: “spiffyjr“, “name“: “Kyle Spraggs“ , “website“: “_links“: “self“: “href“: “http:/example.org/api/locations/mwop“ , “id“: “mwop“, “url“: “http:/“ , 带有分页的结果：“_embedded“ : “currencyLogs“ : “uid“ : “18349348944“,“type“ : 1,“coin“ : 0.50,“usercoin“ : 5.50,“add_time“ : “1504228164“,“expressid

12、“ : 0, “uid“ : “18349348944“,“type“ : 1,“coin“ : 0.50,“usercoin“ : 6.00,“add_time“ : “1504228187“,“expressid“ : 0西安景兆科技有限公司西安景兆科技有限公司,.“uid“ : “18349348944“,“type“ : 1,“coin“ : 0.50,“usercoin“ : 10.00,“add_time“ : “1504228349“,“expressid“ : 0 ,“_links“ : “first“ : “href“ : “http:/localhost:8011/user

13、s/18349348944/currencylogs/group-by-day?page=0&size=10“,“prev“ : “href“ : “http:/localhost:8011/users/18349348944/currencylogs/group-by-day?page=0&size=10“,“self“ : “href“ : “http:/localhost:8011/users/18349348944/currencylogs/group-by-day?page=1&size=10“,西安景兆科技有限公司西安景兆科技有限公司“next“ : “href“ : “http:

14、/localhost:8011/users/18349348944/currencylogs/group-by-day?page=2&size=10“,“last“ : “href“ : “http:/localhost:8011/users/18349348944/currencylogs/group-by-day?page=5345&size=10“,“page“ : “size“ : 10,“totalElements“ : 53454,“totalPages“ : 5346,“number“ : 16各 HTTP 方法成功处理后的返回数据HTTP方法 response 格式GET 单个对象、集合POST 新增成功的对象、或 URIPUT/PATCH 更新成功的对象或 URI