微服务接口定义规范标准.docx
《微服务接口定义规范标准.docx》由会员分享，可在线阅读，更多相关《微服务接口定义规范标准.docx（7页珍藏版）》请在冰豆网上搜索。
微服务接口定义规范标准
接口定义规范
研发部
2018/01
微服务接口设计采用Restful风格的接口规范,下面是基于Restful风格要求制订的接口设计规范。
1．URI命名规范
Ø不用大写；
Ø用中杠-不用下杠_；
Ø参数列表要encode；
Ø使用名词作为资源名称<例如,不要在网址中使用动词>；
Ø使用资源集合的概念；
v每种资源有两类URI〔接口：
◆资源集合〔例如,/orders；
◆集合中的单个资源〔例如,/orders/{orderId}。
v使用复数形式<使用‘orders’而不是‘order’>；
v资源名称和ID组合可以作为一个网址的节点；
例如,/orders/{orderId}/items/{itemId}；
v尽可能的让网址越短越好,单个网址最好不超过三个节点。
可以使用查询参数代替路径中的节点组合
Ø对Composite资源的访问
服务器端的组合实体必须在uri中通过父实体的id导航访问。
GET/orders/12/items
Ø使用有意义的资源描述；
v"禁止单纯的使用ID!
"响应信息中不应该存在单纯的ID,应使用链接或是引用的对象；
v设计资源的表述信息,而不是简简单单的做数据库表的映射；
v合并表述信息,不要通过两个ID直接表示两个表的关系；
Ø资源的集合应支持过滤,排序和分页；
过滤、排序、分页应出现在参数列表中而不是Path中。
例如：
GET/currencies?
page=1&size=10
过滤条件应该合并到一个参数里：
GET:
//example/users?
filter="name:
:
todd|city:
:
denver|title:
:
grandpoobah"
排序字段也应该合并到一个参数里,使用-代表倒序
GET:
//example/users?
sort=last_name|first_name|-hire_date
Ø经常使用的、复杂的查询标签化,降低维护成本。
如：
GET/trades?
status=closed&sort=createddesc
快捷方式：
GET/trades/recently-closed
2．使用方法表示动作行为
vPOST-创建资源,非幂等性操作；
vPUT-更新资源；
vPATCH-部分更新资源；
vGET-获取单个资源或资源集合；
vDELETE-删除单个资源或资源集合；
原则上URI中不应该出现动词,当出现复杂操作超出上述方法描述的行为时,可以考虑通过URL参数来指定动作。
如PUT/books/1?
action=like标注ID为1的图书为喜爱图书
使用其他动作时,方法仍然根据实际操作属于那种类型设定,比如属于资源的更新操作,那么就使用PUT方法。
3．使用内容协商处理资源表示内容
通过请求头/响应头中的Content-Type判断请求提中的数据类型,然后根据数
据类型做出相应处理。
v请求Body内容格式采用JSON格式,其格式通过HeaderContent-Type:
application/json表示。
v或From表单格式,其格式通过Header：
Content-Type:
application/x-www-form-urlencoded
v响应内容格式为JSON,响应头Content-Type:
application/json
v或HAL+JSON,响应头为Content-Type:
application/hal+json
v或XML格式,响应头为Content-Type:
text/xml
4．使用响应状态码标识处理结果状态
v不要发生了错误但给2xx响应,客户端可能会缓存成功的请求；
v正确设置状态码,不要自定义；
下面是常用状态码及其意义：
响应码
说明
200OK
请求处理正常,通常用于GET操作时内容正常返回
201Created
Post或PUT操作时对象被正常创建,通常在Body中返回对象内容。
204Nocontent
处理成功,但没返回值。
如delete操作,没有内容可返回。
301Movedpermanently
资源被移动到其它位置,需要客户端重定向。
400Badrequest
请求有问题,可能是缺少参数或参数不正确,需要客户端修正请求内容。
可以在请求体中返回错误提示信息。
401Unauthorized
指定资源需要授权,用户未认证身份所以不能访问资源。
403Forbidden
用户已登录但是没有指定资源的访问权限。
404Notfound
指定的资源不存在。
405Methodnotallowed
资源不支持访问方法,如对只读资源使用PUT进行更新
409 Conflict
将出现重复的数据或是无效的数据状态。
500Internalservererror
服务器发生非预期错误,此时需要在响应体中返回错误的具体信息。
对于400、409、500这种需要进一步说明原因的错误码,可以在响应体中返回对应的错误信息,格式如下：
{
code:
’500’,
message:
'服务暂不可用,请稍后重试或与管理员联系'
}
5．使用 HAL作为响应数据格式
v简单资源对象：
{"_links":
{"self":
{"href":
":
//example.org/api/user/matthew"}},"id":
"matthew","name":
"MatthewWeierO'Phinney"}
v复杂资源对象：
{"_links":
{"self":
{"href":
":
//example.org/api/user/matthew"}},"id":
"matthew","name":
"MatthewWeierO'Phinney","_embedded":
{"contacts":
[{"_links":
{"self":
{"href":
":
//example.org/api/user/mac_nibblet"}},"id":
"mac_nibblet","name":
"AntoineHedgecock"},{"_links":
{"self":
{"href":
":
//example.org/api/user/spiffyjr"}},"id":
"spiffyjr","name":
"KyleSpraggs"}],"website":
{"_links":
{"self":
{"href":
":
//example.org/api/locations/mwop"}},"id":
"mwop","url":
":
//"},}}
v带有分页的结果：
{
"_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":
{
},
"self":
{
},
"next":
{
"href":
"
},
"last":
{
}
},
"page":
{
"size":
10,
"totalElements":
53454,
"totalPages":
5346,
"number":
1
}
}
6．各方法成功处理后的返回数据
方法
response格式
GET
单个对象、集合
POST
新增成功的对象、或URI
PUT/PATCH
更新成功的对象或URI
DELETE
空
7．不要对返回结果进行封装
response的body直接就是数据,不要做多余的包装。
{
"type":
1,
"coin":
24991.50,
"expressid":
0,
"_links":
{
"self":
{
"href":
":
//localhost:
8011/currencies/270"
}
}
}
8．支持资源的字段裁剪,减少响应中返回的字段数量
9．使用OAuth2来确保API的安全性
v使用BearerToken进行身份验证；
vOAuth2的Bearertoken要求必须通过S/TLS/SSL来访问你的API。
通过进行的未加密通信将导致窃听和重放。
10．确保GET,PUT,DELETE请求是幂等的
幂等性：
执行1次和执行N次,对资源状态改变的效果是等价的。
11．API版本
使用HEADER传递版本信息。
#Request
Accept:
application/json
Content-Type:
application/json;version=1
升级会员 