01 Pourquoi les deux

Django apporte ce qu'il fait de mieux depuis vingt ans : un ORM, des migrations, une interface d'administration complète et des commandes de gestion. FastAPI apporte ce que Django fait moins bien : un code entièrement asynchrone, une validation des requêtes et des réponses par des modèles Pydantic, et une documentation de l'API générée toute seule.

Plutôt que de choisir, le jeu prend les deux, avec un partage strict :

Qui Fait quoi
FastAPI les pages du jeu (gabarits Jinja2), l'API JSON sous /api/, sa documentation sur /api/docs, la validation des données
Django l'ORM et les migrations sur PostgreSQL, l'admin sous /admin/, les commandes (chargement des stations, création des grilles), les fichiers statiques versionnés

Tout le code applicatif est asynchrone : FastAPI reçoit les requêtes et appelle l'ORM de Django avec ses méthodes asynchrones. Django ne répond lui-même qu'à ce que FastAPI ne gère pas : l'admin, et les fichiers statiques en développement.

02 Une seule application ASGI

Le serveur, uvicorn, ne connaît qu'une application : celle de FastAPI. Django y est monté à la racine, en dernier, comme filet de secours.

Caddy request uvicorn one single ASGI application timestamp and log client address database connections FastAPI tries its routes in order /api/… JSON API 1 /, /articles/… game pages 2 /health health 3 /static/ versioned files 4 route found response “no route” 5 AppendSlash mounted on / NotFoundPages Django /admin/
Le routage : FastAPI essaie ses routes d'abord, Django reçoit le reste.

L'ordre compte. Django doit être configuré avant que le moindre modèle soit importé, donc django.setup() s'exécute tout en haut du module, avant les imports du jeu :

PYTHON
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "config.settings")
# Les modèles doivent être importables avant les routes.
django.setup()

from django.conf import settings
from fastapi import FastAPI
from config.asgi import application as django_application

Puis les routes sont déclarées, et le montage de Django vient en dernier. Starlette, sur lequel FastAPI repose, essaie les routes dans l'ordre où elles ont été déclarées : toute route du jeu passe avant Django.

PYTHON
app.include_router(game_api)  # /api/…
app.include_router(game_router)  # les pages
# … /health, puis /static hors développement
app.mount("/", AppendSlash(NotFoundPages(django_application)))

Côté Django, la configuration des URL ne contient plus qu'une ligne, path("admin/", admin.site.urls). Et les réglages de Django servent de configuration à toute l'application, FastAPI compris : une seule source pour la base, les secrets et les options.

03 Ce que les middlewares de Django ne font plus

Il y a un prix : une requête qui s'arrête dans FastAPI ne traverse jamais les middlewares de Django. Ni gestion des connexions, ni protection CSRF, ni session. Tout ce qui comptait a dû être refait à la main, en middlewares ASGI posés autour de toute l'application, Django compris.

Les connexions à la base

Django garde ses connexions ouvertes d'une requête à l'autre (CONN_MAX_AGE à 600 secondes, avec une vérification de santé). D'habitude, ce sont ses signaux de début et de fin de requête qui ferment une connexion trop vieille ou cassée. FastAPI ne les envoie pas : sans rien faire, une connexion coupée par la base ferait échouer toutes les requêtes suivantes du même worker. Un middleware refait donc ce travail :

PYTHON
class DatabaseConnectionsMiddleware:
    async def __call__(self, scope, receive, send) -> None:
        if scope["type"] != "http":
            await self.app(scope, receive, send)
            return
        await _check_old_connections(perf_counter())
        try:
            await self.app(scope, receive, send)
        finally:
            await _close_old_connections()

Subtilité : l'ORM asynchrone de Django exécute toutes ses requêtes SQL dans un seul thread dédié, et les connexions vivent dans ce thread. La vérification doit donc s'y faire aussi : elle passe par sync_to_async, comme l'ORM lui-même.

