API设计规范 - 个人分享

1. 接口设计

1.1 RESTful API

RESTful API（Representational State Transfer Application Programming Interface）是一种基于REST架构风格的API设计理念，它是一种通过网络进行通信的接口设计规范。

RESTful API的核心思想是将资源抽象为URI（Uniform Resource Identifier），使用HTTP协议中的GET、POST、PUT、DELETE等动词对资源进行操作，同时以JSON或XML格式传输数据。这种接口设计灵活可扩展，易于实现，能够满足不同应用场景下的需求。

RESTful API的特点包括：

无状态性：每个请求都独立，服务器不会保留任何上下文信息。

可缓存性：允许客户端缓存服务器响应结果，提高系统性能。

统一接口：采用标准的HTTP协议，使得不同应用之间可以交互使用。

资源定位：每个资源都可以通过唯一的URI进行定位。

操作多样性：允许客户端通过不同的HTTP方法对资源进行不同的操作。

可编程性：可使用各种编程语言进行开发，支持跨语言互操作。

1.2 规则定义

1.2.1 使用HTTP动词来表示资源的操作（例如：GET、POST、PUT、DELETE）

1. GET方法用于查询操作，不应该对数据进行修改；

2. POST方法用于新增或者修改数据，可以有副作用；

3. PUT方法用于更新已存在的资源；

4. DELETE方法用于删除资源。

1.2.2 URL路径只能使用小写字母、数字和短横线（-）,且不要包含文件扩展名

1. URL路径中不应包含尾随正斜杠 （/）

2. 必须使用正斜杠分隔符 （/） 来指示层次结构关系

3. 应使用连字符 （-） 来提高 URI 的可读性，例如：/user-info。

4. 不应在 URI 中使用下划线 （_）

5. URI 路径中应首选小写字母 URI 格式规范 （RFC 3986）

6. 文件扩展名不应包含在 URI 中，应该依赖媒体类型（通过内容类型标头传达）来确定如何处理正文的内容

1.2.3 API版本号应该放在资源路径前端，采用vX的形式（其中X为版本号），

例如：/v1/user-info。

1.2.4 对于具有唯一性的资源，可以采用以ID作为资源标识的方式

例如：/v1/user-info/{user_id}。其中花括号内的user_id为变量。

1.2.5 API请求和响应数据格式采用JSON格式，且编码为UTF-8。

1.2.6 请求参数需要进行合法性检查，包括必填参数、参数类型、长度、格式等等。

1.2.7 使用HTTP状态码表示请求的处理结果

1** 信息，服务器收到请求，需要请求者继续执行操作 2** 成功，操作被成功接收并处理 3** 重定向，需要进一步的操作以完成请求 4** 客户端错误，请求包含语法错误或无法完成请求 5** 服务器错误，服务器在处理请求的过程中发生了错误

1.2.8 API接口文档应当清晰明了，包含请求示例、响应示例、错误码表、版本变更记录等信息。

1.2.9 API接口的安全性需要保障，包括HTTPS传输、防止SQL注入、防止跨站点攻击等。

1.2.10 接口调用频率、并发量、QPS等需要进行限制，以保证系统稳定性

2. 对内部规范

2.1 流程定义

1. 从产品经理确定需求

2. 前后端一起过会讨论接口结构如何设计，提前设计mock好并分享给前端使用；

3. 后端进入代码开发并调试接口是否符合预期，接口正确后前后端联调并交付给测试；

4. 测试人员基于开发完成的接口进行自动化冒烟测试。

2.2 文档定义

2.2.1 采用方案

ApiPost为主

后端维护swagger，导入到ApiPost

2.2.2 接口文档规范

标题：接口名称需要简明扼要，能够清晰地表达该接口的功能。

描述：对接口进行详细的说明，包括接口所属模块、调用方式、功能描述等。

URL：标明接口的访问地址，应包含版本号、资源路径和请求参数。

HTTP 方法：使用HTTP协议中的GET、POST、PUT、DELETE等动词对资源进行操作。

请求参数：列出请求参数及其数据类型、是否必填、长度、格式等信息，并给出示例。

请求头：如果有特殊请求头参数需要加入，需要明确这些参数的意义和取值范围。

响应结果：列出正确响应码及其含义，同时给出响应结果的数据结构和字段含义。

错误处理：列表述错误码及其含义，以及各种错误情况下所返回的错误信息、状态码等。

示例代码：提供示例代码，以便开发者快速调用API。

接口版本管理：如果需要进行接口版本控制，则需要在文件中记录每个版本的变更历史。