欢迎来到天天文库
浏览记录
ID:34561710
大小:31.43 KB
页数:10页
时间:2019-03-07
《微服务接口定义要求规范》由会员上传分享,免费在线阅读,更多相关内容在应用文档-天天文库。
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}/it
3、ems/{itemId};v尽可能的让网址越短越好,单个网址最好不超过三个节点。可以使用查询参数代替路径中的节点组合Ø对Composite资源的访问服务器端的组合实体必须在uri中通过父实体的id导航访问。GET/orders/12/itemsØ使用有意义的资源描述;v“禁止单纯的使用ID!”响应信息中不应该存在单纯的ID,应使用链接或是引用的对象;v设计资源的表述信息,而不是简简单单的做数据库表的映射;v合并表述信息,不要通过两个ID直接表示两个表的关系;Ø资源的集合应支持过滤,排序和分页;过滤、排序、分页应出现在参数列表中而不是Path
4、中。例如:GET/currencies?page=1&size=10文档标准实用文案过滤条件应该合并到一个参数里:GEThttp://www.example.com/users?filter="name::todd
5、city::denver
6、title::grandpoobah”排序字段也应该合并到一个参数里,使用-代表倒序GEThttp://www.example.com/users?sort=last_name
7、first_name
8、-hire_dateØ经常使用的、复杂的查询标签化,降低维护成本。如:GET/trades?status
9、=closed&sort=createddesc快捷方式:GET/trades/recently-closed1.使用HTTP方法表示动作行为vPOST-创建资源,非幂等性操作;vPUT-更新资源;vPATCH-部分更新资源;vGET-获取单个资源或资源集合;vDELETE-删除单个资源或资源集合;原则上URI中不应该出现动词,当出现复杂操作超出上述HTTP方法描述的行为时,可以考虑通过URL参数来指定动作。如PUT/books/1?action=like标注ID为1的图书为喜爱图书使用其他动作时,HTTP方法仍然根据实际操作属于那种类型设
10、定,比如属于资源的更新操作,那么就使用PUT方法。2.使用HTTP内容协商处理资源表示内容通过请求头/响应头中的Content-Type判断请求提中的数据类型,然后根据数据类型做出相应处理。文档标准实用文案v请求Body内容格式采用JSON格式,其格式通过HTTPHeaderContent-Type:application/json表示。v或From表单格式,其格式通过HTTPHeader:Content-Type:application/x-www-form-urlencodedv响应内容格式为JSON,响应头Content-Type:a
11、pplication/jsonv或HAL+JSON,响应头为Content-Type:application/hal+jsonv或XML格式,响应头为Content-Type:text/xml1.使用HTTP响应状态码标识处理结果状态v不要发生了错误但给2xx响应,客户端可能会缓存成功的http请求;v正确设置http状态码,不要自定义;下面是常用状态码及其意义:响应码说明200OK请求处理正常,通常用于GET操作时内容正常返回201CreatedPost或PUT操作时对象被正常创建,通常在Body中返回对象内容。204Nocontent处
12、理成功,但没返回值。如delete操作,没有内容可返回。301Movedpermanently资源被移动到其它位置,需要客户端重定向。400Badrequest请求有问题,可能是
此文档下载收益归作者所有