Skip to content

FastAPI Folha de referência

Framework web Python moderno e rápido para construir APIs.

01

Primeiros passos

Primeira API

O FastAPI é construído sobre Starlette e Pydantic. O uvicorn é o servidor ASGI. --reload habilita o recarregamento automático durante o desenvolvimento.

fastapi
# install FastAPI and uvicorn
pip install fastapi uvicorn

# main.py
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def read_root():
    return {"Hello": "World"}

# run: uvicorn main:app --reload

Rodando com Uvicorn

A instância 'main:app' significa módulo 'main', variável 'app'. Use --reload apenas no desenvolvimento; em produção rode sem ele e use um gerenciador de processos.

fastapi
# development with auto-reload
uvicorn main:app --reload

# specify host and port
uvicorn main:app --host 0.0.0.0 --port 8000

# run programmatically
import uvicorn
if __name__ == "__main__":
    uvicorn.run("main:app", host="127.0.0.1", port=8000, reload=True)

Operações de rota assíncronas

Você pode declarar operações de rota com 'def' (roda em threadpool) ou 'async def'. Use async def quando a função faz I/O via bibliotecas assíncronas; misturar chamadas bloqueantes em async def vai travar o event loop.

fastapi
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def read_root():
    return {"message": "hello"}

@app.get("/sync")
def read_sync():
    return {"message": "sync also works"}

# use async when calling async libs (httpx, databases)
@app.get("/data")
async def fetch_data():
    import httpx
    async with httpx.AsyncClient() as client:
        r = await client.get("https://api.example.com")
    return r.json()

Decorators de operações de rota

O FastAPI suporta os verbos HTTP: GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD. Cada um mapeia para um decorator. Use status_code= no decorator para sobrescrever o status de sucesso padrão.

fastapi
from fastapi import FastAPI

app = FastAPI()

@app.get("/items")
def list_items(): ...

@app.post("/items")
def create_item(): ...

@app.put("/items/{item_id}")
def replace_item(item_id: int): ...

@app.patch("/items/{item_id}")
def update_item(item_id: int): ...

@app.delete("/items/{item_id}")
def delete_item(item_id: int): ...

@app.options("/items")
def options_items(): ...

@app.head("/items")
def head_items(): ...

Resposta JSON e status

Retornar um dict/list é convertido automaticamente para JSON com 200 (ou seu status_code). Para controle total sobre status, headers ou conteúdo, retorne um JSONResponse ou Response diretamente.

fastapi
from fastapi import FastAPI, status
from fastapi.responses import JSONResponse

app = FastAPI()

@app.get("/plain")
def plain():
    return {"key": "value"}  # auto JSON, 200 OK

@app.post("/created", status_code=status.HTTP_201_CREATED)
def created():
    return {"id": 1}

@app.get("/custom")
def custom():
    return JSONResponse(
        status_code=418,
        content={"error": "I'm a teapot"},
        headers={"X-Custom": "yes"},
    )

Estrutura do projeto

Divida uma aplicação que cresce em módulos com APIRouter e registre-os via app.include_router(). Mantenha os schemas Pydantic, a configuração do DB e as dependências em arquivos separados para facilitar a manutenção.

fastapi
myapp/
  main.py              # creates the FastAPI app
  routers/
    users.py           # APIRouter for /users
    items.py           # APIRouter for /items
  models/
    schemas.py         # Pydantic models
    database.py        # DB engine & session
  dependencies.py      # shared Depends functions
  tests/
    test_main.py

# main.py
from fastapi import FastAPI
from routers import users, items
app = FastAPI()
app.include_router(users.router)
app.include_router(items.router, prefix="/items")
02

Parâmetros de path

Parâmetros de path básicos

Valores capturados do path são strings, a menos que você adicione uma anotação de tipo. O nome do parâmetro no path deve corresponder exatamente ao nome do argumento da função.

fastapi
from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
def read_item(item_id):
    return {"item_id": item_id}

# GET /items/42 -> {"item_id": "42"}  (string by default)

Conversão de tipos

Adicionar uma anotação de tipo (int, float, bool, str, Enum) faz o FastAPI validar e converter o valor do path. Valores inválidos retornam uma resposta 422 com mensagem de erro clara.

fastapi
from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
def read_item(item_id: int):
    return {"item_id": item_id}

# GET /items/3   -> {"item_id": 3}
# GET /items/abc -> 422 Validation Error (not an integer)

Validação de path

Path() adiciona metadados e restrições a um parâmetro de path. Restrições numéricas: ge (>=), gt (>), le (<=), lt (<). Parâmetros de path são sempre obrigatórios, então Path() não pode definir um default.

fastapi
from fastapi import FastAPI, Path

app = FastAPI()

@app.get("/items/{item_id}")
def read_item(
    item_id: int = Path(
        title="The ID of the item",
        description="Must be a positive integer",
        ge=1,
        le=1000,
    ),
):
    return {"item_id": item_id}

Restrições numéricas

Use ge/gt/le/lt em parâmetros de path int ou float para impor faixas numéricas. Restrições combinadas dão validação precisa de limites com erros 422 automáticos.

fastapi
from fastapi import FastAPI, Path

app = FastAPI()

@app.get("/ratio/{value}")
def ratio(
    value: float = Path(gt=0, lt=1),  # 0 < value < 1
):
    return {"value": value}

@app.get("/page/{page}")
def page(
    page: int = Path(ge=1),       # >= 1
    size: int = Path(le=100),     # <= 100
):
    return {"page": page, "size": size}

A ordem das rotas importa

As rotas são casadas na ordem de declaração. Declare paths específicos como /users/me antes de padrões dinâmicos como /users/{user_id}, senão a rota dinâmica sombreará a específica.

fastapi
from fastapi import FastAPI

app = FastAPI()

@app.get("/users/me")
def read_current_user():
    return {"user": "me"}

@app.get("/users/{user_id}")
def read_user(user_id: str):
    return {"user_id": user_id}

# /users/me MUST be declared before /users/{user_id}
# otherwise 'me' would match the {user_id} pattern

Parâmetros de path com Enum

Usar um tipo Enum para um parâmetro de path o restringe a valores predefinidos e gera um schema enum na documentação OpenAPI. Herde de (str, Enum) para que os valores se serializem como strings.

fastapi
from enum import Enum
from fastapi import FastAPI

class ModelName(str, Enum):
    alexnet = "alexnet"
    resnet = "resnet"
    lenet = "lenet"

app = FastAPI()

@app.get("/models/{model_name}")
def get_model(model_name: ModelName):
    if model_name is ModelName.alexnet:
        return {"model": model_name, "layers": 5}
    return {"model": model_name}

# GET /models/resnet -> {"model": "resnet"}
03

Parâmetros de query

Parâmetros de query básicos

Parâmetros da função que NÃO estão no path viram parâmetros de query. Fornecer um default os torna opcionais; o default é usado quando a chave de query está ausente.

fastapi
from fastapi import FastAPI

app = FastAPI()

fake_items = [{"item": "a"}, {"item": "b"}, {"item": "c"}]

@app.get("/items")
def list_items(skip: int = 0, limit: int = 10):
    return fake_items[skip : skip + limit]

# GET /items?skip=0&limit=2
# GET /items                -> skip=0, limit=10

Parâmetros de query opcionais

Use Optional[str] = None (ou str | None = None no Python 3.10+) para um parâmetro de query que pode ser omitido. Parâmetros obrigatórios simplesmente não têm valor default.

fastapi
from typing import Optional
from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
def read_item(item_id: str, q: Optional[str] = None):
    if q:
        return {"item_id": item_id, "q": q}
    return {"item_id": item_id}

# GET /items/1?q=hello
# GET /items/1            (q is None)

Validação de query

Query() adiciona validação: min_length/max_length para strings, ge/gt/le/lt para números, pattern (regex) para formato de string. Use default= para definir um valor mantendo as restrições.

fastapi
from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/search")
def search(q: str = Query(min_length=3, max_length=50, pattern="^[a-zA-Z]+$")):
    return {"q": q}

@app.get("/page")
def page(limit: int = Query(default=10, ge=1, le=100)):
    return {"limit": limit}

Conversão de booleanos

Parâmetros de query booleanos aceitam vários valores truthy: true, 1, yes, on (sem diferenciar maiúsculas). Qualquer outra coisa é interpretada como false. Tipos inválidos como ?active=maybe retornam 422.

fastapi
from fastapi import FastAPI

app = FastAPI()

@app.get("/flags")
def flags(active: bool = False):
    return {"active": active}

# GET /flags?active=true   -> {"active": true}
# GET /flags?active=1      -> {"active": true}
# GET /flags?active=yes    -> {"active": true}
# GET /flags?active=off    -> {"active": false}

Parâmetros de query em lista

Um parâmetro List[str] aceita a mesma chave repetida na query string. Use Query(default=[]) para uma lista vazia por padrão, ou Query(default=None) para permitir valores ausentes.

fastapi
from typing import List
from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items")
def list_items(q: List[str] = Query(default=[])):
    return {"q": q}

# GET /items?q=a&q=b&q=c  -> {"q": ["a", "b", "c"]}
# declare default=None to accept a list or null

Parâmetros de query obrigatórios

Use Query(...) (o Ellipsis) para declarar um parâmetro de query obrigatório que ainda tem metadados de validação. Sem default e sem Query(...), um parâmetro anotado simples também é obrigatório.

fastapi
from fastapi import FastAPI, Query

app = FastAPI()

@app.get("/items")
def read_item(q: str = Query(...)):
    return {"q": q}

# GET /items?q=hello   -> ok
# GET /items           -> 422 (q is required)
# Query(...) (Ellipsis) marks a parameter as required
04

Corpo da requisição (Pydantic)

