Docs/Python API et erreurs

Exceptions et erreurs

Une demande peut échouer à quatre endroits, et Nexy répond à chacun différemment. Cette page est l'index : recherchez le statut que vous voyez, puis la ligne qui l'a produit, puis le fichier qui décide du corps.

La version courte

Un client API est une requête dont l'entête Accept demande du JSON et non une page :

curl -H "Accept: application/json" http://localhost:3000/api/items/500# {"detail":"Out of range"}

D'où vient un échec

Browser ──► Middleware ──► Router ──► Page or handler
                 │            │             │
                 │            │             ├─ return ───────────► 200
                 │            │             ├─ HTTPException ────► its status
                 │            │             └─ other exception ───► 500
                 │            └─ no match ────────────────────────► 404
                 └─ raises ──────────────────────────────────────► 500

Partez de n'importe où

redirect, permanentRedirect, notFound, forbidden et unauthorized déclenchent une exception HTTP, donc le même appel fonctionne dans une page .nexy, un gestionnaire d'API, un contrôleur modulaire, un garde, un dependencies.py et une action.

from nexy import notFound, redirect from src.posts import find  async def GET(slug: str):    post = find(slug)    if post is None:        notFound("No such post")    if post.moved_to:        redirect(post.moved_to)    return post

from nexy import notFound, redirectfrom nexy.decorators import Controller from src.posts import find  @Controller("/posts/{slug}")class PostsBySlugController:    async def get(self, slug: str):        post = find(slug)        if post is None:            notFound("No such post")        if post.moved_to:            redirect(post.moved_to)        return post

Construisez la destination à partir de valeurs auxquelles vous faites confiance. redirect(request.query_params["next"]) envoie les visiteurs là où le lien l'indique ; c'est une redirection ouverte. Une destination qui contient un saut de ligne est refusée.

Validation : 422 ou 404

Les paramètres du gestionnaire sont validés par FastAPI par rapport à leurs annotations.

from nexy.http import Header  async def GET(q: str, limit: int = 10, x_token: str = Header(...)):    return {"q": q, "limit": limit}

from nexy.decorators import Controllerfrom nexy.http import Header  @Controller("/api/search")class SearchApiController:    async def get(self, q: str, limit: int = 10, x_token: str = Header(...)):        return {"q": q, "limit": limit}

Le corps de 422 est la forme standard de FastAPI, donc les clients et les SDK générés continuent de fonctionner :

{"detail": [{"loc": ["query", "q"], "msg": "Field required", "type": "missing"}]}

Pour un formulaire ou une action, le client reçoit un ActionError avec status et detail ; un 422 remplit également error.fields avec un message par champ. Voir Actions.

Pages d'erreur personnalisées

<h1>Page not found</h1><p>The link may be old. <a href="/">Start from the home page</a>.</p>

<h1>Something went wrong</h1><p>Try again in a moment.</p>

Exceptions non gérées

Une exception qui n'a rien détecté est enregistrée une seule fois, avec sa référence, son origine et le code qui l'entoure. Le statut est 500, et le corps dépend de l'environnement.

  x ZeroDivisionError: division by zero  GET /boom  ref fe6a5217    at src/routes/boom.py:2 in GET       1 | def GET():       2 |     return {"a": 1 / 0}

La référence est de huit caractères, nouveaux à chaque échec. Un visiteur peut le citer et vous trouvez le traçage en le recherchant dans le journal. Ni l'exception ni le code n'atteignent le visiteur en production.

Actions et formulaires

Une action est un point de terminaison POST avec un chemin généré. Ses échecs suivent les mêmes règles :

Un formulaire sans JavaScript publié dans le chemin d'action ; un succès répond 303 retour à la page, un échec affiche la page d'erreur. Voir Actions.

Une liste de contrôle lorsqu'une page répond à la mauvaise chose

1. Regardez le statut, pas la page. Un notfound.nexy personnalisé répond toujours à 404.
2. Lisez le terminal. Une page dont l'importation échoue n'est pas enregistrée, donc son URL répond 404 tant que le fichier existe. L'erreur d'importation est dans le journal.
3. Vérifiez l'extension. Avec useCSR = True, les pages .nexy appartiennent au mode serveur ; une page dans le mauvais mode n'est pas un itinéraire.
4. Vérifiez la profondeur. Un notfound.nexy ou errors.nexy ne fonctionne que lorsque la copie racine existe.
5. Demandez JSON avec Accept: application/json pour voir la forme que reçoit votre client API.
6. Citez la référence d'un 500 lorsque vous ouvrez un problème ou effectuez une recherche dans le journal.

Prochaines étapes

• Pages d'erreur : le comportement de la page entière, avec des exemples
• Validation et erreurs : gestionnaires d'API
• Dépannage : les erreurs que les gens rencontrent réellement
• Tester : affirmer un statut et un corps

Copier la page en Markdown Modifier sur GitHub