阅读全文

⭐⭐⭐ Spring Boot 项目实战	⭐⭐⭐ Spring Cloud 项目实战
《Dubbo 实现原理与源码解析 —— 精品合集》	《Netty 实现原理与源码解析 —— 精品合集》
《Spring 实现原理与源码解析 —— 精品合集》	《MyBatis 实现原理与源码解析 —— 精品合集》
《Spring MVC 实现原理与源码解析 —— 精品合集》	《数据库实体设计合集》
《Spring Boot 实现原理与源码解析 —— 精品合集》	《Java 面试题 + Java 学习指南》

摘要: 原创出处 捡田螺的小男孩 「捡田螺的小男孩」欢迎转载，保留摘要，谢谢！

• 1. 你的接口名称是否清晰
• 2. 你的接口地址是否完整
• 3. 你的接口请求方式是否正确
• 4. 请求参数的8大要素
• 5. 响应参数的7大要求
• 6. 接口错误码完整
• 7. 接口安全描述
• 8. 接口版本管理
• 9. 维护接口文档更新迭代
• 10. 明确请求头有哪些
• 11. 写清楚接口请求示例
• 12. 完善接口测试方法和结果

---

🙂🙂🙂关注**微信公众号：【芋道源码】**有福利：

1. RocketMQ / MyCAT / Sharding-JDBC 所有源码分析文章列表
2. RocketMQ / MyCAT / Sharding-JDBC 中文注释源码 GitHub 地址
3. 您对于源码的疑问每条留言都将得到认真回复。甚至不知道如何读源码也可以请教噢。
4. 新的源码解析文章实时收到通知。每周更新一篇左右。
5. 认真的源码交流微信群。

---

后端开发，经常需要定义接口文档。如何写好接口文档，真的很重要。

今天给大家带来接口文档设计的12个注意点~

1. 你的接口名称是否清晰

换句话说，你的接口是做什么的，是否易懂清晰？一般接口url也要求能看得出接口的作用。比如说，查询用户信息（queryUserInfo），就是一个不错的接口名称。

2. 你的接口地址是否完整

接口的地址，也叫接口的URL地址。即别人调用你的接口，用的是什么URL。比如/api/user/queryUserInfo就是一个接口地址。但是，我想说的是，这还不是一个完整的接口地址。你的接口是不是HTTP调用呢？

如果是HTTP调用的话，域名是什么呢？端口呢？一个好的http接口地址，应当是这样的：

> https://tianluo.com:15000/api/user/queryUserInfo
>

3. 你的接口请求方式是否正确

接口请求方式通常有以下几种：

• GET：从服务器获取资源，可以在URL中传递参数，通常用于查询数据。
• POST：向服务器提交数据，通常用于新增、修改、删除等操作。
• PUT：向服务器更新资源，通常用于更新数据。
• DELETE：从服务器删除资源，通常用于删除数据。
• PATCH：向服务器局部更新资源，通常用于修改部分数据。
• HEAD：类似于GET请求，但是只返回响应头，不返回实体内容，通常用于获取资源的元信息。
• OPTIONS：请求服务器返回支持的请求方式等信息，通常用于客户端与服务端协商请求方式。

你定义接口文档的时候，需要写清楚，你的接口请求方式是哪一个？一般情况下，我们用POST和GET比较多。也有些公司的所有接口都用POST请求。

4. 请求参数的8大要素

我们定义接口的时候，请求参数是最主要的部分之一。一份合格的接口文档，请求参数应当包含这八大要素：

• 参数名：参数的名字，都是驼峰命名，比如userId。
• 类型：参数的类型，比如String、Integer等。
• 是否必填：请求参数是不是必填的，如果要求必填的，当上游不传这个参数的时候，应当抛参数校验异常。
• 默认值：如果这个参数不传，是否有默认值，默认值是多少。
• 取值范围：如果是Long、Integer等数值类型的话，这个就是一个范围值，比如1~10，如果是枚举值的话，那就是枚举范围，比如ACTIVE、INACTIVE。
• 参数格式：比如你的参数是个日期的话，就需要说明参数格式，如yyyyMMdd
• 入参示例值：提供该响应参数的示例值，以便开发人员更好地理解和使用该参数。
• 备注：如果这个入参字段有特殊说明的话，可以在这一栏说明。如果没有特殊说明，那只描述这个参数作用也可以。

以下就是入参的文档样例：

参数名	类型	是否必填	默认值	取值范围	参数格式	入参示例值	备注（说明）
userId	Long	是	0L	0~99999999L	无	666L	用户Id
birthDay	String	是	19900101	19900101~20231231	yyyyMMdd	19940107	用户生日

5. 响应参数的7大要求

响应参数其实跟入参差不多，有7种要素：