Básico do BaseModel

Um BaseModel do Pydantic declarado como parâmetro da função vira o corpo JSON da requisição. O FastAPI valida o payload, converte tipos e retorna 422 em dados inválidos. Campos com default são opcionais.

fastapi
from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    in_stock: bool = True

app = FastAPI()

@app.post("/items")
def create_item(item: Item):
    return item

# POST /items  body: {"name": "Apple", "price": 0.5}
# -> {"name": "Apple", "price": 0.5, "in_stock": true}

Tipos e restrições de campos

Field() adiciona restrições e metadados aos atributos do model: min_length/max_length para strings, gt/ge/lt/le para números, default_factory para defaults mutáveis. model_config com json_schema_extra adiciona exemplos à documentação.

fastapi
from pydantic import BaseModel, Field
from typing import Optional

class Item(BaseModel):
    name: str = Field(min_length=1, max_length=100)
    price: float = Field(gt=0, description="must be positive")
    tax: Optional[float] = None
    tags: list[str] = Field(default_factory=list)

    model_config = {
        "json_schema_extra": {
            "examples": [{"name": "Apple", "price": 0.5, "tags": ["fruit"]}]
        }
    }

Models aninhados

Models podem ser aninhados: declare outro BaseModel como tipo de campo. O FastAPI valida toda a estrutura aninhada recursivamente, e o schema OpenAPI gerado reflete os objetos aninhados.

fastapi
from pydantic import BaseModel
from typing import Optional

class Image(BaseModel):
    url: str
    name: str

class Item(BaseModel):
    name: str
    description: Optional[str] = None
    image: Optional[Image] = None
    images: list[Image] = []

# valid body:
# {"name": "Phone", "image": {"url": "http://x/a.png", "name": "a"}}

Validação de campos

Use @field_validator (Pydantic v2) para adicionar lógica de validação personalizada por campo. Lance ValueError para rejeitar a entrada (o FastAPI a expõe como 422). Retorne o valor (possivelmente transformado) para mantê-lo.

fastapi
from pydantic import BaseModel, field_validator

class User(BaseModel):
    name: str
    email: str

    @field_validator("email")
    @classmethod
    def email_must_contain_at(cls, v: str) -> str:
        if "@" not in v:
            raise ValueError("must contain @")
        return v.lower()

    @field_validator("name")
    @classmethod
    def name_stripped(cls, v: str) -> str:
        return v.strip()

Campos opcionais e com default

Um campo é obrigatório só se não tem default e não é Optional. Optional[str] = None é o padrão para um campo opcional anulável; um default simples como 0.0 torna o campo opcional com aquele valor.

fastapi
from pydantic import BaseModel
from typing import Optional

class Item(BaseModel):
    name: str                       # required
    description: Optional[str] = None  # optional, defaults to None
    price: float = 0.0              # optional, defaults to 0.0
    tags: list[str] = []            # optional, defaults to empty list

# All of these are valid:
# {"name": "X"}
# {"name": "X", "price": 9.99, "tags": ["a"]}

Body com path e query

Parâmetros de path, query e body podem coexistir numa mesma operação. O FastAPI decide assim: parâmetro de path se está no path, model Pydantic (ou Body()) para o body, caso contrário query. Body opcional precisa de default None.

fastapi
from fastapi import FastAPI, Path, Query
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float

app = FastAPI()

@app.put("/items/{item_id}")
def update_item(
    item_id: int = Path(ge=1),
    q: Optional[str] = Query(default=None),
    item: Item = None,
):
    result = {"item_id": item_id, **item.model_dump()}
    if q:
        result["q"] = q
    return result
05

Response model

Básico do response_model

response_model filtra os dados retornados para apenas os campos definidos no model, mesmo que você retorne um objeto com campos extras. É a forma padrão de esconder campos sensíveis como senhas.

fastapi
from fastapi import FastAPI
from pydantic import BaseModel

class User(BaseModel):
    username: str
    email: str
    hashed_password: str

class UserOut(BaseModel):
    username: str
    email: str

app = FastAPI()

@app.get("/users/me", response_model=UserOut)
def read_user():
    return User(username="bob", email="[email protected]", hashed_password="secret")

# response: {"username": "bob", "email": "[email protected]"}  (no password)

Excluir campos

response_model_include e response_model_exclude permitem whitelist ou blacklist de campos por rota sem definir novos models. Passe um conjunto de nomes de campos. Aplicam-se além do response_model.

fastapi
from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float
    secret: str

app = FastAPI()

@app.get("/items/{id}", response_model=Item, response_model_exclude={"secret"})
def read_item(id: int):
    return {"name": "Apple", "price": 0.5, "secret": "hidden"}

@app.get("/items", response_model=list[Item], response_model_include={"name", "price"})
def list_items():
    return [{"name": "Apple", "price": 0.5, "secret": "x"}]

Resposta em lista

Use response_model=list[Model] (ou List[Model]) para declarar que um endpoint retorna um array de objetos. O FastAPI valida e serializa cada item da lista.

fastapi
from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float

app = FastAPI()

@app.get("/items", response_model=list[Item])
def list_items():
    return [
        {"name": "Apple", "price": 0.5},
        {"name": "Banana", "price": 0.3},
    ]

# response: [{"name": "Apple", "price": 0.5}, {"name": "Banana", "price": 0.3}]

Excluir unset/defaults

exclude_unset omite campos que o cliente nunca enviou (só aparecem os definidos explicitamente). exclude_defaults omite campos iguais aos defaults; exclude_none omite campos None. Útil para respostas esparsas.

fastapi
from fastapi import FastAPI
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    description: str | None = None
    price: float = 0.0
    tax: float = 0.0

app = FastAPI()

@app.get("/items/{id}", response_model=Item, response_model_exclude_unset=True)
def read_item(id: int):
    return {"name": "Apple", "price": 0.5}
# -> {"name": "Apple", "price": 0.5}   (description, tax omitted)

# also: response_model_exclude_defaults=True
#       response_model_exclude_none=True

Resposta por alias

Field(alias=...) permite que o JSON de entrada use um nome de chave diferente do atributo Python. response_model_by_alias=True também gera a saída usando o alias. populate_by_name=True também aceita o nome original do atributo na entrada.

fastapi
from fastapi import FastAPI
from pydantic import BaseModel, ConfigDict, Field

class Item(BaseModel):
    model_config = ConfigDict(populate_by_name=True)
    name: str = Field(alias="itemName")
    price: float

app = FastAPI()

@app.post("/items", response_model=Item, response_model_by_alias=True)
def create(item: Item):
    return item

# input:  {"itemName": "Apple", "price": 0.5}
# output: {"itemName": "Apple", "price": 0.5}

Resposta dict simples

Retornar um dict/list serializa automaticamente para JSON. Use response_class para mudar o tipo de resposta padrão (HTMLResponse, PlainTextResponse), ou retorne uma subclasse de Response diretamente para controle total.

fastapi
from fastapi import FastAPI
from fastapi.responses import JSONResponse, PlainTextResponse

app = FastAPI()

@app.get("/dict")
def dict_resp():
    return {"a": 1, "b": 2}      # auto JSON

@app.get("/text", response_class=PlainTextResponse)
def text_resp():
    return "plain text response"

@app.get("/raw")
def raw_resp():
    return JSONResponse(content={"a": 1}, status_code=200)
06

Form e UploadFile

Dados de formulário

Form() declara um parâmetro lido de application/x-www-form-urlencoded ou dados de formulário multipart. Não é possível misturar Form() com um corpo JSON (BaseModel) na mesma operação — escolha um tipo de conteúdo.

fastapi
from fastapi import FastAPI, Form

app = FastAPI()

@app.post("/login")
def login(username: str = Form(), password: str = Form()):
    return {"username": username}

# Content-Type: application/x-www-form-urlencoded
# body: username=bob&password=secret

UploadFile básico

UploadFile é uma representação de arquivo em streaming com .filename, .content_type, .read(), .write(), .close(). Use 'await file.read()' dentro de async def. Para arquivos grandes, prefira file.file (SpooledTemporaryFile) para não carregar tudo na memória.

fastapi
from fastapi import FastAPI, UploadFile, File

app = FastAPI()

@app.post("/upload")
async def upload_file(file: UploadFile = File(...)):
    contents = await file.read()
    return {
        "filename": file.filename,
        "size": len(contents),
        "content_type": file.content_type,
    }

Múltiplos arquivos

Declare list[UploadFile] para aceitar vários arquivos numa única requisição. Cada arquivo é enviado com o mesmo nome de campo. A ordem dos arquivos na lista corresponde à ordem em que foram enviados.

fastapi
from fastapi import FastAPI, UploadFile

app = FastAPI()

@app.post("/uploads")
async def upload_many(files: list[UploadFile]):
    return [
        {"filename": f.filename, "size": len(await f.read())}
        for f in files
    ]

# curl: curl -F "[email protected]" -F "[email protected]" http://localhost:8000/uploads

Arquivo e form juntos

Form() e UploadFile (File()) podem ser combinados no mesmo endpoint porque ambos usam multipart/form-data. Você ainda não pode combiná-los com um corpo BaseModel JSON.

fastapi
from fastapi import FastAPI, UploadFile, File, Form

app = FastAPI()

@app.post("/items")
async def create_item(
    name: str = Form(),
    description: str = Form(),
    file: UploadFile = File(),
):
    return {
        "name": name,
        "description": description,
        "file": file.filename,
    }

Salvando o arquivo enviado

Para arquivos pequenos, shutil.copyfileobj transfere o SpooledTemporaryFile para o disco com eficiência. Para arquivos muito grandes, leia em blocos (por exemplo, 1MB) para manter a memória baixa. Sempre sanitize file.filename para evitar path traversal.

