Spécification de conception d'interface API HTTP

1. Toutes les requêtes utilisent la méthode POST

• Par rapport à la chaîne de requête de get, l'utilisation de post peut prendre en charge des types complexes de paramètres de requête. Par exemple, dans les projets quotidiens, le paramètre get request est un type de tableau.

• Faciliter la signature unifiée, le chiffrement et le traitement des journaux des demandes et des réponses

2. Règles d'URL

• L'URL ne peut contenir que de l'anglais, utiliser des mots ou des abréviations anglais, ne pas utiliser de pinyin chinois

• Utilisez des lettres minuscules pour tous les caractères

• Séparez plusieurs mots par un trait d'union -, comme third-login, ne pas utiliser thirdlogin, thirdLoginouthird_login

• La partie chemin de l'URL 系统/模块/操作utilise le format, tel queims/video/list

  • System, indiquant à quel service du microservice cette interface correspond, vous pouvez utiliser l'abréviation
  • Les modules, qui représentent les sous-modules du système. Le nom du module utilise le nom complet du nom et utilise la forme singulière
  • L'opération, qui représente une interface spécifique, utilise la forme verbe + nom et doit considérer le singulier et le pluriel. Par exemple add-user,list-usersdelete-users

3. En-tête HTTP

• Placer des données spécifiques indépendantes de l'entreprise dans les en-têtes HTTP
• Le système backend peut gérer une logique commune sans impliquer le corps de la requête et de la réponse

4. Corps de la requête et de la réponse

• utiliser utf-8l'encodage
• Format JSON
• Si le cryptage est requis, le JSON normal peut être crypté et encodé avec base64

5. Code d'état HTTP

• Le résultat du traitement de l'entreprise n'est pas reflété dans le code d'état http, mais est représenté par le champ de code d'erreur du corps de la réponse
• Seuls certains codes d'état http indiquent des réponses indépendantes de l'entreprise, telles que
  • 200: L'entreprise a été traitée, mais le succès ou l'échec du traitement est indiqué par le corps de la réponse
  • 400: Requête erronée, principalement utilisée dans la vérification des paramètres de la requête. Le développement client doit s'assurer que le format correct de la demande est soumis au serveur
  • 401: L'authentification a échoué, généralement il n'y a pas de jeton ou aucun jeton n'expire
  • 403: Aucune autorisation d'appeler cette interface. Le client doit masquer les opérations pour lesquelles l'utilisateur n'a pas l'autorisation
  • 500: exception du serveur

6. Dénomination des champs

• JSON vient du langage javascript, donc la dénomination du champ suit le langage javascript, en utilisant lowerCamelCasela petite orthographe camel
• Ne pas utiliser de liens soulignéssnake_case

7. Types de données

Mappage des types de données communs

• bool : mappé à une chaîne, utilisez Y pour représenter vrai, N pour représenter faux
• int : mappé au nombre
• long : mappé sur une chaîne, car le type de nombre de js ne peut pas gérer une plage de valeurs suffisante, cela entraînera divers problèmes étranges dans les projets réels
• flottant, double, décimal : mappé sur une chaîne
• Date, heure : mappé sur une chaîne

Avis:

• Le champ représentant le concept d'ID, utilise uniformément la chaîne
• Pendant la transmission de données, si un certain champ est vide, omettez ce champ directement pour réduire la surcharge du réseau
• Lorsque les données métier du corps de réponse contiennent plusieurs structures de données, le format imbriqué est préféré, tel que le message créé par l'utilisateur ci-dessous

 "item": {
      "num_iid": "520813250866",
      "title": "三刃木折叠刀过安检创意迷你钥匙扣钥匙刀军刀随身多功能小刀包邮",
      "desc_short": "",
      "price": 25.8,
      "total_price": 0,
      "suggestive_price": 0,
      "orginal_price": "25.80",
      "nick": "欢乐购客栈",
      "num": "832",
      "min_num": 0,
      "detail_url": "http://item.taobao.com/item.htm?id=520813250866",
      "pic_url": "//img.alicdn.com/imgextra/i4/2596264565/TB2p30elFXXXXXQXpXXXXXXXXXX_!!2596264565.jpg",
      "brand": "三刃木",
      "brandId": "4036703",
      "rootCatId": "50013886",
      "cid": "50014822",
      "favcount": "4824",
      "fanscount": "1469",
      "crumbs": [],
      "created_time": "",
      "modified_time": "",
      "delist_time": "",

8. Format du corps de la réponse

• code Le code d'erreur du traitement d'entreprise est représenté par des mots anglais courts qui peuvent refléter le type d'erreur, en utilisant des lettres majuscules et en utilisant des traits de soulignement pour séparer les mots. Il n'est pas recommandé d'utiliser des nombres pour représenter les codes d'erreur, et l'utilisation de nombres pour représenter les tables de codes d'erreur nécessite une maintenance supplémentaire.