Concepts de base de FastAPI
FastAPI est un framework web Python moderne, rapide (haute performance) pour créer des API. Il est basé sur les annotations de type Python standard, utilisant Starlette et Pydantic.
Fonctionnalités principales
- Haute performance: Comparable à NodeJS et Go, l'un des frameworks Python les plus rapides
- Développement rapide: La vitesse de développement a augmenté d'environ 200%-300%
- Réduire les erreurs: Réduire les erreurs humaines d'environ 40 %
- Intuitif: Prise en charge puissante de l'éditeur, autocomplétion partout
- Simple: Facile à utiliser et à apprendre, réduisant le temps passé à lire la documentation
ASGI et programmation asynchrone
Qu'est-ce que l'ASGI ?
ASGI (Asynchronous Server Gateway Interface) est l'interface standard entre les serveurs web asynchrones Python et les applications.
Comparaison WSGI vs ASGI :
Exemple
# Application WSGI (synchrone) - style Flask traditionnel
def wsgi_app(environ, start_response):
status = '200 OK'
response_headers = [('Content-type', 'text/plain')]
start_response(status, response_headers)
return [b'Hello World']
# Application ASGI (asynchrone) - style FastAPI
async def asgi_app(scope, receive, send):
await send({
'type': 'http.response.start',
'status': 200,
'headers': [(b'content-type', b'text/plain')],
})
await send({
'type': 'http.response.body',
'body': b'Hello World',
})
def wsgi_app(environ, start_response):
status = '200 OK'
response_headers = [('Content-type', 'text/plain')]
start_response(status, response_headers)
return [b'Hello World']
# Application ASGI (asynchrone) - style FastAPI
async def asgi_app(scope, receive, send):
await send({
'type': 'http.response.start',
'status': 200,
'headers': [(b'content-type', b'text/plain')],
})
await send({
'type': 'http.response.body',
'body': b'Hello World',
})
Concepts fondamentaux de la programmation asynchrone
Exécution synchrone vs asynchrone :
Exemple
import asyncio
import time
import httpx
# Mode synchrone - exécution bloquante
def sync_fetch_data():
start_time = time.time()
# Simuler trois requêtes réseau
time.sleep(1) # Première requête
time.sleep(1) # Deuxième requête
time.sleep(1) # Troisième requête
print(f"Temps écoulé pour l'exécution synchrone : {time.time() - start_time:.2f} seconds") # environ 3 seconds
# Mode asynchrone - exécution concurrente
async def async_fetch_data():
start_time = time.time()
# Exécuter trois requêtes en parallèle
await asyncio.gather(
asyncio.sleep(1), # Première requête
asyncio.sleep(1), # Deuxième requête
asyncio.sleep(1), # Troisième requête
)
print(fTemps d'exécution asynchrone : {time.time() - start_time:.2f} secondes) # environ 1 seconde
# Exécuter l'exemple
sync_fetch_data() # Sortie : Temps d'exécution synchrone : 3.00 secondes
asyncio.run(async_fetch_data()) # Sortie : Temps d'exécution asynchrone : 1.00 secondes
import time
import httpx
# Mode synchrone - exécution bloquante
def sync_fetch_data():
start_time = time.time()
# Simuler trois requêtes réseau
time.sleep(1) # Première requête
time.sleep(1) # Deuxième requête
time.sleep(1) # Troisième requête
print(f"Temps écoulé pour l'exécution synchrone : {time.time() - start_time:.2f} seconds") # environ 3 seconds
# Mode asynchrone - exécution concurrente
async def async_fetch_data():
start_time = time.time()
# Exécuter trois requêtes en parallèle
await asyncio.gather(
asyncio.sleep(1), # Première requête
asyncio.sleep(1), # Deuxième requête
asyncio.sleep(1), # Troisième requête
)
print(fTemps d'exécution asynchrone : {time.time() - start_time:.2f} secondes) # environ 1 seconde
# Exécuter l'exemple
sync_fetch_data() # Sortie : Temps d'exécution synchrone : 3.00 secondes
asyncio.run(async_fetch_data()) # Sortie : Temps d'exécution asynchrone : 1.00 secondes
Opérations de chemin asynchrones dans FastAPI :
Exemple
from fastapi import FastAPI
import asyncio
app = FastAPI()
# Opération de chemin synchrone
@app.get("/sync")
def sync_endpoint():
# Les opérations synchrones bloquent toute l'application
time.sleep(2)
return {"message": "Réponse synchrone"}
# Opération de chemin asynchrone (recommandée)
@app.get("/async")
async def async_endpoint():
# Les opérations asynchrones ne bloquent pas les autres requêtes
await asyncio.sleep(2)
return {"message": "Réponse asynchrone"}
# Exemple d'opération de base de données asynchrone
@app.get("/users/{user_id}")
async def get_user(user_id: int):
# Requête de base de données asynchrone
user = await database.fetch_one(
"SELECT * FROM users WHERE id = :user_id",
{"user_id": user_id}
)
return user
import asyncio
app = FastAPI()
# Opération de chemin synchrone
@app.get("/sync")
def sync_endpoint():
# Les opérations synchrones bloquent toute l'application
time.sleep(2)
return {"message": "Réponse synchrone"}
# Opération de chemin asynchrone (recommandée)
@app.get("/async")
async def async_endpoint():
# Les opérations asynchrones ne bloquent pas les autres requêtes
await asyncio.sleep(2)
return {"message": "Réponse asynchrone"}
# Exemple d'opération de base de données asynchrone
@app.get("/users/{user_id}")
async def get_user(user_id: int):
# Requête de base de données asynchrone
user = await database.fetch_one(
"SELECT * FROM users WHERE id = :user_id",
{"user_id": user_id}
)
return user
Quand utiliser async ?
Scénarios adaptés aux opérations asynchrones :
- Opération de base de données
- Requêtes réseau (appels API)
- Opérations d'E/S sur fichiers
- Opérations avec de longs temps d'attente
Scénarios non adaptés aux opérations asynchrones :
- Calcul intensif sur le CPU
- Traitement simple de données
- Opérations sans attente d'E/S
Exemple
# Bon usage de l'asynchrone
@app.get("/weather")
async def get_weather():
async with httpx.AsyncClient() as client:
response = await client.get("https://api.weather.com/data")
return response.json()
# async inutile (pas d'attente d'E/S)
@app.get("/calculate")
def calculate_sync(): # Gardez-le simplement synchrone
result = sum(range(1000000))
return {"result": result}
@app.get("/weather")
async def get_weather():
async with httpx.AsyncClient() as client:
response = await client.get("https://api.weather.com/data")
return response.json()
# async inutile (pas d'attente d'E/S)
@app.get("/calculate")
def calculate_sync(): # Gardez-le simplement synchrone
result = sum(range(1000000))
return {"result": result}
Principes de conception des API REST
Fondamentaux de REST
REST (Representational State Transfer) est un style de conception d'API Web qui met l'accent sur :
- Orienté ressources: les URL représentent des ressources
- Sans état: chaque requête est indépendante
- Interface uniforme: utilisez les méthodes HTTP standard
- Système en couches: Prend en charge la mise en cache, l'équilibrage de charge, etc.
Conception d'URL RESTful
Exemples de bonne conception d'URL :
Exemple
from fastapi import FastAPI, HTTPException, status
from pydantic import BaseModel
from typing import List, Optional
app = FastAPI()
# Collections de ressources et ressources individuelles
@app.get("/users") # GET /users - Obtenir la liste des utilisateurs
async def get_users():
return users_db
@app.get("/users/{user_id}") # GET /users/123 - Obtenir un utilisateur spécifique
async def get_user(user_id: int):
return find_user(user_id)
@app.post("/users") # POST /users - Créer un nouvel utilisateur
async def create_user(user: UserCreate):
return create_new_user(user)
@app.put("/users/{user_id}") # PUT /users/123 - Mise à jour complète de l'utilisateur
async def update_user(user_id: int, user: UserUpdate):
return update_existing_user(user_id, user)
@app.patch("/users/{user_id}") # PATCH /users/123 - mise à jour partielle de l'utilisateur
async def patch_user(user_id: int, user: UserPatch):
return patch_existing_user(user_id, user)
@app.delete("/users/{user_id}") # DELETE /users/123 - Supprimer l'utilisateur
async def delete_user(user_id: int):
return delete_existing_user(user_id)
# Ressources imbriquées
@app.get("/users/{user_id}/posts") # Récupérer tous les articles de l'utilisateur
async def get_user_posts(user_id: int):
return get_posts_by_user(user_id)
@app.post("/users/{user_id}/posts") # Créer un nouvel article pour l'utilisateur
async def create_user_post(user_id: int, post: PostCreate):
return create_post_for_user(user_id, post)
from pydantic import BaseModel
from typing import List, Optional
app = FastAPI()
# Collections de ressources et ressources individuelles
@app.get("/users") # GET /users - Obtenir la liste des utilisateurs
async def get_users():
return users_db
@app.get("/users/{user_id}") # GET /users/123 - Obtenir un utilisateur spécifique
async def get_user(user_id: int):
return find_user(user_id)
@app.post("/users") # POST /users - Créer un nouvel utilisateur
async def create_user(user: UserCreate):
return create_new_user(user)
@app.put("/users/{user_id}") # PUT /users/123 - Mise à jour complète de l'utilisateur
async def update_user(user_id: int, user: UserUpdate):
return update_existing_user(user_id, user)
@app.patch("/users/{user_id}") # PATCH /users/123 - mise à jour partielle de l'utilisateur
async def patch_user(user_id: int, user: UserPatch):
return patch_existing_user(user_id, user)
@app.delete("/users/{user_id}") # DELETE /users/123 - Supprimer l'utilisateur
async def delete_user(user_id: int):
return delete_existing_user(user_id)
# Ressources imbriquées
@app.get("/users/{user_id}/posts") # Récupérer tous les articles de l'utilisateur
async def get_user_posts(user_id: int):
return get_posts_by_user(user_id)
@app.post("/users/{user_id}/posts") # Créer un nouvel article pour l'utilisateur
async def create_user_post(user_id: int, post: PostCreate):
return create_post_for_user(user_id, post)
Principes de conception d'URL :
好的设计 GET /api/v1/users # 获取用户列表 GET /api/v1/users/123 # 获取用户 123 POST /api/v1/users # 创建用户 GET /api/v1/users/123/orders # 获取用户 123 的订单 # 不好的设计 GET /api/v1/getAllUsers # 动词不应该在 URL 中 GET /api/v1/user/123 # 集合名应该用复数 POST /api/v1/createUser # URL 中包含动作 GET /api/v1/users-orders-123 # 关系不清晰
Relation hiérarchique des ressources
Exemple
# Conception des relations entre utilisateurs et articles
class User(BaseModel):
id: int
name: str
email: str
class Post(BaseModel):
id: int
title: str
content: str
author_id: int
# Opération sur la ressource principale
@app.get("/users")
async def list_users() -> List[User]:
return users
@app.get("/posts")
async def list_posts() -> List[Post]:
return posts
# Opérations sur les ressources associées
@app.get("/users/{user_id}/posts")
async def get_user_posts(user_id: int) -> List[Post]:
"""Récupérer tous les articles d'un utilisateur spécifique"""
return [post for post in posts if post.author_id == user_id]
@app.get("/posts/{post_id}/author")
async def get_post_author(post_id: int) -> User:
"""Obtenir les informations sur l'auteur de l'article"""
post = find_post(post_id)
if not post:
raise HTTPException(status_code=404, detail="Article introuvable")
return find_user(post.author_id)
class User(BaseModel):
id: int
name: str
email: str
class Post(BaseModel):
id: int
title: str
content: str
author_id: int
# Opération sur la ressource principale
@app.get("/users")
async def list_users() -> List[User]:
return users
@app.get("/posts")
async def list_posts() -> List[Post]:
return posts
# Opérations sur les ressources associées
@app.get("/users/{user_id}/posts")
async def get_user_posts(user_id: int) -> List[Post]:
"""Récupérer tous les articles d'un utilisateur spécifique"""
return [post for post in posts if post.author_id == user_id]
@app.get("/posts/{post_id}/author")
async def get_post_author(post_id: int) -> User:
"""Obtenir les informations sur l'auteur de l'article"""
post = find_post(post_id)
if not post:
raise HTTPException(status_code=404, detail="Article introuvable")
return find_user(post.author_id)
Méthodes HTTP et codes de statut
Sémantique des méthodes HTTP
Exemple
from fastapi import FastAPI, status, HTTPException
from fastapi.responses import JSONResponse
app = FastAPI()
# GET - sûre et idempotente
@app.get("/users/{user_id}")
async def get_user(user_id: int):
"""Obtenir une ressource sans modifier l'état du serveur"""
user = find_user(user_id)
if not user:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail="Utilisateur introuvable"
)
return user
# POST - non sûre et non idempotente
@app.post("/users", status_code=status.HTTP_201_CREATED)
async def create_user(user: UserCreate):
"""Créer une nouvelle ressource"""
if user_exists(user.email):
raise HTTPException(
status_code=status.HTTP_409_CONFLICT,
detail="L'utilisateur existe déjà"
)
new_user = create_new_user(user)
return new_user
# PUT - non sûr mais idempotent
@app.put("/users/{user_id}")
async def replace_user(user_id: int, user: UserUpdate):
"""Remplacer complètement la ressource"""
if not user_exists(user_id):
# PUT peut créer une ressource
return create_user_with_id(user_id, user)
return replace_existing_user(user_id, user)
# PATCH - non sûr et généralement non idempotent
@app.patch("/users/{user_id}")
async def update_user(user_id: int, user: UserPatch):
"""Met à jour partiellement la ressource"""
existing_user = find_user(user_id)
if not existing_user:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail="Utilisateur introuvable"
)
return patch_user_fields(existing_user, user)
# DELETE - non sûr mais idempotent
@app.delete("/users/{user_id}", status_code=status.HTTP_204_NO_CONTENT)
async def delete_user(user_id: int):
"""Supprime la ressource"""
if not user_exists(user_id):
# Idempotence : supprimer une ressource inexistante renvoie quand même un succès
return JSONResponse(status_code=status.HTTP_204_NO_CONTENT)
delete_existing_user(user_id)
return JSONResponse(status_code=status.HTTP_204_NO_CONTENT)
from fastapi.responses import JSONResponse
app = FastAPI()
# GET - sûre et idempotente
@app.get("/users/{user_id}")
async def get_user(user_id: int):
"""Obtenir une ressource sans modifier l'état du serveur"""
user = find_user(user_id)
if not user:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail="Utilisateur introuvable"
)
return user
# POST - non sûre et non idempotente
@app.post("/users", status_code=status.HTTP_201_CREATED)
async def create_user(user: UserCreate):
"""Créer une nouvelle ressource"""
if user_exists(user.email):
raise HTTPException(
status_code=status.HTTP_409_CONFLICT,
detail="L'utilisateur existe déjà"
)
new_user = create_new_user(user)
return new_user
# PUT - non sûr mais idempotent
@app.put("/users/{user_id}")
async def replace_user(user_id: int, user: UserUpdate):
"""Remplacer complètement la ressource"""
if not user_exists(user_id):
# PUT peut créer une ressource
return create_user_with_id(user_id, user)
return replace_existing_user(user_id, user)
# PATCH - non sûr et généralement non idempotent
@app.patch("/users/{user_id}")
async def update_user(user_id: int, user: UserPatch):
"""Met à jour partiellement la ressource"""
existing_user = find_user(user_id)
if not existing_user:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail="Utilisateur introuvable"
)
return patch_user_fields(existing_user, user)
# DELETE - non sûr mais idempotent
@app.delete("/users/{user_id}", status_code=status.HTTP_204_NO_CONTENT)
async def delete_user(user_id: int):
"""Supprime la ressource"""
if not user_exists(user_id):
# Idempotence : supprimer une ressource inexistante renvoie quand même un succès
return JSONResponse(status_code=status.HTTP_204_NO_CONTENT)
delete_existing_user(user_id)
return JSONResponse(status_code=status.HTTP_204_NO_CONTENT)
Utilisation des codes de statut HTTP
Exemple
from fastapi import status
# Réponse de succès 2xx
@app.post("/users", status_code=status.HTTP_201_CREATED) # 201 Créé
@app.get("/users") # 200 OK (par défaut)
@app.delete("/users/{user_id}", status_code=status.HTTP_204_NO_CONTENT) # 204 Aucun contenu
# Erreurs client 4xx
@app.get("/users/{user_id}")
async def get_user(user_id: int):
if user_id < 1:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST, # 400 Mauvaise requête
detail="L'ID utilisateur doit être positif"
)
user = find_user(user_id)
if not user:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND, # 404 Non trouvé
detail="Utilisateur introuvable"
)
return user
# Erreur de logique métier
@app.post("/users/{user_id}/follow")
async def follow_user(user_id: int, current_user_id: int):
if user_id == current_user_id:
raise HTTPException(
status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, # 422 Entité non traitable
detail="Impossible de se suivre soi-même"
)
if is_already_following(current_user_id, user_id):
raise HTTPException(
status_code=status.HTTP_409_CONFLICT, # 409 Conflit
detail="Vous suivez déjà cet utilisateur"
)
# Erreur serveur 5xx (généralement gérée par le gestionnaire d'exceptions)
@app.exception_handler(Exception)
async def general_exception_handler(request, exc):
return JSONResponse(
status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, # 500 Erreur interne du serveur
content={"detail": "Erreur interne du serveur"}
)
# Réponse de succès 2xx
@app.post("/users", status_code=status.HTTP_201_CREATED) # 201 Créé
@app.get("/users") # 200 OK (par défaut)
@app.delete("/users/{user_id}", status_code=status.HTTP_204_NO_CONTENT) # 204 Aucun contenu
# Erreurs client 4xx
@app.get("/users/{user_id}")
async def get_user(user_id: int):
if user_id < 1:
raise HTTPException(
status_code=status.HTTP_400_BAD_REQUEST, # 400 Mauvaise requête
detail="L'ID utilisateur doit être positif"
)
user = find_user(user_id)
if not user:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND, # 404 Non trouvé
detail="Utilisateur introuvable"
)
return user
# Erreur de logique métier
@app.post("/users/{user_id}/follow")
async def follow_user(user_id: int, current_user_id: int):
if user_id == current_user_id:
raise HTTPException(
status_code=status.HTTP_422_UNPROCESSABLE_ENTITY, # 422 Entité non traitable
detail="Impossible de se suivre soi-même"
)
if is_already_following(current_user_id, user_id):
raise HTTPException(
status_code=status.HTTP_409_CONFLICT, # 409 Conflit
detail="Vous suivez déjà cet utilisateur"
)
# Erreur serveur 5xx (généralement gérée par le gestionnaire d'exceptions)
@app.exception_handler(Exception)
async def general_exception_handler(request, exc):
return JSONResponse(
status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, # 500 Erreur interne du serveur
content={"detail": "Erreur interne du serveur"}
)
Référence rapide des codes de statut courants :
# 成功状态码 200 OK # 请求成功 201 Created # 资源创建成功 204 No Content # 成功但无内容返回 206 Partial Content # 部分内容(分页、断点续传) # 重定向 301 Moved Permanently # 永久重定向 302 Found # 临时重定向 304 Not Modified # 资源未修改(缓存) # 客户端错误 400 Bad Request # 请求格式错误 401 Unauthorized # 未认证 403 Forbidden # 已认证但无权限 404 Not Found # 资源不存在 405 Method Not Allowed # HTTP 方法不允许 409 Conflict # 资源冲突 422 Unprocessable Entity # 数据验证失败 429 Too Many Requests # 请求过于频繁 # 服务器错误 500 Internal Server Error # 服务器内部错误 502 Bad Gateway # 网关错误 503 Service Unavailable # 服务不可用
Format de données JSON
Principes fondamentaux de JSON et bonnes pratiques
Exemple
from datetime import datetime
from decimal import Decimal
from typing import Optional, List
from pydantic import BaseModel, Field
import json
# Spécification du format de données JSON
class UserResponse(BaseModel):
id: int
username: str
email: str
full_name: Optional[str] = None
is_active: bool = True
created_at: datetime
updated_at: Optional[datetime] = None
# Configuration de la sérialisation JSON
class Config:
# Autoriser les alias de champs
allow_population_by_field_name = True
# Encodeur JSON
json_encoders = {
datetime: lambda v: v.isoformat(),
Decimal: lambda v: float(v)
}
# Standardiser le format de réponse
class APIResponse(BaseModel):
"""Format standard de réponse API"""
success: bool = True
message: str = "Opération réussie"
data: Optional[dict] = None
errors: Optional[List[str]] = None
timestamp: datetime = Field(default_factory=datetime.now)
# Format de réponse de pagination
class PaginatedResponse(BaseModel):
items: List[dict]
total: int
page: int
size: int
pages: int
@app.get("/users", response_model=PaginatedResponse)
async def get_users(page: int = 1, size: int = 10):
"""Renvoie une liste paginée d'utilisateurs"""
users = get_users_paginated(page, size)
total = count_users()
return PaginatedResponse(
items=users,
total=total,
page=page,
size=size,
pages=(total + size - 1) // size
)
from decimal import Decimal
from typing import Optional, List
from pydantic import BaseModel, Field
import json
# Spécification du format de données JSON
class UserResponse(BaseModel):
id: int
username: str
email: str
full_name: Optional[str] = None
is_active: bool = True
created_at: datetime
updated_at: Optional[datetime] = None
# Configuration de la sérialisation JSON
class Config:
# Autoriser les alias de champs
allow_population_by_field_name = True
# Encodeur JSON
json_encoders = {
datetime: lambda v: v.isoformat(),
Decimal: lambda v: float(v)
}
# Standardiser le format de réponse
class APIResponse(BaseModel):
"""Format standard de réponse API"""
success: bool = True
message: str = "Opération réussie"
data: Optional[dict] = None
errors: Optional[List[str]] = None
timestamp: datetime = Field(default_factory=datetime.now)
# Format de réponse de pagination
class PaginatedResponse(BaseModel):
items: List[dict]
total: int
page: int
size: int
pages: int
@app.get("/users", response_model=PaginatedResponse)
async def get_users(page: int = 1, size: int = 10):
"""Renvoie une liste paginée d'utilisateurs"""
users = get_users_paginated(page, size)
total = count_users()
return PaginatedResponse(
items=users,
total=total,
page=page,
size=size,
pages=(total + size - 1) // size
)
JSON Schema et validation des données
Exemple
from pydantic import BaseModel, validator, Field
from typing import Optional, List
from enum import Enum
class UserRole(str, Enum):
ADMIN = "admin"
USER = "user"
MODERATOR = "moderator"
class UserCreate(BaseModel):
username: str = Field(..., min_length=3, max_length=50, description="Nom d'utilisateur")
email: str = Field(..., regex=r'^[\w\.-]+@[\w\.-]+\.\w+$', description="Adresse e-mail")
password: str = Field(..., min_length=8, description="Mot de passe")
full_name: Optional[str] = Field(None, max_length=100, description="Nom complet")
role: UserRole = Field(UserRole.USER, description="Rôle de l'utilisateur")
age: Optional[int] = Field(None, ge=0, le=150, description="Âge")
@validator('username')
def username_must_be_alphanumeric(cls, v):
if not v.isalnum():
raise ValueError('Le nom d’utilisateur ne peut contenir que des lettres et des chiffres')
return v
@validator('password')
def password_strength(cls, v):
if not any(c.isupper() for c in v):
raise ValueError('Le mot de passe doit contenir au moins une lettre majuscule')
if not any(c.islower() for c in v):
raise ValueError('Le mot de passe doit contenir au moins une lettre minuscule')
if not any(c.isdigit() for c in v):
raise ValueError('Le mot de passe doit contenir au moins un chiffre')
return v
class Config:
# Générer un exemple de JSON Schema
schema_extra = {
"example": {
"username": "johndoe",
"email": "john@example.com",
"password": "SecurePass123",
"full_name": "John Doe",
"role": "user",
"age": 30
}
}
# Utiliser des validateurs personnalisés
@app.post("/users", response_model=UserResponse)
async def create_user(user: UserCreate):
"""Créer un nouvel utilisateur, avec validation des données"""
# Pydantic valide automatiquement les données d'entrée
return await create_new_user(user)
from typing import Optional, List
from enum import Enum
class UserRole(str, Enum):
ADMIN = "admin"
USER = "user"
MODERATOR = "moderator"
class UserCreate(BaseModel):
username: str = Field(..., min_length=3, max_length=50, description="Nom d'utilisateur")
email: str = Field(..., regex=r'^[\w\.-]+@[\w\.-]+\.\w+$', description="Adresse e-mail")
password: str = Field(..., min_length=8, description="Mot de passe")
full_name: Optional[str] = Field(None, max_length=100, description="Nom complet")
role: UserRole = Field(UserRole.USER, description="Rôle de l'utilisateur")
age: Optional[int] = Field(None, ge=0, le=150, description="Âge")
@validator('username')
def username_must_be_alphanumeric(cls, v):
if not v.isalnum():
raise ValueError('Le nom d’utilisateur ne peut contenir que des lettres et des chiffres')
return v
@validator('password')
def password_strength(cls, v):
if not any(c.isupper() for c in v):
raise ValueError('Le mot de passe doit contenir au moins une lettre majuscule')
if not any(c.islower() for c in v):
raise ValueError('Le mot de passe doit contenir au moins une lettre minuscule')
if not any(c.isdigit() for c in v):
raise ValueError('Le mot de passe doit contenir au moins un chiffre')
return v
class Config:
# Générer un exemple de JSON Schema
schema_extra = {
"example": {
"username": "johndoe",
"email": "john@example.com",
"password": "SecurePass123",
"full_name": "John Doe",
"role": "user",
"age": 30
}
}
# Utiliser des validateurs personnalisés
@app.post("/users", response_model=UserResponse)
async def create_user(user: UserCreate):
"""Créer un nouvel utilisateur, avec validation des données"""
# Pydantic valide automatiquement les données d'entrée
return await create_new_user(user)
Format de réponse d'erreur
Exemple
class ErrorDetail(BaseModel):
field: str
message: str
code: str
class ErrorResponse(BaseModel):
error: str
message: str
details: Optional[List[ErrorDetail]] = None
timestamp: datetime = Field(default_factory=datetime.now)
# Gestion personnalisée des exceptions
from fastapi import Request
from fastapi.exceptions import RequestValidationError
from starlette.exceptions import HTTPException as StarletteHTTPException
@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request: Request, exc: RequestValidationError):
errors = []
for error in exc.errors():
errors.append(ErrorDetail(
field='.'.join(str(x) for x in error['loc']),
message=error['msg'],
code=error['type']
))
return JSONResponse(
status_code=422,
content=ErrorResponse(
error="Erreur de validation",
message="Échec de la validation des données de la requête",
details=errors
).dict()
)
@app.exception_handler(StarletteHTTPException)
async def http_exception_handler(request: Request, exc: StarletteHTTPException):
return JSONResponse(
status_code=exc.status_code,
content=ErrorResponse(
error=f"HTTP {exc.status_code}",
message=exc.detail
).dict()
)
field: str
message: str
code: str
class ErrorResponse(BaseModel):
error: str
message: str
details: Optional[List[ErrorDetail]] = None
timestamp: datetime = Field(default_factory=datetime.now)
# Gestion personnalisée des exceptions
from fastapi import Request
from fastapi.exceptions import RequestValidationError
from starlette.exceptions import HTTPException as StarletteHTTPException
@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request: Request, exc: RequestValidationError):
errors = []
for error in exc.errors():
errors.append(ErrorDetail(
field='.'.join(str(x) for x in error['loc']),
message=error['msg'],
code=error['type']
))
return JSONResponse(
status_code=422,
content=ErrorResponse(
error="Erreur de validation",
message="Échec de la validation des données de la requête",
details=errors
).dict()
)
@app.exception_handler(StarletteHTTPException)
async def http_exception_handler(request: Request, exc: StarletteHTTPException):
return JSONResponse(
status_code=exc.status_code,
content=ErrorResponse(
error=f"HTTP {exc.status_code}",
message=exc.detail
).dict()
)
Concepts spécifiques à FastAPI
Génération automatique de la documentation
Exemple
from fastapi import FastAPI, Query, Path, Body
from fastapi.openapi.utils import get_openapi
app = FastAPI(
title="Mon API",
description=Ceci est un exemple d'API, illustrant les fonctionnalités de FastAPI,
version="1.0.0",
terms_of_service="http://example.com/terms/",
contact={
"name": "Développeur",
"url": "http://example.com/contact/",
"email": "developer@example.com",
},
license_info={
"name": "MIT",
"url": "https://opensource.org/licenses/MIT",
},
)
@app.get(
"/users/{user_id}",
summary=Obtenir les informations de l'utilisateur,
description="Obtenir des informations détaillées sur l'utilisateur à partir de son ID utilisateur",
response_description=Objet d'informations utilisateur,
tags=["Gestion des utilisateurs"]
)
async def get_user(
user_id: int = Path(..., title="ID utilisateur", description="ID utilisateur à récupérer", ge=1),
include_posts: bool = Query(False, title="Inclure les articles", description=Indique s'il faut inclure la liste des articles de l'utilisateur)
):
"""
Obtenir les informations de l'utilisateur :
- **user_id** : L'identifiant unique de l'utilisateur.
**include_posts** : Indique s'il faut inclure la liste des publications de l'utilisateur dans la réponse
Retourne les informations de base de l'utilisateur ; si include_posts est True, cela inclura également la liste des articles.
"""
user = find_user(user_id)
if include_posts:
user.posts = get_user_posts(user_id)
return user
# Schéma OpenAPI personnalisé
def custom_openapi():
if app.openapi_schema:
return app.openapi_schema
openapi_schema = get_openapi(
title="Documentation d'API personnalisée",
version="2.5.0",
description="Ceci est un schéma OpenAPI personnalisé",
routes=app.routes,
)
# Ajouter des informations personnalisées
openapi_schema["info"]["x-logo"] = {
"url": "https://example.com/logo.png"
}
app.openapi_schema = openapi_schema
return app.openapi_schema
app.openapi = custom_openapi
from fastapi.openapi.utils import get_openapi
app = FastAPI(
title="Mon API",
description=Ceci est un exemple d'API, illustrant les fonctionnalités de FastAPI,
version="1.0.0",
terms_of_service="http://example.com/terms/",
contact={
"name": "Développeur",
"url": "http://example.com/contact/",
"email": "developer@example.com",
},
license_info={
"name": "MIT",
"url": "https://opensource.org/licenses/MIT",
},
)
@app.get(
"/users/{user_id}",
summary=Obtenir les informations de l'utilisateur,
description="Obtenir des informations détaillées sur l'utilisateur à partir de son ID utilisateur",
response_description=Objet d'informations utilisateur,
tags=["Gestion des utilisateurs"]
)
async def get_user(
user_id: int = Path(..., title="ID utilisateur", description="ID utilisateur à récupérer", ge=1),
include_posts: bool = Query(False, title="Inclure les articles", description=Indique s'il faut inclure la liste des articles de l'utilisateur)
):
"""
Obtenir les informations de l'utilisateur :
- **user_id** : L'identifiant unique de l'utilisateur.
**include_posts** : Indique s'il faut inclure la liste des publications de l'utilisateur dans la réponse
Retourne les informations de base de l'utilisateur ; si include_posts est True, cela inclura également la liste des articles.
"""
user = find_user(user_id)
if include_posts:
user.posts = get_user_posts(user_id)
return user
# Schéma OpenAPI personnalisé
def custom_openapi():
if app.openapi_schema:
return app.openapi_schema
openapi_schema = get_openapi(
title="Documentation d'API personnalisée",
version="2.5.0",
description="Ceci est un schéma OpenAPI personnalisé",
routes=app.routes,
)
# Ajouter des informations personnalisées
openapi_schema["info"]["x-logo"] = {
"url": "https://example.com/logo.png"
}
app.openapi_schema = openapi_schema
return app.openapi_schema
app.openapi = custom_openapi
Aperçu du système d'injection de dépendances
Exemple
from fastapi import Depends
# Dépendance simple
def get_current_user_id() -> int:
# Analyser l'ID utilisateur à partir du token
return 123
def get_database_session():
# Créer une session de base de données
db = DatabaseSession()
try:
yield db
finally:
db.close()
# Utilisation des dépendances
@app.get("/profile")
async def get_profile(
user_id: int = Depends(get_current_user_id),
db = Depends(get_database_session)
):
return get_user_profile(db, user_id)
# chaîne de dépendances
def get_current_user(
user_id: int = Depends(get_current_user_id),
db = Depends(get_database_session)
):
return db.query(User).filter(User.id == user_id).first()
@app.get("/dashboard")
async def get_dashboard(
current_user: User = Depends(get_current_user) # Dépend d'autres dépendances
):
return generate_dashboard(current_user)
# Dépendance simple
def get_current_user_id() -> int:
# Analyser l'ID utilisateur à partir du token
return 123
def get_database_session():
# Créer une session de base de données
db = DatabaseSession()
try:
yield db
finally:
db.close()
# Utilisation des dépendances
@app.get("/profile")
async def get_profile(
user_id: int = Depends(get_current_user_id),
db = Depends(get_database_session)
):
return get_user_profile(db, user_id)
# chaîne de dépendances
def get_current_user(
user_id: int = Depends(get_current_user_id),
db = Depends(get_database_session)
):
return db.query(User).filter(User.id == user_id).first()
@app.get("/dashboard")
async def get_dashboard(
current_user: User = Depends(get_current_user) # Dépend d'autres dépendances
):
return generate_dashboard(current_user)
L'importance des annotations de type
Exemple
from typing import List, Optional, Union, Dict, Any
from pydantic import BaseModel
# FastAPI s'appuie entièrement sur les annotations de type :
# 1. Validation des données
# 2. Génération de la documentation
# 3. Prise en charge de l'éditeur
@app.get("/items/{item_id}")
async def get_item(
item_id: int, # Paramètre de chemin, automatiquement converti en int
q: Optional[str] = None, # Paramètres de requête facultatifs
limit: int = 10 # Paramètres de requête avec valeurs par défaut
) -> Dict[str, Any]: # Indication du type de retour
"""Les annotations de type indiquent à FastAPI comment gérer les paramètres et les réponses"""
return {"item_id": item_id, "q": q, "limit": limit}
# Indication de type complexe
@app.post("/items/")
async def create_items(
items: List[ItemCreate] # Reçoit une liste d'objets ItemCreate
) -> List[ItemResponse]: # Renvoie une liste d'objets ItemResponse
return [create_item(item) for item in items]
# Type Union (plusieurs types possibles)
@app.get("/search")
async def search(
q: str,
result_type: str = "json"
) -> Union[List[Dict], str]: # Peut renvoyer un dictionnaire, une liste ou une chaîne
if result_type == "json":
return [{"title": "Result 1"}, {"title": "Résultat 2"}]
else:
return "Résultat 1, Résultat 2"
from pydantic import BaseModel
# FastAPI s'appuie entièrement sur les annotations de type :
# 1. Validation des données
# 2. Génération de la documentation
# 3. Prise en charge de l'éditeur
@app.get("/items/{item_id}")
async def get_item(
item_id: int, # Paramètre de chemin, automatiquement converti en int
q: Optional[str] = None, # Paramètres de requête facultatifs
limit: int = 10 # Paramètres de requête avec valeurs par défaut
) -> Dict[str, Any]: # Indication du type de retour
"""Les annotations de type indiquent à FastAPI comment gérer les paramètres et les réponses"""
return {"item_id": item_id, "q": q, "limit": limit}
# Indication de type complexe
@app.post("/items/")
async def create_items(
items: List[ItemCreate] # Reçoit une liste d'objets ItemCreate
) -> List[ItemResponse]: # Renvoie une liste d'objets ItemResponse
return [create_item(item) for item in items]
# Type Union (plusieurs types possibles)
@app.get("/search")
async def search(
q: str,
result_type: str = "json"
) -> Union[List[Dict], str]: # Peut renvoyer un dictionnaire, une liste ou une chaîne
if result_type == "json":
return [{"title": "Result 1"}, {"title": "Résultat 2"}]
else:
return "Résultat 1, Résultat 2"
Exemples pratiques des concepts fondamentaux
Exemple
from fastapi import FastAPI, HTTPException, status, Depends, Query
from pydantic import BaseModel, Field
from typing import List, Optional
from datetime import datetime
import asyncio
# Exemple complet : API de blog
app = FastAPI(
title=API de blog,
description="Un système de blog illustrant les concepts fondamentaux de FastAPI",
version="1.0.0"
)
# Modèle de données
class PostBase(BaseModel):
title: str = Field(..., min_length=1, max_length=200)
content: str = Field(..., min_length=1)
published: bool = Field(True)
class PostCreate(PostBase):
pass
class PostResponse(PostBase):
id: int
author_id: int
created_at: datetime
updated_at: Optional[datetime] = None
class Config:
orm_mode = True
# Base de données simulée
posts_db = []
next_id = 1
# Dépendance : obtenir l'utilisateur actuel (version simplifiée)
async def get_current_user() -> int:
# Dans les applications réelles, il sera analysé à partir du jeton JWT
return 1
# Opération de chemin asynchrone
@app.get("/posts", response_model=List[PostResponse], tags=["Article"])
async def list_posts(
skip: int = Query(0, ge=0, description=Nombre d'articles ignorés),
limit: int = Query(10, ge=1, le=100, description=Nombre d'articles retournés),
published_only: bool = Query(True, description="Retourner uniquement les articles publiés")
):
"""
Obtenir la liste des articles
Prend en charge la pagination et le filtrage
"""
# Simuler une requête asynchrone à la base de données
await asyncio.sleep(0.1)
filtered_posts = posts_db
if published_only:
filtered_posts = [p for p in posts_db if p["published"]]
return filtered_posts[skip:skip + limit]
@app.post("/posts", response_model=PostResponse, status_code=status.HTTP_201_CREATED, tags=["Article"])
async def create_post(
post: PostCreate,
current_user_id: int = Depends(get_current_user)
):
"""
Créer un nouvel article
Nécessite l'authentification de l'utilisateur
"""
global next_id
# Simuler des opérations asynchrones sur la base de données
await asyncio.sleep(0.1)
new_post = {
"id": next_id,
"title": post.title,
"content": post.content,
"published": post.published,
"author_id": current_user_id,
"created_at": datetime.now(),
"updated_at": None
}
posts_db.append(new_post)
next_id += 1
return new_post
@app.get("/posts/{post_id}", response_model=PostResponse, tags=["Article"])
async def get_post(post_id: int):
"""
Obtenir un article spécifique
Retourner les détails de l'article en fonction de l'ID de l'article
"""
# Simuler une requête asynchrone à la base de données
await asyncio.sleep(0.1)
post = next((p for p in posts_db if p["id"] == post_id), None)
if not post:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail=f"Article avec l'id {post_id} introuvable"
)
return post
# Point de terminaison de contrôle d'état
@app.get("/health", tags=[System])
async def health_check():
"""Vérification de l'état du système"""
return {
"status": "healthy",
"timestamp": datetime.now(),
"posts_count": len(posts_db)
}
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8000)
from pydantic import BaseModel, Field
from typing import List, Optional
from datetime import datetime
import asyncio
# Exemple complet : API de blog
app = FastAPI(
title=API de blog,
description="Un système de blog illustrant les concepts fondamentaux de FastAPI",
version="1.0.0"
)
# Modèle de données
class PostBase(BaseModel):
title: str = Field(..., min_length=1, max_length=200)
content: str = Field(..., min_length=1)
published: bool = Field(True)
class PostCreate(PostBase):
pass
class PostResponse(PostBase):
id: int
author_id: int
created_at: datetime
updated_at: Optional[datetime] = None
class Config:
orm_mode = True
# Base de données simulée
posts_db = []
next_id = 1
# Dépendance : obtenir l'utilisateur actuel (version simplifiée)
async def get_current_user() -> int:
# Dans les applications réelles, il sera analysé à partir du jeton JWT
return 1
# Opération de chemin asynchrone
@app.get("/posts", response_model=List[PostResponse], tags=["Article"])
async def list_posts(
skip: int = Query(0, ge=0, description=Nombre d'articles ignorés),
limit: int = Query(10, ge=1, le=100, description=Nombre d'articles retournés),
published_only: bool = Query(True, description="Retourner uniquement les articles publiés")
):
"""
Obtenir la liste des articles
Prend en charge la pagination et le filtrage
"""
# Simuler une requête asynchrone à la base de données
await asyncio.sleep(0.1)
filtered_posts = posts_db
if published_only:
filtered_posts = [p for p in posts_db if p["published"]]
return filtered_posts[skip:skip + limit]
@app.post("/posts", response_model=PostResponse, status_code=status.HTTP_201_CREATED, tags=["Article"])
async def create_post(
post: PostCreate,
current_user_id: int = Depends(get_current_user)
):
"""
Créer un nouvel article
Nécessite l'authentification de l'utilisateur
"""
global next_id
# Simuler des opérations asynchrones sur la base de données
await asyncio.sleep(0.1)
new_post = {
"id": next_id,
"title": post.title,
"content": post.content,
"published": post.published,
"author_id": current_user_id,
"created_at": datetime.now(),
"updated_at": None
}
posts_db.append(new_post)
next_id += 1
return new_post
@app.get("/posts/{post_id}", response_model=PostResponse, tags=["Article"])
async def get_post(post_id: int):
"""
Obtenir un article spécifique
Retourner les détails de l'article en fonction de l'ID de l'article
"""
# Simuler une requête asynchrone à la base de données
await asyncio.sleep(0.1)
post = next((p for p in posts_db if p["id"] == post_id), None)
if not post:
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail=f"Article avec l'id {post_id} introuvable"
)
return post
# Point de terminaison de contrôle d'état
@app.get("/health", tags=[System])
async def health_check():
"""Vérification de l'état du système"""
return {
"status": "healthy",
"timestamp": datetime.now(),
"posts_count": len(posts_db)
}
if __name__ == "__main__":
import uvicorn
uvicorn.run(app, host="0.0.0.0", port=8000)