fastapi
import shutil
from pathlib import Path
from fastapi import FastAPI, UploadFile

app = FastAPI()

@app.post("/save")
async def save_file(file: UploadFile):
    dest = Path("uploads") / file.filename
    dest.parent.mkdir(exist_ok=True)
    with dest.open("wb") as buf:
        shutil.copyfileobj(file.file, buf)
    return {"saved_to": str(dest)}

# async alternative for large files:
# async with dest.open("wb") as buf:
#     while chunk := await file.read(1024 * 1024):
#         buf.write(chunk)

Metadados e tamanho do arquivo

Valide file.content_type e o tamanho antes de processar. Depois de read(), o cursor fica no fim; chame 'await file.seek(0)' para rebobinar se precisar ler de novo. A verificação real do tipo deve inspecionar magic bytes, não só o header.

fastapi
from fastapi import FastAPI, UploadFile, File

app = FastAPI()

@app.post("/validate")
async def validate(file: UploadFile = File(...)):
    # allowed types
    allowed = {"image/png", "image/jpeg"}
    if file.content_type not in allowed:
        return {"error": "unsupported type"}

    contents = await file.read()
    max_size = 5 * 1024 * 1024  # 5 MB
    if len(contents) > max_size:
        return {"error": "file too large"}

    await file.seek(0)  # rewind so later reads work
    return {"filename": file.filename, "size": len(contents)}
07

Headers e cookies

Parâmetros de header

Header() declara um parâmetro lido dos headers da requisição. O FastAPI converte underscores em nomes Python para hífens (x_token -> X-Token). Defina convert_underscores=False para desabilitar esse comportamento.

fastapi
from fastapi import FastAPI, Header

app = FastAPI()

@app.get("/items")
def read_items(user_agent: str | None = Header(default=None)):
    return {"User-Agent": user_agent}

# Header names are case-insensitive; an underscore in the
# parameter (x_token) is converted to a hyphen (X-Token) automatically.
@app.get("/secure")
def secure(x_token: str = Header()):
    return {"x-token": x_token}

Parâmetros de cookie

Cookie() lê um valor do header Cookie da requisição. Como os parâmetros de query, cookies sem default são obrigatórios, e você pode aplicar validação (min_length, max_length, etc.).

fastapi
from fastapi import FastAPI, Cookie

app = FastAPI()

@app.get("/session")
def read_session(session_id: str | None = Cookie(default=None)):
    if session_id:
        return {"session_id": session_id}
    return {"message": "no session"}

# Reads the 'session_id' cookie from the Cookie header.

Definindo cookie na resposta

Injete um Response e chame set_cookie() para escrever cookies na resposta de saída. Use httponly=True (bloqueia acesso do JS), secure=True (só HTTPS) e samesite='lax'/'strict' para mitigar CSRF. O corpo da resposta ainda é retornado normalmente.

fastapi
from fastapi import FastAPI, Response

app = FastAPI()

@app.post("/login")
def login(response: Response):
    response.set_cookie(
        key="session_id",
        value="abc123",
        httponly=True,
        max_age=1800,
        secure=True,
        samesite="lax",
    )
    return {"message": "logged in"}

@app.post("/logout")
def logout(response: Response):
    response.delete_cookie("session_id")
    return {"message": "logged out"}

Headers de resposta personalizados

Defina headers num Response injetado para adicioná-los à resposta JSON que o FastAPI constrói, ou passe headers= ao retornar uma subclasse de Response diretamente. Headers personalizados são comuns para info de rate-limit e tempo de processamento.

fastapi
from fastapi import FastAPI, Response
from fastapi.responses import JSONResponse

app = FastAPI()

@app.get("/data")
def get_data(response: Response):
    response.headers["X-Process-Time"] = "0.05"
    response.headers["X-Custom-Header"] = "hello"
    return {"data": 1}

@app.get("/direct")
def direct():
    return JSONResponse(
        content={"data": 1},
        headers={"X-Source": "direct"},
    )

Headers padrão

Headers comuns como Host, Accept, Authorization, If-None-Match são acessíveis via Header(). Para Authorization, prefira os utilitários de segurança embutidos (HTTPBearer, OAuth2), que fazem o parse e a documentação OpenAPI para você.

fastapi
from fastapi import FastAPI, Header

app = FastAPI()

@app.get("/info")
def info(
    host: str | None = Header(default=None),
    accept: str | None = Header(default=None),
    authorization: str | None = Header(default=None),
    if_none_match: str | None = Header(default=None),
):
    return {"host": host, "accept": accept}

Valores de header duplicados

Declarar um tipo de lista para um parâmetro Header coleta os valores repetidos do header numa lista. Útil para headers como Set-Cookie (resposta) ou qualquer header personalizado que pode aparecer várias vezes.

fastapi
from fastapi import FastAPI, Header

app = FastAPI()

@app.get("/multi")
def multi(x_token: list[str] | None = Header(default=None)):
    return {"x_token": x_token}

# Request with:
#   X-Token: a
#   X-Token: b
# -> {"x_token": ["a", "b"]}
08

Injeção de dependência

Depends básico

Depends() injeta o valor de retorno de uma função na sua operação de rota. Lógica compartilhada (paginação, parsing, sessões de DB) fica num só lugar e é reutilizada nos endpoints. Os parâmetros da dependência também são documentados no OpenAPI.

fastapi
from fastapi import FastAPI, Depends

app = FastAPI()

def common_params(q: str | None = None, skip: int = 0, limit: int = 10):
    return {"q": q, "skip": skip, "limit": limit}

@app.get("/items")
def list_items(commons: dict = Depends(common_params)):
    return commons

@app.get("/users")
def list_users(commons: dict = Depends(common_params)):
    return commons

Dependências de classe

Uma classe com __init__ pode ser uma dependência; o FastAPI a chama como uma função. Use Depends(CommonQueryParams) ou a forma abreviada Depends() quando o parâmetro está anotado com a classe. A instância é injetada.

fastapi
from fastapi import FastAPI, Depends

class CommonQueryParams:
    def __init__(self, q: str | None = None, skip: int = 0, limit: int = 10):
        self.q = q
        self.skip = skip
        self.limit = limit

app = FastAPI()

@app.get("/items")
def list_items(commons: CommonQueryParams = Depends(CommonQueryParams)):
    return {"q": commons.q, "skip": commons.skip, "limit": commons.limit}

# shorthand: commons = Depends() infers the type

Dependências aninhadas

Dependências podem depender de outras dependências, formando um grafo. O FastAPI resolve a árvore inteira, faz cache de cada resultado por requisição e propaga exceções. Ideal para autenticação em camadas (token -> user -> permissions).

fastapi
from fastapi import FastAPI, Depends, Header, HTTPException

def get_token(authorization: str = Header()):
    if not authorization.startswith("Bearer "):
        raise HTTPException(status_code=401, detail="invalid header")
    return authorization.removeprefix("Bearer ")

def get_current_user(token: str = Depends(get_token)):
    if token != "admin-token":
        raise HTTPException(status_code=403, detail="forbidden")
    return {"username": "admin"}

app = FastAPI()

@app.get("/me")
def me(user: dict = Depends(get_current_user)):
    return user

Dependências com yield (limpeza)

Um generator com yield é perfeito para recursos que precisam de limpeza: sessões de DB, handles de arquivos, transações. O código após o yield roda como finalizador, mesmo que a rota lance exceção. Só um yield por dependência.

fastapi
from fastapi import FastAPI, Depends

def get_db():
    db = open_db_session()       # acquire resource
    try:
        yield db                 # injected into the route
    finally:
        db.close()               # always runs after the request

app = FastAPI()

@app.get("/items")
def list_items(db = Depends(get_db)):
    return db.query("SELECT * FROM items")

Dependências globais

Passe dependencies=[...] ao FastAPI() (ou a um APIRouter) para aplicá-las a todas as rotas sem injetar o valor de retorno. Útil para auth global, rate limiting ou logging de requisições.

fastapi
from fastapi import FastAPI, Depends, Header, HTTPException

def verify_token(x_token: str = Header()):
    if x_token != "supersecret":
        raise HTTPException(status_code=400, detail="X-Token missing")

def verify_key(x_key: str = Header()):
    if x_key != "realkey":
        raise HTTPException(status_code=400, detail="X-Key missing")

# applied to every route in the app
app = FastAPI(dependencies=[Depends(verify_token), Depends(verify_key)])

@app.get("/items")
def list_items():
    return [{"item": "a"}]   # token & key already checked

Dependências por rota

Use dependencies=[Depends(...)] num decorator (ou no APIRouter) para exigir uma dependência em rotas específicas sem usar o valor de retorno. Mantém as assinaturas das rotas limpas enquanto aplica as checagens.

fastapi
from fastapi import FastAPI, Depends, Header, HTTPException

def verify_token(x_token: str = Header()):
    if x_token != "secret":
        raise HTTPException(status_code=401, detail="bad token")

app = FastAPI()

@app.get("/public")
def public():
    return {"open": True}

@app.get("/private", dependencies=[Depends(verify_token)])
def private():
    return {"secret": "data"}
09

Segurança (HTTPBasic / OAuth2 / JWT)

HTTP Basic Auth

HTTPBasic interpreta o header Authorization: Basic em username/password. Use secrets.compare_digest (não ==) para evitar ataques de timing. Sempre retorne 401 com WWW-Authenticate: Basic para que os navegadores peçam credenciais.

fastapi
import secrets
from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import HTTPBasic, HTTPBasicCredentials

security = HTTPBasic()
app = FastAPI()

