微服务接口定义规范标准[详]

.

接口定义规范研发部

2018/01

1 / 9

.

1． URI命名规范3

2． 使用方法表示动作行为4

3． 使用内容协商处理资源表示内容4

4． 使用响应状态码标识处理结果状态5

5． 使用HAL作为响应数据格式6

6． 各方法成功处理后的返回数据8

7． 不要对返回结果进行封装8

8． 支持资源的字段裁剪,减少响应中返回的字段数量9

9． 使用 OAuth2 来确保 API 的安全性9

10． 确保GET,PUT,DELETE 请求是幂等的9

11． API版本9

2 / 9

.

微服务接口设计采用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

过滤条件应该合并到一个参数里：

3 / 9

.

GET

poobah"

://example/users?filter="name::todd|city::denver|title::grand

排序字段也应该合并到一个参数里,使用-代表倒序

GET ://example/users?sort=last_name|first_name|-hire_date

➢ 经常使用的、复杂的查询标签化,降低维护成本。

如：

GET /trades?status=closed&sort=createddesc

快捷方式：GET /trades/recently-closed

2．使用方法表示动作行为

❖ POST - 创建资源,非幂等性操作；

❖ PUT - 更新资源；

❖ PATCH - 部分更新资源；

❖ GET - 获取单个资源或资源集合；

❖ DELETE - 删除单个资源或资源集合；

原则上URI中不应该出现动词,当出现复杂操作超出上述方法描述的行为时,可以考虑通过URL参数来指定动作。

如 PUT/books/1?action=like 标注ID为1的图书为喜爱图书

使用其他动作时,方法仍然根据实际操作属于那种类型设定,比如属于资源的更新操作,那么就使用PUT方法。

3．使用内容协商处理资源表示内容

通过请求头/响应头中的Content-Type判断请求提中的数据类型,然后根据数

据类型做出相应处理。

❖ 请求Body内容格式采用JSON格式,其格式通过 Header

Content-Type:application/json表示。

❖ 或From表单格式,其格式通过 Header：

Content-Type: application/x-www-form-urlencoded

❖ 响应内容格式为JSON,响应头Content-Type:application/json

❖ 或HAL+JSON,响应头为Content-Type:application/hal+json

4 / 9

.

❖ 或XML格式,响应头为Content-Type:text/xml

4．使用响应状态码标识处理结果状态

❖ 不要发生了错误但给2xx响应,客户端可能会缓存成功的请求；

❖ 正确设置状态码,不要自定义；

下面是常用状态码及其意义：

响应码

200 OK

201 Created

说明

请求处理正常,通常用于GET操作时内容正常返回

Post或PUT操作时对象被正常创建,通常在Body中返回对象内容。

处理成功,但没返回值。如delete操作,没有内容可返回。

资源被移动到其它位置,需要客户端重定向。

请求有问题,可能是缺少参数或参数不正确,需要客户端修正请求内容。可以在请求体中返回错误提示信息。

指定资源需要授权,用户未认证身份所以不能访问资源。

用户已登录但是没有指定资源的访问权限。

指定的资源不存在。

资源不支持访问方法,如对只读资源使用PUT进行更新

将出现重复的数据或是无效的数据状态。

204 No content

301 Moved permanently

400 Bad request

401 Unauthorized

403 Forbidden

404 Not found

405 Method not allowed

409 Conflict

500 Internal server error 服务器发生非预期错误,此时需要在响应体中返回错误的具体信息。

对于400、409、500这种需要进一步说明原因的错误码,可以在响应体中返回对应的错误信息,格式如下：

5 / 9

.

{

code:’500’,

message:'服务暂不可用,请稍后重试或与管理员联系'

}

5．使用HAL作为响应数据格式

❖ 简单资源对象：

{ "_links": { "self": { "href": ":///api/user/matthew" } }, "id": "matthew",

"name": "Matthew Weier O'Phinney" }

❖ 复杂资源对象：

{ "_links": { "self": { "href": ":///api/user/matthew" } }, "id": "matthew",

"name": "Matthew Weier O'Phinney", "_embedded": { "contacts": [ { "_links": { "self":

{ "href": ":///api/user/mac_nibblet" } }, "id": "mac_nibblet", "name":

"Antoine Hedgecock" }, { "_links": { "self": { "href":

":///api/user/spiffyjr" } }, "id": "spiffyjr", "name": "Kyle Spraggs" } ],

"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,

6 / 9

"add_time" : "1504228187",

"expressid" : 0

},

....................

{

"type" : 1,

"coin" : 0.50,

"usercoin" : 10.00,

"add_time" : "1504228349",

"expressid" : 0

} ]

},

"_links" : {

"first" : {

},

"prev" : {

},

"self" : {

},

"next" : {

},

"last" : {

}

},

"page" : {

"size" : 10,

"totalElements" : 53454,

"totalPages" : 5346,

"number" : 1

}

.

7 / 9

.

}

6．各方法成功处理后的返回数据

方法 response 格式

GET

POST

PUT/PATCH

DELETE

单个对象、集合

新增成功的对象、或URI

更新成功的对象或URI

空

7．不要对返回结果进行封装

response 的 body 直接就是数据,不要做多余的包装。

{

"type" : 1,

"coin" : 24991.50,

"expressid" : 0,

"_links" : {

"self" : {

"href" : "://localhost:8011/currencies/270"

}

}

}

8 / 9

.

8．支持资源的字段裁剪,减少响应中返回的字段数量

9．使用 OAuth2 来确保 API 的安全性

❖ 使用 Bearer Token 进行身份验证；

❖ OAuth2 的 Bearer token 要求必须通过 S / TLS / SSL 来访问你的

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

10．确保GET,PUT,DELETE 请求是幂等的

幂等性：执行1次和执行N次,对资源状态改变的效果是等价的。

11．API版本

使用HEADER传递版本信息。

# Request

Accept: application/json

Content-Type: application/json; version=1

9 / 9