Ajouter des routes
Apprenez à ajouter de nouvelles routes d'API à votre projet FastAPI existant.
Choisir la disposition de la route
addroute accepte --layout=classic-layer ou --layout=domain. Sans cette option, il lit [tool.fastapi-fastkit].preset : domain-starter sélectionne domain ; classic-layered, minimal et single-module sélectionnent classic-layer. Si preset est absent, il déduit le préréglage de template, si bien que les projets créés avec startdemo ou init interactif sélectionnent aussi domain pour fastapi-domain-starter. En l'absence de ces deux valeurs, il sélectionne classic-layer. Un préréglage inconnu se rabat sur classic-layer avec un avertissement. Une option explicite remplace cette sélection sans modifier les métadonnées du projet.
$ cd my-api
$ fastkit addroute users . --layout=domain
$ fastkit addroute products . --layout=classic-layer
La disposition sélectionnée est affichée avant la confirmation. Les fichiers sont placés sous le package réel de l'application (src/ ou src/app/), en s'appuyant sur son point d'entrée enregistré lorsqu'il est disponible.
Générer un CRUD de domaine
Pour un projet domain-starter, lancez simplement :
Cette commande crée les fichiers suivants et enregistre automatiquement le routeur du domaine :
src/app/domains/users/
├── __init__.py
├── models.py # Users(id: int, name: str)
├── schemas.py # UsersCreate pour POST/PUT, UsersRead pour les réponses
├── repository.py # opérations CRUD typées et stockage en mémoire
├── service.py # logique métier et UsersNotFoundError
└── router.py # points d'extrémité HTTP et dépendance de service surchargeable
Dans chaque domaine, les classes s'appellent Users, UsersCreate, UsersRead, UsersRepository et UsersService ; les noms de classe utilisent le PascalCase (health_checks devient HealthChecks), sans mise au singulier. Le repository attribue des ID à partir de 1. POST et PUT exigent un name de 1 à 120 caractères ; PUT conserve l'ID existant.
| Méthode | Chemin du domaine | Résultat |
|---|---|---|
| GET | /users |
Lister les entités, 200 |
| GET | /users/{entity_id} |
Lire une entité, 200 ou 404 |
| POST | /users |
Créer une entité, 201 |
| PUT | /users/{entity_id} |
Remplacer une entité, 200 ou 404 |
| DELETE | /users/{entity_id} |
Supprimer une entité, 204 vide ou 404 |
Le préfixe et les tags du domaine sont définis dans le routeur d'API partagé lorsqu'il appelle include_router, comme dans la disposition classique.
Le préfixe d'API existant de l'application reste en vigueur (par exemple /api/v1/users). Les routes de domaine n'incluent pas PATCH.
Le repository généré est autonome et protège ses opérations CRUD par un verrou. Son instance par défaut est partagée entre les requêtes au sein de ce domaine et de ce processus. Les données sont perdues au redémarrage et ne sont pas partagées entre les processus workers. Adaptez le repository pour une persistance durable ; il ne dépend ni du db.memory du starter, ni d'un ORM, ni d'une configuration de base de données.
Pour des tests isolés, injectez un UsersRepository neuf dans UsersService, puis surchargez la dépendance FastAPI get_users_service du routeur. UsersRepository.reset() vide ce repository et redémarre les ID à 1. service.reset_store() réinitialise le repository par défaut partagé entre les requêtes. Les instances de repository créées explicitement disposent de leur propre stockage.
Relancer la commande
Les fichiers de module existants sont conservés ; les fichiers manquants sont créés. Les imports et les enregistrements de routeurs ne sont pas dupliqués. Des modules de même nom dans des dispositions différentes peuvent coexister ; des alias d'import évitent les collisions de noms Python. Le générateur ne vérifie pas les conflits de méthode/chemin HTTP. --layout ne migre pas les modules existants.
Ajout de route basique
Les exemples suivants décrivent la disposition classic-layer. Passez explicitement --layout=classic-layer lorsque vous utilisez un projet domain-starter.
Utiliser la commande addroute
La commande addroute de FastAPI-fastkit facilite l'ajout de nouvelles routes :
$ fastkit addroute users my-awesome-api
Adding New Route
┌──────────────────┬──────────────────────────────────────────┐
│ Project │ my-awesome-api │
│ Route Name │ users │
│ Target Directory │ ~/my-awesome-api │
└──────────────────┴──────────────────────────────────────────┘
Do you want to add route 'users' to project 'my-awesome-api'? [Y/n]: y
╭──────────────────────── Info ────────────────────────╮
│ ℹ Updated main.py to include the API router │
╰──────────────────────────────────────────────────────╯
╭─────────────────────── Success ───────────────────────╮
│ ✨ Successfully added new route 'users' to project │
│ `my-awesome-api` │
╰───────────────────────────────────────────────────────╯
Ce qui est créé
Lorsque vous ajoutez une route, FastAPI-fastkit crée automatiquement :
1. Fichier de route : src/api/routes/users.py
from typing import List
from fastapi import APIRouter, HTTPException, status
from src.schemas.users import User, UserCreate, UserUpdate
from src.crud.users import users_crud
router = APIRouter()
@router.get("/", response_model=List[User])
def read_users():
"""Get all users"""
return users_crud.get_all()
@router.post("/", response_model=User, status_code=status.HTTP_201_CREATED)
def create_user(user: UserCreate):
"""Create a new user"""
return users_crud.create(user)
@router.get("/{user_id}", response_model=User)
def read_user(user_id: int):
"""Get a specific user"""
user = users_crud.get_by_id(user_id)
if user is None:
raise HTTPException(status_code=404, detail="User not found")
return user
@router.put("/{user_id}", response_model=User)
def update_user(user_id: int, user: UserUpdate):
"""Update a user"""
updated_user = users_crud.update(user_id, user)
if updated_user is None:
raise HTTPException(status_code=404, detail="User not found")
return updated_user
@router.delete("/{user_id}", status_code=status.HTTP_204_NO_CONTENT)
def delete_user(user_id: int):
"""Delete a user"""
success = users_crud.delete(user_id)
if not success:
raise HTTPException(status_code=404, detail="User not found")
2. Opérations CRUD : src/crud/users.py
from typing import List, Optional
from src.schemas.users import User, UserCreate, UserUpdate
class UsersCRUD:
def __init__(self):
self._users: List[User] = []
self._next_id = 1
def get_all(self) -> List[User]:
"""Get all users"""
return self._users
def get_by_id(self, user_id: int) -> Optional[User]:
"""Get user by ID"""
return next((user for user in self._users if user.id == user_id), None)
def create(self, user: UserCreate) -> User:
"""Create a new user"""
new_user = User(
id=self._next_id,
title=user.title,
description=user.description
)
self._next_id += 1
self._users.append(new_user)
return new_user
def update(self, user_id: int, user: UserUpdate) -> Optional[User]:
"""Update an existing user"""
existing_user = self.get_by_id(user_id)
if existing_user:
update_data = user.dict(exclude_unset=True)
for field, value in update_data.items():
setattr(existing_user, field, value)
return existing_user
return None
def delete(self, user_id: int) -> bool:
"""Delete a user"""
user = self.get_by_id(user_id)
if user:
self._users.remove(user)
return True
return False
users_crud = UsersCRUD()
3. Schémas Pydantic : src/schemas/users.py
from typing import Optional
from pydantic import BaseModel
class UserBase(BaseModel):
title: str
description: Optional[str] = None
class UserCreate(UserBase):
pass
class UserUpdate(BaseModel):
title: Optional[str] = None
description: Optional[str] = None
class User(UserBase):
id: int
class Config:
from_attributes = True
4. Enregistrement du routeur
La commande met automatiquement à jour src/api/api.py pour inclure le nouveau routeur :
from fastapi import APIRouter
from src.api.routes import items, users
api_router = APIRouter()
api_router.include_router(items.router, prefix="/items", tags=["items"])
api_router.include_router(users.router, prefix="/users", tags=["users"])
Points d'extrémité d'API générés
Après avoir ajouté la route users, vous disposerez de ces points d'extrémité :
| Méthode | Point d'extrémité | Description |
|---|---|---|
GET |
/api/v1/users/ |
Récupérer tous les utilisateurs |
POST |
/api/v1/users/ |
Créer un nouvel utilisateur |
GET |
/api/v1/users/{user_id} |
Récupérer un utilisateur précis |
PUT |
/api/v1/users/{user_id} |
Mettre à jour un utilisateur |
DELETE |
/api/v1/users/{user_id} |
Supprimer un utilisateur |
Tester vos nouvelles routes
1. Démarrer le serveur
2. Consulter la documentation de l'API
Rendez-vous sur http://127.0.0.1:8000/docs pour voir vos nouveaux points d'extrémité dans la documentation interactive.
3. Tester avec curl
Créer un utilisateur :
Récupérer tous les utilisateurs :
Récupérer un utilisateur précis :
Personnaliser le code généré
Le code généré est entièrement personnalisable. Voici des modifications courantes :
1. Schéma utilisateur enrichi
Modifiez src/schemas/users.py pour des données utilisateur plus réalistes :
from typing import Optional
from datetime import datetime
from pydantic import BaseModel, EmailStr, Field
class UserBase(BaseModel):
email: EmailStr
username: str = Field(..., min_length=3, max_length=50)
full_name: Optional[str] = None
is_active: bool = True
class UserCreate(UserBase):
password: str = Field(..., min_length=8)
class UserUpdate(BaseModel):
email: Optional[EmailStr] = None
username: Optional[str] = Field(None, min_length=3, max_length=50)
full_name: Optional[str] = None
is_active: Optional[bool] = None
class User(UserBase):
id: int
created_at: datetime
class Config:
from_attributes = True
class UserInDB(User):
hashed_password: str
2. CRUD enrichi avec validation
Mettez à jour src/crud/users.py avec une meilleure validation :
from typing import List, Optional
from datetime import datetime
import hashlib
from src.schemas.users import UserCreate, UserUpdate, UserInDB
class UsersCRUD:
def __init__(self):
self._users: List[UserInDB] = []
self._next_id = 1
def _hash_password(self, password: str) -> str:
"""Simple password hashing (use bcrypt in production)"""
return hashlib.sha256(password.encode()).hexdigest()
def get_by_email(self, email: str) -> Optional[UserInDB]:
"""Get user by email"""
return next((user for user in self._users if user.email == email), None)
def get_by_username(self, username: str) -> Optional[UserInDB]:
"""Get user by username"""
return next((user for user in self._users if user.username == username), None)
def create(self, user: UserCreate) -> UserInDB:
"""Create a new user with validation"""
# Vérifier les doublons
if self.get_by_email(user.email):
raise ValueError("Email already registered")
if self.get_by_username(user.username):
raise ValueError("Username already taken")
new_user = UserInDB(
id=self._next_id,
email=user.email,
username=user.username,
full_name=user.full_name,
is_active=user.is_active,
created_at=datetime.now(),
hashed_password=self._hash_password(user.password)
)
self._next_id += 1
self._users.append(new_user)
return new_user
users_crud = UsersCRUD()
3. Route enrichie avec gestion d'erreurs
Mettez à jour src/api/routes/users.py avec une meilleure gestion des erreurs :
from typing import List
from fastapi import APIRouter, HTTPException, status
from src.schemas.users import User, UserCreate, UserUpdate
from src.crud.users import users_crud
router = APIRouter()
@router.post("/", response_model=User, status_code=status.HTTP_201_CREATED)
def create_user(user: UserCreate):
"""Create a new user"""
try:
new_user = users_crud.create(user)
# Retourner l'utilisateur sans son hash de mot de passe
return User(**new_user.dict())
except ValueError as e:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST,
detail=str(e)
)
@router.get("/{user_id}", response_model=User)
def read_user(user_id: int):
"""Get a specific user"""
user = users_crud.get_by_id(user_id)
if not user:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail=f"User with id {user_id} not found"
)
return User(**user.dict())
Ajouter plusieurs routes
Vous pouvez ajouter plusieurs routes pour construire une API complète :
Cela crée une API complète avec :
/api/v1/users/— gestion des utilisateurs/api/v1/products/— catalogue de produits/api/v1/orders/— traitement des commandes/api/v1/categories/— gestion des catégories
Organisation des routes
Regrouper des points d'extrémité liés
Vous pouvez organiser les routes par domaine :
# src/api/api.py
from fastapi import APIRouter
from src.api.routes import users, products, orders, categories
api_router = APIRouter()
# Gestion des utilisateurs
api_router.include_router(
users.router,
prefix="/users",
tags=["User Management"]
)
# E-commerce
api_router.include_router(
products.router,
prefix="/products",
tags=["E-commerce"]
)
api_router.include_router(
orders.router,
prefix="/orders",
tags=["E-commerce"]
)
api_router.include_router(
categories.router,
prefix="/categories",
tags=["E-commerce"]
)
Ajouter des dépendances de route
Ajoutez l'authentification ou d'autres dépendances :
from fastapi import APIRouter, Depends
from src.core.auth import get_current_user
router = APIRouter()
@router.get("/profile", response_model=User)
def get_user_profile(current_user: User = Depends(get_current_user)):
"""Get current user's profile"""
return current_user
@router.post("/", response_model=User)
def create_user(
user: UserCreate,
current_user: User = Depends(get_current_user)
):
"""Create a new user (admin only)"""
if not current_user.is_admin:
raise HTTPException(status_code=403, detail="Admin access required")
return users_crud.create(user)
Bonnes pratiques
1. Nommage cohérent
Suivez des conventions de nommage cohérentes :
- Noms de routes : utilisez des noms au pluriel (
users,products,orders) - Noms de schémas : utilisez le singulier (
User,Product,Order) - Classes CRUD : terminez par
CRUD(UsersCRUD,ProductsCRUD)
2. Gestion des erreurs
Gérez toujours les erreurs proprement :
@router.post("/", response_model=User)
def create_user(user: UserCreate):
try:
return users_crud.create(user)
except ValueError as e:
raise HTTPException(status_code=400, detail=str(e))
except Exception as e:
raise HTTPException(status_code=500, detail="Internal server error")
3. Documentation
Ajoutez des docstrings complètes :
@router.get("/{user_id}", response_model=User)
def read_user(user_id: int):
"""
Get a specific user by ID.
Args:
user_id: The unique identifier for the user
Returns:
User: The user object with all details
Raises:
HTTPException: 404 if user not found
"""
user = users_crud.get_by_id(user_id)
if not user:
raise HTTPException(status_code=404, detail="User not found")
return user
4. Tests
Testez toujours vos nouvelles routes :
# tests/test_users.py
from fastapi.testclient import TestClient
from src.main import app
client = TestClient(app)
def test_create_user():
user_data = {
"email": "test@example.com",
"username": "testuser",
"password": "securepassword123"
}
response = client.post("/api/v1/users/", json=user_data)
assert response.status_code == 201
assert response.json()["email"] == user_data["email"]
def test_get_user():
response = client.get("/api/v1/users/1")
assert response.status_code == 200
Dépannage
La route n'apparaît pas
Si votre route n'apparaît pas dans la documentation de l'API :
- Vérifiez l'enregistrement du routeur dans
src/api/api.py - Redémarrez le serveur après avoir ajouté des routes
- Recherchez d'éventuelles erreurs d'import dans le fichier de route
Erreurs d'import
Si vous obtenez des erreurs d'import :
- Vérifiez que la structure des fichiers correspond à la disposition attendue
- Vérifiez les imports des schémas dans les fichiers de route et de CRUD
- Assurez-vous que tous les fichiers
__init__.pyexistent
Le serveur ne démarre pas
Si le serveur ne démarre pas après l'ajout de routes :
- Recherchez les erreurs de syntaxe dans les fichiers générés
- Vérifiez la compatibilité des schémas entre les fichiers
- Consultez les journaux pour des messages d'erreur précis
Étapes suivantes
Maintenant que vous savez ajouter des routes :
- Votre premier projet : construire une API de blog complète
- Référence CLI : découvrir toutes les commandes disponibles
- Utiliser les modèles : explorer les modèles de projet prêts à l'emploi
Astuces de développement de routes
- Testez toujours les nouvelles routes dans la documentation interactive (
/docs) - Utilisez des codes d'état HTTP pertinents
- Implémentez une gestion d'erreurs correcte pour tous les points d'extrémité
- Gardez les gestionnaires de route simples et déléguez la logique métier aux classes CRUD