def get_current_user(credentials: HTTPBasicCredentials = Depends(security)):
    correct_user = secrets.compare_digest(credentials.username, "admin")
    correct_pass = secrets.compare_digest(credentials.password, "secret")
    if not (correct_user and correct_pass):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid credentials",
            headers={"WWW-Authenticate": "Basic"},
        )
    return credentials.username

@app.get("/profile")
def profile(user: str = Depends(get_current_user)):
    return {"user": user}

OAuth2 Password Bearer

OAuth2PasswordBearer declara que as rotas esperam um Bearer token; a dependência o extrai do header Authorization. tokenUrl informa à UI de docs onde enviar as credenciais. O token em si é só uma string até você validá-lo.

fastapi
from fastapi import FastAPI, Depends
from fastapi.security import OAuth2PasswordBearer

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
app = FastAPI()

@app.get("/me")
def me(token: str = Depends(oauth2_scheme)):
    return {"token": token}

# client POSTs username+password to /token, receives an access token,
# then sends it as: Authorization: Bearer <token>

Criando token JWT

Use python-jose (ou PyJWT) para assinar tokens. A claim 'sub' (subject) convencionalmente guarda o username ou o id do usuário, e 'exp' define a expiração. Mantenha o SECRET_KEY longo, aleatório e carregado do ambiente — nunca o commite.

fastapi
from datetime import datetime, timedelta, timezone
from jose import jwt

SECRET_KEY = "keep-this-secret"
ALGORITHM = "HS256"

def create_access_token(data: dict, expires_minutes: int = 30) -> str:
    to_encode = data.copy()
    expire = datetime.now(timezone.utc) + timedelta(minutes=expires_minutes)
    to_encode.update({"exp": expire})
    return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)

# token = create_access_token({"sub": "alice"})
# -> eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Decodificando token JWT

jwt.decode verifica a assinatura e a claim 'exp' automaticamente, lançando JWTError em caso de falha. Mapeie a dependência para um 401 com WWW-Authenticate: Bearer para que os clientes saibam que precisam fornecer um token válido.

fastapi
from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer
from jose import jwt, JWTError

oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")
SECRET_KEY = "keep-this-secret"
ALGORITHM = "HS256"

def get_current_user(token: str = Depends(oauth2_scheme)) -> str:
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
        username: str | None = payload.get("sub")
        if username is None:
            raise credentials_exception
        return username
    except JWTError:
        raise credentials_exception

credentials_exception = HTTPException(
    status_code=status.HTTP_401_UNAUTHORIZED,
    detail="Could not validate credentials",
    headers={"WWW-Authenticate": "Bearer"},
)

Hashing de senhas

Nunca armazene senhas em texto puro. passlib com bcrypt (ou argon2) cuida do salting e do hashing. verify() compara uma entrada em texto puro contra um hash armazenado. pip install passlib[bcrypt] para obter o backend bcrypt.

fastapi
from passlib.context import CryptContext

pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")

def hash_password(plain: str) -> str:
    return pwd_context.hash(plain)

def verify_password(plain: str, hashed: str) -> bool:
    return pwd_context.verify(plain, hashed)

# usage when issuing tokens:
def authenticate_user(username: str, password: str):
    user = fake_db.get(username)
    if not user or not verify_password(password, user.hashed_password):
        return False
    return user

Fluxo de login OAuth2

OAuth2PasswordRequestForm lê username/password de um POST codificado como form (o fluxo padrão OAuth2 password). Retorne access_token e token_type: 'bearer'. Esse endpoint é para onde tokenUrl no OAuth2PasswordBearer aponta.

fastapi
from fastapi import FastAPI, Depends, HTTPException, status
from fastapi.security import OAuth2PasswordRequestForm

app = FastAPI()

@app.post("/token")
def login(form: OAuth2PasswordRequestForm = Depends()):
    user = authenticate_user(form.username, form.password)
    if not user:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Incorrect username or password",
        )
    token = create_access_token({"sub": user.username})
    return {"access_token": token, "token_type": "bearer"}

# OAuth2PasswordRequestForm parses username+password from form data
# and powers the 'Authorize' button in the Swagger UI.
10

Middleware

Adicionando middleware

@app.middleware('http') registra uma função que envolve cada requisição. Ela deve fazer await em call_next(request) para obter a resposta, e então pode inspecioná-la ou modificá-la antes de retornar. O middleware roda para todas as rotas.

fastapi
import time
from fastapi import FastAPI, Request

app = FastAPI()

@app.middleware("http")
async def add_process_time(request: Request, call_next):
    start = time.perf_counter()
    response = await call_next(request)
    duration = time.perf_counter() - start
    response.headers["X-Process-Time"] = f"{duration:.4f}"
    return response

Middleware de header personalizado

O middleware é o lugar certo para anexar headers que devem estar em toda resposta (headers de segurança, banner do servidor, IDs de tracing). Modifique o objeto de resposta depois do await em call_next.

fastapi
from fastapi import FastAPI, Request

app = FastAPI()

@app.middleware("http")
async def add_banner(request: Request, call_next):
    response = await call_next(request)
    response.headers["X-Powered-By"] = "FastAPI"
    response.headers["X-Frame-Options"] = "DENY"
    return response

# every response now carries these headers

BaseHTTPMiddleware

Para middleware reutilizável e configurável, herde de BaseHTTPMiddleware e registre com app.add_middleware(MyMiddleware, **options). É assim que os middlewares embutidos CORS, GZip e TrustedHost são adicionados.

fastapi
from starlette.middleware.base import BaseHTTPMiddleware
from fastapi import FastAPI, Request

class TimingMiddleware(BaseHTTPMiddleware):
    async def dispatch(self, request: Request, call_next):
        start = time.perf_counter()
        response = await call_next(request)
        response.headers["X-Duration"] = str(time.perf_counter() - start)
        return response

app = FastAPI()
app.add_middleware(TimingMiddleware)

# class-based middleware is reusable and configurable

Redirecionamento HTTPS

HTTPSRedirectMiddleware retorna um redirecionamento 308 para a versão HTTPS de qualquer requisição HTTP. Use atrás de um balanceador que termina o TLS, para garantir que os clientes migrem para conexão segura.

fastapi
from fastapi import FastAPI
from fastapi.middleware.httpsredirect import HTTPSRedirectMiddleware

app = FastAPI()
app.add_middleware(HTTPSRedirectMiddleware)

# all HTTP requests are redirected to HTTPS (308)

Trusted Host

TrustedHostMiddleware rejeita requisições cujo header Host não está na allow-list, prevenindo ataques de Host-header injection. Curingas como '*.example.com' são suportados. Sempre inclua 'localhost' para desenvolvimento local.

fastapi
from fastapi import FastAPI
from fastapi.middleware.trustedhost import TrustedHostMiddleware

app = FastAPI()
app.add_middleware(
    TrustedHostMiddleware,
    allowed_hosts=["example.com", "*.example.com", "localhost"],
)

# requests with a disallowed Host header get a 400 response

Ordem do middleware

O Starlette executa o middleware em ordem LIFO para requisições de entrada: o último adicionado roda primeiro. Adicione o CORS cedo (para o preflight funcionar) e o GZip depois. Lembre disso ao depurar por que um header definido por um middleware não é visto por outro.

fastapi
from fastapi import FastAPI
from fastapi.middleware.gzip import GZipMiddleware
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

# Middleware runs in REVERSE order of registration for requests,
# and in registration order for responses.
app.add_middleware(GZipMiddleware, minimum_size=1000)
app.add_middleware(CORSMiddleware, allow_origins=["*"])

# request flow:  CORS -> GZip -> route
# response flow: route -> GZip -> CORS
11

CORS

Configuração do CORSMiddleware

O CORSMiddleware trata o preflight CORS (OPTIONS) e adiciona os headers Access-Control-*. allow_origins deve listar as origens exatas permitidas; use uma lista de URLs específicas em produção em vez de ['*'].

fastapi
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://example.com", "https://www.example.com"],
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

@app.get("/api/data")
def data():
    return {"data": 1}

Permitir todas as origens (só dev)

allow_origins=['*'] permite qualquer origem mas não pode ser combinado com allow_credentials=True (os navegadores rejeitam). Use só para APIs totalmente públicas em desenvolvimento; em produção enumere as origens reais.

fastapi
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_methods=["*"],
    allow_headers=["*"],
    # allow_credentials=True CANNOT be combined with allow_origins=["*"]
)

Permitir credenciais

allow_credentials=True permite que o navegador envie cookies e headers Authorization entre origens. Exige origens específicas (nunca '*'). O navegador define Access-Control-Allow-Credentials: true nas respostas.

fastapi
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://app.example.com"],
    allow_credentials=True,    # send cookies / Authorization
    allow_methods=["GET", "POST"],
    allow_headers=["Authorization", "Content-Type"],
)

# needed when the frontend sends cookies or credentials with requests

Funções e headers permitidos

allow_methods/allow_headers restringem o que o navegador pode enviar. expose_headers lista os headers de resposta que o JavaScript do frontend pode ler (caso contrário os navegadores escondem headers personalizados). As respostas de preflight são cacheadas pelo navegador.

fastapi
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://app.example.com"],
    allow_methods=["GET", "POST", "PUT", "PATCH", "DELETE"],
    allow_headers=["Authorization", "Content-Type", "X-Request-ID"],
    expose_headers=["X-Total-Count", "X-Process-Time"],
)

# expose_headers lets the frontend JS read these response headers

Requisições preflight

Para requisições 'não simples' (por exemplo, headers personalizados, PUT/DELETE, content type JSON), o navegador envia um preflight OPTIONS. O CORSMiddleware intercepta o OPTIONS e responde com as funções/headers permitidos. max_age controla por quanto tempo o navegador cacheia essa resposta.

fastapi
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://app.example.com"],
    allow_methods=["*"],
    allow_headers=["*"],
    max_age=600,   # browser caches preflight result for 600s
)

