微服务接口定义规范方案

..接口定义规范研发部2018/01..TOC\o"1-3"\h\u1．URI命名规范32．使用HTTP方法表示动作行为43．使用HTTP内容协商处理资源表示内容44．使用HTTP响应状态码标识处理结果状态55．使用HAL<HypertextApplicationLanguage>作为响应数据格式66．各HTTP方法成功处理后的返回数据97．不要对返回结果进行封装98．支持资源的字段裁剪,减少响应中返回的字段数量109．使用

OAuth2

来确保API的安全性1010．确保GET,PUT,DELETE请求是幂等的1011．API版本10..微服务接口设计采用Restful风格的接口规范,下面是基于Restful风格要求制订的接口设计规范。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/users?filter="name::todd|city::denver|title::grandpoobah" 排序字段也应该合并到一个参数里,使用-代表倒序 GET/users?sort=last_name|first_name|-hire_date经常使用的、复杂的查询标签化,降低维护成本。如：GET/trades?status=closed&sort=createddesc快捷方式：GET/trades/recently-closed使用HTTP方法表示动作行为POST-创建资源,非幂等性操作；PUT-更新资源；PATCH-部分更新资源；GET-获取单个资源或资源集合；DELETE-删除单个资源或资源集合；原则上URI中不应该出现动词,当出现复杂操作超出上述HTTP方法描述的行为时,可以考虑通过URL参数来指定动作。如PUT/books/1?action=like标注ID为1的图书为喜爱图书使用其他动作时,HTTP方法仍然根据实际操作属于那种类型设定,比如属于资源的更新操作,那么就使用PUT方法。使用HTTP内容协商处理资源表示内容通过请求头/响应头中的Content-Type判断请求提中的数据类型,然后根据数 据类型做出相应处理。请求Body内容格式采用JSON格式,其格式通过HTTPHeader Content-Type:application/json表示。或From表单格式,其格式通过HTTPHeader：Content-Type:application/x-www-form-urlencoded响应内容格式为JSON,响应头Content-Type:application/json或HAL+JSON,响应头为Content-Type:application/hal+json或XML格式,响应头为Content-Type:text/xml使用HTTP响应状态码标识处理结果状态不要发生了错误但给2xx响应,客户端可能会缓存成功的http请求；正确设置http状态码,不要自定义；下面是常用状态码及其意义：响应码说明200OK请求处理正常,通常用于GET操作时内容正常返回201CreatedPost或PUT操作时对象被正常创建,通常在Body中返回对象内容。204Nocontent处理成功,但没返回值。如delete操作,没有内容可返回。301Movedpermanently资源被移动到其它位置,需要客户端重定向。400Badrequest请求有问题,可能是缺少参数或参数不正确,需要客户端修正请求内容。可以在请求体中返回错误提示信息。401Unauthorized指定资源需要授权,用户未认证身份所以不能访问资源。403Forbidden用户已登录但是没有指定资源的访问权限。404Notfound指定的资源不存在。405Methodnotallowed资源不支持访问方法,如对只读资源使用PUT进行更新409

Conflict将出现重复的数据或是无效的数据状态。500Internalservererror服务器发生非预期错误,此时需要在响应体中返回错误的具体信息。对于400、409、500这种需要进一步说明原因的错误码,可以在响应体中返回对应的错误信息,格式如下：{code:’500’,message:'服务暂不可用,请稍后重试或与管理员联系'}使用HAL<HypertextApplicationLanguage>作为响应数据格式简单资源对象：{"_links":{"self":{"href":"/api/user/matthew"}},"id":"matthew","name":"MatthewWeierO'Phinney"}复杂资源对象：{"_links":{"self":{"href":"/api/user/matthew"}},"id":"matthew","name":"MatthewWeierO'Phinney","_embedded":{"contacts":[{"_links":{"self":{"href":"/api/user/mac_nibblet"}},"id":"mac_nibblet","name":"AntoineHedgecock"},{"_links":{"self":{"href":"/api/user/spiffyjr"}},"id":"spiffyjr","name":"KyleSpraggs"}],"website":{"_links":{"self":{"href":"/api/locations/mwop"}},"id":"mwop","url":""},}}带有分页的结果：{"_embedded":{"currencyLogs":[{"type":1,"coin":0.50,"usercoin":5.50,"add_time":"1504228164","expressid":0},{"type":1,"coin":0.50,"usercoin":6.00,"add_time":"1504228187","expressid":0},{"type":1,"coin":0.50,"usercoin":10.00,"add_time":"1504228349","expressid":0}]},"_links":{"first":{},"prev":{gs/group-by-day?page=0&size=10"},"self":{},"next":{page=2&size=10"},"last":{}},"page":{"size":10,"totalElements":53454,"totalPages":5346,"number":1}}各HTTP方法成功处理后的返回数据HTTP方法response格式GET单个对象、集合POST新增成功的对象、或URIPUT/PATCH更新成功的对象或URIDELETE空不要对返回结果进行封装response的body直接就是数据,不要做多余的包装。{"type":1,"coin":24991.50,"expressid":0,"_links":{"self":{"href":"http://localhost:8011/currencies/270"}}}支持资源的字段裁剪,减少响应中返回的字段数量使用

OAuth2

来确保API的安全性使用