Docs/Python API e erros

Exceções e erros

Uma solicitação pode falhar em quatro lugares e o Nexy responde a cada um de maneira diferente. Esta página é o índice: encontre o status que você vê, depois a linha que o produziu e depois o arquivo que decide o corpo.

A versão curta

Um cliente API é uma solicitação cujo cabeçalho Accept pede JSON e não uma página:

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

De onde vem uma falha

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

Saia de qualquer lugar

redirect, permanentRedirect, notFound, forbidden e unauthorized levantam uma exceção HTTP, então a mesma chamada funciona em uma página .nexy, um manipulador de API, um controlador modular, um guarda, um dependencies.py e uma ação.

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

Construa o destino a partir de valores em que você confia. redirect(request.query_params["next"]) envia visitantes para onde quer que o link indique; é um redirecionamento aberto. Um destino que contém uma quebra de linha é recusado.

Validação: 422 ou 404

Os parâmetros do manipulador são validados por FastAPI em relação às suas anotações.

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}

O corpo do 422 é o formato padrão do FastAPI, então os clientes e SDKs gerados continuam funcionando:

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

Para um formulário ou ação, o cliente recebe um ActionError com status e detail; um 422 também preenche error.fields com uma mensagem por campo. Consulte Ações.

Páginas de erro personalizadas

<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>

Exceções não tratadas

Uma exceção que nada capturado é registrado uma vez, com sua referência, de onde veio e o código ao seu redor. O status é 500 e o corpo depende do meio ambiente.

  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}

A referência são oito caracteres, novos para cada falha. Um visitante pode citá-lo e você encontrará o rastreamento pesquisando-o no log. Nem a exceção nem o código chegam ao visitante em produção.

Ações e formulários

Uma ação é um endpoint POST com um caminho gerado. Suas falhas seguem as mesmas regras:

Um formulário sem JavaScript postagens no caminho da ação; um sucesso responde 303 de volta à página, uma falha mostra a página de erro. Consulte Ações.

Uma lista de verificação quando uma página responde à coisa errada

1. Observe o status, não a página. Um notfound.nexy personalizado ainda responde 404.
2. Leia o terminal. Uma página que falha na importação não é registrada, então sua URL responde 404 enquanto o arquivo existir. O erro de importação está no log.
3. Verifique a extensão. Com useCSR = True, .nexy as páginas pertencem ao modo servidor; uma página no modo errado não é uma rota.
4. Verifique a profundidade. Um notfound.nexy ou errors.nexy só funciona quando a cópia raiz existe.
5. Peça JSON com Accept: application/json para ver a forma que seu cliente API recebe.
6. Cite a referência de um 500 ao abrir um problema ou pesquisar no log.

Próximas etapas

• Páginas de erro: o comportamento da página inteira, com exemplos
• Validação e erros: manipuladores de API
• Solução de problemas: os erros que as pessoas realmente encontraram
• Testando: afirmar um status e um corpo

Copiar a página como Markdown Editar no GitHub