当前位置:文档之家› 微服务接口定义规范

微服务接口定义规范

接口定义规范研发部2018/011.URI命名规范 (3)2.使用HTTP方法表示动作行为 (4)3.使用HTTP内容协商处理资源表示内容 (4)4.使用HTTP响应状态码标识处理结果状态 (5)5.使用HAL(Hypertext Application Language)作为响应数据格式 (6)6.各HTTP方法成功处理后的返回数据 (9)7.不要对返回结果进行封装 (9)8.支持资源的字段裁剪,减少响应中返回的字段数量 (10)9.使用OAuth2来确保API 的安全性 (10)10.确保GET,PUT,DELETE 请求是幂等的 (10)11.API版本 (10)微服务接口设计采用Restful风格的接口规范,下面是基于Restful风格要求制订的接口设计规范。

1.URI命名规范➢不用大写;➢用中杠-不用下杠_;➢参数列表要encode;➢使用名词作为资源名称 (例如,不要在网址中使用动词);➢使用资源集合的概念;❖每种资源有两类URI(接口):◆资源集合(例如,/orders);◆集合中的单个资源(例如,/orders/{orderId})。

❖使用复数形式 (使用‘orders’而不是‘order’);❖资源名称和 ID 组合可以作为一个网址的节点;例如,/orders/{orderId}/items/{itemId};❖尽可能的让网址越短越好,单个网址最好不超过三个节点。

可以使用查询参数代替路径中的节点组合➢对Composite资源的访问服务器端的组合实体必须在uri中通过父实体的id导航访问。

GET /orders/12/items➢使用有意义的资源描述;❖“禁止单纯的使用 ID!”响应信息中不应该存在单纯的 ID,应使用链接或是引用的对象;❖设计资源的表述信息,而不是简简单单的做数据库表的映射;❖合并表述信息,不要通过两个 ID 直接表示两个表的关系;➢资源的集合应支持过滤,排序和分页;过滤、排序、分页应出现在参数列表中而不是Path中。

例如:GET /currencies?page=1&size=10过滤条件应该合并到一个参数里:GET "name::todd|city::denver|title::grand poobah”排序字段也应该合并到一个参数里,使用-代表倒序GET _name|first_name|-hire_date➢经常使用的、复杂的查询标签化,降低维护成本。

如:GET /trades?status=closed&sort=created desc快捷方式:GET /trades/recently-closed2.使用HTTP方法表示动作行为❖POST - 创建资源,非幂等性操作;❖PUT - 更新资源;❖PATCH - 部分更新资源;❖GET - 获取单个资源或资源集合;❖DELETE - 删除单个资源或资源集合;原则上URI中不应该出现动词,当出现复杂操作超出上述HTTP方法描述的行为时,可以考虑通过URL参数来指定动作。

如 PUT /books/1?action=like 标注ID为1的图书为喜爱图书使用其他动作时,HTTP方法仍然根据实际操作属于那种类型设定,比如属于资源的更新操作,那么就使用PUT方法。

3.使用HTTP内容协商处理资源表示内容通过请求头/响应头中的Content-Type判断请求提中的数据类型,然后根据数据类型做出相应处理。

❖请求Body内容格式采用JSON格式,其格式通过HTTP HeaderContent-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/xml4.使用HTTP响应状态码标识处理结果状态❖不要发生了错误但给2xx响应,客户端可能会缓存成功的http请求;❖正确设置http状态码,不要自定义;下面是常用状态码及其意义:对于400、409、500这种需要进一步说明原因的错误码,可以在响应体中返回对应的错误信息,格式如下:{code:’500’,message:'服务暂不可用,请稍后重试或与管理员联系'}5.使用 HAL(Hypertext Application Language)作为响应数据格式❖简单资源对象:{ "_links": { "self": { "href": "/user/matthew" } }, "id": "matthew", "name": "Matthew Weier O'Phinney" }❖复杂资源对象:{ "_links": { "self": { "href": "/user/matthew" } }, "id": "matthew", "name": "Matthew Weier O'Phinney", "_embedded": { "contacts": [ { "_links": { "self": { "href": "/user/mac_nibblet" } }, "id": "mac_nibblet", "name": "Antoine Hedgecock" }, { "_links": { "self": { "href": "/user/spiffyjr" } }, "id": "spiffyjr", "name": "Kyle Spraggs" } ], "website": { "_links": { "self": { "href":"/locations/mwop" } }, "id": "mwop", "url": "" }, } }❖带有分页的结果:{"_embedded" : {"currencyLogs" : [ { "uid" : "","type" : 1,"coin" : 0.50,"usercoin" : 5.50, "add_time" : "64", "expressid" : 0}, {"uid" : "","type" : 1,"coin" : 0.50,"usercoin" : 6.00, "add_time" : "87", "expressid" : 0},....................{"uid" : "","type" : 1,"coin" : 0.50,"usercoin" : 10.00, "add_time" : "49", "expressid" : 0} ]},"_links" : {"first" : {"href" : ""},"prev" : {"href" : ""},"self" : {"href" : ""},"next" : {"href" : ""},"last" : {"href" : ""}},"page" : {"size" : 10,"totalElements" : 53454, "totalPages" : 5346,"number" : 1}}6.各HTTP方法成功处理后的返回数据7.不要对返回结果进行封装response 的 body 直接就是数据,不要做多余的包装。

{"uid" : "","type" : 1,"coin" : 24991.50,"expressid" : 0,"_links" : {"self" : {"href" : ""}}}8.支持资源的字段裁剪,减少响应中返回的字段数量9.使用来确保API 的安全性❖使用 Bearer Token 进行身份验证;❖OAuth2 的 Bearer token 要求必须通过 HTTPS / TLS / SSL 来访问你的API。

通过 HTTP 进行的未加密通信将导致窃听和重放。

10.确保GET,PUT,DELETE 请求是幂等性:执行1次和执行N次,对资源状态改变的效果是等价的。

相关主题