12 points à noter lors du partage de documents de conception d'interface

Avant-propos

Nous faisons du développement back-end, et nous avons souvent besoin de définir des documents d'interface.

Récemment, alors que je faisais une examen du document d'interface, j'ai découvert que le paramètre de sortie défini par un petit partenaire est une valeur d'énumération, mais le document d'interface ne donnait pas la valeur d'énumération spécifique correspondante. En fait, il est très important de bien rédiger les documents d’interface. Aujourd'hui, frère Tianluo vous propose 12 points à noter dans les documents de conception d'interface~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

• Compte public : Le petit garçon ramassant des escargots
(avec l'interview PDF soigneusement créée par les escargots)

github Adresse, merci pour chaque étoile : github

1. Le nom de votre interface est-il clair ? 🎜En d’autres termes, que fait votre interface et est-elle facile à comprendre et claire ? L'interface générale url nécessite également que la fonction de l'interface puisse être vue. Par exemple, 🎜interroger les informations utilisateur (queryUserInfo)🎜 est un 🎜bon nom d'interface🎜. 🎜🎜🎜

2. L'adresse de votre interface est-elle complète ? L'adresse de l'interface est également appelée adresse URL de l'interface. Autrement dit, quelle URL est utilisée lorsque d'autres appellent votre interface. Par exemple, /api/user/queryUserInfo est une 🎜adresse d'interface🎜. Cependant, ce que je veux dire, c'est qu'il ne s'agit pas d'une adresse d'interface complète. Votre interface est-elle appelée par HTTP ? 🎜🎜S'il est appelé par HTTP, quel est le 🎜nom de domaine🎜 ? 🎜Port🎜. Une bonne adresse d'interface http devrait ressembler à ceci : 🎜

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

🎜🎜

3. Votre méthode de requête d'interface est-elle correcte ? 🎜🎜Les méthodes de requête d'interface incluent généralement les éléments suivants : 🎜

🎜GET : obtenez des ressources du serveur, qui peuvent être trouvées dans URL code > Passer les paramètres, généralement utilisés pour interroger des données. 🎜🎜POST : Soumettez des données au serveur, généralement utilisées pour des opérations telles que l'ajout, la modification, la suppression, etc. 🎜🎜PUT : Mettre à jour les ressources sur le serveur, généralement utilisé pour mettre à jour les données. 🎜🎜DELETE : Supprimer des ressources du serveur, généralement utilisé pour supprimer des données. 🎜🎜PATCH : met à jour partiellement les ressources sur le serveur, généralement utilisé pour modifier certaines données. 🎜🎜HEAD : similaire à la requête <code>GET, mais renvoie uniquement l'en-tête de réponse et non le contenu de l'entité. Elle est généralement utilisée pour obtenir des méta-informations sur les ressources. 🎜🎜OPTIONS : demandez au serveur de renvoyer les méthodes de requête prises en charge et d'autres informations, généralement utilisées par le client et le serveur pour négocier la méthode de requête. 🎜🎜🎜Lorsque vous définissez le document d'interface, vous devez écrire clairement, quelle est votre méthode de demande d'interface ? Dans des circonstances normales, nous utilisons POST et GET plus souvent. Certaines entreprises utilisent également des requêtes POST pour toutes les interfaces. 🎜🎜🎜

4. Les 8 éléments majeurs des paramètres de requête🎜🎜Lorsque nous définissons l'interface, les paramètres de requête sont l'une des parties les plus importantes🎜. Pour un document d'interface qualifié, les paramètres de la requête doivent contenir ces huit éléments : 🎜

🎜Nom du paramètre : Le nom du paramètre est nommé en casse chameau, tel que userId. 🎜🎜Type : Le type de paramètre, tel que String, Integer, etc. 🎜🎜Est-ce obligatoire : le paramètre de requête est-il obligatoire ? Si nécessaire, lorsque l'amont ne transmet pas ce paramètre, une exception de vérification du paramètre doit être levée. 🎜🎜Valeur par défaut : Si ce paramètre n'est pas passé, existe-t-il une valeur par défaut et quelle est la valeur par défaut. 🎜🎜Plage de valeurs : s'il s'agit d'un type numérique tel que Long, Integer, il s'agit d'une valeur de plage, telle que 1~10, s'il s'agit d'une valeur d'énumération, c'est-à-dire une plage d'énumération, telle que ACTIVE, INACTIVE. 🎜🎜Format du paramètre : par exemple, si votre paramètre est une date, vous devez spécifier le format du paramètre, tel que aaaaMMjj🎜🎜Exemple de valeur du paramètre d'entrée : fournissez un exemple de valeur du paramètre de réponse afin que les développeurs peuvent mieux comprendre et utiliser ce paramètre. 🎜🎜Remarque : S'il existe des 🎜instructions spéciales🎜 pour ce champ de paramètre d'entrée, vous pouvez l'expliquer dans cette colonne. S’il n’y a pas d’explication particulière, il suffit de décrire la fonction de ce paramètre. 🎜🎜🎜🎜Ce qui suit est un exemple de document pour la saisie des paramètres🎜 :🎜

Nom du paramètre	Type	Est-il obligatoire ?	Valeur par défaut	Plage de valeurs	Format du paramètre	Exemple de valeur du paramètre d'entrée	Remarques (description)
IDutilisateur	Long	is	0L	0~99999999L	Aucun	666L	UserId
birthDay	String	is	19900101	19900101~20231231	aaaaMMjj	19940107	Anniversaire de l'utilisateur



5. 7 exigences majeures pour les paramètres de réponse

Les paramètres de réponse sont en fait similaires aux paramètres d'entrée, avec 7 éléments :

• Nom du paramètre : décrit le nom du paramètre de réponse.
• Type de paramètre : décrit le type de données du paramètre de réponse, tel que String, Integer, etc. String、Integer等。
• 参数格式：描述该响应参数的数据格式，如yyyy-MM-dd、HH:mm:ss等。
• 参数说明：对该响应参数的含义进行详细的描述。
• 取值范围：描述该响应参数的取值范围，如整数范围、字符串长度等。
• 是否必填：描述该响应参数是否为必填项。
• 示例值：提供该响应参数的示例值，以便开发人员更好地理解和使用该参数。

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

Format du paramètre : décrit le format de données du paramètre de réponse, tel que aaaa-MM-jj, HH:mm:ss, etc.
Description du paramètre : Description détaillée de la signification de ce paramètre de réponse.

Plage de valeurs : décrit la plage de valeurs du paramètre de réponse, telle que plage d'entiers, longueur de chaîne

, etc. Obligatoire ou non : Décrivez si le paramètre de réponse est obligatoire.

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

Une bonne copie des documents d'interface doit inclure. énumération des codes d'erreur. La définition générale du code d'erreur comprend trois colonnes : Code d'erreur, informations sur le code d'erreur, significationCode d'erreurMessage d'erreurSignification1001Erreur de paramètreParamètres de demande illégaux1002L'utilisateur n'existe pas

Exemple de valeur : fournissez un exemple de valeur pour ce paramètre de réponse afin que les développeurs puissent mieux comprendre et utiliser ce paramètre.	La différence est que les paramètres de réponse sont généralement renvoyés au format code, msg, data :	6 Code d'erreur de l'interface

🎜Aucune information utilisateur correspondante n'a été trouvée en fonction de l'ID utilisateur donné🎜🎜🎜🎜1003🎜🎜Erreur de base de données🎜🎜Erreur d'accès à la base de données🎜🎜🎜🎜



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. 接口测试

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

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!