인터페이스 디자인 문서를 공유할 때 주의할 점 12가지-PHP 튜토리얼-php.cn

머리말

우리는 백엔드 개발을 하는데, 인터페이스 문서를 정의해야 하는 경우가 많습니다.

최근 인터페이스 문서를 검토하던 중 소규모 파트너가 정의한 출력 매개변수가 열거형 값이었지만 인터페이스 문서에서 해당하는 특정 열거형 값을 제공하지 않은 것을 발견했습니다. 사실 인터페이스 문서를 어떻게 잘 작성하느냐가 정말 중요합니다. 오늘 Tianluo 형제가 인터페이스 디자인 문서에서 주의할 점 12개를 가져왔습니다~12个注意点~

인터페이스 디자인 문서를 공유할 때 주의할 점 12가지

公众号：捡田螺的小男孩 （有田螺精心原创的面试PDF）
github地址，感谢每颗star：github

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

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

인터페이스 디자인 문서를 공유할 때 주의할 점 12가지

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

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

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

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

인터페이스 디자인 문서를 공유할 때 주의할 점 12가지

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

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

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

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

인터페이스 디자인 문서를 공유할 때 주의할 점 12가지

4.请求参数的8大要素

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

参数名: 参数的名字,都是驼峰命名，比如userId。
类型: 参数的类型,比如String、Integer等。
是否必填: 请求参数是不是必填的，如果要求必填的，当上游不传这个参数的时候，应当抛参数校验异常。
默认值: 如果这个参数不传，是否有默认值，默认值是多少。
取值范围: 如果是Long，Integer等数值类型的话，这个就是一个范围值，比如1~10，如果是枚举值的话，那就是枚举范围，比如ACTIVE、INACTIVE。
参数格式：比如你的参数是个日期的话，就需要说明参数格式，如yyyyMMdd

공개 계정: 달팽이를 줍는 꼬마

github 주소, 모든 별에 감사드립니다: github

1. 인터페이스 이름이 명확합니까? 🎜즉, 인터페이스의 기능은 무엇이며 이해하기 쉽고 명확합니까? 일반 인터페이스 `url`에서도 인터페이스의 기능을 볼 수 있어야 합니다. 예를 들어 🎜사용자 정보 쿼리(queryUserInfo)🎜는 🎜좋은 인터페이스 이름🎜입니다. 🎜🎜🎜

2. 인터페이스 주소가 완전합니까? 인터페이스 주소를 인터페이스의 `URL` 주소라고도 합니다. 즉, 다른 사람이 귀하의 인터페이스를 호출할 때 사용되는 `URL`입니다. 예를 들어 `/api/user/queryUserInfo`는 🎜인터페이스 주소🎜입니다. 그러나 제가 말씀드리고 싶은 것은 이것이 완전한 인터페이스 주소가 아니라는 것입니다. 인터페이스가 `HTTP`에 의해 호출됩니까? 🎜🎜`HTTP`로 호출되는 경우 🎜도메인 이름🎜은 무엇인가요? 🎜항구🎜. 좋은 `http` 인터페이스 주소는 다음과 같아야 합니다: 🎜
🎜`https//tianluo.com:15000/api/user/queryUserInfo`🎜
🎜🎜

3. 인터페이스 요청 방법이 올바른가요? 🎜🎜인터페이스 요청 방법에는 일반적으로 다음이 포함됩니다. 🎜

URL에서 찾을 수 있는 서버에서 리소스를 얻습니다. code > 매개변수를 전달합니다. 일반적으로 데이터를 쿼리하는 데 사용됩니다. 🎜🎜POST: 일반적으로 추가, 수정, 삭제 등과 같은 작업에 사용되는 데이터를 서버에 제출합니다. 🎜🎜PUT: 일반적으로 데이터를 업데이트하는 데 사용되는 서버에 대한 리소스를 업데이트합니다. 🎜🎜DELETE: 일반적으로 데이터를 삭제하는 데 사용되는 서버에서 리소스를 삭제합니다. 🎜🎜PATCH: 일반적으로 일부 데이터를 수정하는 데 사용되는 리소스를 서버에 부분적으로 업데이트합니다. 🎜🎜HEAD: <code>GET

POST 및 GET

POST

4. 요청 매개변수의 8가지 주요 요소🎜🎜인터페이스를 정의할 때 요청 매개변수는 가장 중요한 부분 중 하나입니다🎜. 적격 인터페이스 문서의 경우 요청 매개변수에는 다음 8개 요소가 포함되어야 합니다. 🎜

userId

문자열, 정수

Long, Integer

1~10

ACTIVE, INACTIVE

yyyyMMdd

매개변수 이름	유형	필수인가요?	기본값	값 범위	매개변수 형식	입력 매개변수 예시 값	비고(설명)
userId	Long	is	0L	0~99999999L	None	666L	UserId
birthDay	String	is	19900101	19900101~20231231	yyyyMMdd	19940107	사용자 생일

인터페이스 디자인 문서를 공유할 때 주의할 점 12가지

5. 응답 매개변수에 대한 7가지 주요 요구사항

응답 매개변수는 실제로 입력 매개변수와 유사하며 7개 요소로 구성됩니다.

매개변수 이름: 응답 매개변수의 이름을 설명합니다.
매개변수 유형: 문자열, 정수 등과 같은 응답 매개변수의 데이터 유형을 설명합니다. String、Integer等。
参数格式：描述该响应参数的数据格式，如yyyy-MM-dd、HH:mm:ss等。
参数说明：对该响应参数的含义进行详细的描述。
取值范围：描述该响应参数的取值范围，如整数范围、字符串长度等。
是否必填：描述该响应参数是否为必填项。
示例值：提供该响应参数的示例值，以便开发人员更好地理解和使用该参数。

不一样的地方是，响应参数，一般都是按照code，msg，data

yyyy-MM-dd, HH:mm:ss

값 범위: 정수 범위, 문자열 길이

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

로그인 후 복사

예제 값: 개발자가 이 매개변수를 더 잘 이해하고 사용할 수 있도록 이 응답 매개변수에 대한 예시 값을 제공하세요.	차이점은 응답 매개변수가 일반적으로 `code, msg, data` 형식으로 반환된다는 것입니다:	6. 인터페이스 오류 코드

인터페이스 디자인 문서를 공유할 때 주의할 점 12가지

7.接口安全

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

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

인터페이스 디자인 문서를 공유할 때 주의할 점 12가지

8. 接口版本管理

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

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

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

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

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

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

日期	变更描述	操作人
2023-04-16	创建接口文档，定义了第一版接口文档	捡田螺的小男孩
2023-04-18	修改接口文档，增加了错误码，出参等	田螺哥

인터페이스 디자인 문서를 공유할 때 주의할 점 12가지

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"}

로그인 후 복사