# Browser sends OPTIONS preflight for non-simple requests;
# CORSMiddleware answers automatically with the right headers.

Validação dinâmica de origem

Para allow-lists dinâmicas, use allow_origin_regex (compara com o Origin da requisição) em vez de uma lista estática. Prático quando as origens válidas seguem um padrão (por exemplo, qualquer subdomínio de example.com).

fastapi
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

VALID_DOMAINS = {"example.com", "staging.example.com"}

def origin_check(origin: str) -> str | None:
    if origin and origin.replace("https://", "").replace("http://", "") in VALID_DOMAINS:
        return origin
    return None

app.add_middleware(
    CORSMiddleware,
    allow_origin_regex=r"https://.*\.example\.com",
    allow_methods=["*"],
    allow_headers=["*"],
)
12

Tratamento de exceções

Lançando HTTPException

Lance HTTPException em qualquer lugar da rota ou dependência para interromper e retornar uma resposta de erro. detail pode ser string, dict ou lista — vira o campo 'detail' do JSON. headers opcionalmente adiciona headers de resposta.

fastapi
from fastapi import FastAPI, HTTPException, status

app = FastAPI()

items = {1: "Apple", 2: "Banana"}

@app.get("/items/{item_id}")
def read_item(item_id: int):
    if item_id not in items:
        raise HTTPException(
            status_code=status.HTTP_404_NOT_FOUND,
            detail="Item not found",
            headers={"X-Error": "missing"},
        )
    return {"item": items[item_id]}

Exceção personalizada

Registre um handler com @app.exception_handler(MyException) para converter qualquer exceção personalizada numa resposta HTTP. O handler recebe a requisição e a exceção. Isso centraliza a formatação de erros de domínio da sua app.

fastapi
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

class UnicornException(Exception):
    def __init__(self, name: str):
        self.name = name

app = FastAPI()

@app.exception_handler(UnicornException)
async def unicorn_handler(request: Request, exc: UnicornException):
    return JSONResponse(
        status_code=418,
        content={"message": f"Oops, {exc.name} did it again"},
    )

@app.get("/unicorns/{name}")
def read_unicorn(name: str):
    if name == "yolo":
        raise UnicornException(name=name)
    return {"name": name}

Sobrescrevendo erro de validação

RequestValidationError é lançada quando a entrada falha na validação do Pydantic. Sobrescreva seu handler com @app.exception_handler(RequestValidationError) para personalizar o formato da resposta 422, por exemplo para casar com um envelope de erro padrão da empresa.

fastapi
from fastapi import FastAPI, Request, status
from fastapi.responses import JSONResponse
from fastapi.exceptions import RequestValidationError

app = FastAPI()

@app.exception_handler(RequestValidationError)
async def validation_handler(request: Request, exc: RequestValidationError):
    return JSONResponse(
        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
        content={
            "success": False,
            "errors": exc.errors(),
            "body": exc.body,
        },
    )

Sobrescrevendo o handler do HTTPException

Sobrescreva o handler padrão do HTTPException para impor um formato de erro JSON consistente em todas as HTTPException lançadas. Importe a classe como fastapi.exceptions.HTTPException (a mesma usada pelo raise) ao redefinir o handler.

fastapi
from fastapi import FastAPI, HTTPException
from fastapi.responses import JSONResponse
from fastapi.exceptions import HTTPException as FastAPIHTTPException

app = FastAPI()

@app.exception_handler(FastAPIHTTPException)
async def custom_http_handler(request, exc: FastAPIHTTPException):
    return JSONResponse(
        status_code=exc.status_code,
        content={
            "success": False,
            "status": exc.status_code,
            "message": exc.detail,
        },
        headers=exc.headers,
    )

Códigos de status comuns

O módulo status fornece constantes nomeadas para os códigos de status HTTP, evitando números mágicos. 200 (GET padrão), 201 (criado), 204 (sem conteúdo), 422 (validação) são os mais comuns em apps FastAPI.

fastapi
from fastapi import FastAPI, status

app = FastAPI()

@app.get("/ok", status_code=status.HTTP_200_OK)
def ok(): return {"ok": True}

@app.post("/create", status_code=status.HTTP_201_CREATED)
def create(): return {"id": 1}

@app.get("/no-content", status_code=status.HTTP_204_NO_CONTENT)
def no_content(): return None

@app.get("/not-found")
def missing():
    # raise HTTPException(status.HTTP_404_NOT_FOUND, "nope")
    ...

# Other common: 400 BAD_REQUEST, 401 UNAUTHORIZED,
# 403 FORBIDDEN, 409 CONFLICT, 422 UNPROCESSABLE_ENTITY, 500 INTERNAL_SERVER_ERROR

Handler de exceção genérica

Registrar um handler para a Exception base captura tudo que ainda não foi tratado, impedindo que stack traces vazem para os clientes. Sempre registre o traceback completo no servidor; retorne um 500 genérico ao cliente.

fastapi
import logging
from fastapi import FastAPI, Request
from fastapi.responses import JSONResponse

logger = logging.getLogger("uvicorn.error")
app = FastAPI()

@app.exception_handler(Exception)
async def unhandled(request: Request, exc: Exception):
    logger.exception("Unhandled error on %s", request.url.path)
    return JSONResponse(
        status_code=500,
        content={"detail": "Internal Server Error"},
    )

@app.get("/boom")
def boom():
    raise RuntimeError("something exploded")
13

Tarefas em segundo plano

BackgroundTasks básico

BackgroundTasks roda funções depois que a resposta é enviada — perfeito para trabalho fire-and-forget como logging, e-mails ou invalidação de cache. add_task agenda uma função (e argumentos) sem bloquear a resposta.

fastapi
from fastapi import FastAPI, BackgroundTasks

app = FastAPI()

def write_log(message: str):
    with open("log.txt", "a") as f:
        f.write(message + "\n")

@app.post("/send")
def send_notification(background_tasks: BackgroundTasks):
    background_tasks.add_task(write_log, "notification sent")
    return {"message": "notification queued"}

Múltiplas tarefas

Adicione quantas tarefas quiser; elas rodam em sequência, na ordem adicionada, após a resposta ser retornada. Como rodam no mesmo processo, mantenha-as rápidas e não bloqueantes, ou migre para uma fila real (Celery, RQ, Dramatiq).

fastapi
from fastapi import FastAPI, BackgroundTasks

app = FastAPI()

def send_email(to: str, subject: str): ...
def update_cache(key: str): ...
def notify_slack(msg: str): ...

@app.post("/signup")
def signup(background_tasks: BackgroundTasks):
    background_tasks.add_task(send_email, "[email protected]", "Welcome")
    background_tasks.add_task(update_cache, "user_count")
    background_tasks.add_task(notify_slack, "new signup")
    return {"status": "ok"}

Tarefa com dependências

BackgroundTasks é injetado como qualquer dependência. A função da tarefa pode receber valores (como uma sessão de DB) capturados no momento da requisição. Note que recursos yielded/fechados por dependências fecham depois que as tarefas terminam, pois as tarefas rodam dentro do escopo do ciclo de vida da requisição.

fastapi
from fastapi import FastAPI, BackgroundTasks, Depends

app = FastAPI()

def get_db_session():
    db = "session"
    yield db

def write_log(db, message: str):
    print(db, message)

@app.get("/items")
def list_items(background_tasks: BackgroundTasks, db = Depends(get_db_session)):
    background_tasks.add_task(write_log, db, "list called")
    return {"items": []}

Função de tarefa assíncrona

Funções de tarefa em segundo plano podem ser sync (rodam em threadpool) ou async (aguardadas no event loop). Use tarefas async para trabalho limitado por I/O que usa bibliotecas assíncronas, e tarefas sync para trabalho de CPU/bloqueante.

fastapi
from fastapi import FastAPI, BackgroundTasks
import httpx

app = FastAPI()

async def fetch_url(url: str):
    async with httpx.AsyncClient() as client:
        r = await client.get(url)
        return r.status_code

@app.post("/webhook")
def webhook(url: str, background_tasks: BackgroundTasks):
    background_tasks.add_task(fetch_url, url)
    return {"queued": url}

Background vs Celery

Use BackgroundTasks para trabalho leve, não crítico, que pode se perder num reinício. Para jobs que precisam sobreviver a falhas, tentar de novo ou escalar entre máquinas, use uma fila de tarefas real (Celery, RQ, Dramatiq, Arq) com um broker como Redis ou RabbitMQ.

fastapi
# BackgroundTasks: in-process, no broker, lost if process crashes
@app.post("/quick")
def quick(tasks: BackgroundTasks):
    tasks.add_task(small_job)
    return {"ok": True}

# Celery/RQ/Dramatiq: separate workers, persistent, retryable
# from celery import Celery
# @celery.task
# def big_job(payload): ...
#
# @app.post("/heavy")
# def heavy(payload: dict):
#     big_job.delay(payload)
#     return {"queued": True}

Exemplo de envio de e-mail

Envio de e-mail é o caso de uso clássico do BackgroundTasks: é lento e o usuário não deve esperar. A resposta retorna imediatamente enquanto o e-mail é despachado depois. Para alto volume, prefira uma fila e um SDK de serviço de e-mail com retentativas.

fastapi
from fastapi import FastAPI, BackgroundTasks
from pydantic import BaseModel, EmailStr

class Message(BaseModel):
    to: EmailStr
    subject: str
    body: str

app = FastAPI()

def send_email(to: str, subject: str, body: str):
    # smtplib or your provider's SDK
    import smtplib
    with smtplib.SMTP("localhost") as s:
        s.sendmail("[email protected]", to, f"Subject: {subject}\n\n{body}")

