接口对接文档规范2023年最新版（Restful API风格）

最新推荐文章于 2024-04-24 22:51:49 发布

信息安全与项目管理

最新推荐文章于 2024-04-24 22:51:49 发布

阅读量2.4k

点赞数 1

文章标签： java

本文链接：https://blog.csdn.net/alafqq/article/details/128528408

版权

接口对接文档

服务共享

1、设计模式

使用Restful API风格, Restful API的优势是具备更好的易用性，让异构系统更容易集成，且开发执行效率比较高，面向资源要求也比较高。

2、设计约束

2.1 协议约束

这里的协议是指API与用户的通信协议，建议使用HTTPS协议。

2.2 URI约束

URI统一资源标识符是一个用于标识某一互联网资源名称的字符串。该种标识允许用户对任何（包括本地和互联网）的资源通过特定的协议进行交互操作。URI由包括确定语法和相关协议的方案所定义。Web上可用的每种资源-HTML文档、图像、视频片段、程序等-由一个通用资源标识符（Uniform Resource Identifier, 简称"URI"）进行定位。

现定义URI规范如下：

不使用大写。
用中杠-不用下杠_。
参数列表要encode
URI中的名词表示资源集合，使用复数形式
URI表示资源的两种方式：资源集合、单个资源。比如：

A: 资源集合：

/zoos //所有动物园

/zoos/1/animals //id为1的动物园中的所有动物

B: 单个资源：

/zoos/1 //id为1的动物园

路径层级小于三层，避免层级过深。

/在url中表达层级，用于按实体关联关系进行对象导航，一般根据id导航。

过深的导航容易导致url膨胀，不易维护，如 GET /zoos/1/areas/3/animals/4，尽量使用查询参数代替路径中的实体导航，如GET /animals?zoo=1&area=3；

组合资源的访问必须通过父实体的id导航访问。

组合实体不是first-class的实体，它的生命周期完全依赖父实体，无法独立存在，在实现上通常是对数据库表中某些列的抽象，不直接对应表，也无id。一个常见的例子是 User— Address，Address是对User表中zipCode/country/city三个字段的简单抽象，无法独立于User存在。必须通过User索引到Address：GET /user/1/addresses

2.3 请求方式

通过标准HTTP方法对资源CRUD，禁用一种访问方式进行多种形式的资源操作。建议采用GET获取某个资源，采用POST新建某个资源。其他请求方法不建议使用。

（1）GET请求：

查询可能附带的约束：过滤条件，排序，投影，分页等。

比如：?size=10¤t=1

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

比如：GET /trades/recently-closed

（2）POST：创建单个资源（注：POST一般向“资源集合”型uri发起，如果是组合资源一般向父级实体发起）

2.4 数据格式

使用常用的数据格式，这里建议使用：

Content-Type： application/json;charset=UTF-8

2.5 请求内容

基于不通的请求方式GET或者POST，使用不同的参数内容。

如使用GET方式请求参数使用Query参数。参数列表要使用encode格式化。如果存在分页查询，分页参数这里限定使用size表示每页记录数，使用current表示第几页。

如使用POST方式请求参数使用request body形式提交参数，请求体使用json格式。

备注：不允许存在空的请求参数，比如：{}，这种方式是不允许的，默认需要存在一个必填的参数，其它参数可非必填。

2.6 响应状态

HTTP 应答中，需要带一个很重要的字段：status code。它说明了请求的大致情况，是否正常完成、需要进一步处理、出现了什么错误，对于客户端非常重要。状态码都是三位的整数，大概分成了几个区间：

2XX：请求正常处理并返回

3XX：重定向，请求的资源位置发生变化

4XX：客户端发送的请求有错误

5XX：服务器端错误

2.7 错误处理

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

2、正确设置http状态码，不要自定义；

3、Response body 提供错误的描述文本(展示给用户)。

API 可能抛出两类异常：业务异常和非业务异常。业务异常由自己的业务代码抛出，表示一个用例的前置条件不满足、业务规则冲突等，比如参数校验不通过、权限校验失败。非业务类异常表示不在预期内的问题，通常由类库、框架抛出，或由于自己的代码逻辑错误导致，比如数据库连接失败、空指针异常、除0错误等。

业务类异常必须提供2种信息：

(1)如果抛出该类异常，对业务类异常，用它指定的 HTTP code；对非业务类异常，统一500；

(2)异常的文本描述；

需要在Controller层使用统一的异常拦截器：

Response Body 的错误描述：对业务类异常，用它指定的错误文本；对非业务类异常，线上可以统一文案如“服务器端错误，请稍后再试”，针对非业务类异常，应该在 Response body 中通过 msg 给出明确的错误信息(一般来说，返回的信息中将 msg 作为键名，出错详情作为键值即可)。比如客户端发送的请求有错误，一般会返回 4XX Bad Request 结果。这个结果很模糊，给出错误 msg 的话，能更好地让客户端知道具体哪里有问题，进行快速修改。错误信息应该是代码处理后的错误描述，不应该返回程序自动抛出的错误信息。

2.8 响应内容

响应的数据内容应该有标准的JSON输出格式

1、响应基本格式

{

"code": "xxx",

"msg": "xxx",

"data": { }

}

code：表示返回状态。

message: 表示返回消息提示

data：表示返回消息体，如果为数组，则表现为[]。

Code状态统一限定三类，其他响应参数值可自行扩展。