Designspezifikation für HTTP-API-Schnittstellen

1. Alle Anfragen verwenden die POST-Methode

• Verglichen mit der Abfragezeichenfolge von get kann die Verwendung von post komplexe Arten von Anforderungsparametern unterstützen. Beispielsweise ist in täglichen Projekten der Get-Anforderungsparameter ein Array-Typ.

• Erleichtern Sie die einheitliche Signatur, Verschlüsselung und Protokollverarbeitung von Anfragen und Antworten

2. URL-Regeln

• Die URL darf nur Englisch enthalten, englische Wörter oder Abkürzungen verwenden, kein chinesisches Pinyin verwenden

• Verwenden Sie Kleinbuchstaben für alle Zeichen

• Trennen Sie mehrere Wörter mit einem Bindestrich -, z. B. third-login, verwenden Sie nicht thirdlogin, thirdLoginoderthird_login

• Der Pfadteil der URL 系统/模块/操作verwendet das Format, zims/video/list

  • System, das angibt, welcher Dienst im Microservice diese Schnittstelle ist, können Sie die Abkürzung verwenden
  • Module, die Untermodule des Systems darstellen. Der Modulname verwendet den vollständigen Namen des Substantivs und verwendet die Singularform
  • Die Operation, die eine bestimmte Schnittstelle darstellt, verwendet die Form Verb + Substantiv und muss Singular und Plural berücksichtigen. Zum add-userBeispiel list-users_delete-users

3. HTTP-Header

• Fügen Sie spezifische unternehmensunabhängige Daten in HTTP-Header ein
• Das Back-End-System kann einige gängige Logik verarbeiten, ohne den Anforderungs- und Antworttext einzubeziehen

4. Anfrage- und Antwortstelle

• utf-8Codierung verwenden
• JSON-Format
• Wenn eine Verschlüsselung erforderlich ist, kann normales JSON verschlüsselt und mit base64 codiert werden

5. HTTP-Statuscode

• Das Verarbeitungsergebnis des Geschäfts spiegelt sich nicht im HTTP-Statuscode wider, sondern wird durch das Fehlercodefeld des Antworttexts dargestellt
• Nur einige HTTP-Statuscodes weisen auf unternehmensunabhängige Antworten hin, z
  • 200: Das Geschäft wurde verarbeitet, aber der Erfolg oder Misserfolg der Verarbeitung wird von der Antwortstelle angezeigt
  • 400: Falsche Anforderung, wird meistens bei der Überprüfung von Anforderungsparametern verwendet. Die Cliententwicklung muss sicherstellen, dass das richtige Format der Anfrage an den Server gesendet wird
  • 401: Authentifizierung fehlgeschlagen, im Allgemeinen ist kein Token vorhanden oder kein Token läuft ab
  • 403: Keine Berechtigung zum Aufrufen dieser Schnittstelle. Der Client sollte Vorgänge ausblenden, für die der Benutzer keine Berechtigung hat
  • 500: Server-Ausnahme

6. Feldbenennung

• JSON stammt aus der Javascript-Sprache, daher folgt die Feldbenennung der Javascript-Sprache und verwendet lowerCamelCasedie kleine Kamelschreibweise
• Verwenden Sie keine unterstrichenen Linkssnake_case

7. Datentypen

Gemeinsame Datentypzuordnung

• bool: auf Zeichenfolge abgebildet, verwenden Sie Y, um wahr darzustellen, N, um falsch darzustellen
• int: auf Zahl abgebildet
• long: auf string abgebildet, da der Zahlentyp von js nicht genügend Wertebereich verarbeiten kann, führt dies zu verschiedenen seltsamen Problemen in aktuellen Projekten
• float, double, decimal: auf String abgebildet
• Datum, Uhrzeit: auf Zeichenfolge abgebildet

Notiz:

• Das Feld, das das Konzept der ID darstellt, verwendet einheitlich eine Zeichenfolge
• Wenn während der Datenübertragung ein bestimmtes Feld leer ist, lassen Sie dieses Feld direkt weg, um den Netzwerkaufwand zu reduzieren
• Wenn die Geschäftsdaten des Antworttexts mehrere Datenstrukturen enthalten, wird das verschachtelte Format bevorzugt, z. B. die vom Benutzer unten erstellte Nachricht

 "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. Antworttextformat

• code Der Fehlercode der Geschäftsverarbeitung wird durch kurze englische Wörter dargestellt, die die Art des Fehlers widerspiegeln können, wobei Großbuchstaben verwendet werden und Wörter durch Unterstriche getrennt werden. Es wird nicht empfohlen, Zahlen zur Darstellung von Fehlercodes zu verwenden, und die Verwendung von Zahlen zur Darstellung von Fehlercodetabellen erfordert zusätzliche Wartung.