@app.post("/contact")
def contact(msg: Message, tasks: BackgroundTasks):
    tasks.add_task(send_email, msg.to, msg.subject, msg.body)
    return {"status": "queued", "to": msg.to}
14

WebSocket

WebSocket básico

Use @app.websocket() para definir um endpoint WebSocket. Você precisa aceitar a conexão com accept() antes de enviar/receber. A função normalmente faz um loop lendo mensagens; receive_text/receive_bytes/receive_json aguardam dados do cliente.

fastapi
from fastapi import FastAPI, WebSocket

app = FastAPI()

@app.websocket("/ws")
async def websocket_endpoint(ws: WebSocket):
    await ws.accept()
    while True:
        data = await ws.receive_text()
        await ws.send_text(f"echo: {data}")

# client (browser):
# const ws = new WebSocket("ws://localhost:8000/ws");
# ws.onmessage = (e) => console.log(e.data);

Enviando JSON

send_json() e receive_json() cuidam da serialização, trocando objetos JSON pelo socket. Para dados binários use send_bytes/receive_bytes. Cada send/receive é um frame separado no WebSocket.

fastapi
import json
from fastapi import FastAPI, WebSocket

app = FastAPI()

@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket):
    await ws.accept()
    while True:
        msg = await ws.receive_json()
        await ws.send_json({"reply": msg.get("text", "").upper()})

# send_text / send_bytes / send_json helpers are available

Fechando o WebSocket

WebSocketDisconnect é lançada quando o cliente fecha a conexão — capture para fazer a limpeza. Chame ws.close(code=1000) para fechamento normal; códigos comuns: 1000 (normal), 1008 (violação de política), 1011 (erro do servidor).

fastapi
from fastapi import FastAPI, WebSocket, WebSocketDisconnect

app = FastAPI()

@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket):
    await ws.accept()
    try:
        while True:
            data = await ws.receive_text()
            if data == "quit":
                await ws.close(code=1000)
                break
            await ws.send_text(data)
    except WebSocketDisconnect:
        print("client disconnected")

Gerenciador de conexões

Um ConnectionManager rastreia os sockets ativos para você poder transmitir para os clientes conectados (por exemplo, uma sala de chat). Sempre remova o socket ao desconectar para não enviar a conexões fechadas e manter a memória limitada.

fastapi
from fastapi import FastAPI, WebSocket, WebSocketDisconnect

class ConnectionManager:
    def __init__(self):
        self.active: list[WebSocket] = []

    async def connect(self, ws: WebSocket):
        await ws.accept()
        self.active.append(ws)

    def disconnect(self, ws: WebSocket):
        self.active.remove(ws)

    async def broadcast(self, message: str):
        for ws in self.active:
            await ws.send_text(message)

manager = ConnectionManager()
app = FastAPI()

@app.websocket("/chat")
async def chat(ws: WebSocket):
    await manager.connect(ws)
    try:
        while True:
            msg = await ws.receive_text()
            await manager.broadcast(msg)
    except WebSocketDisconnect:
        manager.disconnect(ws)

Auth de WebSocket via query param

Navegadores não podem definir headers personalizados em conexões WebSocket, então tokens de auth costumam ser passados como query parameters (ou cookies). Valide antes de chamar accept() e feche com código 1008 (violação de política) se não autorizado.

fastapi
from fastapi import FastAPI, WebSocket, WebSocketDisconnect, HTTPException

app = FastAPI()

async def authenticate(token: str) -> str:
    if token != "secret":
        raise HTTPException(status_code=401)
    return "alice"

@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket):
    token = ws.query_params.get("token")
    if not token:
        await ws.close(code=1008)
        return
    user = await authenticate(token)
    await ws.accept()
    try:
        while True:
            data = await ws.receive_text()
            await ws.send_text(f"{user}: {data}")
    except WebSocketDisconnect:
        pass

WebSocket com dependências

Dependências podem ser usadas em endpoints WebSocket como em rotas HTTP, mas só fazem sentido dependências que leem do handshake inicial (headers, query params, cookies) — não há body. Injete via Depends() como de costume.

fastapi
from fastapi import FastAPI, WebSocket, Depends, Header

app = FastAPI()

def token_validator(token: str = Header(default="")):
    # for WS, headers come from the initial HTTP handshake
    return token == "valid"

@app.websocket("/ws")
async def ws_endpoint(ws: WebSocket, valid: bool = Depends(token_validator)):
    if not valid:
        await ws.close(code=1008)
        return
    await ws.accept()
    while True:
        msg = await ws.receive_text()
        await ws.send_text(msg)
15

Banco de dados (SQLAlchemy)

Configuração do SQLAlchemy

create_engine monta o pool de conexões do DB; SessionLocal é uma factory de sessões; Base é a base declarativa dos models. Para SQLite com FastAPI, defina check_same_thread=False porque as requisições podem rodar em threads diferentes.

fastapi
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker, declarative_base

SQLALCHEMY_DATABASE_URL = "sqlite:///./app.db"
# postgresql: "postgresql://user:pass@localhost:5432/dbname"

engine = create_engine(
    SQLALCHEMY_DATABASE_URL,
    connect_args={"check_same_thread": False},  # sqlite only
)
SessionLocal = sessionmaker(bind=engine, autoflush=False, autocommit=False)
Base = declarative_base()

Dependência de sessão

Uma dependência com yield é a forma canônica de fornecer uma sessão de DB: cada requisição recebe uma sessão nova, fechada no bloco finally. Isso garante a limpeza mesmo que a rota lance exceção.

fastapi
from fastapi import Depends
from sqlalchemy.orm import Session

def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

@app.get("/items")
def list_items(db: Session = Depends(get_db)):
    return db.query(Item).all()

# each request gets its own session, closed automatically afterward

Definição de models

Defina tabelas como models ORM do SQLAlchemy herdando de Base. Use Alembic para migrações de schema em produção, em vez de create_all(). Colunas podem ser indexadas, nullable e ter defaults aplicados no banco ou no Python.

fastapi
from sqlalchemy import Column, Integer, String, Boolean
from sqlalchemy.orm import declarative_base

Base = declarative_base()

class Item(Base):
    __tablename__ = "items"
    id = Column(Integer, primary_key=True, index=True)
    name = Column(String, index=True, nullable=False)
    price = Column(Integer, default=0)
    in_stock = Column(Boolean, default=True)

# create tables (for dev; use Alembic migrations in prod)
Base.metadata.create_all(bind=engine)

Criando registros

add() prepara uma nova linha, commit() grava no DB e refresh() recarrega a instância com valores gerados pelo servidor (como o id auto-increment). Envolva múltiplas escritas numa transação e faça commit uma vez no fim.

fastapi
from fastapi import FastAPI, Depends
from sqlalchemy.orm import Session

app = FastAPI()

@app.post("/items", status_code=201)
def create_item(payload: ItemCreate, db: Session = Depends(get_db)):
    item = Item(name=payload.name, price=payload.price)
    db.add(item)
    db.commit()
    db.refresh(item)        # load generated id
    return item

Consultando registros

db.query(Model) inicia uma consulta; .filter() aplica condições WHERE, .offset()/.limit() paginam, .first() retorna uma linha ou None, .all() retorna uma lista. Use .filter_by(name=x) para condições simples de igualdade.

fastapi
from fastapi import FastAPI, Depends, HTTPException
from sqlalchemy.orm import Session

app = FastAPI()

@app.get("/items")
def list_items(skip: int = 0, limit: int = 10, db: Session = Depends(get_db)):
    return db.query(Item).offset(skip).limit(limit).all()

@app.get("/items/{item_id}")
def get_item(item_id: int, db: Session = Depends(get_db)):
    item = db.query(Item).filter(Item.id == item_id).first()
    if not item:
        raise HTTPException(status_code=404, detail="not found")
    return item

Atualização e exclusão

Para atualizações parciais, itere model_dump(exclude_unset=True) para que só os campos fornecidos mudem. delete() prepara a remoção; commit() a finaliza. Retorne 204 No Content para DELETE em caso de sucesso.

fastapi
from fastapi import FastAPI, Depends, HTTPException
from sqlalchemy.orm import Session

app = FastAPI()

@app.put("/items/{item_id}")
def update_item(item_id: int, payload: ItemUpdate, db: Session = Depends(get_db)):
    item = db.query(Item).filter(Item.id == item_id).first()
    if not item:
        raise HTTPException(status_code=404, detail="not found")
    for k, v in payload.model_dump(exclude_unset=True).items():
        setattr(item, k, v)
    db.commit()
    db.refresh(item)
    return item

@app.delete("/items/{item_id}", status_code=204)
def delete_item(item_id: int, db: Session = Depends(get_db)):
    item = db.query(Item).filter(Item.id == item_id).first()
    if item:
        db.delete(item)
        db.commit()
16

Banco de dados (Tortoise ORM)

Configuração do Tortoise

Tortoise ORM é async nativo, combina bem com FastAPI. Inicialize no startup com db_url e o(s) módulo(s) que contêm seus models. generate_schemas() serve para dev; use Aerich para migrações em produção. Use o handler lifespan em vez de on_event em código novo.

fastapi
from fastapi import FastAPI
from tortoise import Tortoise

app = FastAPI()

async def init():
    await Tortoise.init(
        db_url="sqlite://db.sqlite3",
        modules={"models": ["app.models"]},
    )
    await Tortoise.generate_schemas()

@app.on_event("startup")
async def startup():
    await init()

@app.on_event("shutdown")
async def shutdown():
    await Tortoise.close_connections()

Definição de models

Models do Tortoise herdam de Model e declaram campos via tortoise.fields. Os tipos de campo mapeiam para tipos de coluna do DB. Defina o nome da tabela na classe interna Meta. Relacionamentos usam ForeignKeyField, ManyToManyField, etc.

