🌐 Add Portuguese translation for `docs/pt/docs/tutorial/bigger-applications.md` (#11971)

docs/pt/docs/tutorial/bigger-applications.md

@@ -0,0 +1,556 @@
+# Aplicações Maiores - Múltiplos Arquivos
+
+Se você está construindo uma aplicação ou uma API web, é raro que você possa colocar tudo em um único arquivo.
+
+**FastAPI** oferece uma ferramenta conveniente para estruturar sua aplicação, mantendo toda a flexibilidade.
+
+/// info | "Informação"
+
+Se você vem do Flask, isso seria o equivalente aos Blueprints do Flask.
+
+///
+
+## Um exemplo de estrutura de arquivos
+
+Digamos que você tenha uma estrutura de arquivos como esta:
+
+```
+.
+├── app
+│   ├── __init__.py
+│   ├── main.py
+│   ├── dependencies.py
+│   └── routers
+│   │   ├── __init__.py
+│   │   ├── items.py
+│   │   └── users.py
+│   └── internal
+│       ├── __init__.py
+│       └── admin.py
+```
+
+/// tip | "Dica"
+
+Existem vários arquivos `__init__.py` presentes em cada diretório ou subdiretório.
+
+Isso permite a importação de código de um arquivo para outro.
+
+Por exemplo, no arquivo `app/main.py`, você poderia ter uma linha como:
+
+```
+from app.routers import items
+```
+
+///
+
+* O diretório `app` contém todo o código da aplicação. Ele possui um arquivo `app/__init__.py` vazio, o que o torna um "pacote Python" (uma coleção de "módulos Python"): `app`.
+* Dentro dele, o arquivo `app/main.py` está localizado em um pacote Python (diretório com  `__init__.py`). Portanto, ele é um "módulo" desse pacote: `app.main`.
+* Existem também um arquivo `app/dependencies.py`, assim como o `app/main.py`, ele é um "módulo": `app.dependencies`.
+* Há um subdiretório `app/routers/` com outro arquivo `__init__.py`, então ele é um "subpacote Python": `app.routers`.
+* O arquivo `app/routers/items.py` está dentro de um pacote, `app/routers/`, portanto, é um "submódulo": `app.routers.items`.
+* O mesmo com `app/routers/users.py`,  ele é outro submódulo: `app.routers.users`.
+* Há também um subdiretório `app/internal/` com outro arquivo `__init__.py`, então ele é outro "subpacote Python":`app.internal`.
+* E o arquivo `app/internal/admin.py` é outro submódulo: `app.internal.admin`.
+
+<img src="/img/tutorial/bigger-applications/package.svg">
+
+A mesma estrutura de arquivos com comentários:
+
+```
+.
+├── app                  # "app" é um pacote Python
+│   ├── __init__.py      # este arquivo torna "app" um "pacote Python"
+│   ├── main.py          # "main" módulo, e.g. import app.main
+│   ├── dependencies.py  # "dependencies" módulo, e.g. import app.dependencies
+│   └── routers          # "routers" é um  "subpacote Python"
+│   │   ├── __init__.py  # torna "routers" um "subpacote Python"
+│   │   ├── items.py     # "items" submódulo, e.g. import app.routers.items
+│   │   └── users.py     # "users" submódulo, e.g. import app.routers.users
+│   └── internal         # "internal" é um  "subpacote Python"
+│       ├── __init__.py  # torna "internal" um  "subpacote Python"
+│       └── admin.py     # "admin" submódulo, e.g. import app.internal.admin
+```
+
+## `APIRouter`
+
+Vamos supor que o arquivo dedicado a lidar apenas com usuários seja o submódulo em `/app/routers/users.py`.
+
+Você quer manter as *operações de rota* relacionadas aos seus usuários separadas do restante do código, para mantê-lo organizado.
+
+Mas ele ainda faz parte da mesma aplicação/web API **FastAPI** (faz parte do mesmo "pacote Python").
+
+Você pode criar as *operações de rotas* para esse módulo usando o `APIRouter`.
+
+### Importar `APIRouter`
+
+você o importa e cria uma "instância" da mesma maneira que faria com a classe `FastAPI`:
+
+```Python hl_lines="1  3" title="app/routers/users.py"
+{!../../../docs_src/bigger_applications/app/routers/users.py!}
+```
+
+### *Operações de Rota* com `APIRouter`
+
+E então você o utiliza para declarar suas *operações de rota*.
+
+Utilize-o da mesma maneira que utilizaria a classe  `FastAPI`:
+
+```Python hl_lines="6  11  16" title="app/routers/users.py"
+{!../../../docs_src/bigger_applications/app/routers/users.py!}
+```
+
+Você pode pensar em `APIRouter` como uma classe "mini `FastAPI`".
+
+Todas as mesmas opções são suportadas.
+
+Todos os mesmos `parameters`, `responses`, `dependencies`, `tags`, etc.
+
+/// tip | "Dica"
+
+Neste exemplo, a variável é chamada de `router`, mas você pode nomeá-la como quiser.
+
+///
+
+Vamos incluir este `APIRouter` na aplicação principal `FastAPI`, mas primeiro, vamos verificar as dependências e outro `APIRouter`.
+
+## Dependências
+
+Vemos que precisaremos de algumas dependências usadas em vários lugares da aplicação.
+
+Então, as colocamos em seu próprio módulo de `dependencies` (`app/dependencies.py`).
+
+Agora usaremos uma dependência simples para ler um cabeçalho `X-Token` personalizado:
+
+//// tab | Python 3.9+
+
+```Python hl_lines="3  6-8" title="app/dependencies.py"
+{!> ../../../docs_src/bigger_applications/app_an_py39/dependencies.py!}
+```
+
+////
+
+//// tab | Python 3.8+
+
+```Python hl_lines="1  5-7" title="app/dependencies.py"
+{!> ../../../docs_src/bigger_applications/app_an/dependencies.py!}
+```
+
+////
+
+//// tab | Python 3.8+ non-Annotated
+
+/// tip | "Dica"
+
+Prefira usar a versão `Annotated` se possível.
+
+///
+
+```Python hl_lines="1  4-6" title="app/dependencies.py"
+{!> ../../../docs_src/bigger_applications/app/dependencies.py!}
+```
+
+////
+
+/// tip | "Dica"
+
+Estamos usando um cabeçalho inventado para simplificar este exemplo.
+
+Mas em casos reais, você obterá melhores resultados usando os [Utilitários de Segurança](security/index.md){.internal-link target=_blank} integrados.
+
+///
+
+## Outro módulo com `APIRouter`
+
+Digamos que você também tenha os endpoints dedicados a manipular "itens" do seu aplicativo no módulo em `app/routers/items.py`.
+
+Você tem *operações de rota* para:
+
+* `/items/`
+* `/items/{item_id}`
+
+É tudo a mesma estrutura de `app/routers/users.py`.
+
+Mas queremos ser mais inteligentes e simplificar um pouco o código.
+
+Sabemos que todas as *operações de rota* neste módulo têm o mesmo:
+
+* Path `prefix`: `/items`.
+* `tags`: (apenas uma tag: `items`).
+* Extra `responses`.
+* `dependências`: todas elas precisam da dependência `X-Token` que criamos.
+
+Então, em vez de adicionar tudo isso a cada *operação de rota*, podemos adicioná-lo ao `APIRouter`.
+
+```Python hl_lines="5-10  16  21" title="app/routers/items.py"
+{!../../../docs_src/bigger_applications/app/routers/items.py!}
+```
+
+Como o caminho de cada *operação de rota* deve começar com `/`, como em:
+
+```Python hl_lines="1"
+@router.get("/{item_id}")
+async def read_item(item_id: str):
+    ...
+```
+
+...o prefixo não deve incluir um `/` final.
+
+Então, o prefixo neste caso é `/items`.
+
+Também podemos adicionar uma lista de `tags` e `responses` extras que serão aplicadas a todas as *operações de rota* incluídas neste roteador.
+
+E podemos adicionar uma lista de `dependencies` que serão adicionadas a todas as *operações de rota* no roteador e serão executadas/resolvidas para cada solicitação feita a elas.
+
+/// tip | "Dica"
+
+Observe que, assim como [dependências em *decoradores de operação de rota*](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}, nenhum valor será passado para sua *função de operação de rota*.
+
+///
+
+O resultado final é que os caminhos dos itens agora são:
+
+* `/items/`
+* `/items/{item_id}`
+
+...como pretendíamos.
+
+* Elas serão marcadas com uma lista de tags que contêm uma única string `"items"`.
+    * Essas "tags" são especialmente úteis para os sistemas de documentação interativa automática (usando OpenAPI).
+* Todas elas incluirão as `responses` predefinidas.
+* Todas essas *operações de rota* terão a lista de `dependencies` avaliada/executada antes delas.
+    * Se você também declarar dependências em uma *operação de rota* específica, **elas também serão executadas**.
+    * As dependências do roteador são executadas primeiro, depois as [`dependencies` no decorador](dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank} e, em seguida, as dependências de parâmetros normais.
+    * Você também pode adicionar [dependências de `Segurança` com `scopes`](../advanced/security/oauth2-scopes.md){.internal-link target=_blank}.
+
+/// tip | "Dica"
+
+Ter `dependências` no `APIRouter` pode ser usado, por exemplo, para exigir autenticação para um grupo inteiro de *operações de rota*. Mesmo que as dependências não sejam adicionadas individualmente a cada uma delas.
+
+///
+
+/// check
+
+Os parâmetros `prefix`, `tags`, `responses` e `dependencies` são (como em muitos outros casos) apenas um recurso do **FastAPI** para ajudar a evitar duplicação de código.
+
+///
+
+### Importar as dependências
+
+Este código reside no módulo `app.routers.items`, o arquivo `app/routers/items.py`.
+
+E precisamos obter a função de dependência do módulo `app.dependencies`, o arquivo `app/dependencies.py`.
+
+Então usamos uma importação relativa com `..` para as dependências:
+
+```Python hl_lines="3" title="app/routers/items.py"
+{!../../../docs_src/bigger_applications/app/routers/items.py!}
+```
+
+#### Como funcionam as importações relativas
+
+/// tip | "Dica"
+
+Se você sabe perfeitamente como funcionam as importações, continue para a próxima seção abaixo.
+
+///
+
+Um único ponto `.`, como em:
+
+```Python
+from .dependencies import get_token_header
+```
+
+significaria:
+
+* Começando no mesmo pacote em que este módulo (o arquivo `app/routers/items.py`) vive (o diretório `app/routers/`)...
+* encontre o módulo `dependencies` (um arquivo imaginário em `app/routers/dependencies.py`)...
+* e dele, importe a função `get_token_header`.
+
+Mas esse arquivo não existe, nossas dependências estão em um arquivo em `app/dependencies.py`.
+
+Lembre-se de como nossa estrutura app/file se parece:
+
+<img src="/img/tutorial/bigger-applications/package.svg">
+
+---
+
+Os dois pontos `..`, como em:
+
+```Python
+from ..dependencies import get_token_header
+```
+
+significa:
+
+* Começando no mesmo pacote em que este módulo (o arquivo `app/routers/items.py`) reside (o diretório `app/routers/`)...
+* vá para o pacote pai (o diretório `app/`)...
+* e lá, encontre o módulo `dependencies` (o arquivo em `app/dependencies.py`)...
+* e dele, importe a função `get_token_header`.
+
+Isso funciona corretamente! 🎉
+
+---
+
+Da mesma forma, se tivéssemos usado três pontos `...`, como em:
+
+```Python
+from ...dependencies import get_token_header
+```
+
+isso significaria:
+
+* Começando no mesmo pacote em que este módulo (o arquivo `app/routers/items.py`) vive (o diretório `app/routers/`)...
+* vá para o pacote pai (o diretório `app/`)...
+* então vá para o pai daquele pacote (não há pacote pai, `app` é o nível superior 😱)...
+* e lá, encontre o módulo `dependencies` (o arquivo em `app/dependencies.py`)...
+* e dele, importe a função `get_token_header`.
+
+Isso se referiria a algum pacote acima de `app/`, com seu próprio arquivo `__init__.py`, etc. Mas não temos isso. Então, isso geraria um erro em nosso exemplo. 🚨
+
+Mas agora você sabe como funciona, então você pode usar importações relativas em seus próprios aplicativos, não importa o quão complexos eles sejam. 🤓
+
+### Adicione algumas `tags`, `respostas` e `dependências` personalizadas
+
+Não estamos adicionando o prefixo `/items` nem `tags=["items"]` a cada *operação de rota* porque os adicionamos ao `APIRouter`.
+
+Mas ainda podemos adicionar _mais_ `tags` que serão aplicadas a uma *operação de rota* específica, e também algumas `respostas` extras específicas para essa *operação de rota*:
+
+```Python hl_lines="30-31" title="app/routers/items.py"
+{!../../../docs_src/bigger_applications/app/routers/items.py!}
+```
+
+/// tip | "Dica"
+
+Esta última operação de caminho terá a combinação de tags: `["items", "custom"]`.
+
+E também terá ambas as respostas na documentação, uma para `404` e uma para `403`.
+
+///
+
+## O principal `FastAPI`
+
+Agora, vamos ver o módulo em `app/main.py`.
+
+Aqui é onde você importa e usa a classe `FastAPI`.
+
+Este será o arquivo principal em seu aplicativo que une tudo.
+
+E como a maior parte de sua lógica agora viverá em seu próprio módulo específico, o arquivo principal será bem simples.
+
+### Importar `FastAPI`
+
+Você importa e cria uma classe `FastAPI` normalmente.
+
+E podemos até declarar [dependências globais](dependencies/global-dependencies.md){.internal-link target=_blank} que serão combinadas com as dependências para cada `APIRouter`:
+
+```Python hl_lines="1  3  7" title="app/main.py"
+{!../../../docs_src/bigger_applications/app/main.py!}
+```
+
+### Importe o `APIRouter`
+
+Agora importamos os outros submódulos que possuem `APIRouter`s:
+
+```Python hl_lines="4-5" title="app/main.py"
+{!../../../docs_src/bigger_applications/app/main.py!}
+```
+
+Como os arquivos `app/routers/users.py` e `app/routers/items.py` são submódulos que fazem parte do mesmo pacote Python `app`, podemos usar um único ponto `.` para importá-los usando "importações relativas".
+
+### Como funciona a importação
+
+A seção:
+
+```Python
+from .routers import items, users
+```
+
+significa:
+
+* Começando no mesmo pacote em que este módulo (o arquivo `app/main.py`) reside (o diretório `app/`)...
+* procure o subpacote `routers` (o diretório em `app/routers/`)...
+* e dele, importe o submódulo `items` (o arquivo em `app/routers/items.py`) e `users` (o arquivo em `app/routers/users.py`)...
+
+O módulo `items` terá uma variável `router` (`items.router`). Esta é a mesma que criamos no arquivo `app/routers/items.py`, é um objeto `APIRouter`.
+
+E então fazemos o mesmo para o módulo `users`.
+
+Também poderíamos importá-los como:
+
+```Python
+from app.routers import items, users
+```
+
+/// info | "Informação"
+
+A primeira versão é uma "importação relativa":
+
+```Python
+from .routers import items, users
+```
+
+A segunda versão é uma "importação absoluta":
+
+```Python
+from app.routers import items, users
+```
+
+Para saber mais sobre pacotes e módulos Python, leia <a href="https://docs.python.org/3/tutorial/modules.html" class="external-link" target="_blank">a documentação oficial do Python sobre módulos</a>.
+
+///
+
+### Evite colisões de nomes
+
+Estamos importando o submódulo `items` diretamente, em vez de importar apenas sua variável `router`.
+
+Isso ocorre porque também temos outra variável chamada `router` no submódulo `users`.
+
+Se tivéssemos importado um após o outro, como:
+
+```Python
+from .routers.items import router
+from .routers.users import router
+```
+
+o `router` de `users` sobrescreveria o de `items` e não poderíamos usá-los ao mesmo tempo.
+
+Então, para poder usar ambos no mesmo arquivo, importamos os submódulos diretamente:
+
+```Python hl_lines="5" title="app/main.py"
+{!../../../docs_src/bigger_applications/app/main.py!}
+```
+
+### Incluir o `APIRouter`s para `usuários` e `itens`
+
+Agora, vamos incluir os `roteadores` dos submódulos `usuários` e `itens`:
+
+```Python hl_lines="10-11" title="app/main.py"
+{!../../../docs_src/bigger_applications/app/main.py!}
+```
+
+/// info | "Informação"
+
+`users.router` contém o `APIRouter` dentro do arquivo `app/routers/users.py`.
+
+E `items.router` contém o `APIRouter` dentro do arquivo `app/routers/items.py`.
+
+///
+
+Com `app.include_router()` podemos adicionar cada `APIRouter` ao aplicativo principal `FastAPI`.
+
+Ele incluirá todas as rotas daquele roteador como parte dele.
+
+/// note | "Detalhe Técnico"
+
+Na verdade, ele criará internamente uma *operação de rota* para cada *operação de rota* que foi declarada no `APIRouter`.
+
+Então, nos bastidores, ele realmente funcionará como se tudo fosse o mesmo aplicativo único.
+
+///
+
+/// check
+
+Você não precisa se preocupar com desempenho ao incluir roteadores.
+
+Isso levará microssegundos e só acontecerá na inicialização.
+
+Então não afetará o desempenho. ⚡
+
+///
+
+### Incluir um `APIRouter` com um `prefix` personalizado, `tags`, `responses` e `dependencies`
+
+Agora, vamos imaginar que sua organização lhe deu o arquivo `app/internal/admin.py`.
+
+Ele contém um `APIRouter` com algumas *operações de rota* de administração que sua organização compartilha entre vários projetos.
+
+Para este exemplo, será super simples. Mas digamos que, como ele é compartilhado com outros projetos na organização, não podemos modificá-lo e adicionar um `prefix`, `dependencies`, `tags`, etc. diretamente ao `APIRouter`:
+
+```Python hl_lines="3" title="app/internal/admin.py"
+{!../../../docs_src/bigger_applications/app/internal/admin.py!}
+```
+
+Mas ainda queremos definir um `prefixo` personalizado ao incluir o `APIRouter` para que todas as suas *operações de rota* comecem com `/admin`, queremos protegê-lo com as `dependências` que já temos para este projeto e queremos incluir `tags` e `responses`.
+
+Podemos declarar tudo isso sem precisar modificar o `APIRouter` original passando esses parâmetros para `app.include_router()`:
+
+```Python hl_lines="14-17" title="app/main.py"
+{!../../../docs_src/bigger_applications/app/main.py!}
+```
+
+Dessa forma, o `APIRouter` original permanecerá inalterado, para que possamos compartilhar o mesmo arquivo `app/internal/admin.py` com outros projetos na organização.
+
+O resultado é que em nosso aplicativo, cada uma das *operações de rota* do módulo `admin` terá:
+
+* O prefixo `/admin`.
+* A tag `admin`.
+* A dependência `get_token_header`.
+* A resposta `418`. 🍵
+
+Mas isso afetará apenas o `APIRouter` em nosso aplicativo, e não em nenhum outro código que o utilize.
+
+Assim, por exemplo, outros projetos poderiam usar o mesmo `APIRouter` com um método de autenticação diferente.
+
+### Incluir uma *operação de rota*
+
+Também podemos adicionar *operações de rota* diretamente ao aplicativo `FastAPI`.
+
+Aqui fazemos isso... só para mostrar que podemos 🤷:
+
+```Python hl_lines="21-23" title="app/main.py"
+{!../../../docs_src/bigger_applications/app/main.py!}
+```
+
+e funcionará corretamente, junto com todas as outras *operações de rota* adicionadas com `app.include_router()`.
+
+/// info | "Detalhes Técnicos"
+
+**Observação**: este é um detalhe muito técnico que você provavelmente pode **simplesmente pular**.
+
+---
+
+Os `APIRouter`s não são "montados", eles não são isolados do resto do aplicativo.
+
+Isso ocorre porque queremos incluir suas *operações de rota* no esquema OpenAPI e nas interfaces de usuário.
+
+Como não podemos simplesmente isolá-los e "montá-los" independentemente do resto, as *operações de rota* são "clonadas" (recriadas), não incluídas diretamente.
+
+///
+
+## Verifique a documentação automática da API
+
+Agora, execute `uvicorn`, usando o módulo `app.main` e a variável `app`:
+
+<div class="termy">
+
+```console
+$ uvicorn app.main:app --reload
+
+<span style="color: green;">INFO</span>:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
+```
+
+</div>
+
+E abra os documentos em <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>.
+
+Você verá a documentação automática da API, incluindo os caminhos de todos os submódulos, usando os caminhos (e prefixos) corretos e as tags corretas:
+
+<img src="/img/tutorial/bigger-applications/image01.png">
+
+## Incluir o mesmo roteador várias vezes com `prefixos` diferentes
+
+Você também pode usar `.include_router()` várias vezes com o *mesmo* roteador usando prefixos diferentes.
+
+Isso pode ser útil, por exemplo, para expor a mesma API sob prefixos diferentes, por exemplo, `/api/v1` e `/api/latest`.
+
+Esse é um uso avançado que você pode não precisar, mas está lá caso precise.
+
+## Incluir um `APIRouter` em outro
+
+Da mesma forma que você pode incluir um `APIRouter` em um aplicativo `FastAPI`, você pode incluir um `APIRouter` em outro `APIRouter` usando:
+
+```Python
+router.include_router(other_router)
+```
+
+Certifique-se de fazer isso antes de incluir `router` no aplicativo `FastAPI`, para que as *operações de rota* de `other_router` também sejam incluídas.