La protection CSRF

Les joueurs n'ont pas de compte : le navigateur s'identifie par un cookie HttpOnly portant son identifiant, et les clients natifs par un en-tête, X-Player-Id (qui gagne). Une requête qui modifie quelque chose, identifiée par le seul cookie, doit porter un Origin ou un Referer du site. Une page d'un autre site ne peut pas ajouter cet en-tête sans une requête préalable CORS que le jeu n'autorise jamais. Il reste à refuser les requêtes qui modifient quelque chose et viennent d'une autre origine, comme le fait le contrôle Origin de Django :

PYTHON
async def same_origin(request: Request) -> None:
    if request.method not in UNSAFE_METHODS:
        return
    source = request.headers.get("origin") or request.headers.get("referer")
    if source is not None and urlsplit(source).netloc != request.headers.get("host"):
        raise APIError(
            status.HTTP_403_FORBIDDEN, ErrorCode.ORIGIN_REFUSED, "Request origin refused."
        )

Un navigateur envoie toujours Origin sur une requête POST venue d'un autre site. Une requête sans Origin ni Referer vient donc d'un client qui n'est pas un navigateur, comme curl : le CSRF ne la concerne pas, elle passe.

La session de l'admin

L'admin de Django a ses sessions et son authentification, qui continuent de marcher pour /admin/. Mais certaines pages du jeu doivent savoir si la personne connectée est de l'équipe, par exemple pour « voir le jeu comme » un joueur, en lecture seule. FastAPI lit alors le cookie de session de l'admin lui-même, comme le ferait Django, avec les API asynchrones des sessions et de l'ORM.

La barre oblique finale

Les pages sont déclarées avec une barre oblique finale, à la manière de Django. AppendSlash enveloppe le montage de Django : pour un GET sans barre finale, il regarde si une route FastAPI correspondrait avec la barre, et répond alors par une redirection permanente.

PYTHON
probe = {**scope, "path": f"{path}/"}
for route in scope["app"].router.routes:
    if not isinstance(route, Mount) and route.matches(probe)[0] == Match.FULL:
        return f"{path}/"

Il ignore l'API, les chemins qui ressemblent à un fichier, et ceux qui commencent par //, pour ne jamais servir de redirection ouverte vers un autre site.

La page 404

Un chemin que personne ne connaît finit chez Django, qui répond par sa propre page 404. NotFoundPages intercepte la réponse au niveau ASGI : dès que Django commence à envoyer un statut 404, il envoie à la place la page 404 du jeu.

PYTHON
async def send_or_replace(message: Message) -> None:
    nonlocal replaced
    if message["type"] == "http.response.start" and message["status"] == 404:
        replaced = True
        await not_found_page(Request(scope, receive))(scope, receive, send)
    elif not replaced:
        await send(message)

L'API, l'admin et les fichiers statiques gardent leurs propres réponses. La page d'erreur 500, elle, ne touche pas à la base : elle doit pouvoir s'afficher quand c'est justement la base qui est en panne.

04 Un ORM synchrone dans un monde asynchrone

Les routes et la logique du jeu appellent l'ORM de Django avec ses méthodes asynchrones : aget, afirst, acreate, async for… Une seule règle, mais stricte : aucun accès synchrone dans ce code. Un objet.station qui déclencherait une requête en douce lève SynchronousOnlyOperation. Les relations sont donc chargées à l'avance, avec select_related et prefetch_related.

Les gabarits ne voient jamais un modèle Django. Les données passent d'abord dans des modèles Pydantic, construits une fois les objets chargés : un gabarit ne reçoit que des données simples et typées, et ne peut pas déclencher de requête par accident.

Les transactions sont le seul endroit où le code redevient synchrone : une fonction ordinaire, avec transaction.atomic(), appelée à travers sync_to_async, pour que toutes ses requêtes passent dans le même thread et la même transaction.

