接口规范标准

第一章 总则

• 本标准定义了在做接口设计时，需要遵守的基本约束。
• 如违反接口设计标准，采用一事一议原则。

第二章 术语

• RESTful : REST(Representational state transfer)是Roy Fielding在2000年提出的一种架构风格。 RESTful风格API是符合该架构的一种API设计风格。
• HATEOAS : 全称是Hypertext As The Engine Of Application State，是REST架构的一种约束，通过在返回值中带有操作资源的链接信息，进一步将客户端和服务器解耦。
• Richardson成熟度模型 : 根据REST的约束对API进行评级的一种方法，分为四级（Level0到Level3）:
  • Level 0 : 仅将HTTP（或其它协议）当成传输方式，实际上只是RPC的一种方式，没有资源的概念。
  • Level 1 : 引入了资源的概念，不过通常只用到GET或POST，而且可能将二者等价使用。
  • Level 2 : 使用HTTP的方法（POST , DELETE , PUT , GET）来代表资源的增删改查，并使用HTTP状态码来代表不同的结果。
  • Level 3 : 使用HATEOAS方式，在资源的返回值中包含操作资源的链接信息。

第三章 接口设计原则

• 接口设计采用RESTful Level 2模型，不反对采用Level 3模型。
• 接口需要带版本号。
• 接口需要有文档。
• 接口需要做认证。
• 接口需要无状态，不能依赖于会话（session）。

第四章 接口设计细则

4.1 URL格式

接口URL定义中，需要将接口请求的数据抽象为资源，接口即是对资源的增加、删除、修改（覆盖或部分修改）、查询。

4.1.1 资源名

请求URL全部为小写字母，两个词之间采用-作为连接符。

正例：

GET  	/user/{id} 		// 根据ID获取用户信息
POST 	/user/save		// 保存用户信息
PUT  	/user/update 	// 修改用户信息
DELETE	/user/delete	// 删除用户信息

反例：

/addUser
/deleteUser
/modifyUser
/queryUser

4.1.2 采用HTTP method

HTTP method	说明
GET	GET方法代表读取，其请求是幂等的，不能修改资源的信息。当请求参数过多时，应更换为POST请求
POST	POST方法代表创建资源，创建成功后返回状态码200或201，并返回该资源给调用方。可带请求体
DELETE	DELETE方法代表删除该资源。删除成功后返回状态码200或204，不返回数据。可带请求体
PUT	PUT方法代表覆盖资源。更新成功后返回状态码200或204，无响应体返回。可带请求体
PATCH	PATCH方法代表修改部分资源。更新成功后返回状态码200或204，无响应体返回。可带请求体

4.1.3 版本信息

所有接口必须带版本信息，版本信息放URL中，而不是在header中。
推荐格式：/api/v1/资源名称/{id}。

4.1.4 统一前缀

推荐接口都以/api开头，便于统一处理。

4.1.5 分页及排序

分页接口统一使用POST请求，请求参数至少包含以下三个字段：

@Schema(description= "当前页码")
private Integer pageNum = 1;

// 此处使用了PageHelper插件，且开启了 page-size-zero: true
@Schema(description = "每页数量（传0则查询全部数据）")
private Integer pageSize = 10;

@Schema(description = "排序字段：默认按创建时间倒序排序（create_time desc）")
private String orderBy = "create_time desc";

4.2 请求头（Request headers）

• 带有Bearer 认证信息：Authorization : Bearer <token>
• 推荐采用JWT token。

4.3 请求体(Request body)

• 文件上传采用multipart/form-data格式。
• 其它请求均采用application/json格式，不得使用application/x-www-form-urlencoded。

4.4 响应状态码（Response status）

如无必要，勿增实体。凡是HTTP Response Status能表述的，均使用HTTP的响应状态码。

2XX

• 200 : 请求成功，响应体中带有资源的数据。
• 201 : 资源创建成功。
• 202 : 请求已接收。对于耗时较长的需要后台异步处理的，服务在接收请求后，返回202。
• 204 : 响应中无内容。通常是在执行PUT、POST、DELETE后，不返回资源的内容。

3XX

• 301 : 如果接口废弃，迁移到新接口中，可以返回301重定向。
• 304 : 资源未修改。和204一样，在响应体中不会带有内容，其区别在于如果针对请求头中的If-Modified-Since或者If-None-Match指定的版本，资源没有修改，则返回304。

4XX

• 400 ： 错误请求。通用的客户端错误状态码。通常是由于参数不正确。
• 401 ： 未授权。客户端未能提供有效的认证信息。
• 403 ： 请求被拒绝。客户端已经认证成功，但是无权访问该资源。
• 404 ： 资源不存在。
• 410 ： 如果接口永久废弃不用，可返回410。请慎用。
• 429 ： 请求次数超限。

5XX

• 500 ： 服务器内部错误。

4.5 响应头（Response headers）

Content-Type需要与数据保持一致，POJO类的数据统一采用application/json;charset=UTF-8做Content-Type。

4.6 响应体（Response body）

1. 除文件下载外，响应体均采用JSON格式，JSON不要进行格式化。针对4XX错误和5XX错误，需要提供有供的信息，格式如下：

{
  "code":"",
  "message":""
}

code是业务系统针对响应状态码细化的业务错误码，不做统一约束，默认为500。
message是针对该错误的描述信息，不能为空。

2. 响应体的VO，应该同时带有代码值和代码文本。
   如单值代码、多值代码、组织机构、案由。
   对于外键引用的数据不做要求，根据业务自行设计。

4.7 认证

外部系统（服务）调用接口时采用oauth2.0的client_credentials方式进行认证。