接口规范标准

接口标准

---

第一章 总则

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

第二章 术语

• 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 资源名

• 中文名称的资源采用单数，英文名称的资源采用复数。

  /users/{id} // 某ID的用户

• 不要在资源上加上动词描述,比如：

  /addUser

  /deleteUser

  /modifyUser

  /queryUser

• 特殊情况需要指定行为的，在行为前面加上统一的actions关键字，例如：

  /user/{id}/actions/sx　　// 对某个用户进行刷新

• 两个词之间采用-做为连接符。

4.1.2 采用HTTP method

• GET
  GET方法代表读取，其请求是幂等的，不能修改资源的信息。
  注意：
  如果对于一个参数超长的get请求，可采用post请求，并在在header中加上X-HTTP-Method-Override:get。Controller层仍是以get来处理。
• DELETE
  DELETE方法代表删除该资源。删除成功后返回状态码204，不返回数据。可带请求体。
• POST
  POST方法代表创建资源。创建成功后返回状态码201，并返回该资源给调用方。可带请求体。
• PUT
  PUT方法代表覆盖资源。更新成功后返回状态码204，无响应体返回。可带请求体。
• PATCH
  PATCH方法代表修改部分资源。更新成功后返回状态码204，无响应体返回。可带请求体。
  注意：推荐用patch方法，大部分应用场景下，更新都只是更新部分数据。

4.1.3 版本信息

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

4.1.4 统一前缀

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

4.1.5 分页及排序

• 在URL中增加offset和limit参数用于分页。

• 在URL中增加sort参数用于排序，默认正序，带-表示倒序。比如：

  /api/v1/users?sort=-fyid,create_time 代表fyid倒序，create_time正序。

• 返回的分页数据中，在响应全中，包含如下元素：

  • offset (和请求值一样)
  • limit (和请求值一样)
  • total（能查出的总记录数）,注：total非必须，可以不传，以提高性能。
  • data（此次分页的数据）

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是业务系统针对响应状态码细化的业务错误码，不做统一约束,可以为空。
message是针对该错误的描述信息，不能为空。

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

4.7 认证

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