fastapi
from tortoise import fields
from tortoise.models import Model

class Item(Model):
    id = fields.IntField(pk=True)
    name = fields.CharField(max_length=100)
    price = fields.FloatField(default=0.0)
    created_at = fields.DatetimeField(auto_now_add=True)

    class Meta:
        table = "items"

    def __str__(self):
        return self.name

Criando registros

Item.create() é uma coroutine que insere e retorna a nova linha. Para retornar uma resposta Pydantic, construa um BaseModel com from_tortoise_orm() (via tortoise.contrib.pydantic) para que o Tortoise serialize relações carregadas de forma assíncrona corretamente.

fastapi
from fastapi import FastAPI
from pydantic import BaseModel
from .models import Item

app = FastAPI()

class ItemIn(BaseModel):
    name: str
    price: float

@app.post("/items", response_model=ItemOut, status_code=201)
async def create_item(payload: ItemIn):
    item = await Item.create(name=payload.name, price=payload.price)
    return await ItemOut.from_tortoise_orm(item)

Consulta assíncrona

Consultas do Tortoise são awaited: .all() retorna um queryset, .filter() adiciona condições, .get_or_none() busca uma linha ou None, .first() retorna a primeira correspondência. Evite .get() a menos que espere exatamente uma linha (lança erro se não encontrar).

fastapi
from fastapi import FastAPI, HTTPException
from .models import Item

app = FastAPI()

@app.get("/items")
async def list_items(skip: int = 0, limit: int = 10):
    return await Item.all().offset(skip).limit(limit)

@app.get("/items/{item_id}")
async def get_item(item_id: int):
    item = await Item.get_or_none(id=item_id)
    if not item:
        raise HTTPException(status_code=404, detail="not found")
    return item

Atualização e exclusão

Modifique os atributos do model e faça await em save() para atualizar uma linha, ou await Item.filter(id=...).update(name=x) para atualizações em lote. await item.delete() remove a linha. Cada função é uma coroutine e precisa de await.

fastapi
from fastapi import FastAPI, HTTPException
from .models import Item

app = FastAPI()

@app.put("/items/{item_id}")
async def update_item(item_id: int, name: str):
    item = await Item.get_or_none(id=item_id)
    if not item:
        raise HTTPException(status_code=404, detail="not found")
    item.name = name
    await item.save()
    return item

@app.delete("/items/{item_id}", status_code=204)
async def delete_item(item_id: int):
    item = await Item.get_or_none(id=item_id)
    if item:
        await item.delete()

Schemas Pydantic do Tortoise

tortoise.contrib.pydantic gera models Pydantic diretamente dos models do Tortoise, então você não mantém dois schemas. Use pydantic_model_creator para um objeto único e pydantic_queryset_creator para uma resposta em lista.

fastapi
from tortoise.contrib.pydantic import pydantic_model_creator, pydantic_queryset_creator
from .models import Item

ItemOut = pydantic_model_creator(Item, name="ItemOut")
ItemList = pydantic_queryset_creator(Item)

@app.get("/items", response_model=ItemList)
async def list_items():
    return await Item.all()

# auto-generates a Pydantic model from the Tortoise model,
# including types and docstrings.
17

Testes (TestClient)

TestClient básico

O TestClient envolve sua app e permite fazer requisições no mesmo processo (sem socket real). Baseado em httpx, funciona com pytest de imediato. Importe a mesma instância da app que roda em produção.

fastapi
from fastapi.testclient import TestClient
from main import app

client = TestClient(app)

def test_root():
    response = client.get("/")
    assert response.status_code == 200
    assert response.json() == {"Hello": "World"}

# TestClient is based on httpx; no network is involved —
# it calls the ASGI app directly in-process.

Testando GET e POST

Passe json= para corpos JSON, params= para parâmetros de query, headers= para headers e files= para uploads multipart. Falhas de validação retornam 422 — faça asserções sobre status_code e a estrutura do 'detail' do erro.

fastapi
from fastapi.testclient import TestClient
from main import app

client = TestClient(app)

def test_create_item():
    response = client.post(
        "/items",
        json={"name": "Apple", "price": 0.5},
    )
    assert response.status_code == 201
    assert response.json()["name"] == "Apple"

def test_validation_error():
    response = client.post("/items", json={"name": "Apple"})  # missing price
    assert response.status_code == 422

Fixture do pytest

Uma fixture do pytest que retorna um TestClient mantém os testes DRY e permite que cada teste receba um client novo. Para testes com DB, adicione uma fixture que cria/apaga tabelas ou usa rollback de transação por teste para mantê-los isolados.

fastapi
import pytest
from fastapi.testclient import TestClient
from main import app

@pytest.fixture
def client():
    return TestClient(app)

def test_read(client):
    r = client.get("/items")
    assert r.status_code == 200

def test_create(client):
    r = client.post("/items", json={"name": "X"})
    assert r.status_code == 201

# run: pytest -v

Sobrescrevendo dependências

app.dependency_overrides troca uma dependência (como a sessão real do DB ou a auth) por um mock/fake durante os testes, sem alterar as rotas. É a forma canônica de testar endpoints isolados de serviços externos. Limpe depois dos testes.

fastapi
from fastapi.testclient import TestClient
from main import app, get_db

def get_test_db():
    # return a test session or mock
    yield FakeSession()

app.dependency_overrides[get_db] = get_test_db

client = TestClient(app)

def test_items():
    r = client.get("/items")
    assert r.status_code == 200

# restore afterwards:
app.dependency_overrides.clear()

Testando autenticação

OAuth2PasswordRequestForm espera dados codificados como form (data=, não json=). Use o token retornado no header Authorization: Bearer nas requisições protegidas seguintes. Para burlar a auth por completo, sobrescreva a dependência get_current_user.

fastapi
from fastapi.testclient import TestClient
from main import app

client = TestClient(app)

def get_token():
    r = client.post(
        "/token",
        data={"username": "admin", "password": "secret"},
    )
    return r.json()["access_token"]

def test_protected():
    token = get_token()
    r = client.get(
        "/me",
        headers={"Authorization": f"Bearer {token}"},
    )
    assert r.status_code == 200
    assert r.json()["username"] == "admin"

Testando WebSocket

TestClient.websocket_connect() abre um WebSocket dentro de um context manager. Use send_text/receive_text (e as variantes json/bytes) para trocar mensagens. Receber numa conexão fechada lança WebSocketDisconnect.

fastapi
from fastapi.testclient import TestClient
from main import app

client = TestClient(app)

def test_websocket():
    with client.websocket_connect("/ws") as ws:
        ws.send_text("hello")
        data = ws.receive_text()
        assert data == "echo: hello"

def test_websocket_close():
    with client.websocket_connect("/ws") as ws:
        ws.send_text("quit")
        # the server closes the connection
18

Documentação OpenAPI

Swagger UI

O FastAPI gera automaticamente uma Swagger UI interativa em /docs a partir das suas rotas, tipos e docstrings. Defina title/description/version na app e adicione docstring ou summary/description em cada rota para enriquecer a UI.

fastapi
from fastapi import FastAPI

app = FastAPI(
    title="My API",
    description="Sample API with auto docs",
    version="1.0.0",
)

@app.get("/items", summary="List items", description="Returns all items")
def list_items():
    """Get every item in the catalog."""
    return [{"id": 1}]

# interactive docs at: http://localhost:8000/docs

ReDoc

ReDoc em /redoc é uma alternativa somente leitura e focada em documentação em relação ao Swagger. O schema OpenAPI bruto fica em /openapi.json e pode alimentar outras ferramentas. Desabilite a documentação com docs_url=None, redoc_url=None, openapi_url=None (por exemplo, em produção).

fastapi
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def root():
    return {"hello": "world"}

# ReDoc (alternative docs UI) at: http://localhost:8000/redoc
# raw OpenAPI JSON at: http://localhost:8000/openapi.json

# disable docs entirely:
# app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)

Tags e agrupamento

Tags agrupam rotas na UI de documentação. Pré-declare metadados de tags (name, description, externalDocs) em openapi_tags para que o grupo apareça antes mesmo de qualquer rota usá-lo. Defina deprecated=True para marcar um endpoint como obsoleto na documentação.

fastapi
from fastapi import FastAPI

app = FastAPI(openapi_tags=[
    {"name": "users", "description": "User management"},
    {"name": "items", "description": "Item operations"},
])

@app.get("/users", tags=["users"])
def list_users(): ...

@app.post("/items", tags=["items"])
def create_item(): ...

@app.get("/items/{id}", tags=["items"], deprecated=True)
def get_item(id: int): ...

Metadados de rota

Decorators aceitam metadados que fluem para o OpenAPI: summary (título curto), description (texto longo), response_description, tags, deprecated e status_code. A docstring é usada como description se você não passar uma explicitamente.

fastapi
from fastapi import FastAPI, status
from pydantic import BaseModel

class Item(BaseModel):
    name: str
    price: float

app = FastAPI()

@app.post(
    "/items",
    response_model=Item,
    status_code=status.HTTP_201_CREATED,
    summary="Create an item",
    description="Creates a new item and returns it.",
    tags=["items"],
    response_description="The created item",
)
def create_item(item: Item):
    """Create endpoint docstring — also shown in docs."""
    return item

Exemplos de campos

Field(examples=[...]) e Body(examples=[...]) adicionam payloads de exemplo ao 'Try it out' e ao menu de exemplos da Swagger UI. Exemplos de body podem incluir múltiplos casos com summaries para mostrar entradas válidas e inválidas.

fastapi
from pydantic import BaseModel, Field
from fastapi import FastAPI, Body

