Guide de création de modèles FastAPI
Un guide complet pour ajouter de nouveaux modèles de projet FastAPI à FastAPI-fastkit.
🎯 Vue d'ensemble
L'ajout d'un nouveau modèle suit un processus en 5 étapes :
- 📋 Planification et conception — définir l'objectif et la structure du modèle
- 🏗️ Implémentation du modèle — créer la structure et les fichiers requis
- 🔍 Validation locale — valider le modèle avec l'inspecteur
- 📚 Documentation — rédiger le README et le guide d'utilisation
- 🚀 Soumission et relecture — créer la PR et relecture par la communauté
📋 Étape 1 : Planification et conception
Définir l'objectif du modèle
Avant de créer un nouveau modèle, répondez à ces questions :
- Quelle est la valeur unique de ce modèle ?
- En quoi se distingue-t-il des modèles existants ?
- Quel groupe d'utilisateurs est visé ?
- Quelle pile technique sera incluse ?
Convention de nommage des modèles
Exemples :
fastapi-microservice(modèle microservice)fastapi-graphql(modèle d'intégration GraphQL)fastapi-auth-jwt(modèle d'authentification JWT)
Planification de la pile technique
Définissez à l'avance les principales technologies à inclure :
# Example: fastapi-microservice template
core_dependencies:
- fastapi
- uvicorn
- pydantic
- pydantic-settings
additional_features:
- sqlalchemy (ORM)
- alembic (migrations)
- redis (caching)
- celery (background tasks)
- pytest (testing)
development_tools:
- black (code formatting)
- isort (import sorting)
- mypy (vérification des types)
- pre-commit (hooks Git)
🏗️ Étape 2 : Implémentation du modèle
Structure de répertoires requise
fastapi-{template-name}/
├── src/ # Code source de l'application
│ ├── main.py-tpl # ✅ Point d'entrée FastAPI (obligatoire)
│ ├── __init__.py-tpl
│ ├── api/ # Routeurs API
│ │ ├── __init__.py-tpl
│ │ ├── api.py-tpl # Routeur API principal
│ │ └── routes/ # Routes individuelles
│ │ ├── __init__.py-tpl
│ │ └── items.py-tpl # Exemple de route
│ ├── core/ # Configuration centrale
│ │ ├── __init__.py-tpl
│ │ └── config.py-tpl # Gestion des paramètres
│ ├── crud/ # Logique CRUD
│ │ ├── __init__.py-tpl
│ │ └── items.py-tpl
│ ├── schemas/ # Modèles Pydantic
│ │ ├── __init__.py-tpl
│ │ └── items.py-tpl
│ └── utils/ # Fonctions utilitaires
│ ├── __init__.py-tpl
│ └── helpers.py-tpl
├── tests/ # ✅ Tests (obligatoires)
│ ├── __init__.py-tpl
│ ├── conftest.py-tpl # Configuration pytest
│ └── test_items.py-tpl # Exemples de tests
├── scripts/ # Scripts
│ ├── format.sh-tpl # Formatage du code
│ ├── lint.sh-tpl # Vérifications de style
│ ├── run-server.sh-tpl # Lancement du serveur
│ └── test.sh-tpl # Exécution des tests
├── pyproject.toml-tpl # ✅ Métadonnées principales (PEP 621, requis)
├── requirements.txt-tpl # 🟡 Optionnel si pyproject déclare déjà les dépendances
├── setup.cfg-tpl # Configuration des outils de développement
├── README.md-tpl # ✅ Documentation du projet (obligatoire)
├── .env-tpl # Modèle de variables d'environnement
└── .gitignore-tpl # Fichier d'exclusion Git
Fichiers minimaux requis. Un modèle doit fournir :
- un répertoire
tests/ - un fichier
README.md-tpl pyproject.toml-tpl(PEP 621)- une déclaration de
fastapicomme dépendance danspyproject.toml-tpl[project].dependenciesou dansrequirements.txt-tpl
requirements.txt-tpl n'est pas requis quand pyproject.toml-tpl déclare [project].dependencies — mais lorsqu'un modèle fournit les deux, ils doivent concorder : l'inspection échoue en cas de divergence des dépendances entre eux.
Les nouveaux modèles sont pyproject-first et ne doivent pas fournir de setup.py-tpl. Aucun modèle livré n'en contient depuis v1.4.0. L'inspection accepte toujours ce fichier pour que les modèles hors dépôt continuent de fonctionner, mais il s'agit d'un chemin legacy.
Ciblez Python 3.12 de manière cohérente : requires-python = ">=3.12", black target-version = ["py312"], mypy python_version = "3.12", et python:3.12-slim pour toute image Docker de base. L'inspection vérifie que ces trois épinglages concordent.
Ne déclarez jamais FastAPI-fastkit comme dépendance d'exécution d'un projet généré. Le CLI est un outil de développement ; la liste des dépendances d'un modèle ne doit contenir que ce que l'application générée importe elle-même.
Guide d'écriture des fichiers
1. Écrire main.py-tpl
"""
Point d'entrée de l'application FastAPI
Ce fichier correspond à l'application principale du projet <project_name> créé avec FastAPI-fastkit.
"""
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from api.api import api_router
from core.config import settings
# Create FastAPI app (required for inspector validation)
app = FastAPI(
title="<project_name>",
description="Project created with FastAPI-fastkit",
version="1.0.0",
)
# CORS middleware configuration
app.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_credentials=True,
allow_methods=["*"],
allow_headers=["*"],
)
# Register API router
app.include_router(api_router, prefix="/api/v1")
@app.get("/")
async def root():
"""Root endpoint"""
return {"message": "Hello from <project_name>!"}
@app.get("/health")
async def health_check():
"""Health check endpoint"""
return {"status": "healthy"}
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8000)
2. Écrire pyproject.toml-tpl (préféré)
Les modèles modernes doivent déclarer leurs métadonnées et leurs dépendances avec un pyproject.toml-tpl PEP 621. Au minimum, le fichier doit exposer une section [project] avec name, version, une description et une liste dependencies qui inclut fastapi. Les modèles doivent aussi porter deux marqueurs d'identité FastAPI-fastkit afin que is_fastkit_project() puisse distinguer les projets générés des projets FastAPI non liés dans l'espace de travail de l'utilisateur :
- préfixe
[FastAPI-fastkit templated]dansdescription - une table dédiée
[tool.fastapi-fastkit]avecmanaged = true
La détection accepte n'importe lequel des deux marqueurs (la comparaison est insensible à la casse). L'injection de métadonnées ajoutera les deux au moment de la génération du projet si un modèle les omet, mais les auteurs devraient les inclure explicitement.
[project]
name = "<project_name>"
version = "0.1.0"
description = "[FastAPI-fastkit templated] <description>"
authors = [
{name = "<author>", email = "<author_email>"},
]
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
"fastapi>=0.115.0",
"uvicorn[standard]>=0.34.0",
"pydantic>=2.10.0",
"pydantic-settings>=2.7.0",
"python-dotenv>=1.0.0",
]
[project.optional-dependencies]
dev = [
"pytest>=8.0.0",
"httpx>=0.28.0",
]
[tool.fastapi-fastkit]
managed = true
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
3. Écrire requirements.txt-tpl (optionnel)
Optionnel quand pyproject.toml-tpl déclare [project].dependencies. Reste utile pour les modèles qui préfèrent des flux de travail uniquement pip.
# FastAPI core dependencies (required)
fastapi==0.104.1
uvicorn[standard]==0.24.0
# Data validation
pydantic==2.5.0
pydantic-settings==2.1.0
# Environment variable management
python-dotenv==1.0.0
# Database (if needed)
sqlalchemy==2.0.23
alembic==1.13.0
# Development tools
pytest==7.4.3
pytest-asyncio==0.21.1
httpx==0.25.2
# Code quality
black==23.11.0
isort==5.12.0
mypy==1.7.1
4. Ancres de routes
Les modèles qui fournissent un main.py-tpl ou un module d'agrégation d'API doivent marquer l'endroit où fastkit addroute insère du code :
from src.app.api import health
# fastkit:imports
api_router = APIRouter()
api_router.include_router(health.router)
# fastkit:routes
Sans ces ancres, addroute se rabat sur une insertion fondée sur l'AST qui repère elle-même le bloc d'imports et les enregistrements de routeurs — un modèle qui en est dépourvu fonctionne donc toujours, mais le résultat est moins prévisible. Conservez ces commentaires lorsque vous modifiez ces fichiers.
5. Écrire les fichiers de test
# tests/test_items.py-tpl
"""
Items API test module
"""
import pytest
from fastapi.testclient import TestClient
from main import app
client = TestClient(app)
def test_read_root():
"""Test root endpoint"""
response = client.get("/")
assert response.status_code == 200
assert "message" in response.json()
def test_health_check():
"""Tester le point de contrôle de santé"""
response = client.get("/health")
assert response.status_code == 200
assert response.json() == {"status": "healthy"}
def test_create_item():
"""Test item creation"""
item_data = {
"name": "Test Item",
"description": "Test Description"
}
response = client.post("/api/v1/items/", json=item_data)
assert response.status_code == 200
data = response.json()
assert data["name"] == item_data["name"]
assert data["description"] == item_data["description"]
def test_read_items():
"""Test reading items list"""
response = client.get("/api/v1/items/")
assert response.status_code == 200
assert isinstance(response.json(), list)
🔍 Étape 3 : Validation locale
Exécuter les scripts de validation automatisés
Une fois votre nouveau modèle prêt, validez-le avec ces commandes :
# Validate all templates
make inspect-templates
# Validate specific template only
make inspect-template TEMPLATES="fastapi-your-template"
# Validate with verbose output
python scripts/inspect-templates.py --templates "fastapi-your-template" --verbose
# Fast local loop: no network, no server boot
python scripts/inspect-templates.py --templates "fastapi-your-template" \
--offline --no-smoke
# Full check before opening a PR (adds mypy over the generated project)
python scripts/inspect-templates.py --templates "fastapi-your-template" --mypy
--offline ignore les vérifications de fraîcheur des dépendances sur PyPI, --no-smoke ignore le démarrage du projet généré (l'étape la plus lente) et --mypy vérifie les types du projet généré. Consultez Assurance qualité des modèles pour savoir ce que fait chaque vérification.
Note
Lorsque vous soumettez une PR, le workflow Template PR Inspection se déclenche automatiquement et valide vos changements de modèle. Vous recevrez le retour directement sur votre PR.
Liste de vérification
L'inspecteur valide automatiquement les éléments suivants :
✅ Validation de la structure des fichiers
- [ ] Le répertoire
tests/existe - [ ] Le fichier
README.md-tplexiste - [ ]
pyproject.toml-tplexiste (pas desetup.py-tpldans les nouveaux modèles)
✅ Validation des extensions de fichiers
- [ ] Tous les fichiers Python utilisent l'extension
.py-tpl - [ ] Aucun fichier en
.pyn'existe
✅ Validation des dépendances
- [ ]
fastapiest déclaré dans au moins l'un de :- [ ]
pyproject.toml-tplsous[project].dependencies(préféré) - [ ]
requirements.txt-tpl
- [ ]
- [ ]
requirements.txt-tplet[project].dependenciesne divergent pas - [ ]
FastAPI-fastkitn'est pas une dépendance d'exécution
✅ Validation de l'implémentation FastAPI
- [ ] L'import
FastAPIexiste dansmain.py-tpl - [ ] La création d'application du type
app = FastAPI()existe dansmain.py-tpl
✅ Validation de l'exécution des tests
- [ ] La création de l'environnement virtuel réussit
- [ ] L'installation des dépendances réussit
- [ ] Tous les tests pytest passent
✅ Test smoke
- [ ] Le projet généré démarre sous uvicorn
- [ ]
/docsrépond - [ ]
/healthrépond
La cible uvicorn est résolue à partir de [tool.fastapi-fastkit].app_module dans le pyproject.toml généré, puis de app_module dans template-config.yml, puis des emplacements conventionnels de main.py.
✅ Cohérence de la configuration
- [ ]
requires-python, blacktarget-versionet mypypython_versionindiquent tous Python 3.12 - [ ] Aucune divergence de dépendances entre
requirements.txt-tplet[project].dependencies - [ ] Aucune auto-dépendance à
FastAPI-fastkit
✅ Résidus d'emplacements
- [ ] Aucun
<placeholder>ne subsiste après la génération du projet
✅ Tests automatisés des modèles
FastAPI-fastkit inclut des tests automatisés des modèles qui exécutent des tests complets pour tous les modèles :
Couverture des tests :
- ✅ Processus de création de modèle
- ✅ Injection des métadonnées de projet
- ✅ Mise en place de l'environnement virtuel
- ✅ Installation des dépendances (tous les gestionnaires de paquets)
- ✅ Validation de la structure basique du projet
- ✅ Identification du projet FastAPI
Exécution des tests :
# Test all templates automatically
$ pytest tests/test_templates/test_all_templates.py -v
# Test specific template
$ pytest tests/test_templates/test_all_templates.py::TestAllTemplates::test_template_creation[your-template-name] -v
Découverte des tests de modèle : Les nouveaux modèles sont automatiquement découverts et testés sans configuration manuelle :
- ✅ Zéro configuration : ajoutez un modèle → tests automatiques
- ✅ Tests cohérents : mêmes standards de qualité pour tous les modèles
- ✅ Gestionnaires de paquets multiples : tests avec UV, PDM, Poetry et PIP
- ✅ Validation complète : vérifications de structure, métadonnées et fonctionnalités
Ce que cela signifie pour vous :
- 🚀 Aucun fichier de test supplémentaire dans la source principale de
FastAPI-fastkit: votre modèle est testé automatiquement - ⚡ Développement plus rapide : concentrez-vous sur le contenu du modèle, pas sur la configuration des tests
- 🛡️ Assurance qualité : tests cohérents pour tous les modèles
- 🔄 Intégration CI/CD : tests automatiques dans les pull requests
Tests manuels toujours requis :
- 🧪 Fonctionnalités propres au modèle : logique métier et fonctionnalités personnalisées
- 🔧 Tests d'intégration : services externes et flux de travail complexes
- 📱 Scénarios de bout en bout : flux utilisateurs complets
Bonnes pratiques de test :
# 1. Test your template locally
$ fastkit startdemo your-template-name
# 2. Run automated tests
$ pytest tests/test_templates/test_all_templates.py::TestAllTemplates::test_template_creation[your-template-name] -v
# 3. Test with different package managers
$ fastkit startdemo your-template-name --package-manager poetry
$ fastkit startdemo your-template-name --package-manager pdm
$ fastkit startdemo your-template-name --package-manager uv
Liste de vérification manuelle
En complément de la validation automatisée, vérifiez manuellement les éléments suivants :
🔧 Qualité du code
- [ ] Le code respecte le guide de style PEP 8
- [ ] Utilisation appropriée des annotations de type
- [ ] Noms de variables et de fonctions explicites
- [ ] Commentaires et docstrings appropriés
🏗️ Architecture
- [ ] Séparation des préoccupations (séparation API, logique métier, accès aux données)
- [ ] Conception de composants réutilisables
- [ ] Structure évolutive
- [ ] Bonnes pratiques de sécurité appliquées
📚 Documentation
- [ ] README.md-tpl respecte le format de PROJECT_README_TEMPLATE.md
- [ ] Méthodes d'installation et d'exécution précisées
- [ ] Documentation de l'API (OpenAPI/Swagger)
- [ ] Explication des variables d'environnement
📚 Étape 4 : Documentation
Rédiger README.md-tpl
Rédigez en suivant le guide PROJECT_README_TEMPLATE.md.
Rédiger la documentation de description du modèle
Ajoutez une description de votre nouveau modèle à src/fastapi_fastkit/fastapi_project_template/README.md :
## fastapi-your-template
Write a brief description and use cases for your new template here.
### Features:
- Feature 1
- Feature 2
- Feature 3
### Use Cases:
- Use case 1
- Use case 2
🚀 Étape 5 : Soumission et relecture
Liste de vérification avant création de la PR
- [ ] Toute la validation automatisée est passée (
make inspect-templates) - [ ] La mise en forme du code est terminée (
make format) - [ ] Les contrôles de linting sont passés (
make lint) - [ ] Tous les tests sont passés (
make test) - [ ] La documentation est complète
- [ ] Les directives de CONTRIBUTING.md sont respectées
Titre et description de la PR
[TEMPLATE] Add fastapi-{template-name} template
## Overview
Adds a new {purpose} template.
## Key Features
- Feature 1
- Feature 2
- Feature 3
## Validation Results
- [ ] Inspector validation passed
- [ ] All tests passed
- [ ] Documentation completed
## Usage Example
\```bash
fastkit startdemo
# Select template: fastapi-{template-name}
\```
## Related Issues
Closes #issue-number
Processus de relecture
- Validation automatisée : GitHub Actions valide automatiquement le modèle
- Template PR Inspection : exécute
inspect-changed-templates.pysur les PR qui modifient des modèles - Inspection hebdomadaire : validation complète des modèles chaque mercredi
- Template PR Inspection : exécute
- Relecture de code : les mainteneurs et la communauté relisent le code
- Tests : le modèle est testé dans divers environnements
- Relecture de la documentation : vérification de l'exactitude et de la complétude de la documentation
- Approbation et fusion : fusion dans la branche main lorsque toutes les exigences sont satisfaites
Note
Vous recevrez des commentaires automatiques de PR avec les résultats de validation. Vérifiez-les avant de demander une relecture !
🎯 Bonnes pratiques
Considérations de sécurité
- Gérez les informations sensibles avec des variables d'environnement
- Configuration CORS correcte
- Validation des données d'entrée
- Prévention des injections SQL
Optimisation des performances
- Tirer parti du traitement asynchrone
- Optimiser les requêtes de base de données
- Stratégies de mise en cache appropriées
- Paramètres de compression des réponses
Maintenabilité
- Structure de code claire
- Couverture de tests complète
- Documentation détaillée
- Mise en place de journalisation et de supervision
🆘 Besoin d'aide ?
- 📖 Guide de configuration du développement
- 📋 Directives de code
- 💬 GitHub Discussions
- 📧 Contacter le mainteneur
Ajouter un nouveau modèle est une superbe contribution à la communauté FastAPI-fastkit. Vos idées et vos efforts seront d'une grande aide pour d'autres développeurs ! 🚀