Ce thread unique a une conséquence mesurable : un worker occupé met en file ses appels à la base. Chaque requête l'écrit dans les journaux :

TEXT
GET /articles/ 200 app=3.4ms db=1.2ms/2 dbwait=0.1ms dbcheck=0.0ms

app est le temps total, db le temps SQL et le nombre de requêtes, dbwait le temps passé à attendre ce thread, dbcheck celui de la vérification des connexions. Le temps SQL est mesuré par un crochet de Django sur chaque connexion, et une variable de contexte le transporte jusqu'au middleware. Aucune adresse, aucun identifiant de joueur ni paramètre d'URL n'y figure.

05 Les gabarits et les URL

Les pages sont rendues par un environnement Jinja2 unique, mais qui emprunte à Django ce qu'il fait bien : static() donne le nom versionné d'un fichier (stationdoku.3f9a1c2b7e4d.css), et le filtre date formate les dates comme Django. Les liens, eux, viennent de FastAPI :

PYTHON
@pass_context
def url(context: dict[str, Any], name: str, /, **path_params: object) -> str:
    request: Request = context["request"]
    return str(request.app.url_path_for(name, **path_params))

Un gabarit écrit url('game:articles') et ne contient jamais d'adresse en dur. Le moteur de gabarits de Django ne sert plus qu'à l'admin.

06 Les erreurs, en deux langues

Une erreur de l'API a deux parties : un message en anglais pour les développeurs, et un code stable, grid_not_found ou origin_refused. Le navigateur ne montre jamais le message : il traduit le code en français. Une même exception, APIError, donne du JSON pour l'API et la page 404 du jeu pour une page.

07 Un schéma, des types partout

FastAPI décrit toute l'API en OpenAPI. Ce schéma est transformé en types TypeScript, et le front n'appelle l'API qu'à travers eux : le corps de la requête et la forme de la réponse sont vérifiés à la compilation, à partir de l'adresse et de la méthode. La CI régénère les types à chaque modification et échoue s'ils ne correspondent plus au code Python. Un champ renommé côté serveur casse donc la compilation du front, pas le jeu en production.

Côté Python, mypy tourne en mode strict avec les types de Django. Une seule annotation d'exception reste dans le montage : Django et Starlette décrivent la requête ASGI avec deux types différents pour le même protocole.

08 Les tests

Les tests ne lancent pas de serveur : un client HTTP parle directement à l'application ASGI complète, FastAPI et Django ensemble, sur un vrai PostgreSQL.

PYTHON
async with httpx.AsyncClient(
    transport=httpx.ASGITransport(app=app),
    base_url=BASE_URL,
    headers={"Origin": BASE_URL, **headers},
) as client:
    response = await client.post("/api/players")
    client.headers["X-Player-Id"] = response.json()["id"]

Ils passent par les mêmes middlewares, le même contrôle d'origine et le même montage que la production.

09 En production

  • uvicorn sert l'application, avec plusieurs workers, chacun avec sa connexion à la base. Pas de gunicorn devant.
  • Les fichiers statiques sont collectés par Django à la construction de l'image, avec un hachage dans leur nom, puis servis par Starlette avec un cache d'un an : un fichier modifié change de nom.
  • Les migrations passent avant le démarrage de la nouvelle version, pendant que l'ancienne sert encore : chaque migration doit marcher avec la version précédente.
  • Le déploiement est bleu-vert : la nouvelle version démarre à côté de l'ancienne, Caddy ne bascule le trafic qu'une fois sa route /health en bonne santé, puis l'ancienne s'arrête.

10 Le bilan

Ce montage garde le meilleur de chaque côté : l'admin et l'ORM de Django sans en écrire une ligne, la rapidité et la rigueur de FastAPI pour tout ce que voient les joueurs. Le prix, c'est une poignée de middlewares qui refont ce que Django faisait seul, chacun petit, commenté et testé. Et une règle à ne jamais oublier : dans ce code, tout appel à la base s'attend avec await.