• 参数名称：描述该响应参数的名称。
• 参数类型：描述该响应参数的数据类型，如String、Integer等。
• 参数格式：描述该响应参数的数据格式，如yyyy-MM-dd、HH:mm:ss等。
• 参数说明：对该响应参数的含义进行详细的描述。
• 取值范围：描述该响应参数的取值范围，如整数范围、字符串长度等。
• 是否必填：描述该响应参数是否为必填项。
• 示例值：提供该响应参数的示例值，以便开发人员更好地理解和使用该参数。

不一样的地方是，响应参数一般都是按照code，msg，data的格式返回的：

{
    "code": 0,
    "message": "success",
    "data": {
        "name": "Tom",
        "age": 20,
        "gender": "男"
    }
}

6. 接口错误码完整

一份好的接口文档，一定少不了错误码列举。一般错误码定义包括三列：错误码、错误码信息、含义。

错误码	错误信息	含义
1001	参数错误	请求参数不合法
1002	用户不存在	根据给定的用户ID没有找到对应的用户信息
1003	数据库错误	数据库访问出错

7. 接口安全描述

定义接口文档时，对于一些需要保护的接口，也需要考虑接口的安全，例如权限管理、防止 SQL 注入等。

因此，接口文档应当包含接口的安全性说明：例如接口的访问授权方式、数据传输加密方式等。此外，接口文档还应该对于敏感数据和操作进行标注，方便使用者注意隐私和安全问题。

8. 接口版本管理

在接口文档定义时，接口版本管理是非常重要的一个方面。由于软件项目的迭代和升级，接口可能会随着版本的变化而发生变化。为了避免接口变化给用户带来不必要的困扰，需要对接口进行版本管理。

以下是一些常用的接口版本管理方法：

• 在接口文档中明确版本号：在接口文档中明确标识接口的版本号，例如在接口地址中添加版本号信息，如https://example.com/api/v1/user，表示该接口的版本号为v1。
• 使用语义化版本号：采用语义化版本号（Semantic Versioning）规范，即版本号格式为X.Y.Z，其中X表示主版本号、Y表示次版本号、Z表示修订号。当进行兼容性变更时，需升级主版本号；当增加功能且不影响现有功能时，需升级次版本号；当进行bug修复或小功能改进时，需升级修订号。
• 增量发布：在接口发生变化时，先发布新版本的接口，同时保留旧版本的接口。用户可以根据自己的需求来选择使用哪个版本的接口。随着新版本的接口逐步替换旧版本的接口，最终可以将旧版本的接口废弃。

无论采用何种方法，接口版本管理都应该得到充分的考虑。在接口版本变化时，需要及时更新接口文档（详细描述版本的变化、兼容性问题、版本切换方式等），以确保用户能够获得最新的接口信息。

9. 维护接口文档更新迭代

如果接口发生了变更，比如参数有哪些变更、错误码变更等等，都需要维护到文档上。同时需要登记变更的记录。

日期	变更描述	操作人
2023-04-16	创建接口文档，定义了第一版接口文档	张三
2023-04-18	修改接口文档，增加了错误码、出参等	王五

10. 明确请求头有哪些

接口文档，是需要写清楚请求头的。接口文档的请求头可以看到以下的信息：

• Content-Type：指定请求体的数据格式，如application/json、application/x-www-form-urlencoded、multipart/form-data等。
• Authorization：用于身份验证的令牌信息，如Token、Bearer等。
• Accept：指定客户端可以接受的响应数据格式，如application/json、text/html等。
• User-Agent：指定客户端的类型和版本信息，可以用于服务端进行针对性优化。
• Accept-Encoding：指定客户端可以接受的数据压缩格式，如gzip、deflate等。
• Cache-Control：指定客户端缓存的策略，如no-cache、max-age等。
• Cookie：包含客户端发送给服务器的cookie信息。

下面是一个接口文档请求头的示例：

POST /api/user HTTP/1.1
Host: example.com
Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
Accept: application/json
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/96.0.4664.110 Safari/537.36
Accept-Encoding: gzip, deflate, br
Cache-Control: no-cache
Cookie: _ga=GA1.2.1234567890.1234567890; _gid=GA1.2.0987654321.0987654321
If-None-Match: W/"2a-3TjT7VaqgkT1nJdKjX9Cpijp2FA"
Referer: https://example.com/login
Origin: https://example.com
Content-Length: 43

{"name": "John Doe", "age": 25, "email": "john.doe@example.com"}

11. 写清楚接口请求示例

接口文档，需要提供接口的使用案例：以方便开发者理解接口的使用方法和调用流程。

12. 完善接口测试方法和结果

一般来说，接口文档需要完善接口测试的方法和结果，以便用户可以测试接口是否符合自己的需求，让用户用得放心。