12 Punkte, die Sie beim Teilen von Interface-Design-Dokumenten beachten sollten

Vorwort

Wir führen Backend-Entwicklung durch und müssen häufig Schnittstellendokumente definieren.

Als ich kürzlich das Schnittstellendokument durchgesehen habe, habe ich festgestellt, dass der von einem kleinen Partner definierte Ausgabeparameter ein Aufzählungswert war, das Schnittstellendokument jedoch nicht den entsprechenden spezifischen Aufzählungswert angab. Tatsächlich ist es wirklich wichtig, wie man Schnittstellendokumente gut schreibt. Heute präsentiert Ihnen Bruder Tianluo 12 Punkte, die Sie in Interface-Design-Dokumenten beachten sollten~12个注意点~

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

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

• Öffentlicher Account: Der kleine Junge, der Schnecken aufsammelt
(mit dem von Snails sorgfältig erstellten Interview-PDF)

github Adresse, vielen Dank für jeden Stern: github

1. Ist Ihr Schnittstellenname klar? 🎜Mit anderen Worten: Was macht Ihre Benutzeroberfläche und ist sie leicht verständlich und klar? Die allgemeine Schnittstelle url erfordert außerdem, dass die Funktion der Schnittstelle erkennbar ist. Beispielsweise ist 🎜queryUserInfo🎜 ein 🎜guter Schnittstellenname🎜. 🎜🎜🎜

2. Ist Ihre Schnittstellenadresse vollständig? Die Adresse der Schnittstelle wird auch als URL-Adresse der Schnittstelle bezeichnet. Das heißt, welche URL verwendet wird, wenn andere Ihre Schnittstelle aufrufen. Beispielsweise ist /api/user/queryUserInfo eine 🎜Schnittstellenadresse🎜. Ich möchte jedoch darauf hinweisen, dass dies keine vollständige Schnittstellenadresse ist. Wird Ihre Schnittstelle über HTTP aufgerufen? 🎜🎜Wenn es über HTTP aufgerufen wird, wie lautet der 🎜Domainname🎜? 🎜Hafen🎜. Eine gute http-Schnittstellenadresse sollte wie folgt aussehen: 🎜

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

🎜🎜

3. Ist Ihre Schnittstellenanforderungsmethode korrekt? 🎜🎜Schnittstellenanforderungsmethoden umfassen normalerweise Folgendes: 🎜

🎜GET: Ressourcen vom Server abrufen, die in URL zu finden sind Code > Übergeben Sie Parameter, die normalerweise zum Abfragen von Daten verwendet werden. 🎜🎜POST: Daten an den Server senden, normalerweise für Vorgänge wie Hinzufügen, Ändern, Löschen usw. verwendet. 🎜🎜PUT: Ressourcen auf dem Server aktualisieren, die normalerweise zum Aktualisieren von Daten verwendet werden. 🎜🎜LÖSCHEN: Ressourcen vom Server löschen, die normalerweise zum Löschen von Daten verwendet werden. 🎜🎜PATCH: Aktualisiert teilweise Ressourcen auf dem Server, wird normalerweise zum Ändern einiger Daten verwendet. 🎜🎜HEAD: Ähnlich der <code>GET-Anfrage, gibt jedoch nur den Antwortheader und nicht den Entitätsinhalt zurück. Wird normalerweise zum Abrufen von Metainformationen von Ressourcen verwendet. 🎜🎜OPTIONEN: Fordern Sie den Server auf, unterstützte Anforderungsmethoden und andere Informationen zurückzugeben, die normalerweise für die Aushandlung der Anforderungsmethode durch Client und Server verwendet werden. 🎜🎜🎜Wenn Sie das Schnittstellendokument definieren, müssen Sie klar schreiben: Welche Methode verwenden Sie für die Schnittstellenanforderung? Unter normalen Umständen verwenden wir POST und GET häufiger. Es gibt auch Unternehmen, die POST-Anfragen für alle Schnittstellen verwenden. 🎜🎜🎜

4. Die 8 Hauptelemente der Anforderungsparameter🎜🎜Wenn wir die Schnittstelle definieren, sind die Anforderungsparameter einer der wichtigsten Teile🎜. Für ein qualifiziertes Schnittstellendokument sollten die Anforderungsparameter diese acht Elemente enthalten: 🎜

