[Python] restful Specification Practice Based on fastapi

AvantRestfulPourquoi la spécification n'a - t - elle pas été maintenue

Nous savons tous qu'une bonne spécification est une garantie importante pour la maintenabilité du système,Mais presque tous les deux ou trois ans,Je vais devoir revenir sur les spécifications de l'interface.

PourquoirestfulLes spécifications sont difficiles à maintenir？Résumé,Les principales raisons en sont les suivantes:：

1. La conception des spécifications est trop complexe：Une spécification trop complexe équivaut à ne pas avoir;
2. La mobilité des personnes entraîne l'absence d'héritage de la spécification：Le Mouvement des personnes peut causer beaucoup de choses qui peuvent facilement se casser;
3. Il y a des spécifications, pas d'outils：Ça pourrait êtrerestfulLe principal problème.Tout le monde a sa propre compréhension,Il se transforme lentement;
4. Il n'y a pas de personnes ou d'organisations spécialisées pour continuer à avancer：Surtout en cas de rotation du personnel,C'est plus évident..

Donc,,L'application des normes doit être garantie：

1. Les spécifications doivent être aussi simples que possible,Abandonner des détails moins importants;
2. Outils plus lourds que les spécifications：UnionfastapiSpécifications de conception,Un outil sera également mis au point pour harmoniser les spécifications;
3. Le Comité technique assure un suivi et un contrôle continus de la mise en œuvre des spécifications.

Les principes les plus élevés de la conception des interfaces：Idempotence

Le principe suprême de la conception de l'interface est de maintenir l'idémpotence autant que possible,Voir ici pour plus de détails.

HTTPVerbes

http Il y a plusieurs verbes ,Mais il suffit de se concentrer sur quatre：

• GET：Obtenir ou interroger l'utilisation des données, Maintenir l'idempotent ;
• DELETE： Supprimer l'utilisation des données , Maintenir l'idempotent ;
• POST：Il y a généralement deux scénarios d'utilisation：
  • D'abord, quand on ajoute des données, Elle n'est pas idéaliste. ,Mais il y a des moyens de s'assurer que la répétition n'a pas d'effets secondaires;
  • L'autre est de faire des requêtes complexes,Il faut utiliserPOST,Au lieu d'utiliserGET.
• PUT： Modifier l'utilisation des enregistrements , Maintenir l'idempotent .

Certains sont utilisés pour la simplicité, On va l'utiliser. PUT Ça marche aussi. POST, Ce n'est pas un problème non plus. ,Il n'y a pas besoin de trop s'emmêler.

HTTPCode d'état

FréquentHTTP Les codes d'état sont les suivants: ：

On devrait essayer d'utiliserHTTPCode d'état pour distinguer le type d'exception d'interface,Si vous voulez définir votre propre type,Il faut utiliser1000 Et plus tard .

Pas dans la valeur de retour,Contient à nouveau le type d'exception,La valeur de retour de l'interface n'est que les données elles - mêmes.

Spécification de nommage du routage

D'abord, quelques règles simples：

1. N'utilisez pas de majuscules dans le routage;
2. Essayez de ne pas souligner dans le routage,Si c'est vraiment deux mots pour décrire une ressource,Ça pourrait utiliser un connecteur（Moins）;
3. Habituellement, seul le dernier verbe d'une route peut être un verbe,Tout ce qui précède devrait être des noms.Si vous utilisezhttpLes mots d'action de,Alors aucun verbe n'est nécessaire dans le routage.

Par exemple：

Il y a beaucoup de discussions en ligne restfulLa question de savoir si la spécification est au singulier ou au pluriel,Je ne pense pas qu'il soit nécessaire de trop s'attarder sur ce point.

S'il s'agit d'une action sur une seule ressource, Peut être utilisé id Directement dans le routage ,Format comme：

/Nom de la ressource/{Ressourcesid}/{Action}

Comme vous pouvez le voir directement à partir du routage,C'est ce qu'on fait aux ressources.

En plus,Le premier nom de la route comme nom du module,InFastAPIImplémenté comme sous - routage（Module）.

