Como você estrutura um app grande com APIRouter?

Question

Accepted Answer

**`APIRouter`** permite dividir um app FastAPI grande em múltiplos módulos — cada roteador agrupa endpoints relacionados (p. ex. todas as rotas `/users`), e o app principal os inclui. Isso mantém uma base de código crescente organizada e mantível.

## Definindo um roteador em seu próprio módulo

```python
# routers/users.py
from fastapi import APIRouter

router = APIRouter(
    prefix="/users",          # all routes here start with /users
    tags=["users"],           # grouped under "users" in the docs
)

@router.get("/")              # GET /users/
def list_users(): ...

@router.get("/{user_id}")     # GET /users/{user_id}
def get_user(user_id: int): ...
```

Um `APIRouter` funciona como um mini-app — você define operações de caminho nele com os mesmos decoradores, e um `prefix` se aplica a todos eles.

## Incluindo roteadores no app principal

```python
# main.py
from fastapi import FastAPI
from routers import users, items, auth

app = FastAPI()
app.include_router(users.router)     # mounts /users/* endpoints
app.include_router(items.router)
app.include_router(auth.router)
```

`app.include_router()` monta os endpoints de cada roteador no app principal — montando a API completa a partir de peças modulares.

## Uma estrutura de projeto típica

```text
app/
  main.py              # creates the app, includes routers
  routers/
    users.py           # APIRouter for /users
    items.py           # APIRouter for /items
    auth.py            # APIRouter for /auth
  models.py            # Pydantic models
  database.py          # DB setup
  dependencies.py      # shared dependencies
```

Cada feature/domínio recebe seu próprio módulo roteador — mantendo rotas relacionadas e a base de código bem-organizada.

## Dependências e configuração em nível de roteador

```python
router = APIRouter(
    prefix="/admin",
    dependencies=[Depends(verify_admin)],   # apply a dependency to ALL routes in the router
)
# you can also nest routers via include_router on a router
```

Roteadores podem carregar dependências compartilhadas (p. ex. requerem autenticação de admin para um grupo inteiro de rotas) — aplicadas a todos os seus endpoints de uma vez.

## Por que isso importa

`APIRouter` é essencial para construir qualquer coisa além de um app FastAPI trivial — sem ele, todos os endpoints viveriam em um arquivo, o que se torna ingerenciável conforme a API cresce.

Entender isso é importante para **organização de código e manutenibilidade**: dividir endpoints em módulos roteadores baseados em features (usuários, itens, auth) mantém código relacionado junto, torna o projeto navegável e permite que equipes trabalhem em áreas diferentes independentemente.

O `prefix` e `tags` mantêm rotas e documentação organizadas, e **dependências em nível de roteador** (como exigir autenticação de admin para um grupo inteiro) fornecem comportamento limpo e em toda a grupo.

Esta estrutura modular é prática padrão para aplicações FastAPI reais, tornando `APIRouter` e os padrões de organização de projeto em torno dele conhecimento importante, praticamente essencial, para construir APIs escaláveis e mantíveis.

Definindo um roteador em seu próprio módulo

Incluindo roteadores no app principal

Uma estrutura de projeto típica

Dependências e configuração em nível de roteador

Por que isso importa

question.related