class Item(BaseModel):
    name: str = Field(examples=["Apple"])
    price: float = Field(examples=[0.5], gt=0)

app = FastAPI()

@app.post("/items")
def create_item(item: Item):
    return item

@app.post("/manual")
def manual(
    item: Item = Body(
        examples=[
            {"summary": "valid", "value": {"name": "Apple", "price": 0.5}},
            {"summary": "invalid", "value": {"name": "Apple", "price": -1}},
        ],
    ),
):
    return item

Schema OpenAPI personalizado

Sobrescreva app.openapi para personalizar o schema gerado — adicionar um logo, metadados extras ou remover/transformar operações. Faça cache do resultado em app.openapi_schema para gerar só uma vez. O schema é o que /openapi.json serve.

fastapi
from fastapi import FastAPI
from fastapi.openapi.utils import get_openapi

app = FastAPI()

def custom_openapi():
    if app.openapi_schema:
        return app.openapi_schema
    schema = get_openapi(
        title="Custom API",
        version="2.0.0",
        routes=app.routes,
    )
    schema["info"]["x-logo"] = {"url": "https://example.com/logo.png"}
    app.openapi_schema = schema
    return schema

app.openapi = custom_openapi
19

Deploy (Uvicorn / Gunicorn)

Uvicorn em produção

Em produção, rode o Uvicorn atrás de um proxy reverso (Nginx, Caddy, um balanceador na nuvem). Use --proxy-headers para que a app veja o IP/host real do cliente de X-Forwarded-For/X-Forwarded-Proto. Evite --reload em produção.

fastapi
# Run directly with uvicorn (single worker)
uvicorn main:app --host 0.0.0.0 --port 8000 --workers 1

# Recommended: behind a reverse proxy (nginx) on port 8000
# Use --proxy-headers so X-Forwarded-* is trusted
uvicorn main:app --host 0.0.0.0 --port 8000 --proxy-headers --forwarded-allow-ips='*'

Gunicorn com workers Uvicorn

O Gunicorn gerencia múltiplos processos worker do Uvicorn, dando reloads graciosos, reinício em falhas e escalonamento pré-fork. Use a classe UvicornWorker. Comece com workers = (2 * núcleos de CPU + 1) e depois faça benchmark.

fastapi
# install the uvicorn worker class
pip install "uvicorn[standard]" gunicorn

# run 4 worker processes managed by gunicorn
gunicorn main:app \
    -w 4 \
    -k uvicorn.workers.UvicornWorker \
    -b 0.0.0.0:8000 \
    --timeout 120

# -w workers (commonly 2*CPU+1), -k worker class

Deploy com Docker

Uma imagem base Python enxuta mantém a imagem pequena. Instale as dependências antes de copiar o código para aproveitar o cache de camadas do Docker. Rode com workers gunicorn+uvicorn dentro do contêiner e exponha a porta 8000 para o host ou orquestrador.

fastapi
# Dockerfile
FROM python:3.12-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .
CMD ["gunicorn", "main:app", "-w", "4", \
     "-k", "uvicorn.workers.UvicornWorker", \
     "-b", "0.0.0.0:8000"]

# build & run:
# docker build -t myapi .
# docker run -p 8000:8000 myapi

Configuração por ambiente

pydantic-settings (antes pydantic.BaseSettings) carrega configuração de variáveis de ambiente e arquivos .env com validação de tipos. Isso permite que a mesma imagem rode em ambientes diferentes (dev/staging/prod) apenas mudando as env vars.

fastapi
import os
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    database_url: str = "sqlite:///./app.db"
    secret_key: str = "change-me"
    debug: bool = False
    allowed_origins: list[str] = ["http://localhost:3000"]

    class Config:
        env_file = ".env"
        env_file_encoding = "utf-8"

settings = Settings()

# .env file:
# DATABASE_URL=postgresql://user:pass@db:5432/app
# SECRET_KEY=long-random-string
# DEBUG=false

Proxy reverso Nginx

O Nginx termina o HTTP(S) e encaminha para o Uvicorn em localhost:8000. Defina os headers X-Forwarded-* (e use --proxy-headers no Uvicorn) para que a app veja o IP e o scheme reais do cliente. As linhas Upgrade/Connection habilitam suporte a WebSocket.

fastapi
# /etc/nginx/conf.d/api.conf
server {
    listen 80;
    server_name api.example.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host \$host;
        proxy_set_header X-Real-IP \$remote_addr;
        proxy_set_header X-Forwarded-For \$proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto \$scheme;

        proxy_http_version 1.1;
        proxy_set_header Upgrade \$http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Escalonamento e concorrência

Escale de duas formas: mais processos worker do Uvicorn por máquina (limitado por CPU) e mais máquinas atrás de um balanceador (horizontal). Para apps assíncronas, o event loop trata muitas requisições de I/O concorrentes por worker. Adicione um endpoint /health para que orquestradores (k8s, ECS) verifiquem a liveness.

fastapi
# Workers = process count (vertical scaling); pick ~2*CPU
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker

# Inside async app: concurrency is cooperative via the event loop.
# CPU-bound work blocks it — offload to a threadpool or task queue.

# Horizontal scaling: run several containers behind a load balancer.
# Use a shared store (Redis) for session state and rate limits.

# Health check endpoint for the balancer:
@app.get("/health")
def health():
    return {"status": "ok"}
20

Tópicos avançados

Eventos de lifespan

O context manager lifespan substitui os handlers descontinuados on_event('startup'/'shutdown'). Código antes do yield roda no startup; código depois do yield roda no shutdown, mesmo que o startup falhe. Use para inicializar conexões de DB, models de ML e caches.

fastapi
from contextlib import asynccontextmanager
from fastapi import FastAPI

@asynccontextmanager
async def lifespan(app: FastAPI):
    # runs at startup
    print("starting up")
    app.state.cache = {}
    yield
    # runs at shutdown
    print("shutting down")
    await app.state.cache.clear()

app = FastAPI(lifespan=lifespan)

# the old @app.on_event("startup") / "shutdown" are deprecated
# in favor of the lifespan handler above.

Sub-aplicações (mount)

app.mount() anexa uma sub-aplicação sob um prefixo de path, útil para APIs versionadas ou combinar várias apps. Cada sub-app tem rotas e schema OpenAPI próprios; a documentação da app pai não inclui as rotas da filha por padrão.

fastapi
from fastapi import FastAPI

app = FastAPI()

api_v1 = FastAPI()
api_v2 = FastAPI()

@api_v1.get("/items")
def v1_items():
    return {"version": 1}

@api_v2.get("/items")
def v2_items():
    return {"version": 2}

app.mount("/v1", api_v1)
app.mount("/v2", api_v2)

# GET /v1/items -> {"version": 1}
# GET /v2/items -> {"version": 2}

APIRouter

APIRouter agrupa rotas relacionadas num módulo com prefix, tags, dependencies e responses compartilhados. Inclua via app.include_router(router) (opcionalmente com prefix ou tags próprios). É o padrão padrão para estruturar apps não triviais.

fastapi
from fastapi import APIRouter, Depends

router = APIRouter(
    prefix="/items",
    tags=["items"],
    dependencies=[Depends(verify_token)],
    responses={404: {"description": "Not found"}},
)

@router.get("/")
def list_items():
    return []

@router.get("/{item_id}")
def get_item(item_id: int):
    return {"id": item_id}

# in main.py: app.include_router(router)

Arquivos estáticos

StaticFiles serve um diretório de assets estáticos (imagens, CSS, JS) num prefixo de URL. Monte uma vez por diretório. Para frontends SPA, monte uma rota final catch-all apontando para index.html. Arquivos estáticos bypassam o sistema de rotas por velocidade.

fastapi
from fastapi import FastAPI
from fastapi.staticfiles import StaticFiles

app = FastAPI()

# serve files from ./static at /static
app.mount("/static", StaticFiles(directory="static"), name="static")

# /static/logo.png -> ./static/logo.png
# /static/css/app.css -> ./static/css/app.css

StreamingResponse

StreamingResponse envia uma resposta gerada em blocos (um generator/iterator) em vez de construir o corpo inteiro na memória — ideal para exportações CSV grandes, streaming de arquivos ou SSE. Defina media_type adequadamente para que os clientes tratem o stream corretamente.

fastapi
from fastapi import FastAPI
from fastapi.responses import StreamingResponse
import csv, io

app = FastAPI()

def iter_csv():
    output = io.StringIO()
    writer = csv.writer(output)
    writer.writerow(["id", "name"])
    for i in range(1000):
        writer.writerow([i, f"name-{i}"])
        yield output.getvalue()
        output.seek(0)
        output.truncate(0)

@app.get("/export.csv")
def export():
    return StreamingResponse(
        iter_csv(),
        media_type="text/csv",
        headers={"Content-Disposition": "attachment; filename=export.csv"},
    )

Classe de rota personalizada

Herdar de APIRoute permite envolver cada handler de rota com lógica personalizada (logging, tracing, timing) sem tocar em cada endpoint. Defina app.router.route_class ou passe route_class ao APIRouter. O handler roda para cada requisição correspondente.

fastapi
from fastapi import FastAPI, Request, Response
from fastapi.routing import APIRoute
from typing import Callable

class LoggingRoute(APIRoute):
    def get_route_handler(self) -> Callable:
        original = super().get_route_handler()
        async def handler(request: Request) -> Response:
            print(f"-> {request.method} {request.url.path}")
            response = await original(request)
            print(f"<- {response.status_code}")
            return response
        return handler

app = FastAPI()
app.router.route_class = LoggingRoute

@app.get("/items")
def items():
    return {"items": []}

Was this helpful?

Learning path

Learn from scratch

Learn this language from the ground up with structured lessons.