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.
# 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 --reloadRodando 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.
# 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.
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.
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.
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.
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")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.
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.
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.
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.
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.
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} patternParâ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.
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"}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.
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=10Parâ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.
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.
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.
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.
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 nullParâ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.
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 requiredCorpo 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.
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.
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.
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.
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.
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.
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 resultResponse 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.
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.
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.
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.
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=TrueResposta 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.
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.
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)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.
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=secretUploadFile 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.
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.
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/uploadsArquivo 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.
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.
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.
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)}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.
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 commonsDependê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.
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 typeDependê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).
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 userDependê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.
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.
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 checkedDependê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.
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"}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.
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.
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.
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.
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.
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 userFluxo 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.
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.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.
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 responseMiddleware 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.
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 headersBaseHTTPMiddleware
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.
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 configurableRedirecionamento 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.
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.
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 responseOrdem 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.
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 -> CORSCORS
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 ['*'].
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.
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.
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 requestsFunçõ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.
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 headersRequisiçõ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.
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).
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=["*"],
)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.
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.
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.
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.
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.
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_ERRORHandler 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.
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")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.
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).
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.
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.
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.
# 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.
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}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.
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.
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 availableFechando 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).
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.
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.
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:
passWebSocket 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.
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)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.
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.
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 afterwardDefiniçã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.
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.
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 itemConsultando 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.
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 itemAtualizaçã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.
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()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.
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.
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.nameCriando 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.
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).
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 itemAtualizaçã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.
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.
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.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.
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.
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 == 422Fixture 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.
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 -vSobrescrevendo 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.
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.
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.
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 connectionDocumentaçã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.
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/docsReDoc
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).
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.
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.
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 itemExemplos 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.
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 itemSchema 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.
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_openapiDeploy (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.
# 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.
# 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 classDeploy 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.
# 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 myapiConfiguraçã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.
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=falseProxy 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.
# /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.
# 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"}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.
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.
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.
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.
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.cssStreamingResponse
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.
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.
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": []}Snippets de FastAPI relacionados
Copy-paste ready code for common tasks.
Path Parameters
Capture typed path segments with validation.
Query Parameters
Parse query strings with defaults and validation.
Pydantic Request Body
Validate JSON bodies with Pydantic models.
Dependency Injection
Share logic via Depends and yield-based dependencies.
Response Model
Shape and filter responses with response_model.
JWT Auth
Issue and verify JSON Web Tokens with OAuth2.
Async and Await
Define async handlers and run blocking work in a thread.
Middleware
Add CORS, timing, and custom middleware.
Was this helpful?