Spécification d'entrée / sortie

Les données de sortie suivent FastAPISpécifications de base：

• La valeur de retour de l'interface ne contient que des données,Ne contient pas de code d'état d'exception;
• Chaque champ d'entrée / sortie doit être clairement défini,Type inclus,Plage de valeurs,Avec les instructions correspondantes;
• Pour les types complexes,Attention..Par exemple, liste,Il faut définir clairement le type de chaque élément,Si c'est un dictionnaire,Doit être défini comme une structure distincte,Définir clairement le sens de chaque champ.

Par exemple：

class PaddingArgs(BaseModel):
left: float = Field(0.0, title='La marge gauche de la page est vide', ge=0, lt=0.5,
description='SiboxDerightLes coordonnées sont inférieures au produit de cette valeur et de la largeur, Filtrer ceci box')
right: float = Field(0.0, title='La marge droite de la page est vide', ge=0, lt=0.5,
description='SiboxDeleftLes coordonnées sont plus grandes que la largeur de la page moins le produit de cette valeur et de la largeur, Filtrer ceci box')
top: float = Field(0.0, title='Zone vide à la limite supérieure de la page', ge=0, lt=0.5,
description='SiboxDebottomLes coordonnées sont inférieures au produit de cette valeur et de la hauteur, Filtrer ceci box')
bottom: float = Field(0.0, title='Zone vide à la limite inférieure de la page', ge=0, lt=0.5,
description='SiboxDetopLes coordonnées sont supérieures à la hauteur moins le produit de cette valeur et de la hauteur, Filtrer ceci box')

Les types de dictionnaires ne sont généralement pas utilisés directement dans les entrées / sorties,Au lieu de cela, il devrait être converti en une structure comme celle - ci.Si dans les paramètres d'entrée,Cette définition devient un objet.

FastAPI Table des matières

FastAPI Structure du Répertoire des projets pour ：

.
├── app
│ ├── __init__.py
│ ├── readme.md # Description de l'interface document
│ ├── main.py # Fichier d'entrée principal
│ ├── schema.py # Généralitésschema
│ ├── settings.py # Profil
│ ├── dependencies.py #
│ ├── exceptions.py # Corrélation anormale
│ ├── utile.py # Fonctions générales de l'outil
│ ├── common # Module commun
│ │ ├── __init__.py
│ └── module_name # Répertoire des modules,Chaque module est séparé dans un répertoire
│ ├── __init__.py
│ ├── router.py # Fichier de routage du module
│ └── schema.py # Configuration du fichier de routage
├── .vscode # vscodeConfiguration
│ ├── settings.json
├── .gitignore
├── README.md # Description du projet document
├── install.md # Installer la documentation de déploiement et d'exploitation et d'entretien
├── Dockerfile # Docker
├── requirements.txt # Paquet de dépendances du projet

À propos de la structure du Répertoire des projets,Après, on aura unFastAPI Spécification des échafaudages ,Voici le répertoire des modules,Nous incluons les modules eux - mêmes dans le répertoire des modules, Inclure les fichiers de routage （Certaines personnes aiment gérer les fichiers de routage dans un répertoire unifié,Mais je pense que les répertoires de modules sont étroitement couplés à d'autres répertoires）.

Plus tard, nous pourrons développer et partager quelques modules, Par exemple, module utilisateur , Module de code de vérification, etc. ,Il suffit de placer le répertoire des modules dansappSous la table des matières,Puis à l'entrée globalemain.pyIl suffit d'enregistrer le routage approprié. Autres informations sur le Web：

• http://restful.p2hp.com/
• Compris.Restful：http://www.ruanyifeng.com/blog/2011/09/restful.html
• RestfulGuide de conception：http://www.ruanyifeng.com/blog/2014/05/restful_api.html
• MicrosoftRestful API Directives de conception ：https://github.com/Microsoft/api-guidelines/blob/master/Guidelines.md
• Github Restful API：https://docs.github.com/en/rest/guides/getting-started-with-the-rest-api