🎜Parametername: Der Name des Parameters wird in Kamel-Schreibweise benannt, z. B. userId. 🎜🎜Typ: Der Typ des Parameters, z. B. String, Integer usw. 🎜🎜Ist es erforderlich: Ist der Anforderungsparameter erforderlich? Wenn der Upstream diesen Parameter nicht übergibt, sollte eine Parameterüberprüfungsausnahme ausgelöst werden. 🎜🎜Standardwert: Wenn dieser Parameter nicht übergeben wird, gibt es einen Standardwert und was ist der Standardwert? 🎜🎜Wertebereich: Wenn es sich um einen numerischen Typ wie Long, Integer handelt, ist dies ein Bereichswert, wie z. B. 1~10, wenn es sich um einen Aufzählungswert handelt, Das ist der Aufzählungsbereich, z. B. ACTIVE, INACTIVE. 🎜🎜Parameterformat: Wenn Ihr Parameter beispielsweise ein Datum ist, müssen Sie das Parameterformat angeben, z. B. yyyyMMdd🎜🎜Beispielwert für Eingabeparameter: Geben Sie einen Beispielwert des Antwortparameters an, damit Entwickler können es besser verstehen und diesen Parameter verwenden. 🎜🎜Hinweis: Wenn es für dieses Eingabeparameterfeld 🎜besondere Anweisungen🎜 gibt, können Sie diese in dieser Spalte erläutern. Wenn es keine spezielle Erklärung gibt, ist es in Ordnung, nur die Funktion dieses Parameters zu beschreiben. 🎜🎜🎜🎜Das Folgende ist ein Beispieldokument zur Eingabe von Parametern🎜:🎜

Parametername	Typ	Ist es erforderlich?	Standardwert	Wertebereich	Parameterformat	Eingabeparameter-Beispielwert	Bemerkungen (Beschreibung)
userId	Long	is	0L	0~99999999L	None	666L	UserId
birthDay	String	is	19900101.	19900101~20231231	yyyyMMdd	19940107	Benutzergeburtstag



5. 7 Hauptanforderungen für Antwortparameter

Antwortparameter ähneln eigentlich Eingabeparametern mit 7 Elementen:

• Parametername: beschreibt den Namen des Antwortparameters.
• Parametertyp: Beschreibt den Datentyp des Antwortparameters, z. B. String, Integer usw. String、Integer等。
• 参数格式：描述该响应参数的数据格式，如yyyy-MM-dd、HH:mm:ss等。
• 参数说明：对该响应参数的含义进行详细的描述。
• 取值范围：描述该响应参数的取值范围，如整数范围、字符串长度等。
• 是否必填：描述该响应参数是否为必填项。
• 示例值：提供该响应参数的示例值，以便开发人员更好地理解和使用该参数。

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

Parameterformat: Beschreibt das Datenformat des Antwortparameters, z. B. jjjj-MM-tt, HH:mm:ss usw.
Parameterbeschreibung: Detaillierte Beschreibung der Bedeutung des Antwortparameters.

Wertebereich: Beschreibt den Wertebereich des Antwortparameters, z. B. Ganzzahlbereich, Zeichenfolgenlänge

usw. Erforderlich oder nicht: Beschreiben Sie, ob der Antwortparameter erforderlich ist.

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

Nach dem Login kopieren
Fehlercode, Fehlercodeinformationen, BedeutungFehlercodeFehlermeldungBedeutung1001Parameter. FehlerI zulässige Anforderungsparameter1002Der Benutzer existiert nichtKeine entsprechenden Benutzerinformationen wurden basierend auf der angegebenen Benutzer-ID gefunden

Beispielwert: Geben Sie einen Beispielwert für diesen Antwortparameter an, damit Entwickler diesen Parameter besser verstehen und verwenden können.	Der Unterschied besteht darin, dass die Antwortparameter im Allgemeinen im Format code, msg, data zurückgegeben werden:	6. Eine gute Kopie der Schnittstellendokumente muss enthalten sein Fehlercodeaufzählung. Die allgemeine Fehlercodedefinition umfasst drei Spalten:

🎜🎜🎜1003🎜🎜Datenbankfehler🎜🎜Datenbankzugriffsfehler🎜🎜🎜🎜



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

Nach dem Login kopieren

11 接口请求示例

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

12. 接口测试

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