Heim > Artikel > Backend-Entwicklung > 12 Punkte, die Sie beim Teilen von Interface-Design-Dokumenten beachten sollten
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
个注意点~
换句话说,你的接口是做什么的,是否易懂清晰?一般接口url
也要求能看得出接口的作用。比如说,查询用户信息(queryUserInfo),就是一个不错的接口名称。
接口的地址,也叫接口的URL
地址。即别人调用你的接口,用的是什么URL
。比如/api/user/queryUserInfo
就是一个接口地址。但是,我想说的是,这还不是一个完整的接口地址。你的接口是不是HTTP
调用呢?
如果是HTTP
调用的话,域名是什么呢?端口呢。一个好的http
接口地址,应当是这样的:
https//tianluo.com:15000/api/user/queryUserInfo
接口请求方式通常有以下几种:
URL
中传递参数,通常用于查询数据。GET
请求,但是只返回响应头,不返回实体内容,通常用于获取资源的元信息。你定义接口文档的时候,需要写清楚,你的接口请求方式是哪一个?一般情况下,我们用POST和GET
比较多。也有些公司的所有接口都用POST
请求。
我们定义接口的时候,请求参数是最主要的部分之一。一份合格的接口文档,请求参数应当包含这八大要素:
userId
。String、Integer
等。Long,Integer
等数值类型的话,这个就是一个范围值,比如1~10
,如果是枚举值的话,那就是枚举范围,比如ACTIVE、INACTIVE
。yyyyMMdd
github Adresse, vielen Dank für jeden Stern: github
url
erfordert außerdem, dass die Funktion der Schnittstelle erkennbar ist. Beispielsweise ist 🎜queryUserInfo🎜 ein 🎜guter Schnittstellenname🎜. 🎜🎜🎜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
🎜
🎜🎜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. 🎜🎜🎜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 |
Antwortparameter ähneln eigentlich Eingabeparametern mit 7 Elementen:
String, Integer
usw. String、Integer
等。yyyy-MM-dd、HH:mm:ss
等。不一样的地方是,响应参数,一般都是按照code,msg,data
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.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: | Fehlercode, Fehlercodeinformationen, Bedeutung
---|---|---|
Fehlercode | Fehlermeldung | Bedeutung |
1001 | Parameter. Fehler | |
1002 | Der Benutzer existiert nicht |
定义接口文档时,对于一些需要保护的接口,也需要考虑接口的安全,例如权限管理、防止 SQL 注入等。
因此,接口文档应当包含接口的安全性说明:例如接口的访问授权方式、数据传输加密方式等。此外,接口文档还应该对于敏感数据和操作进行标注,方便使用者注意隐私和安全问题。
在接口文档定义时,接口版本管理是非常重要的一个方面。由于软件项目的迭代和升级,接口可能会随着版本的变化而发生变化。为了避免接口变化给用户带来不必要的困扰,需要对接口进行版本管理。
以下是一些常用的接口版本管理方法:
https://example.com/api/v1/user
,表示该接口的版本号为v1
。Semantic Versioning
)规范,即版本号格式为X.Y.Z
,其中X
表示主版本号、Y
表示次版本号、Z
表示修订号。当进行兼容性变更时,需升级主版本号;当增加功能且不影响现有功能时,需升级次版本号;当进行bug
修复或小功能改进时,需升级修订号。无论采用何种方法,接口版本管理都应该得到充分的考虑。在接口版本变化时,需要及时更新接口文档(详细描述版本的变化、兼容性问题、版本切换方式等),以确保用户能够获得最新的接口信息。
如果接口发生了变更,比如参数有哪些变更,错误码变更等等,都需要维护到文档上。同时需要登记变更的记录。
日期 | 变更描述 | 操作人 |
---|---|---|
2023-04-16 | 创建接口文档,定义了第一版接口文档 | 捡田螺的小男孩 |
2023-04-18 | 修改接口文档,增加了错误码,出参等 | 田螺哥 |
接口文档,是需要写清楚的请求头的。接口文档的请求头可以看到以下的信息:
application/json、application/x-www-form-urlencoded、multipart/form-data
等。Token、Bearer
等。application/json、text/html
等。gzip、deflate
等。no-cache、max-age
等。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"}
接口文档,需要提供接口的使用案例:以方便开发者理解接口的使用方法和调用流程。
一般来说,接口文档需要完善:接口测试的方法和测试结果,以便用户可以测试接口是否符合自己的需求,让用户用得放心~哈哈
Das obige ist der detaillierte Inhalt von12 Punkte, die Sie beim Teilen von Interface-Design-Dokumenten beachten sollten. Für weitere Informationen folgen Sie bitte anderen verwandten Artikeln auf der PHP chinesischen Website!