接口标准
第一章 总则
- 本标准定义了在做接口设计时,需要遵守的基本约束。
- 如违反接口设计标准,采用一事一议原则。
第二章 术语
- 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)
- 除文件下载外,响应体均采用JSON格式,JSON不要进行格式化。针对4XX错误和5XX错误,需要提供有供的信息,格式如下:
{
"code":"",
"message":""
}
code
是业务系统针对响应状态码细化的业务错误码,不做统一约束,可以为空。message
是针对该错误的描述信息,不能为空。
- 响应体的
VO
,应该同时带有带有代码值
和代码文本
。
如单值代码
、多值代码
、组织机构
、案由
。
对于外键
引用的数据不做要求,根据业务自行设计。
4.7 认证
- 外部系统(服务)调用接口时采用
oauth2.0
的client_credentials
方式进行认证。