接口规范标准

接口标准


第一章 总则

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

第二章 术语

  • 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中增加offsetlimit参数用于分页。

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

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

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

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

4.2 请求头(Request headers)

  • 带有Bearer 认证信息:
    Authorization: Bearer

    推荐采用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-8Content-Type

4.6 响应体(Response body)

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

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

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

4.7 认证

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

你可能感兴趣的:(架构,restful,java,后端)