JONEMI21
6 months ago
642 changed files with 37972 additions and 25879 deletions
@ -7,7 +7,8 @@ on: |
|||
- synchronize |
|||
|
|||
env: |
|||
IS_FORK: ${{ github.event.pull_request.head.repo.full_name != github.repository }} |
|||
# Forks and Dependabot don't have access to secrets |
|||
HAS_SECRETS: ${{ secrets.PRE_COMMIT != '' }} |
|||
|
|||
jobs: |
|||
pre-commit: |
|||
@ -19,7 +20,7 @@ jobs: |
|||
run: echo "$GITHUB_CONTEXT" |
|||
- uses: actions/checkout@v5 |
|||
name: Checkout PR for own repo |
|||
if: env.IS_FORK == 'false' |
|||
if: env.HAS_SECRETS == 'true' |
|||
with: |
|||
# To be able to commit it needs to fetch the head of the branch, not the |
|||
# merge commit |
|||
@ -31,7 +32,7 @@ jobs: |
|||
# pre-commit lite ci needs the default checkout configs to work |
|||
- uses: actions/checkout@v5 |
|||
name: Checkout PR for fork |
|||
if: env.IS_FORK == 'true' |
|||
if: env.HAS_SECRETS == 'false' |
|||
with: |
|||
# To be able to commit it needs the head branch of the PR, the remote one |
|||
ref: ${{ github.event.pull_request.head.sha }} |
|||
@ -39,24 +40,21 @@ jobs: |
|||
- name: Set up Python |
|||
uses: actions/setup-python@v6 |
|||
with: |
|||
python-version: "3.14" |
|||
python-version-file: ".python-version" |
|||
- name: Setup uv |
|||
uses: astral-sh/setup-uv@v7 |
|||
with: |
|||
cache-dependency-glob: | |
|||
requirements**.txt |
|||
pyproject.toml |
|||
uv.lock |
|||
- name: Install Dependencies |
|||
run: | |
|||
uv venv |
|||
uv pip install -r requirements.txt |
|||
run: uv sync --locked --extra all |
|||
- name: Run prek - pre-commit |
|||
id: precommit |
|||
run: uvx prek run --from-ref origin/${GITHUB_BASE_REF} --to-ref HEAD --show-diff-on-failure |
|||
continue-on-error: true |
|||
- name: Commit and push changes |
|||
if: env.IS_FORK == 'false' |
|||
if: env.HAS_SECRETS == 'true' |
|||
run: | |
|||
git config user.name "github-actions[bot]" |
|||
git config user.email "github-actions[bot]@users.noreply.github.com" |
|||
@ -68,7 +66,7 @@ jobs: |
|||
git push |
|||
fi |
|||
- uses: pre-commit-ci/[email protected] |
|||
if: env.IS_FORK == 'true' |
|||
if: env.HAS_SECRETS == 'false' |
|||
with: |
|||
msg: 🎨 Auto format |
|||
- name: Error out on pre-commit errors |
|||
|
|||
@ -15,6 +15,7 @@ jobs: |
|||
- fastapi-slim |
|||
permissions: |
|||
id-token: write |
|||
contents: read |
|||
steps: |
|||
- name: Dump GitHub context |
|||
env: |
|||
@ -24,19 +25,15 @@ jobs: |
|||
- name: Set up Python |
|||
uses: actions/setup-python@v6 |
|||
with: |
|||
python-version: "3.10" |
|||
python-version-file: ".python-version" |
|||
# Issue ref: https://github.com/actions/setup-python/issues/436 |
|||
# cache: "pip" |
|||
# cache-dependency-path: pyproject.toml |
|||
- name: Install build dependencies |
|||
run: pip install build |
|||
- name: Install uv |
|||
uses: astral-sh/setup-uv@v7 |
|||
- name: Build distribution |
|||
run: uv build |
|||
env: |
|||
TIANGOLO_BUILD_PACKAGE: ${{ matrix.package }} |
|||
run: python -m build |
|||
- name: Publish |
|||
uses: pypa/[email protected] |
|||
- name: Dump GitHub context |
|||
env: |
|||
GITHUB_CONTEXT: ${{ toJson(github) }} |
|||
run: echo "$GITHUB_CONTEXT" |
|||
run: uv publish |
|||
|
|||
@ -0,0 +1 @@ |
|||
3.11 |
|||
@ -22,21 +22,13 @@ Hier ist eine allgemeine Idee, wie die Modelle mit ihren Passwortfeldern aussehe |
|||
|
|||
{* ../../docs_src/extra_models/tutorial001_py310.py hl[7,9,14,20,22,27:28,31:33,38:39] *} |
|||
|
|||
/// info | Info |
|||
### Über `**user_in.model_dump()` { #about-user-in-model-dump } |
|||
|
|||
In Pydantic v1 hieß die Methode `.dict()`, in Pydantic v2 wurde sie <abbr title="veraltet, obsolet: Es soll nicht mehr verwendet werden">deprecatet</abbr> (aber weiterhin unterstützt) und in `.model_dump()` umbenannt. |
|||
|
|||
Die Beispiele hier verwenden `.dict()` für die Kompatibilität mit Pydantic v1, aber Sie sollten `.model_dump()` verwenden, wenn Sie Pydantic v2 verwenden können. |
|||
|
|||
/// |
|||
|
|||
### Über `**user_in.dict()` { #about-user-in-dict } |
|||
|
|||
#### Die `.dict()`-Methode von Pydantic { #pydantics-dict } |
|||
#### Pydantics `.model_dump()` { #pydantics-model-dump } |
|||
|
|||
`user_in` ist ein Pydantic-Modell der Klasse `UserIn`. |
|||
|
|||
Pydantic-Modelle haben eine `.dict()`-Methode, die ein <abbr title="Dictionary – Zuordnungstabelle: In anderen Sprachen auch Hash, Map, Objekt, Assoziatives Array genannt">`dict`</abbr> mit den Daten des Modells zurückgibt. |
|||
Pydantic-Modelle haben eine `.model_dump()`-Methode, die ein <abbr title="Dictionary – Zuordnungstabelle: In anderen Sprachen auch Hash, Map, Objekt, Assoziatives Array genannt">`dict`</abbr> mit den Daten des Modells zurückgibt. |
|||
|
|||
Wenn wir also ein Pydantic-Objekt `user_in` erstellen, etwa so: |
|||
|
|||
@ -47,7 +39,7 @@ user_in = UserIn(username="john", password="secret", email="[email protected] |
|||
und dann aufrufen: |
|||
|
|||
```Python |
|||
user_dict = user_in.dict() |
|||
user_dict = user_in.model_dump() |
|||
``` |
|||
|
|||
haben wir jetzt ein `dict` mit den Daten in der Variablen `user_dict` (es ist ein `dict` statt eines Pydantic-Modellobjekts). |
|||
@ -103,20 +95,20 @@ UserInDB( |
|||
|
|||
#### Ein Pydantic-Modell aus dem Inhalt eines anderen { #a-pydantic-model-from-the-contents-of-another } |
|||
|
|||
Da wir im obigen Beispiel `user_dict` von `user_in.dict()` bekommen haben, wäre dieser Code: |
|||
Da wir im obigen Beispiel `user_dict` von `user_in.model_dump()` bekommen haben, wäre dieser Code: |
|||
|
|||
```Python |
|||
user_dict = user_in.dict() |
|||
user_dict = user_in.model_dump() |
|||
UserInDB(**user_dict) |
|||
``` |
|||
|
|||
gleichwertig zu: |
|||
|
|||
```Python |
|||
UserInDB(**user_in.dict()) |
|||
UserInDB(**user_in.model_dump()) |
|||
``` |
|||
|
|||
... weil `user_in.dict()` ein `dict` ist, und dann lassen wir Python es „entpacken“, indem wir es an `UserInDB` mit vorangestelltem `**` übergeben. |
|||
... weil `user_in.model_dump()` ein `dict` ist, und dann lassen wir Python es „entpacken“, indem wir es an `UserInDB` mit vorangestelltem `**` übergeben. |
|||
|
|||
Auf diese Weise erhalten wir ein Pydantic-Modell aus den Daten eines anderen Pydantic-Modells. |
|||
|
|||
@ -125,7 +117,7 @@ Auf diese Weise erhalten wir ein Pydantic-Modell aus den Daten eines anderen Pyd |
|||
Und dann fügen wir das zusätzliche Schlüsselwort-Argument `hashed_password=hashed_password` hinzu, wie in: |
|||
|
|||
```Python |
|||
UserInDB(**user_in.dict(), hashed_password=hashed_password) |
|||
UserInDB(**user_in.model_dump(), hashed_password=hashed_password) |
|||
``` |
|||
|
|||
... was so ist wie: |
|||
@ -180,7 +172,6 @@ Wenn Sie eine <a href="https://docs.pydantic.dev/latest/concepts/types/#unions" |
|||
|
|||
{* ../../docs_src/extra_models/tutorial003_py310.py hl[1,14:15,18:20,33] *} |
|||
|
|||
|
|||
### `Union` in Python 3.10 { #union-in-python-3-10 } |
|||
|
|||
In diesem Beispiel übergeben wir `Union[PlaneItem, CarItem]` als Wert des Arguments `response_model`. |
|||
@ -203,7 +194,6 @@ Dafür verwenden Sie Pythons Standard-`typing.List` (oder nur `list` in Python 3 |
|||
|
|||
{* ../../docs_src/extra_models/tutorial004_py39.py hl[18] *} |
|||
|
|||
|
|||
## Response mit beliebigem `dict` { #response-with-arbitrary-dict } |
|||
|
|||
Sie können auch eine Response deklarieren, die ein beliebiges `dict` zurückgibt, indem Sie nur die Typen der Schlüssel und Werte ohne ein Pydantic-Modell deklarieren. |
|||
@ -214,7 +204,6 @@ In diesem Fall können Sie `typing.Dict` verwenden (oder nur `dict` in Python 3. |
|||
|
|||
{* ../../docs_src/extra_models/tutorial005_py39.py hl[6] *} |
|||
|
|||
|
|||
## Zusammenfassung { #recap } |
|||
|
|||
Verwenden Sie gerne mehrere Pydantic-Modelle und vererben Sie je nach Bedarf. |
|||
|
|||
|
After Width: | Height: | Size: 187 KiB |
|
After Width: | Height: | Size: 5.6 KiB |
@ -46,12 +46,6 @@ $ pip install "fastapi[all]" |
|||
|
|||
</div> |
|||
|
|||
/// info | Información |
|||
|
|||
En Pydantic v1 venía incluido con el paquete principal. Ahora se distribuye como este paquete independiente para que puedas elegir si instalarlo o no si no necesitas esa funcionalidad. |
|||
|
|||
/// |
|||
|
|||
### Crear el objeto `Settings` { #create-the-settings-object } |
|||
|
|||
Importa `BaseSettings` de Pydantic y crea una sub-clase, muy similar a un modelo de Pydantic. |
|||
@ -60,31 +54,15 @@ De la misma forma que con los modelos de Pydantic, declaras atributos de clase c |
|||
|
|||
Puedes usar todas las mismas funcionalidades de validación y herramientas que usas para los modelos de Pydantic, como diferentes tipos de datos y validaciones adicionales con `Field()`. |
|||
|
|||
//// tab | Pydantic v2 |
|||
|
|||
{* ../../docs_src/settings/tutorial001_py39.py hl[2,5:8,11] *} |
|||
|
|||
//// |
|||
|
|||
//// tab | Pydantic v1 |
|||
|
|||
/// info | Información |
|||
|
|||
En Pydantic v1 importarías `BaseSettings` directamente desde `pydantic` en lugar de desde `pydantic_settings`. |
|||
|
|||
/// |
|||
|
|||
{* ../../docs_src/settings/tutorial001_pv1_py39.py hl[2,5:8,11] *} |
|||
|
|||
//// |
|||
|
|||
/// tip | Consejo |
|||
|
|||
Si quieres algo rápido para copiar y pegar, no uses este ejemplo, usa el último más abajo. |
|||
|
|||
/// |
|||
|
|||
Luego, cuando creas una instance de esa clase `Settings` (en este caso, en el objeto `settings`), Pydantic leerá las variables de entorno de una manera indiferente a mayúsculas y minúsculas, por lo que una variable en mayúsculas `APP_NAME` aún será leída para el atributo `app_name`. |
|||
Luego, cuando creas un instance de esa clase `Settings` (en este caso, en el objeto `settings`), Pydantic leerá las variables de entorno de una manera indiferente a mayúsculas y minúsculas, por lo que una variable en mayúsculas `APP_NAME` aún será leída para el atributo `app_name`. |
|||
|
|||
Luego convertirá y validará los datos. Así que, cuando uses ese objeto `settings`, tendrás datos de los tipos que declaraste (por ejemplo, `items_per_user` será un `int`). |
|||
|
|||
@ -110,7 +88,7 @@ $ ADMIN_EMAIL="[email protected]" APP_NAME="ChimichangApp" fastapi run main.p |
|||
|
|||
/// tip | Consejo |
|||
|
|||
Para establecer múltiples variables de entorno para un solo comando, simplemente sepáralas con un espacio y ponlas todas antes del comando. |
|||
Para establecer múltiples env vars para un solo comando, simplemente sepáralas con un espacio y ponlas todas antes del comando. |
|||
|
|||
/// |
|||
|
|||
@ -150,7 +128,7 @@ Proveniente del ejemplo anterior, tu archivo `config.py` podría verse como: |
|||
|
|||
{* ../../docs_src/settings/app02_an_py39/config.py hl[10] *} |
|||
|
|||
Nota que ahora no creamos una instance por defecto `settings = Settings()`. |
|||
Nota que ahora no creamos un instance por defecto `settings = Settings()`. |
|||
|
|||
### El archivo principal de la app { #the-main-app-file } |
|||
|
|||
@ -172,11 +150,11 @@ Y luego podemos requerirlo desde la *path operation function* como una dependenc |
|||
|
|||
### Configuraciones y pruebas { #settings-and-testing } |
|||
|
|||
Luego sería muy fácil proporcionar un objeto de configuraciones diferente durante las pruebas al sobrescribir una dependencia para `get_settings`: |
|||
Luego sería muy fácil proporcionar un objeto de configuraciones diferente durante las pruebas al crear una sobrescritura de dependencia para `get_settings`: |
|||
|
|||
{* ../../docs_src/settings/app02_an_py39/test_main.py hl[9:10,13,21] *} |
|||
|
|||
En la dependencia sobreescrita establecemos un nuevo valor para el `admin_email` al crear el nuevo objeto `Settings`, y luego devolvemos ese nuevo objeto. |
|||
En la sobrescritura de dependencia establecemos un nuevo valor para el `admin_email` al crear el nuevo objeto `Settings`, y luego devolvemos ese nuevo objeto. |
|||
|
|||
Luego podemos probar que se está usando. |
|||
|
|||
@ -215,8 +193,6 @@ APP_NAME="ChimichangApp" |
|||
|
|||
Y luego actualizar tu `config.py` con: |
|||
|
|||
//// tab | Pydantic v2 |
|||
|
|||
{* ../../docs_src/settings/app03_an_py39/config.py hl[9] *} |
|||
|
|||
/// tip | Consejo |
|||
@ -225,26 +201,6 @@ El atributo `model_config` se usa solo para configuración de Pydantic. Puedes l |
|||
|
|||
/// |
|||
|
|||
//// |
|||
|
|||
//// tab | Pydantic v1 |
|||
|
|||
{* ../../docs_src/settings/app03_an_py39/config_pv1.py hl[9:10] *} |
|||
|
|||
/// tip | Consejo |
|||
|
|||
La clase `Config` se usa solo para configuración de Pydantic. Puedes leer más en <a href="https://docs.pydantic.dev/1.10/usage/model_config/" class="external-link" target="_blank">Pydantic Model Config</a>. |
|||
|
|||
/// |
|||
|
|||
//// |
|||
|
|||
/// info | Información |
|||
|
|||
En la versión 1 de Pydantic la configuración se hacía en una clase interna `Config`, en la versión 2 de Pydantic se hace en un atributo `model_config`. Este atributo toma un `dict`, y para obtener autocompletado y errores en línea, puedes importar y usar `SettingsConfigDict` para definir ese `dict`. |
|||
|
|||
/// |
|||
|
|||
Aquí definimos la configuración `env_file` dentro de tu clase Pydantic `Settings`, y establecemos el valor en el nombre del archivo con el archivo dotenv que queremos usar. |
|||
|
|||
### Creando el `Settings` solo una vez con `lru_cache` { #creating-the-settings-only-once-with-lru-cache } |
|||
@ -331,7 +287,7 @@ participant execute as Ejecutar función |
|||
end |
|||
``` |
|||
|
|||
En el caso de nuestra dependencia `get_settings()`, la función ni siquiera toma argumentos, por lo que siempre devolverá el mismo valor. |
|||
En el caso de nuestra dependencia `get_settings()`, la función ni siquiera toma argumentos, por lo que siempre devuelve el mismo valor. |
|||
|
|||
De esa manera, se comporta casi como si fuera solo una variable global. Pero como usa una función de dependencia, entonces podemos sobrescribirla fácilmente para las pruebas. |
|||
|
|||
|
|||
@ -22,21 +22,13 @@ Aquí tienes una idea general de cómo podrían ser los modelos con sus campos d |
|||
|
|||
{* ../../docs_src/extra_models/tutorial001_py310.py hl[7,9,14,20,22,27:28,31:33,38:39] *} |
|||
|
|||
/// info | Información |
|||
### Acerca de `**user_in.model_dump()` { #about-user-in-model-dump } |
|||
|
|||
En Pydantic v1 el método se llamaba `.dict()`, fue deprecado (pero aún soportado) en Pydantic v2, y renombrado a `.model_dump()`. |
|||
|
|||
Los ejemplos aquí usan `.dict()` para compatibilidad con Pydantic v1, pero deberías usar `.model_dump()` en su lugar si puedes usar Pydantic v2. |
|||
|
|||
/// |
|||
|
|||
### Acerca de `**user_in.dict()` { #about-user-in-dict } |
|||
|
|||
#### `.dict()` de Pydantic { #pydantics-dict } |
|||
#### `.model_dump()` de Pydantic { #pydantics-model-dump } |
|||
|
|||
`user_in` es un modelo Pydantic de la clase `UserIn`. |
|||
|
|||
Los modelos Pydantic tienen un método `.dict()` que devuelve un `dict` con los datos del modelo. |
|||
Los modelos Pydantic tienen un método `.model_dump()` que devuelve un `dict` con los datos del modelo. |
|||
|
|||
Así que, si creamos un objeto Pydantic `user_in` como: |
|||
|
|||
@ -47,7 +39,7 @@ user_in = UserIn(username="john", password="secret", email="[email protected] |
|||
y luego llamamos a: |
|||
|
|||
```Python |
|||
user_dict = user_in.dict() |
|||
user_dict = user_in.model_dump() |
|||
``` |
|||
|
|||
ahora tenemos un `dict` con los datos en la variable `user_dict` (es un `dict` en lugar de un objeto modelo Pydantic). |
|||
@ -58,7 +50,7 @@ Y si llamamos a: |
|||
print(user_dict) |
|||
``` |
|||
|
|||
obtendremos un `dict` de Python con: |
|||
obtendríamos un `dict` de Python con: |
|||
|
|||
```Python |
|||
{ |
|||
@ -103,20 +95,20 @@ UserInDB( |
|||
|
|||
#### Un modelo Pydantic a partir del contenido de otro { #a-pydantic-model-from-the-contents-of-another } |
|||
|
|||
Como en el ejemplo anterior obtuvimos `user_dict` de `user_in.dict()`, este código: |
|||
Como en el ejemplo anterior obtuvimos `user_dict` de `user_in.model_dump()`, este código: |
|||
|
|||
```Python |
|||
user_dict = user_in.dict() |
|||
user_dict = user_in.model_dump() |
|||
UserInDB(**user_dict) |
|||
``` |
|||
|
|||
sería equivalente a: |
|||
|
|||
```Python |
|||
UserInDB(**user_in.dict()) |
|||
UserInDB(**user_in.model_dump()) |
|||
``` |
|||
|
|||
...porque `user_in.dict()` es un `dict`, y luego hacemos que Python lo "desempaquete" al pasarlo a `UserInDB` con el prefijo `**`. |
|||
...porque `user_in.model_dump()` es un `dict`, y luego hacemos que Python lo "desempaquete" al pasarlo a `UserInDB` con el prefijo `**`. |
|||
|
|||
Así, obtenemos un modelo Pydantic a partir de los datos en otro modelo Pydantic. |
|||
|
|||
@ -125,7 +117,7 @@ Así, obtenemos un modelo Pydantic a partir de los datos en otro modelo Pydantic |
|||
Y luego agregando el argumento de palabra clave adicional `hashed_password=hashed_password`, como en: |
|||
|
|||
```Python |
|||
UserInDB(**user_in.dict(), hashed_password=hashed_password) |
|||
UserInDB(**user_in.model_dump(), hashed_password=hashed_password) |
|||
``` |
|||
|
|||
...termina siendo como: |
|||
@ -156,7 +148,7 @@ Y estos modelos están compartiendo muchos de los datos y duplicando nombres y t |
|||
|
|||
Podríamos hacerlo mejor. |
|||
|
|||
Podemos declarar un modelo `UserBase` que sirva como base para nuestros otros modelos. Y luego podemos hacer subclases de ese modelo que heredan sus atributos (anotaciones de tipos, validación, etc). |
|||
Podemos declarar un modelo `UserBase` que sirva como base para nuestros otros modelos. Y luego podemos hacer subclases de ese modelo que heredan sus atributos (declaraciones de tipos, validación, etc). |
|||
|
|||
Toda la conversión de datos, validación, documentación, etc. seguirá funcionando normalmente. |
|||
|
|||
@ -180,20 +172,19 @@ Al definir una <a href="https://docs.pydantic.dev/latest/concepts/types/#unions" |
|||
|
|||
{* ../../docs_src/extra_models/tutorial003_py310.py hl[1,14:15,18:20,33] *} |
|||
|
|||
|
|||
### `Union` en Python 3.10 { #union-in-python-3-10 } |
|||
|
|||
En este ejemplo pasamos `Union[PlaneItem, CarItem]` como el valor del argumento `response_model`. |
|||
|
|||
Porque lo estamos pasando como un **valor a un argumento** en lugar de ponerlo en **anotaciones de tipos**, tenemos que usar `Union` incluso en Python 3.10. |
|||
Porque lo estamos pasando como un **valor a un argumento** en lugar de ponerlo en una **anotación de tipos**, tenemos que usar `Union` incluso en Python 3.10. |
|||
|
|||
Si estuviera en anotaciones de tipos podríamos haber usado la barra vertical, como: |
|||
Si estuviera en una anotación de tipos podríamos haber usado la barra vertical, como: |
|||
|
|||
```Python |
|||
some_variable: PlaneItem | CarItem |
|||
``` |
|||
|
|||
Pero si ponemos eso en la asignación `response_model=PlaneItem | CarItem` obtendríamos un error, porque Python intentaría realizar una **operación inválida** entre `PlaneItem` y `CarItem` en lugar de interpretar eso como anotaciones de tipos. |
|||
Pero si ponemos eso en la asignación `response_model=PlaneItem | CarItem` obtendríamos un error, porque Python intentaría realizar una **operación inválida** entre `PlaneItem` y `CarItem` en lugar de interpretar eso como una anotación de tipos. |
|||
|
|||
## Lista de modelos { #list-of-models } |
|||
|
|||
@ -203,7 +194,6 @@ Para eso, usa el `typing.List` estándar de Python (o simplemente `list` en Pyth |
|||
|
|||
{* ../../docs_src/extra_models/tutorial004_py39.py hl[18] *} |
|||
|
|||
|
|||
## Response con `dict` arbitrario { #response-with-arbitrary-dict } |
|||
|
|||
También puedes declarar un response usando un `dict` arbitrario plano, declarando solo el tipo de las claves y valores, sin usar un modelo Pydantic. |
|||
@ -214,7 +204,6 @@ En este caso, puedes usar `typing.Dict` (o solo `dict` en Python 3.9 y posterior |
|||
|
|||
{* ../../docs_src/extra_models/tutorial005_py39.py hl[6] *} |
|||
|
|||
|
|||
## Recapitulación { #recap } |
|||
|
|||
Usa múltiples modelos Pydantic y hereda libremente para cada caso. |
|||
|
|||
@ -0,0 +1,503 @@ |
|||
# LLM 테스트 파일 { #llm-test-file } |
|||
|
|||
이 문서는 문서를 번역하는 <abbr title="Large Language Model - 대규모 언어 모델">LLM</abbr>이 `scripts/translate.py`의 `general_prompt`와 `docs/{language code}/llm-prompt.md`의 언어별 프롬프트를 이해하는지 테스트합니다. 언어별 프롬프트는 `general_prompt`에 추가됩니다. |
|||
|
|||
여기에 추가된 테스트는 언어별 프롬프트를 설계하는 모든 사람이 보게 됩니다. |
|||
|
|||
사용 방법은 다음과 같습니다: |
|||
|
|||
* 언어별 프롬프트 `docs/{language code}/llm-prompt.md`를 준비합니다. |
|||
* 이 문서를 원하는 대상 언어로 새로 번역합니다(예: `translate.py`의 `translate-page` 명령). 그러면 `docs/{language code}/docs/_llm-test.md` 아래에 번역이 생성됩니다. |
|||
* 번역에서 문제가 없는지 확인합니다. |
|||
* 필요하다면 언어별 프롬프트, 일반 프롬프트, 또는 영어 문서를 개선합니다. |
|||
* 그런 다음 번역에서 남아 있는 문제를 수동으로 수정해 좋은 번역이 되게 합니다. |
|||
* 좋은 번역을 둔 상태에서 다시 번역합니다. 이상적인 결과는 LLM이 더 이상 번역에 변경을 만들지 않는 것입니다. 이는 일반 프롬프트와 언어별 프롬프트가 가능한 한 최선이라는 뜻입니다(때때로 몇 가지 seemingly random 변경을 할 수 있는데, 그 이유는 <a href="https://doublespeak.chat/#/handbook#deterministic-output" class="external-link" target="_blank">LLM은 결정론적 알고리즘이 아니기 때문</a>입니다). |
|||
|
|||
테스트: |
|||
|
|||
## 코드 스니펫 { #code-snippets } |
|||
|
|||
//// tab | 테스트 |
|||
|
|||
다음은 코드 스니펫입니다: `foo`. 그리고 이것은 또 다른 코드 스니펫입니다: `bar`. 그리고 또 하나: `baz quux`. |
|||
|
|||
//// |
|||
|
|||
//// tab | 정보 |
|||
|
|||
코드 스니펫의 내용은 그대로 두어야 합니다. |
|||
|
|||
`scripts/translate.py`의 일반 프롬프트에서 `### Content of code snippets` 섹션을 참고하세요. |
|||
|
|||
//// |
|||
|
|||
## 따옴표 { #quotes } |
|||
|
|||
//// tab | 테스트 |
|||
|
|||
어제 제 친구가 이렇게 썼습니다: "If you spell incorrectly correctly, you have spelled it incorrectly". 이에 저는 이렇게 답했습니다: "Correct, but 'incorrectly' is incorrectly not '"incorrectly"'"". |
|||
|
|||
/// note | 참고 |
|||
|
|||
LLM은 아마 이것을 잘못 번역할 것입니다. 흥미로운 점은 재번역할 때 고정된 번역을 유지하는지 여부뿐입니다. |
|||
|
|||
/// |
|||
|
|||
//// |
|||
|
|||
//// tab | 정보 |
|||
|
|||
프롬프트 설계자는 중립 따옴표를 타이포그래피 따옴표로 변환할지 선택할 수 있습니다. 그대로 두어도 괜찮습니다. |
|||
|
|||
예를 들어 `docs/de/llm-prompt.md`의 `### Quotes` 섹션을 참고하세요. |
|||
|
|||
//// |
|||
|
|||
## 코드 스니펫의 따옴표 { #quotes-in-code-snippets } |
|||
|
|||
//// tab | 테스트 |
|||
|
|||
`pip install "foo[bar]"` |
|||
|
|||
코드 스니펫에서 문자열 리터럴의 예: `"this"`, `'that'`. |
|||
|
|||
코드 스니펫에서 문자열 리터럴의 어려운 예: `f"I like {'oranges' if orange else "apples"}"` |
|||
|
|||
하드코어: `Yesterday, my friend wrote: "If you spell incorrectly correctly, you have spelled it incorrectly". To which I answered: "Correct, but 'incorrectly' is incorrectly not '"incorrectly"'"` |
|||
|
|||
//// |
|||
|
|||
//// tab | 정보 |
|||
|
|||
... 하지만 코드 스니펫 안의 따옴표는 그대로 유지되어야 합니다. |
|||
|
|||
//// |
|||
|
|||
## 코드 블록 { #code-blocks } |
|||
|
|||
//// tab | 테스트 |
|||
|
|||
Bash 코드 예시... |
|||
|
|||
```bash |
|||
# 우주에 인사말 출력 |
|||
echo "Hello universe" |
|||
``` |
|||
|
|||
...그리고 콘솔 코드 예시... |
|||
|
|||
```console |
|||
$ <font color="#4E9A06">fastapi</font> run <u style="text-decoration-style:solid">main.py</u> |
|||
<span style="background-color:#009485"><font color="#D3D7CF"> FastAPI </font></span> Starting server |
|||
Searching for package file structure |
|||
``` |
|||
|
|||
...그리고 또 다른 콘솔 코드 예시... |
|||
|
|||
```console |
|||
// "Code" 디렉터리 생성 |
|||
$ mkdir code |
|||
// 해당 디렉터리로 이동 |
|||
$ cd code |
|||
``` |
|||
|
|||
...그리고 Python 코드 예시... |
|||
|
|||
```Python |
|||
wont_work() # 이건 동작하지 않습니다 😱 |
|||
works(foo="bar") # 이건 동작합니다 🎉 |
|||
``` |
|||
|
|||
...이상입니다. |
|||
|
|||
//// |
|||
|
|||
//// tab | 정보 |
|||
|
|||
코드 블록의 코드는(주석을 제외하고) 수정하면 안 됩니다. |
|||
|
|||
`scripts/translate.py`의 일반 프롬프트에서 `### Content of code blocks` 섹션을 참고하세요. |
|||
|
|||
//// |
|||
|
|||
## 탭과 색상 박스 { #tabs-and-colored-boxes } |
|||
|
|||
//// tab | 테스트 |
|||
|
|||
/// info | 정보 |
|||
일부 텍스트 |
|||
/// |
|||
|
|||
/// note | 참고 |
|||
일부 텍스트 |
|||
/// |
|||
|
|||
/// note Technical details | 기술 세부사항 |
|||
일부 텍스트 |
|||
/// |
|||
|
|||
/// check | 확인 |
|||
일부 텍스트 |
|||
/// |
|||
|
|||
/// tip | 팁 |
|||
일부 텍스트 |
|||
/// |
|||
|
|||
/// warning | 경고 |
|||
일부 텍스트 |
|||
/// |
|||
|
|||
/// danger | 위험 |
|||
일부 텍스트 |
|||
/// |
|||
|
|||
//// |
|||
|
|||
//// tab | 정보 |
|||
|
|||
탭과 `Info`/`Note`/`Warning`/등의 블록은 제목 번역을 수직 막대(`|`) 뒤에 추가해야 합니다. |
|||
|
|||
`scripts/translate.py`의 일반 프롬프트에서 `### Special blocks`와 `### Tab blocks` 섹션을 참고하세요. |
|||
|
|||
//// |
|||
|
|||
## 웹 및 내부 링크 { #web-and-internal-links } |
|||
|
|||
//// tab | 테스트 |
|||
|
|||
링크 텍스트는 번역되어야 하고, 링크 주소는 변경되지 않아야 합니다: |
|||
|
|||
* [위의 제목으로 가는 링크](#code-snippets) |
|||
* [내부 링크](index.md#installation){.internal-link target=_blank} |
|||
* <a href="https://sqlmodel.tiangolo.com/" class="external-link" target="_blank">외부 링크</a> |
|||
* <a href="https://fastapi.tiangolo.com/css/styles.css" class="external-link" target="_blank">스타일로 가는 링크</a> |
|||
* <a href="https://fastapi.tiangolo.com/js/logic.js" class="external-link" target="_blank">스크립트로 가는 링크</a> |
|||
* <a href="https://fastapi.tiangolo.com/img/foo.jpg" class="external-link" target="_blank">이미지로 가는 링크</a> |
|||
|
|||
링크 텍스트는 번역되어야 하고, 링크 주소는 번역 페이지를 가리켜야 합니다: |
|||
|
|||
* <a href="https://fastapi.tiangolo.com/ko/" class="external-link" target="_blank">FastAPI 링크</a> |
|||
|
|||
//// |
|||
|
|||
//// tab | 정보 |
|||
|
|||
링크는 번역되어야 하지만, 주소는 변경되지 않아야 합니다. 예외는 FastAPI 문서 페이지로 향하는 절대 링크이며, 이 경우 번역 페이지로 연결되어야 합니다. |
|||
|
|||
`scripts/translate.py`의 일반 프롬프트에서 `### Links` 섹션을 참고하세요. |
|||
|
|||
//// |
|||
|
|||
## HTML "abbr" 요소 { #html-abbr-elements } |
|||
|
|||
//// tab | 테스트 |
|||
|
|||
여기 HTML "abbr" 요소로 감싼 몇 가지가 있습니다(일부는 임의로 만든 것입니다): |
|||
|
|||
### abbr가 전체 문구를 제공 { #the-abbr-gives-a-full-phrase } |
|||
|
|||
* <abbr title="Getting Things Done - 일을 끝내는 방법론">GTD</abbr> |
|||
* <abbr title="less than - 보다 작음"><code>lt</code></abbr> |
|||
* <abbr title="XML Web Token - XML 웹 토큰">XWT</abbr> |
|||
* <abbr title="Parallel Server Gateway Interface - 병렬 서버 게이트웨이 인터페이스">PSGI</abbr> |
|||
|
|||
### abbr가 설명을 제공 { #the-abbr-gives-an-explanation } |
|||
|
|||
* <abbr title="어떤 방식으로든 서로 연결되고 함께 작동하도록 구성된 머신들의 집합입니다.">cluster</abbr> |
|||
* <abbr title="입력과 출력 계층 사이에 수많은 은닉 계층을 둔 인공 신경망을 사용하는 머신 러닝 방법으로, 이를 통해 포괄적인 내부 구조를 형성합니다">Deep Learning</abbr> |
|||
|
|||
### abbr가 전체 문구와 설명을 제공 { #the-abbr-gives-a-full-phrase-and-an-explanation } |
|||
|
|||
* <abbr title="Mozilla Developer Network - 모질라 개발자 네트워크: Firefox를 만드는 사람들이 작성한 개발자용 문서">MDN</abbr> |
|||
* <abbr title="Input/Output - 입력/출력: 디스크 읽기 또는 쓰기, 네트워크 통신.">I/O</abbr>. |
|||
|
|||
//// |
|||
|
|||
//// tab | 정보 |
|||
|
|||
"abbr" 요소의 "title" 속성은 몇 가지 구체적인 지침에 따라 번역됩니다. |
|||
|
|||
번역에서는(영어 단어를 설명하기 위해) 자체 "abbr" 요소를 추가할 수 있으며, LLM은 이를 제거하면 안 됩니다. |
|||
|
|||
`scripts/translate.py`의 일반 프롬프트에서 `### HTML abbr elements` 섹션을 참고하세요. |
|||
|
|||
//// |
|||
|
|||
## 제목 { #headings } |
|||
|
|||
//// tab | 테스트 |
|||
|
|||
### 웹앱 개발하기 - 튜토리얼 { #develop-a-webapp-a-tutorial } |
|||
|
|||
안녕하세요. |
|||
|
|||
### 타입 힌트와 -애너테이션 { #type-hints-and-annotations } |
|||
|
|||
다시 안녕하세요. |
|||
|
|||
### super- 및 subclasses { #super-and-subclasses } |
|||
|
|||
다시 안녕하세요. |
|||
|
|||
//// |
|||
|
|||
//// tab | 정보 |
|||
|
|||
제목에 대한 유일한 강한 규칙은, LLM이 중괄호 안의 해시 부분을 변경하지 않아 링크가 깨지지 않게 하는 것입니다. |
|||
|
|||
`scripts/translate.py`의 일반 프롬프트에서 `### Headings` 섹션을 참고하세요. |
|||
|
|||
언어별 지침은 예를 들어 `docs/de/llm-prompt.md`의 `### Headings` 섹션을 참고하세요. |
|||
|
|||
//// |
|||
|
|||
## 문서에서 사용되는 용어 { #terms-used-in-the-docs } |
|||
|
|||
//// tab | 테스트 |
|||
|
|||
* 당신 |
|||
* 당신의 |
|||
|
|||
* 예: (e.g.) |
|||
* 등 (etc.) |
|||
|
|||
* `int`로서의 `foo` |
|||
* `str`로서의 `bar` |
|||
* `list`로서의 `baz` |
|||
|
|||
* 튜토리얼 - 사용자 가이드 |
|||
* 고급 사용자 가이드 |
|||
* SQLModel 문서 |
|||
* API 문서 |
|||
* 자동 문서 |
|||
|
|||
* Data Science |
|||
* Deep Learning |
|||
* Machine Learning |
|||
* Dependency Injection |
|||
* HTTP Basic authentication |
|||
* HTTP Digest |
|||
* ISO format |
|||
* JSON Schema 표준 |
|||
* JSON schema |
|||
* schema definition |
|||
* Password Flow |
|||
* Mobile |
|||
|
|||
* deprecated |
|||
* designed |
|||
* invalid |
|||
* on the fly |
|||
* standard |
|||
* default |
|||
* case-sensitive |
|||
* case-insensitive |
|||
|
|||
* 애플리케이션을 서빙하다 |
|||
* 페이지를 서빙하다 |
|||
|
|||
* 앱 |
|||
* 애플리케이션 |
|||
|
|||
* 요청 |
|||
* 응답 |
|||
* 오류 응답 |
|||
|
|||
* 경로 처리 |
|||
* 경로 처리 데코레이터 |
|||
* 경로 처리 함수 |
|||
|
|||
* body |
|||
* 요청 body |
|||
* 응답 body |
|||
* JSON body |
|||
* form body |
|||
* file body |
|||
* 함수 body |
|||
|
|||
* parameter |
|||
* body parameter |
|||
* path parameter |
|||
* query parameter |
|||
* cookie parameter |
|||
* header parameter |
|||
* form parameter |
|||
* function parameter |
|||
|
|||
* event |
|||
* startup event |
|||
* 서버 startup |
|||
* shutdown event |
|||
* lifespan event |
|||
|
|||
* handler |
|||
* event handler |
|||
* exception handler |
|||
* 처리하다 |
|||
|
|||
* model |
|||
* Pydantic model |
|||
* data model |
|||
* database model |
|||
* form model |
|||
* model object |
|||
|
|||
* class |
|||
* base class |
|||
* parent class |
|||
* subclass |
|||
* child class |
|||
* sibling class |
|||
* class method |
|||
|
|||
* header |
|||
* headers |
|||
* authorization header |
|||
* `Authorization` header |
|||
* forwarded header |
|||
|
|||
* dependency injection system |
|||
* dependency |
|||
* dependable |
|||
* dependant |
|||
|
|||
* I/O bound |
|||
* CPU bound |
|||
* concurrency |
|||
* parallelism |
|||
* multiprocessing |
|||
|
|||
* env var |
|||
* environment variable |
|||
* `PATH` |
|||
* `PATH` variable |
|||
|
|||
* authentication |
|||
* authentication provider |
|||
* authorization |
|||
* authorization form |
|||
* authorization provider |
|||
* 사용자가 인증한다 |
|||
* 시스템이 사용자를 인증한다 |
|||
|
|||
* CLI |
|||
* command line interface |
|||
|
|||
* server |
|||
* client |
|||
|
|||
* cloud provider |
|||
* cloud service |
|||
|
|||
* development |
|||
* development stages |
|||
|
|||
* dict |
|||
* dictionary |
|||
* enumeration |
|||
* enum |
|||
* enum member |
|||
|
|||
* encoder |
|||
* decoder |
|||
* encode하다 |
|||
* decode하다 |
|||
|
|||
* exception |
|||
* raise하다 |
|||
|
|||
* expression |
|||
* statement |
|||
|
|||
* frontend |
|||
* backend |
|||
|
|||
* GitHub discussion |
|||
* GitHub issue |
|||
|
|||
* performance |
|||
* performance optimization |
|||
|
|||
* return type |
|||
* return value |
|||
|
|||
* security |
|||
* security scheme |
|||
|
|||
* task |
|||
* background task |
|||
* task function |
|||
|
|||
* template |
|||
* template engine |
|||
|
|||
* type annotation |
|||
* type hint |
|||
|
|||
* server worker |
|||
* Uvicorn worker |
|||
* Gunicorn Worker |
|||
* worker process |
|||
* worker class |
|||
* workload |
|||
|
|||
* deployment |
|||
* deploy하다 |
|||
|
|||
* SDK |
|||
* software development kit |
|||
|
|||
* `APIRouter` |
|||
* `requirements.txt` |
|||
* Bearer Token |
|||
* breaking change |
|||
* bug |
|||
* button |
|||
* callable |
|||
* code |
|||
* commit |
|||
* context manager |
|||
* coroutine |
|||
* database session |
|||
* disk |
|||
* domain |
|||
* engine |
|||
* fake X |
|||
* HTTP GET method |
|||
* item |
|||
* library |
|||
* lifespan |
|||
* lock |
|||
* middleware |
|||
* mobile application |
|||
* module |
|||
* mounting |
|||
* network |
|||
* origin |
|||
* override |
|||
* payload |
|||
* processor |
|||
* property |
|||
* proxy |
|||
* pull request |
|||
* query |
|||
* RAM |
|||
* remote machine |
|||
* status code |
|||
* string |
|||
* tag |
|||
* web framework |
|||
* wildcard |
|||
* return하다 |
|||
* validate하다 |
|||
|
|||
//// |
|||
|
|||
//// tab | 정보 |
|||
|
|||
이것은 문서에서 보이는 (대부분) 기술 용어의 불완전하고 비규범적인 목록입니다. 프롬프트 설계자가 어떤 용어에 대해 LLM에 추가적인 도움이 필요한지 파악하는 데 유용할 수 있습니다. 예를 들어, 좋은 번역을 계속 덜 좋은 번역으로 되돌릴 때, 또는 언어에서 용어의 활용/변화를 처리하는 데 문제가 있을 때 도움이 됩니다. |
|||
|
|||
예를 들어 `docs/de/llm-prompt.md`의 `### List of English terms and their preferred German translations` 섹션을 참고하세요. |
|||
|
|||
//// |
|||
@ -1,3 +1,3 @@ |
|||
# 소개 |
|||
# 소개 { #about } |
|||
|
|||
FastAPI에 대한 디자인, 영감 등에 대해 🤓 |
|||
FastAPI, 그 디자인, 영감 등에 대해 🤓 |
|||
|
|||
@ -0,0 +1,247 @@ |
|||
# OpenAPI에서 추가 응답 { #additional-responses-in-openapi } |
|||
|
|||
/// warning | 경고 |
|||
|
|||
이는 꽤 고급 주제입니다. |
|||
|
|||
**FastAPI**를 막 시작했다면, 이 내용이 필요 없을 수도 있습니다. |
|||
|
|||
/// |
|||
|
|||
추가 상태 코드, 미디어 타입, 설명 등을 포함한 추가 응답을 선언할 수 있습니다. |
|||
|
|||
이러한 추가 응답은 OpenAPI 스키마에 포함되므로 API 문서에도 표시됩니다. |
|||
|
|||
하지만 이러한 추가 응답의 경우, 상태 코드와 콘텐츠를 포함하여 `JSONResponse` 같은 `Response`를 직접 반환하도록 반드시 처리해야 합니다. |
|||
|
|||
## `model`을 사용한 추가 응답 { #additional-response-with-model } |
|||
|
|||
*경로 처리 데코레이터*에 `responses` 파라미터를 전달할 수 있습니다. |
|||
|
|||
이는 `dict`를 받습니다. 키는 각 응답의 상태 코드(예: `200`)이고, 값은 각 응답에 대한 정보를 담은 다른 `dict`입니다. |
|||
|
|||
각 응답 `dict`에는 `response_model`처럼 Pydantic 모델을 담는 `model` 키가 있을 수 있습니다. |
|||
|
|||
**FastAPI**는 그 모델을 사용해 JSON Schema를 생성하고, OpenAPI의 올바른 위치에 포함합니다. |
|||
|
|||
예를 들어, 상태 코드 `404`와 Pydantic 모델 `Message`를 사용하는 다른 응답을 선언하려면 다음과 같이 작성할 수 있습니다: |
|||
|
|||
{* ../../docs_src/additional_responses/tutorial001_py39.py hl[18,22] *} |
|||
|
|||
/// note | 참고 |
|||
|
|||
`JSONResponse`를 직접 반환해야 한다는 점을 기억하세요. |
|||
|
|||
/// |
|||
|
|||
/// info | 정보 |
|||
|
|||
`model` 키는 OpenAPI의 일부가 아닙니다. |
|||
|
|||
**FastAPI**는 여기에서 Pydantic 모델을 가져와 JSON Schema를 생성하고 올바른 위치에 넣습니다. |
|||
|
|||
올바른 위치는 다음과 같습니다: |
|||
|
|||
* 값으로 또 다른 JSON 객체(`dict`)를 가지는 `content` 키 안에: |
|||
* 미디어 타입(예: `application/json`)을 키로 가지며, 값으로 또 다른 JSON 객체를 포함하고: |
|||
* `schema` 키가 있고, 그 값이 모델에서 생성된 JSON Schema입니다. 이것이 올바른 위치입니다. |
|||
* **FastAPI**는 이를 직접 포함하는 대신, OpenAPI의 다른 위치에 있는 전역 JSON Schemas를 참조하도록 여기에서 reference를 추가합니다. 이렇게 하면 다른 애플리케이션과 클라이언트가 그 JSON Schema를 직접 사용할 수 있고, 더 나은 코드 생성 도구 등을 제공할 수 있습니다. |
|||
|
|||
/// |
|||
|
|||
이 *경로 처리*에 대해 OpenAPI에 생성되는 응답은 다음과 같습니다: |
|||
|
|||
```JSON hl_lines="3-12" |
|||
{ |
|||
"responses": { |
|||
"404": { |
|||
"description": "Additional Response", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"$ref": "#/components/schemas/Message" |
|||
} |
|||
} |
|||
} |
|||
}, |
|||
"200": { |
|||
"description": "Successful Response", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"$ref": "#/components/schemas/Item" |
|||
} |
|||
} |
|||
} |
|||
}, |
|||
"422": { |
|||
"description": "Validation Error", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": { |
|||
"$ref": "#/components/schemas/HTTPValidationError" |
|||
} |
|||
} |
|||
} |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
스키마는 OpenAPI 스키마 내부의 다른 위치를 참조합니다: |
|||
|
|||
```JSON hl_lines="4-16" |
|||
{ |
|||
"components": { |
|||
"schemas": { |
|||
"Message": { |
|||
"title": "Message", |
|||
"required": [ |
|||
"message" |
|||
], |
|||
"type": "object", |
|||
"properties": { |
|||
"message": { |
|||
"title": "Message", |
|||
"type": "string" |
|||
} |
|||
} |
|||
}, |
|||
"Item": { |
|||
"title": "Item", |
|||
"required": [ |
|||
"id", |
|||
"value" |
|||
], |
|||
"type": "object", |
|||
"properties": { |
|||
"id": { |
|||
"title": "Id", |
|||
"type": "string" |
|||
}, |
|||
"value": { |
|||
"title": "Value", |
|||
"type": "string" |
|||
} |
|||
} |
|||
}, |
|||
"ValidationError": { |
|||
"title": "ValidationError", |
|||
"required": [ |
|||
"loc", |
|||
"msg", |
|||
"type" |
|||
], |
|||
"type": "object", |
|||
"properties": { |
|||
"loc": { |
|||
"title": "Location", |
|||
"type": "array", |
|||
"items": { |
|||
"type": "string" |
|||
} |
|||
}, |
|||
"msg": { |
|||
"title": "Message", |
|||
"type": "string" |
|||
}, |
|||
"type": { |
|||
"title": "Error Type", |
|||
"type": "string" |
|||
} |
|||
} |
|||
}, |
|||
"HTTPValidationError": { |
|||
"title": "HTTPValidationError", |
|||
"type": "object", |
|||
"properties": { |
|||
"detail": { |
|||
"title": "Detail", |
|||
"type": "array", |
|||
"items": { |
|||
"$ref": "#/components/schemas/ValidationError" |
|||
} |
|||
} |
|||
} |
|||
} |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
## 주요 응답에 대한 추가 미디어 타입 { #additional-media-types-for-the-main-response } |
|||
|
|||
같은 `responses` 파라미터를 사용해 동일한 주요 응답에 대해 다른 미디어 타입을 추가할 수도 있습니다. |
|||
|
|||
예를 들어, *경로 처리*가 JSON 객체(미디어 타입 `application/json`) 또는 PNG 이미지(미디어 타입 `image/png`)를 반환할 수 있다고 선언하기 위해 `image/png`라는 추가 미디어 타입을 추가할 수 있습니다: |
|||
|
|||
{* ../../docs_src/additional_responses/tutorial002_py310.py hl[17:22,26] *} |
|||
|
|||
/// note | 참고 |
|||
|
|||
이미지는 `FileResponse`를 사용해 직접 반환해야 한다는 점에 유의하세요. |
|||
|
|||
/// |
|||
|
|||
/// info | 정보 |
|||
|
|||
`responses` 파라미터에서 다른 미디어 타입을 명시적으로 지정하지 않는 한, FastAPI는 응답이 주요 응답 클래스와 동일한 미디어 타입(기본값 `application/json`)을 가진다고 가정합니다. |
|||
|
|||
하지만 커스텀 응답 클래스를 지정하면서 미디어 타입을 `None`으로 설정했다면, FastAPI는 연결된 모델이 있는 모든 추가 응답에 대해 `application/json`을 사용합니다. |
|||
|
|||
/// |
|||
|
|||
## 정보 결합하기 { #combining-information } |
|||
|
|||
`response_model`, `status_code`, `responses` 파라미터를 포함해 여러 위치의 응답 정보를 결합할 수도 있습니다. |
|||
|
|||
기본 상태 코드 `200`(또는 필요하다면 커스텀 코드)을 사용하여 `response_model`을 선언하고, 그와 동일한 응답에 대한 추가 정보를 `responses`에서 OpenAPI 스키마에 직접 선언할 수 있습니다. |
|||
|
|||
**FastAPI**는 `responses`의 추가 정보를 유지하고, 모델의 JSON Schema와 결합합니다. |
|||
|
|||
예를 들어, Pydantic 모델을 사용하고 커스텀 `description`을 가진 상태 코드 `404` 응답을 선언할 수 있습니다. |
|||
|
|||
또한 `response_model`을 사용하는 상태 코드 `200` 응답을 선언하되, 커스텀 `example`을 포함할 수도 있습니다: |
|||
|
|||
{* ../../docs_src/additional_responses/tutorial003_py39.py hl[20:31] *} |
|||
|
|||
이 모든 내용은 OpenAPI에 결합되어 포함되고, API 문서에 표시됩니다: |
|||
|
|||
<img src="/img/tutorial/additional-responses/image01.png"> |
|||
|
|||
## 미리 정의된 응답과 커스텀 응답 결합하기 { #combine-predefined-responses-and-custom-ones } |
|||
|
|||
여러 *경로 처리*에 적용되는 미리 정의된 응답이 필요할 수도 있지만, 각 *경로 처리*마다 필요한 커스텀 응답과 결합하고 싶을 수도 있습니다. |
|||
|
|||
그런 경우 Python의 `dict` “unpacking” 기법인 `**dict_to_unpack`을 사용할 수 있습니다: |
|||
|
|||
```Python |
|||
old_dict = { |
|||
"old key": "old value", |
|||
"second old key": "second old value", |
|||
} |
|||
new_dict = {**old_dict, "new key": "new value"} |
|||
``` |
|||
|
|||
여기서 `new_dict`는 `old_dict`의 모든 키-값 쌍에 더해 새 키-값 쌍까지 포함합니다: |
|||
|
|||
```Python |
|||
{ |
|||
"old key": "old value", |
|||
"second old key": "second old value", |
|||
"new key": "new value", |
|||
} |
|||
``` |
|||
|
|||
이 기법을 사용해 *경로 처리*에서 일부 미리 정의된 응답을 재사용하고, 추가 커스텀 응답과 결합할 수 있습니다. |
|||
|
|||
예를 들어: |
|||
|
|||
{* ../../docs_src/additional_responses/tutorial004_py310.py hl[11:15,24] *} |
|||
|
|||
## OpenAPI 응답에 대한 추가 정보 { #more-information-about-openapi-responses } |
|||
|
|||
응답에 정확히 무엇을 포함할 수 있는지 보려면, OpenAPI 사양의 다음 섹션을 확인하세요: |
|||
|
|||
* <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#responses-object" class="external-link" target="_blank">OpenAPI Responses Object</a>: `Response Object`를 포함합니다. |
|||
* <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#response-object" class="external-link" target="_blank">OpenAPI Response Object</a>: `responses` 파라미터 안의 각 응답에 이것의 어떤 항목이든 직접 포함할 수 있습니다. `description`, `headers`, `content`(여기에서 서로 다른 미디어 타입과 JSON Schema를 선언합니다), `links` 등을 포함할 수 있습니다. |
|||
@ -0,0 +1,466 @@ |
|||
# 프록시 뒤에서 실행하기 { #behind-a-proxy } |
|||
|
|||
많은 경우 FastAPI 앱 앞단에 Traefik이나 Nginx 같은 **프록시(proxy)**를 두고 사용합니다. |
|||
|
|||
이런 프록시는 HTTPS 인증서 처리 등 여러 작업을 담당할 수 있습니다. |
|||
|
|||
## 프록시 전달 헤더 { #proxy-forwarded-headers } |
|||
|
|||
애플리케이션 앞단의 **프록시**는 보통 **서버**로 요청을 보내기 전에, 해당 요청이 프록시에 의해 **전달(forwarded)**되었다는 것을 서버가 알 수 있도록 몇몇 헤더를 동적으로 설정합니다. 이를 통해 서버는 도메인을 포함한 원래의 (공개) URL, HTTPS 사용 여부 등 정보를 알 수 있습니다. |
|||
|
|||
**서버** 프로그램(예: **FastAPI CLI**를 통해 실행되는 **Uvicorn**)은 이런 헤더를 해석할 수 있고, 그 정보를 애플리케이션으로 전달할 수 있습니다. |
|||
|
|||
하지만 보안상, 서버는 자신이 신뢰할 수 있는 프록시 뒤에 있다는 것을 모르면 해당 헤더를 해석하지 않습니다. |
|||
|
|||
/// note | 기술 세부사항 |
|||
|
|||
프록시 헤더는 다음과 같습니다: |
|||
|
|||
* <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Forwarded-For" class="external-link" target="_blank">X-Forwarded-For</a> |
|||
* <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Forwarded-Proto" class="external-link" target="_blank">X-Forwarded-Proto</a> |
|||
* <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Forwarded-Host" class="external-link" target="_blank">X-Forwarded-Host</a> |
|||
|
|||
/// |
|||
|
|||
### 프록시 전달 헤더 활성화하기 { #enable-proxy-forwarded-headers } |
|||
|
|||
FastAPI CLI를 *CLI 옵션* `--forwarded-allow-ips`로 실행하고, 전달 헤더를 읽을 수 있도록 신뢰할 IP 주소들을 넘길 수 있습니다. |
|||
|
|||
`--forwarded-allow-ips="*"`로 설정하면 들어오는 모든 IP를 신뢰합니다. |
|||
|
|||
**서버**가 신뢰할 수 있는 **프록시** 뒤에 있고 프록시만 서버에 접근한다면, 이는 해당 **프록시**의 IP가 무엇이든 간에 받아들이게 됩니다. |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ fastapi run --forwarded-allow-ips="*" |
|||
|
|||
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
### HTTPS에서 리디렉션 { #redirects-with-https } |
|||
|
|||
예를 들어, *경로 처리* `/items/`를 정의했다고 해봅시다: |
|||
|
|||
{* ../../docs_src/behind_a_proxy/tutorial001_01_py39.py hl[6] *} |
|||
|
|||
클라이언트가 `/items`로 접근하면, 기본적으로 `/items/`로 리디렉션됩니다. |
|||
|
|||
하지만 *CLI 옵션* `--forwarded-allow-ips`를 설정하기 전에는 `http://localhost:8000/items/`로 리디렉션될 수 있습니다. |
|||
|
|||
그런데 애플리케이션이 `https://mysuperapp.com`에 호스팅되어 있고, 리디렉션도 `https://mysuperapp.com/items/`로 되어야 할 수 있습니다. |
|||
|
|||
이때 `--proxy-headers`를 설정하면 FastAPI가 올바른 위치로 리디렉션할 수 있습니다. 😎 |
|||
|
|||
``` |
|||
https://mysuperapp.com/items/ |
|||
``` |
|||
|
|||
/// tip | 팁 |
|||
|
|||
HTTPS에 대해 더 알아보려면 가이드 [HTTPS에 대하여](../deployment/https.md){.internal-link target=_blank}를 확인하세요. |
|||
|
|||
/// |
|||
|
|||
### 프록시 전달 헤더가 동작하는 방식 { #how-proxy-forwarded-headers-work } |
|||
|
|||
다음은 **프록시**가 클라이언트와 **애플리케이션 서버** 사이에서 전달 헤더를 추가하는 과정을 시각적으로 나타낸 것입니다: |
|||
|
|||
```mermaid |
|||
sequenceDiagram |
|||
participant Client |
|||
participant Proxy as Proxy/Load Balancer |
|||
participant Server as FastAPI Server |
|||
|
|||
Client->>Proxy: HTTPS Request<br/>Host: mysuperapp.com<br/>Path: /items |
|||
|
|||
Note over Proxy: Proxy adds forwarded headers |
|||
|
|||
Proxy->>Server: HTTP Request<br/>X-Forwarded-For: [client IP]<br/>X-Forwarded-Proto: https<br/>X-Forwarded-Host: mysuperapp.com<br/>Path: /items |
|||
|
|||
Note over Server: Server interprets headers<br/>(if --forwarded-allow-ips is set) |
|||
|
|||
Server->>Proxy: HTTP Response<br/>with correct HTTPS URLs |
|||
|
|||
Proxy->>Client: HTTPS Response |
|||
``` |
|||
|
|||
**프록시**는 원래의 클라이언트 요청을 가로채고, **애플리케이션 서버**로 요청을 전달하기 전에 특수한 *forwarded* 헤더(`X-Forwarded-*`)를 추가합니다. |
|||
|
|||
이 헤더들은 그렇지 않으면 사라질 수 있는 원래 요청의 정보를 보존합니다: |
|||
|
|||
* **X-Forwarded-For**: 원래 클라이언트의 IP 주소 |
|||
* **X-Forwarded-Proto**: 원래 프로토콜(`https`) |
|||
* **X-Forwarded-Host**: 원래 호스트(`mysuperapp.com`) |
|||
|
|||
**FastAPI CLI**를 `--forwarded-allow-ips`로 설정하면, 이 헤더를 신뢰하고 사용합니다. 예를 들어 리디렉션에서 올바른 URL을 생성하는 데 사용됩니다. |
|||
|
|||
## 제거된 경로 접두사를 가진 프록시 { #proxy-with-a-stripped-path-prefix } |
|||
|
|||
애플리케이션에 경로 접두사(prefix)를 추가하는 프록시를 둘 수도 있습니다. |
|||
|
|||
이런 경우 `root_path`를 사용해 애플리케이션을 구성할 수 있습니다. |
|||
|
|||
`root_path`는 (FastAPI가 Starlette를 통해 기반으로 하는) ASGI 사양에서 제공하는 메커니즘입니다. |
|||
|
|||
`root_path`는 이러한 특정 사례를 처리하는 데 사용됩니다. |
|||
|
|||
또한 서브 애플리케이션을 마운트할 때 내부적으로도 사용됩니다. |
|||
|
|||
경로 접두사가 제거(stripped)되는 프록시가 있다는 것은, 코드에서는 `/app`에 경로를 선언하지만, 위에 한 겹(프록시)을 추가해 **FastAPI** 애플리케이션을 `/api/v1` 같은 경로 아래에 두는 것을 의미합니다. |
|||
|
|||
이 경우 원래 경로 `/app`은 실제로 `/api/v1/app`에서 서비스됩니다. |
|||
|
|||
코드는 모두 `/app`만 있다고 가정하고 작성되어 있는데도 말입니다. |
|||
|
|||
{* ../../docs_src/behind_a_proxy/tutorial001_py39.py hl[6] *} |
|||
|
|||
그리고 프록시는 요청을 앱 서버(아마 FastAPI CLI를 통해 실행되는 Uvicorn)로 전달하기 전에, 동적으로 **경로 접두사**를 **"제거"**합니다. 그래서 애플리케이션은 여전히 `/app`에서 서비스된다고 믿게 되고, 코드 전체를 `/api/v1` 접두사를 포함하도록 수정할 필요가 없어집니다. |
|||
|
|||
여기까지는 보통 정상적으로 동작합니다. |
|||
|
|||
하지만 통합 문서 UI(프론트엔드)를 열면, OpenAPI 스키마를 `/api/v1/openapi.json`이 아니라 `/openapi.json`에서 가져오려고 합니다. |
|||
|
|||
그래서 브라우저에서 실행되는 프론트엔드는 `/openapi.json`에 접근하려고 시도하지만 OpenAPI 스키마를 얻지 못합니다. |
|||
|
|||
앱에 대해 `/api/v1` 경로 접두사를 가진 프록시가 있으므로, 프론트엔드는 `/api/v1/openapi.json`에서 OpenAPI 스키마를 가져와야 합니다. |
|||
|
|||
```mermaid |
|||
graph LR |
|||
|
|||
browser("Browser") |
|||
proxy["Proxy on http://0.0.0.0:9999/api/v1/app"] |
|||
server["Server on http://127.0.0.1:8000/app"] |
|||
|
|||
browser --> proxy |
|||
proxy --> server |
|||
``` |
|||
|
|||
/// tip | 팁 |
|||
|
|||
IP `0.0.0.0`은 보통 해당 머신/서버에서 사용 가능한 모든 IP에서 프로그램이 리슨한다는 의미로 사용됩니다. |
|||
|
|||
/// |
|||
|
|||
문서 UI는 또한 OpenAPI 스키마에서 이 API `server`가 `/api/v1`(프록시 뒤) 위치에 있다고 선언해야 합니다. 예: |
|||
|
|||
```JSON hl_lines="4-8" |
|||
{ |
|||
"openapi": "3.1.0", |
|||
// More stuff here |
|||
"servers": [ |
|||
{ |
|||
"url": "/api/v1" |
|||
} |
|||
], |
|||
"paths": { |
|||
// More stuff here |
|||
} |
|||
} |
|||
``` |
|||
|
|||
이 예시에서 "Proxy"는 **Traefik** 같은 것이고, 서버는 **Uvicorn**으로 실행되는 FastAPI CLI처럼, FastAPI 애플리케이션을 실행하는 구성일 수 있습니다. |
|||
|
|||
### `root_path` 제공하기 { #providing-the-root-path } |
|||
|
|||
이를 달성하려면 다음처럼 커맨드 라인 옵션 `--root-path`를 사용할 수 있습니다: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 |
|||
|
|||
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
Hypercorn을 사용한다면, Hypercorn에도 `--root-path` 옵션이 있습니다. |
|||
|
|||
/// note | 기술 세부사항 |
|||
|
|||
ASGI 사양은 이 사용 사례를 위해 `root_path`를 정의합니다. |
|||
|
|||
그리고 커맨드 라인 옵션 `--root-path`가 그 `root_path`를 제공합니다. |
|||
|
|||
/// |
|||
|
|||
### 현재 `root_path` 확인하기 { #checking-the-current-root-path } |
|||
|
|||
요청마다 애플리케이션에서 사용 중인 현재 `root_path`를 얻을 수 있는데, 이는 `scope` 딕셔너리(ASGI 사양의 일부)에 포함되어 있습니다. |
|||
|
|||
여기서는 데모 목적을 위해 메시지에 포함하고 있습니다. |
|||
|
|||
{* ../../docs_src/behind_a_proxy/tutorial001_py39.py hl[8] *} |
|||
|
|||
그 다음 Uvicorn을 다음과 같이 시작하면: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 |
|||
|
|||
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
응답은 다음과 비슷할 것입니다: |
|||
|
|||
```JSON |
|||
{ |
|||
"message": "Hello World", |
|||
"root_path": "/api/v1" |
|||
} |
|||
``` |
|||
|
|||
### FastAPI 앱에서 `root_path` 설정하기 { #setting-the-root-path-in-the-fastapi-app } |
|||
|
|||
또는 `--root-path` 같은 커맨드 라인 옵션(또는 동등한 방법)을 제공할 수 없는 경우, FastAPI 앱을 생성할 때 `root_path` 파라미터를 설정할 수 있습니다: |
|||
|
|||
{* ../../docs_src/behind_a_proxy/tutorial002_py39.py hl[3] *} |
|||
|
|||
`FastAPI`에 `root_path`를 전달하는 것은 Uvicorn이나 Hypercorn에 커맨드 라인 옵션 `--root-path`를 전달하는 것과 동일합니다. |
|||
|
|||
### `root_path`에 대하여 { #about-root-path } |
|||
|
|||
서버(Uvicorn)는 그 `root_path`를 앱에 전달하는 것 외에는 다른 용도로 사용하지 않는다는 점을 기억하세요. |
|||
|
|||
하지만 브라우저로 <a href="http://127.0.0.1:8000/app" class="external-link" target="_blank">http://127.0.0.1:8000/app</a>에 접속하면 정상 응답을 볼 수 있습니다: |
|||
|
|||
```JSON |
|||
{ |
|||
"message": "Hello World", |
|||
"root_path": "/api/v1" |
|||
} |
|||
``` |
|||
|
|||
따라서 `http://127.0.0.1:8000/api/v1/app`로 접근될 것이라고 기대하지는 않습니다. |
|||
|
|||
Uvicorn은 프록시가 `http://127.0.0.1:8000/app`에서 Uvicorn에 접근할 것을 기대하고, 그 위에 `/api/v1` 접두사를 추가하는 것은 프록시의 책임입니다. |
|||
|
|||
## 제거된 경로 접두사를 가진 프록시에 대하여 { #about-proxies-with-a-stripped-path-prefix } |
|||
|
|||
경로 접두사가 제거되는 프록시는 구성 방법 중 하나일 뿐이라는 점을 기억하세요. |
|||
|
|||
많은 경우 기본값은 프록시가 경로 접두사를 제거하지 않는 방식일 것입니다. |
|||
|
|||
그런 경우(경로 접두사를 제거하지 않는 경우) 프록시는 `https://myawesomeapp.com` 같은 곳에서 리슨하고, 브라우저가 `https://myawesomeapp.com/api/v1/app`로 접근하면, 서버(예: Uvicorn)가 `http://127.0.0.1:8000`에서 리슨하고 있을 때 프록시(경로 접두사를 제거하지 않는)는 동일한 경로로 Uvicorn에 접근합니다: `http://127.0.0.1:8000/api/v1/app`. |
|||
|
|||
## Traefik으로 로컬 테스트하기 { #testing-locally-with-traefik } |
|||
|
|||
<a href="https://docs.traefik.io/" class="external-link" target="_blank">Traefik</a>을 사용하면, 경로 접두사가 제거되는 구성을 로컬에서 쉽게 실험할 수 있습니다. |
|||
|
|||
<a href="https://github.com/containous/traefik/releases" class="external-link" target="_blank">Traefik 다운로드</a>는 단일 바이너리이며, 압축 파일을 풀고 터미널에서 바로 실행할 수 있습니다. |
|||
|
|||
그 다음 다음 내용을 가진 `traefik.toml` 파일을 생성하세요: |
|||
|
|||
```TOML hl_lines="3" |
|||
[entryPoints] |
|||
[entryPoints.http] |
|||
address = ":9999" |
|||
|
|||
[providers] |
|||
[providers.file] |
|||
filename = "routes.toml" |
|||
``` |
|||
|
|||
이는 Traefik이 9999 포트에서 리슨하고, 다른 파일 `routes.toml`을 사용하도록 지시합니다. |
|||
|
|||
/// tip | 팁 |
|||
|
|||
표준 HTTP 포트 80 대신 9999 포트를 사용해서, 관리자(`sudo`) 권한으로 실행하지 않아도 되게 했습니다. |
|||
|
|||
/// |
|||
|
|||
이제 다른 파일 `routes.toml`을 생성하세요: |
|||
|
|||
```TOML hl_lines="5 12 20" |
|||
[http] |
|||
[http.middlewares] |
|||
|
|||
[http.middlewares.api-stripprefix.stripPrefix] |
|||
prefixes = ["/api/v1"] |
|||
|
|||
[http.routers] |
|||
|
|||
[http.routers.app-http] |
|||
entryPoints = ["http"] |
|||
service = "app" |
|||
rule = "PathPrefix(`/api/v1`)" |
|||
middlewares = ["api-stripprefix"] |
|||
|
|||
[http.services] |
|||
|
|||
[http.services.app] |
|||
[http.services.app.loadBalancer] |
|||
[[http.services.app.loadBalancer.servers]] |
|||
url = "http://127.0.0.1:8000" |
|||
``` |
|||
|
|||
이 파일은 Traefik이 경로 접두사 `/api/v1`을 사용하도록 설정합니다. |
|||
|
|||
그리고 Traefik은 요청을 `http://127.0.0.1:8000`에서 실행 중인 Uvicorn으로 전달합니다. |
|||
|
|||
이제 Traefik을 시작하세요: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ ./traefik --configFile=traefik.toml |
|||
|
|||
INFO[0000] Configuration loaded from file: /home/user/awesomeapi/traefik.toml |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
그리고 `--root-path` 옵션을 사용해 앱을 시작하세요: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 |
|||
|
|||
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
### 응답 확인하기 { #check-the-responses } |
|||
|
|||
이제 Uvicorn의 포트로 된 URL인 <a href="http://127.0.0.1:8000/app" class="external-link" target="_blank">http://127.0.0.1:8000/app</a>로 접속하면 정상 응답을 볼 수 있습니다: |
|||
|
|||
```JSON |
|||
{ |
|||
"message": "Hello World", |
|||
"root_path": "/api/v1" |
|||
} |
|||
``` |
|||
|
|||
/// tip | 팁 |
|||
|
|||
`http://127.0.0.1:8000/app`로 접근했는데도 `/api/v1`의 `root_path`가 표시되는 것에 주의하세요. 이는 옵션 `--root-path`에서 가져온 값입니다. |
|||
|
|||
/// |
|||
|
|||
이제 Traefik의 포트가 포함되고 경로 접두사가 포함된 URL <a href="http://127.0.0.1:9999/api/v1/app" class="external-link" target="_blank">http://127.0.0.1:9999/api/v1/app</a>을 여세요. |
|||
|
|||
동일한 응답을 얻습니다: |
|||
|
|||
```JSON |
|||
{ |
|||
"message": "Hello World", |
|||
"root_path": "/api/v1" |
|||
} |
|||
``` |
|||
|
|||
하지만 이번에는 프록시가 제공한 접두사 경로 `/api/v1`이 포함된 URL에서의 응답입니다. |
|||
|
|||
물론 여기서의 아이디어는 모두가 프록시를 통해 앱에 접근한다는 것이므로, `/api/v1` 경로 접두사가 있는 버전이 "올바른" 접근입니다. |
|||
|
|||
그리고 경로 접두사가 없는 버전(`http://127.0.0.1:8000/app`)은 Uvicorn이 직접 제공하는 것이며, 오직 _프록시_(Traefik)가 접근하기 위한 용도입니다. |
|||
|
|||
이는 프록시(Traefik)가 경로 접두사를 어떻게 사용하는지, 그리고 서버(Uvicorn)가 옵션 `--root-path`로부터의 `root_path`를 어떻게 사용하는지를 보여줍니다. |
|||
|
|||
### 문서 UI 확인하기 { #check-the-docs-ui } |
|||
|
|||
하지만 재미있는 부분은 여기입니다. ✨ |
|||
|
|||
앱에 접근하는 "공식" 방법은 우리가 정의한 경로 접두사를 가진 프록시를 통해서입니다. 따라서 기대하는 대로, URL에 경로 접두사가 없는 상태에서 Uvicorn이 직접 제공하는 docs UI를 시도하면, 프록시를 통해 접근된다고 가정하고 있기 때문에 동작하지 않습니다. |
|||
|
|||
<a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>에서 확인할 수 있습니다: |
|||
|
|||
<img src="/img/tutorial/behind-a-proxy/image01.png"> |
|||
|
|||
하지만 프록시(포트 `9999`)를 사용해 "공식" URL인 `/api/v1/docs`에서 docs UI에 접근하면, 올바르게 동작합니다! 🎉 |
|||
|
|||
<a href="http://127.0.0.1:9999/api/v1/docs" class="external-link" target="_blank">http://127.0.0.1:9999/api/v1/docs</a>에서 확인할 수 있습니다: |
|||
|
|||
<img src="/img/tutorial/behind-a-proxy/image02.png"> |
|||
|
|||
원하던 그대로입니다. ✔️ |
|||
|
|||
이는 FastAPI가 이 `root_path`를 사용해, OpenAPI에서 기본 `server`를 `root_path`가 제공한 URL로 생성하기 때문입니다. |
|||
|
|||
## 추가 서버 { #additional-servers } |
|||
|
|||
/// warning | 경고 |
|||
|
|||
이는 더 고급 사용 사례입니다. 건너뛰어도 괜찮습니다. |
|||
|
|||
/// |
|||
|
|||
기본적으로 **FastAPI**는 OpenAPI 스키마에서 `root_path`의 URL로 `server`를 생성합니다. |
|||
|
|||
하지만 예를 들어 동일한 docs UI가 스테이징과 프로덕션 환경 모두와 상호작용하도록 하려면, 다른 대안 `servers`를 제공할 수도 있습니다. |
|||
|
|||
사용자 정의 `servers` 리스트를 전달했고 `root_path`(API가 프록시 뒤에 있기 때문)가 있다면, **FastAPI**는 리스트의 맨 앞에 이 `root_path`를 가진 "server"를 삽입합니다. |
|||
|
|||
예: |
|||
|
|||
{* ../../docs_src/behind_a_proxy/tutorial003_py39.py hl[4:7] *} |
|||
|
|||
다음과 같은 OpenAPI 스키마를 생성합니다: |
|||
|
|||
```JSON hl_lines="5-7" |
|||
{ |
|||
"openapi": "3.1.0", |
|||
// More stuff here |
|||
"servers": [ |
|||
{ |
|||
"url": "/api/v1" |
|||
}, |
|||
{ |
|||
"url": "https://stag.example.com", |
|||
"description": "Staging environment" |
|||
}, |
|||
{ |
|||
"url": "https://prod.example.com", |
|||
"description": "Production environment" |
|||
} |
|||
], |
|||
"paths": { |
|||
// More stuff here |
|||
} |
|||
} |
|||
``` |
|||
|
|||
/// tip | 팁 |
|||
|
|||
`root_path`에서 가져온 값인 `/api/v1`의 `url` 값을 가진, 자동 생성된 server에 주목하세요. |
|||
|
|||
/// |
|||
|
|||
<a href="http://127.0.0.1:9999/api/v1/docs" class="external-link" target="_blank">http://127.0.0.1:9999/api/v1/docs</a>의 docs UI에서는 다음처럼 보입니다: |
|||
|
|||
<img src="/img/tutorial/behind-a-proxy/image03.png"> |
|||
|
|||
/// tip | 팁 |
|||
|
|||
docs UI는 선택한 server와 상호작용합니다. |
|||
|
|||
/// |
|||
|
|||
/// note | 기술 세부사항 |
|||
|
|||
OpenAPI 사양에서 `servers` 속성은 선택 사항입니다. |
|||
|
|||
`servers` 파라미터를 지정하지 않고 `root_path`가 `/`와 같다면, 생성된 OpenAPI 스키마의 `servers` 속성은 기본적으로 완전히 생략되며, 이는 `url` 값이 `/`인 단일 server와 동등합니다. |
|||
|
|||
/// |
|||
|
|||
### `root_path`에서 자동 server 비활성화하기 { #disable-automatic-server-from-root-path } |
|||
|
|||
**FastAPI**가 `root_path`를 사용한 자동 server를 포함하지 않게 하려면, `root_path_in_servers=False` 파라미터를 사용할 수 있습니다: |
|||
|
|||
{* ../../docs_src/behind_a_proxy/tutorial004_py39.py hl[9] *} |
|||
|
|||
그러면 OpenAPI 스키마에 포함되지 않습니다. |
|||
|
|||
## 서브 애플리케이션 마운트하기 { #mounting-a-sub-application } |
|||
|
|||
프록시에서 `root_path`를 사용하면서도, [서브 애플리케이션 - 마운트](sub-applications.md){.internal-link target=_blank}에 설명된 것처럼 서브 애플리케이션을 마운트해야 한다면, 기대하는 대로 일반적으로 수행할 수 있습니다. |
|||
|
|||
FastAPI가 내부적으로 `root_path`를 똑똑하게 사용하므로, 그냥 동작합니다. ✨ |
|||
@ -0,0 +1,95 @@ |
|||
# Dataclasses 사용하기 { #using-dataclasses } |
|||
|
|||
FastAPI는 **Pydantic** 위에 구축되어 있으며, 지금까지는 Pydantic 모델을 사용해 요청과 응답을 선언하는 방법을 보여드렸습니다. |
|||
|
|||
하지만 FastAPI는 <a href="https://docs.python.org/3/library/dataclasses.html" class="external-link" target="_blank">`dataclasses`</a>도 같은 방식으로 사용하는 것을 지원합니다: |
|||
|
|||
{* ../../docs_src/dataclasses_/tutorial001_py310.py hl[1,6:11,18:19] *} |
|||
|
|||
이는 **Pydantic** 덕분에 여전히 지원되는데, Pydantic이 <a href="https://docs.pydantic.dev/latest/concepts/dataclasses/#use-of-stdlib-dataclasses-with-basemodel" class="external-link" target="_blank">`dataclasses`에 대한 내부 지원</a>을 제공하기 때문입니다. |
|||
|
|||
따라서 위 코드처럼 Pydantic을 명시적으로 사용하지 않더라도, FastAPI는 Pydantic을 사용해 표준 dataclasses를 Pydantic의 dataclasses 변형으로 변환합니다. |
|||
|
|||
그리고 물론 다음과 같은 기능도 동일하게 지원합니다: |
|||
|
|||
* 데이터 검증 |
|||
* 데이터 직렬화 |
|||
* 데이터 문서화 등 |
|||
|
|||
이는 Pydantic 모델을 사용할 때와 같은 방식으로 동작합니다. 그리고 실제로도 내부적으로는 Pydantic을 사용해 같은 방식으로 구현됩니다. |
|||
|
|||
/// info | 정보 |
|||
|
|||
dataclasses는 Pydantic 모델이 할 수 있는 모든 것을 할 수는 없다는 점을 기억하세요. |
|||
|
|||
그래서 여전히 Pydantic 모델을 사용해야 할 수도 있습니다. |
|||
|
|||
하지만 이미 여러 dataclasses를 가지고 있다면, 이것은 FastAPI로 웹 API를 구동하는 데 그것들을 활용할 수 있는 좋은 방법입니다. 🤓 |
|||
|
|||
/// |
|||
|
|||
## `response_model`에서 Dataclasses 사용하기 { #dataclasses-in-response-model } |
|||
|
|||
`response_model` 매개변수에서도 `dataclasses`를 사용할 수 있습니다: |
|||
|
|||
{* ../../docs_src/dataclasses_/tutorial002_py310.py hl[1,6:12,18] *} |
|||
|
|||
dataclass는 자동으로 Pydantic dataclass로 변환됩니다. |
|||
|
|||
이렇게 하면 해당 스키마가 API docs 사용자 인터페이스에 표시됩니다: |
|||
|
|||
<img src="/img/tutorial/dataclasses/image01.png"> |
|||
|
|||
## 중첩 데이터 구조에서 Dataclasses 사용하기 { #dataclasses-in-nested-data-structures } |
|||
|
|||
`dataclasses`를 다른 타입 애너테이션과 조합해 중첩 데이터 구조를 만들 수도 있습니다. |
|||
|
|||
일부 경우에는 Pydantic 버전의 `dataclasses`를 사용해야 할 수도 있습니다. 예를 들어 자동 생성된 API 문서에서 오류가 발생하는 경우입니다. |
|||
|
|||
그런 경우 표준 `dataclasses`를 드롭인 대체재인 `pydantic.dataclasses`로 간단히 바꾸면 됩니다: |
|||
|
|||
{* ../../docs_src/dataclasses_/tutorial003_py310.py hl[1,4,7:10,13:16,22:24,27] *} |
|||
|
|||
1. 표준 `dataclasses`에서 `field`를 계속 임포트합니다. |
|||
|
|||
2. `pydantic.dataclasses`는 `dataclasses`의 드롭인 대체재입니다. |
|||
|
|||
3. `Author` dataclass에는 `Item` dataclasses의 리스트가 포함됩니다. |
|||
|
|||
4. `Author` dataclass가 `response_model` 매개변수로 사용됩니다. |
|||
|
|||
5. 요청 본문으로 dataclasses와 함께 다른 표준 타입 애너테이션을 사용할 수 있습니다. |
|||
|
|||
이 경우에는 `Item` dataclasses의 리스트입니다. |
|||
|
|||
6. 여기서는 dataclasses 리스트인 `items`를 포함하는 딕셔너리를 반환합니다. |
|||
|
|||
FastAPI는 여전히 데이터를 JSON으로 <abbr title="converting the data to a format that can be transmitted - 데이터를 전송 가능한 형식으로 변환하는 것">serializing</abbr>할 수 있습니다. |
|||
|
|||
7. 여기서 `response_model`은 `Author` dataclasses 리스트에 대한 타입 애너테이션을 사용합니다. |
|||
|
|||
다시 말해, `dataclasses`를 표준 타입 애너테이션과 조합할 수 있습니다. |
|||
|
|||
8. 이 *경로 처리 함수*는 `async def` 대신 일반 `def`를 사용하고 있다는 점에 주목하세요. |
|||
|
|||
언제나처럼 FastAPI에서는 필요에 따라 `def`와 `async def`를 조합해 사용할 수 있습니다. |
|||
|
|||
어떤 것을 언제 사용해야 하는지 다시 확인하고 싶다면, [`async`와 `await`](../async.md#in-a-hurry){.internal-link target=_blank} 문서의 _"급하신가요?"_ 섹션을 확인하세요. |
|||
|
|||
9. 이 *경로 처리 함수*는 dataclasses를(물론 반환할 수도 있지만) 반환하지 않고, 내부 데이터를 담은 딕셔너리들의 리스트를 반환합니다. |
|||
|
|||
FastAPI는 `response_model` 매개변수(dataclasses 포함)를 사용해 응답을 변환합니다. |
|||
|
|||
`dataclasses`는 다른 타입 애너테이션과 매우 다양한 조합으로 결합해 복잡한 데이터 구조를 구성할 수 있습니다. |
|||
|
|||
더 구체적인 내용은 위 코드 내 애너테이션 팁을 확인하세요. |
|||
|
|||
## 더 알아보기 { #learn-more } |
|||
|
|||
`dataclasses`를 다른 Pydantic 모델과 조합하거나, 이를 상속하거나, 여러분의 모델에 포함하는 등의 작업도 할 수 있습니다. |
|||
|
|||
자세한 내용은 <a href="https://docs.pydantic.dev/latest/concepts/dataclasses/" class="external-link" target="_blank">dataclasses에 관한 Pydantic 문서</a>를 참고하세요. |
|||
|
|||
## 버전 { #version } |
|||
|
|||
이 기능은 FastAPI `0.67.0` 버전부터 사용할 수 있습니다. 🔖 |
|||
@ -0,0 +1,208 @@ |
|||
# SDK 생성하기 { #generating-sdks } |
|||
|
|||
**FastAPI**는 **OpenAPI** 사양을 기반으로 하므로, FastAPI의 API는 많은 도구가 이해할 수 있는 표준 형식으로 설명할 수 있습니다. |
|||
|
|||
덕분에 여러 언어용 클라이언트 라이브러리(<abbr title="Software Development Kits - 소프트웨어 개발 키트">**SDKs**</abbr>), 최신 **문서**, 그리고 코드와 동기화된 **테스트** 또는 **자동화 워크플로**를 쉽게 생성할 수 있습니다. |
|||
|
|||
이 가이드에서는 FastAPI 백엔드용 **TypeScript SDK**를 생성하는 방법을 배웁니다. |
|||
|
|||
## 오픈 소스 SDK 생성기 { #open-source-sdk-generators } |
|||
|
|||
다양하게 활용할 수 있는 옵션으로 <a href="https://openapi-generator.tech/" class="external-link" target="_blank">OpenAPI Generator</a>가 있으며, **다양한 프로그래밍 언어**를 지원하고 OpenAPI 사양으로부터 SDK를 생성할 수 있습니다. |
|||
|
|||
**TypeScript 클라이언트**의 경우 <a href="https://heyapi.dev/" class="external-link" target="_blank">Hey API</a>는 TypeScript 생태계에 최적화된 경험을 제공하는 목적에 맞게 설계된 솔루션입니다. |
|||
|
|||
더 많은 SDK 생성기는 <a href="https://openapi.tools/#sdk" class="external-link" target="_blank">OpenAPI.Tools</a>에서 확인할 수 있습니다. |
|||
|
|||
/// tip | 팁 |
|||
|
|||
FastAPI는 **OpenAPI 3.1** 사양을 자동으로 생성하므로, 사용하는 도구는 이 버전을 지원해야 합니다. |
|||
|
|||
/// |
|||
|
|||
## FastAPI 스폰서의 SDK 생성기 { #sdk-generators-from-fastapi-sponsors } |
|||
|
|||
이 섹션에서는 FastAPI를 후원하는 회사들이 제공하는 **벤처 투자 기반** 및 **기업 지원** 솔루션을 소개합니다. 이 제품들은 고품질로 생성된 SDK에 더해 **추가 기능**과 **통합**을 제공합니다. |
|||
|
|||
✨ [**FastAPI 후원하기**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨를 통해, 이 회사들은 프레임워크와 그 **생태계**가 건강하고 **지속 가능**하게 유지되도록 돕습니다. |
|||
|
|||
또한 이들의 후원은 FastAPI **커뮤니티**(여러분)에 대한 강한 헌신을 보여주며, **좋은 서비스**를 제공하는 것뿐 아니라, 견고하고 활발한 프레임워크인 FastAPI를 지원하는 데에도 관심이 있음을 나타냅니다. 🙇 |
|||
|
|||
예를 들어 다음을 사용해 볼 수 있습니다: |
|||
|
|||
* <a href="https://speakeasy.com/editor?utm_source=fastapi+repo&utm_medium=github+sponsorship" class="external-link" target="_blank">Speakeasy</a> |
|||
* <a href="https://www.stainless.com/?utm_source=fastapi&utm_medium=referral" class="external-link" target="_blank">Stainless</a> |
|||
* <a href="https://developers.liblab.com/tutorials/sdk-for-fastapi?utm_source=fastapi" class="external-link" target="_blank">liblab</a> |
|||
|
|||
이 중 일부는 오픈 소스이거나 무료 티어를 제공하므로, 비용 부담 없이 사용해 볼 수 있습니다. 다른 상용 SDK 생성기도 있으며 온라인에서 찾을 수 있습니다. 🤓 |
|||
|
|||
## TypeScript SDK 만들기 { #create-a-typescript-sdk } |
|||
|
|||
간단한 FastAPI 애플리케이션으로 시작해 보겠습니다: |
|||
|
|||
{* ../../docs_src/generate_clients/tutorial001_py39.py hl[7:9,12:13,16:17,21] *} |
|||
|
|||
*path operation*에서 요청 페이로드와 응답 페이로드에 사용하는 모델을 `Item`, `ResponseMessage` 모델로 정의하고 있다는 점에 주목하세요. |
|||
|
|||
### API 문서 { #api-docs } |
|||
|
|||
`/docs`로 이동하면, 요청으로 보낼 데이터와 응답으로 받을 데이터에 대한 **스키마(schemas)**가 있는 것을 볼 수 있습니다: |
|||
|
|||
<img src="/img/tutorial/generate-clients/image01.png"> |
|||
|
|||
이 스키마는 앱에서 모델로 선언되었기 때문에 볼 수 있습니다. |
|||
|
|||
그 정보는 앱의 **OpenAPI 스키마**에서 사용할 수 있고, 이후 API 문서에 표시됩니다. |
|||
|
|||
OpenAPI에 포함된 모델의 동일한 정보가 **클라이언트 코드 생성**에 사용될 수 있습니다. |
|||
|
|||
### Hey API { #hey-api } |
|||
|
|||
모델이 포함된 FastAPI 앱이 준비되면, Hey API를 사용해 TypeScript 클라이언트를 생성할 수 있습니다. 가장 빠른 방법은 npx를 사용하는 것입니다. |
|||
|
|||
```sh |
|||
npx @hey-api/openapi-ts -i http://localhost:8000/openapi.json -o src/client |
|||
``` |
|||
|
|||
이 명령은 `./src/client`에 TypeScript SDK를 생성합니다. |
|||
|
|||
<a href="https://heyapi.dev/openapi-ts/get-started" class="external-link" target="_blank">`@hey-api/openapi-ts` 설치 방법</a>과 <a href="https://heyapi.dev/openapi-ts/output" class="external-link" target="_blank">생성된 결과물</a>은 해당 웹사이트에서 확인할 수 있습니다. |
|||
|
|||
### SDK 사용하기 { #using-the-sdk } |
|||
|
|||
이제 클라이언트 코드를 import해서 사용할 수 있습니다. 아래처럼 사용할 수 있으며, 메서드에 대한 자동 완성이 제공되는 것을 확인할 수 있습니다: |
|||
|
|||
<img src="/img/tutorial/generate-clients/image02.png"> |
|||
|
|||
보낼 페이로드에 대해서도 자동 완성이 제공됩니다: |
|||
|
|||
<img src="/img/tutorial/generate-clients/image03.png"> |
|||
|
|||
/// tip | 팁 |
|||
|
|||
`name`과 `price`에 대한 자동 완성은 FastAPI 애플리케이션에서 `Item` 모델에 정의된 내용입니다. |
|||
|
|||
/// |
|||
|
|||
전송하는 데이터에 대해 인라인 오류도 표시됩니다: |
|||
|
|||
<img src="/img/tutorial/generate-clients/image04.png"> |
|||
|
|||
응답 객체도 자동 완성을 제공합니다: |
|||
|
|||
<img src="/img/tutorial/generate-clients/image05.png"> |
|||
|
|||
## 태그가 있는 FastAPI 앱 { #fastapi-app-with-tags } |
|||
|
|||
대부분의 경우 FastAPI 앱은 더 커지고, 서로 다른 *path operations* 그룹을 분리하기 위해 태그를 사용하게 될 가능성이 큽니다. |
|||
|
|||
예를 들어 **items** 섹션과 **users** 섹션이 있고, 이를 태그로 분리할 수 있습니다: |
|||
|
|||
{* ../../docs_src/generate_clients/tutorial002_py39.py hl[21,26,34] *} |
|||
|
|||
### 태그로 TypeScript 클라이언트 생성하기 { #generate-a-typescript-client-with-tags } |
|||
|
|||
태그를 사용하는 FastAPI 앱에 대해 클라이언트를 생성하면, 일반적으로 생성된 클라이언트 코드도 태그를 기준으로 분리됩니다. |
|||
|
|||
이렇게 하면 클라이언트 코드에서 항목들이 올바르게 정렬되고 그룹화됩니다: |
|||
|
|||
<img src="/img/tutorial/generate-clients/image06.png"> |
|||
|
|||
이 경우 다음이 있습니다: |
|||
|
|||
* `ItemsService` |
|||
* `UsersService` |
|||
|
|||
### 클라이언트 메서드 이름 { #client-method-names } |
|||
|
|||
현재 `createItemItemsPost` 같은 생성된 메서드 이름은 그다지 깔끔하지 않습니다: |
|||
|
|||
```TypeScript |
|||
ItemsService.createItemItemsPost({name: "Plumbus", price: 5}) |
|||
``` |
|||
|
|||
...이는 클라이언트 생성기가 각 *path operation*에 대해 OpenAPI 내부의 **operation ID**를 사용하기 때문입니다. |
|||
|
|||
OpenAPI는 모든 *path operations* 전체에서 operation ID가 각각 유일해야 한다고 요구합니다. 그래서 FastAPI는 operation ID가 유일하도록 **함수 이름**, **경로**, **HTTP method/operation**을 조합해 operation ID를 생성합니다. |
|||
|
|||
하지만 다음에서 이를 개선하는 방법을 보여드리겠습니다. 🤓 |
|||
|
|||
## 커스텀 Operation ID와 더 나은 메서드 이름 { #custom-operation-ids-and-better-method-names } |
|||
|
|||
클라이언트에서 **더 단순한 메서드 이름**을 갖도록, operation ID가 **생성되는 방식**을 **수정**할 수 있습니다. |
|||
|
|||
이 경우 operation ID가 다른 방식으로도 **유일**하도록 보장해야 합니다. |
|||
|
|||
예를 들어 각 *path operation*이 태그를 갖도록 한 다음, **태그**와 *path operation* **이름**(함수 이름)을 기반으로 operation ID를 생성할 수 있습니다. |
|||
|
|||
### 유일 ID 생성 함수 커스터마이징 { #custom-generate-unique-id-function } |
|||
|
|||
FastAPI는 각 *path operation*에 대해 **유일 ID**를 사용하며, 이는 **operation ID** 및 요청/응답에 필요한 커스텀 모델 이름에도 사용됩니다. |
|||
|
|||
이 함수를 커스터마이징할 수 있습니다. 이 함수는 `APIRoute`를 받아 문자열을 반환합니다. |
|||
|
|||
예를 들어 아래에서는 첫 번째 태그(대부분 태그는 하나만 있을 것입니다)와 *path operation* 이름(함수 이름)을 사용합니다. |
|||
|
|||
그 다음 이 커스텀 함수를 `generate_unique_id_function` 매개변수로 **FastAPI**에 전달할 수 있습니다: |
|||
|
|||
{* ../../docs_src/generate_clients/tutorial003_py39.py hl[6:7,10] *} |
|||
|
|||
### 커스텀 Operation ID로 TypeScript 클라이언트 생성하기 { #generate-a-typescript-client-with-custom-operation-ids } |
|||
|
|||
이제 클라이언트를 다시 생성하면, 개선된 메서드 이름을 확인할 수 있습니다: |
|||
|
|||
<img src="/img/tutorial/generate-clients/image07.png"> |
|||
|
|||
보시다시피, 이제 메서드 이름은 태그 다음에 함수 이름이 오며, URL 경로와 HTTP operation의 정보는 포함하지 않습니다. |
|||
|
|||
### 클라이언트 생성기를 위한 OpenAPI 사양 전처리 { #preprocess-the-openapi-specification-for-the-client-generator } |
|||
|
|||
생성된 코드에는 여전히 일부 **중복 정보**가 있습니다. |
|||
|
|||
`ItemsService`(태그에서 가져옴)에 이미 **items**가 포함되어 있어 이 메서드가 items와 관련되어 있음을 알 수 있지만, 메서드 이름에도 태그 이름이 접두사로 붙어 있습니다. 😕 |
|||
|
|||
OpenAPI 전반에서는 operation ID가 **유일**하다는 것을 보장하기 위해 이 방식을 유지하고 싶을 수 있습니다. |
|||
|
|||
하지만 생성된 클라이언트에서는, 클라이언트를 생성하기 직전에 OpenAPI operation ID를 **수정**해서 메서드 이름을 더 보기 좋고 **깔끔하게** 만들 수 있습니다. |
|||
|
|||
OpenAPI JSON을 `openapi.json` 파일로 다운로드한 뒤, 아래와 같은 스크립트로 **접두사 태그를 제거**할 수 있습니다: |
|||
|
|||
{* ../../docs_src/generate_clients/tutorial004_py39.py *} |
|||
|
|||
//// tab | Node.js |
|||
|
|||
```Javascript |
|||
{!> ../../docs_src/generate_clients/tutorial004.js!} |
|||
``` |
|||
|
|||
//// |
|||
|
|||
이렇게 하면 operation ID가 `items-get_items` 같은 형태에서 `get_items`로 변경되어, 클라이언트 생성기가 더 단순한 메서드 이름을 생성할 수 있습니다. |
|||
|
|||
### 전처리된 OpenAPI로 TypeScript 클라이언트 생성하기 { #generate-a-typescript-client-with-the-preprocessed-openapi } |
|||
|
|||
이제 최종 결과가 `openapi.json` 파일에 있으므로, 입력 위치를 업데이트해야 합니다: |
|||
|
|||
```sh |
|||
npx @hey-api/openapi-ts -i ./openapi.json -o src/client |
|||
``` |
|||
|
|||
새 클라이언트를 생성한 후에는 **깔끔한 메서드 이름**을 가지면서도, **자동 완성**, **인라인 오류** 등은 그대로 제공됩니다: |
|||
|
|||
<img src="/img/tutorial/generate-clients/image08.png"> |
|||
|
|||
## 장점 { #benefits } |
|||
|
|||
자동으로 생성된 클라이언트를 사용하면 다음에 대해 **자동 완성**을 받을 수 있습니다: |
|||
|
|||
* 메서드 |
|||
* 본문(body)의 요청 페이로드, 쿼리 파라미터 등 |
|||
* 응답 페이로드 |
|||
|
|||
또한 모든 것에 대해 **인라인 오류**도 확인할 수 있습니다. |
|||
|
|||
그리고 백엔드 코드를 업데이트한 뒤 프론트엔드를 **재생성(regenerate)**하면, 새 *path operations*가 메서드로 추가되고 기존 것은 제거되며, 그 밖의 변경 사항도 생성된 코드에 반영됩니다. 🤓 |
|||
|
|||
이는 무언가 변경되면 그 변경이 클라이언트 코드에도 자동으로 **반영**된다는 뜻입니다. 또한 클라이언트를 **빌드(build)**하면 사용된 데이터가 **불일치(mismatch)**할 경우 오류가 발생합니다. |
|||
|
|||
따라서 운영 환경에서 최종 사용자에게 오류가 노출된 뒤 문제를 추적하는 대신, 개발 사이클 초기에 **많은 오류를 매우 빨리 감지**할 수 있습니다. ✨ |
|||
@ -0,0 +1,97 @@ |
|||
# 고급 Middleware { #advanced-middleware } |
|||
|
|||
메인 튜토리얼에서 애플리케이션에 [커스텀 Middleware](../tutorial/middleware.md){.internal-link target=_blank}를 추가하는 방법을 읽었습니다. |
|||
|
|||
그리고 [`CORSMiddleware`로 CORS 처리하기](../tutorial/cors.md){.internal-link target=_blank}도 읽었습니다. |
|||
|
|||
이 섹션에서는 다른 middleware들을 사용하는 방법을 살펴보겠습니다. |
|||
|
|||
## ASGI middleware 추가하기 { #adding-asgi-middlewares } |
|||
|
|||
**FastAPI**는 Starlette를 기반으로 하고 <abbr title="Asynchronous Server Gateway Interface">ASGI</abbr> 사양을 구현하므로, 어떤 ASGI middleware든 사용할 수 있습니다. |
|||
|
|||
ASGI 사양을 따르기만 하면, FastAPI나 Starlette를 위해 만들어진 middleware가 아니어도 동작합니다. |
|||
|
|||
일반적으로 ASGI middleware는 첫 번째 인자로 ASGI 앱을 받도록 기대하는 클래스입니다. |
|||
|
|||
그래서 서드파티 ASGI middleware 문서에서는 아마 다음과 같이 하라고 안내할 것입니다: |
|||
|
|||
```Python |
|||
from unicorn import UnicornMiddleware |
|||
|
|||
app = SomeASGIApp() |
|||
|
|||
new_app = UnicornMiddleware(app, some_config="rainbow") |
|||
``` |
|||
|
|||
하지만 FastAPI(정확히는 Starlette)는 더 간단한 방법을 제공하며, 이를 통해 내부 middleware가 서버 오류를 처리하고 커스텀 예외 핸들러가 올바르게 동작하도록 보장합니다. |
|||
|
|||
이를 위해(그리고 CORS 예제에서처럼) `app.add_middleware()`를 사용합니다. |
|||
|
|||
```Python |
|||
from fastapi import FastAPI |
|||
from unicorn import UnicornMiddleware |
|||
|
|||
app = FastAPI() |
|||
|
|||
app.add_middleware(UnicornMiddleware, some_config="rainbow") |
|||
``` |
|||
|
|||
`app.add_middleware()`는 첫 번째 인자로 middleware 클래스를 받고, 그 뒤에는 middleware에 전달할 추가 인자들을 받습니다. |
|||
|
|||
## 통합 middleware { #integrated-middlewares } |
|||
|
|||
**FastAPI**에는 일반적인 사용 사례를 위한 여러 middleware가 포함되어 있습니다. 다음에서 이를 사용하는 방법을 살펴보겠습니다. |
|||
|
|||
/// note | 기술 세부사항 |
|||
|
|||
다음 예제에서는 `from starlette.middleware.something import SomethingMiddleware`를 사용해도 됩니다. |
|||
|
|||
**FastAPI**는 개발자 편의를 위해 `fastapi.middleware`에 여러 middleware를 제공하지만, 사용 가능한 대부분의 middleware는 Starlette에서 직접 제공됩니다. |
|||
|
|||
/// |
|||
|
|||
## `HTTPSRedirectMiddleware` { #httpsredirectmiddleware } |
|||
|
|||
들어오는 모든 요청이 `https` 또는 `wss`여야 하도록 강제합니다. |
|||
|
|||
`http` 또는 `ws`로 들어오는 모든 요청은 대신 보안 스킴으로 리디렉션됩니다. |
|||
|
|||
{* ../../docs_src/advanced_middleware/tutorial001_py39.py hl[2,6] *} |
|||
|
|||
## `TrustedHostMiddleware` { #trustedhostmiddleware } |
|||
|
|||
HTTP Host Header 공격을 방어하기 위해, 들어오는 모든 요청에 올바르게 설정된 `Host` 헤더가 있어야 하도록 강제합니다. |
|||
|
|||
{* ../../docs_src/advanced_middleware/tutorial002_py39.py hl[2,6:8] *} |
|||
|
|||
다음 인자들을 지원합니다: |
|||
|
|||
* `allowed_hosts` - 호스트명으로 허용할 도메인 이름 목록입니다. `*.example.com` 같은 와일드카드 도메인으로 서브도메인을 매칭하는 것도 지원합니다. 어떤 호스트명이든 허용하려면 `allowed_hosts=["*"]`를 사용하거나 middleware를 생략하세요. |
|||
* `www_redirect` - True로 설정하면, 허용된 호스트의 non-www 버전으로 들어오는 요청을 www 버전으로 리디렉션합니다. 기본값은 `True`입니다. |
|||
|
|||
들어오는 요청이 올바르게 검증되지 않으면 `400` 응답이 전송됩니다. |
|||
|
|||
## `GZipMiddleware` { #gzipmiddleware } |
|||
|
|||
`Accept-Encoding` 헤더에 `"gzip"`이 포함된 어떤 요청이든 GZip 응답을 처리합니다. |
|||
|
|||
이 middleware는 일반 응답과 스트리밍 응답을 모두 처리합니다. |
|||
|
|||
{* ../../docs_src/advanced_middleware/tutorial003_py39.py hl[2,6] *} |
|||
|
|||
다음 인자들을 지원합니다: |
|||
|
|||
* `minimum_size` - 바이트 단위로 지정한 최소 크기보다 작은 응답은 GZip으로 압축하지 않습니다. 기본값은 `500`입니다. |
|||
* `compresslevel` - GZip 압축 중에 사용됩니다. 1부터 9까지의 정수입니다. 기본값은 `9`입니다. 값이 낮을수록 압축은 더 빠르지만 파일 크기는 더 커지고, 값이 높을수록 압축은 더 느리지만 파일 크기는 더 작아집니다. |
|||
|
|||
## 다른 middleware { #other-middlewares } |
|||
|
|||
다른 ASGI middleware도 많이 있습니다. |
|||
|
|||
예를 들어: |
|||
|
|||
* <a href="https://github.com/encode/uvicorn/blob/master/uvicorn/middleware/proxy_headers.py" class="external-link" target="_blank">Uvicorn의 `ProxyHeadersMiddleware`</a> |
|||
* <a href="https://github.com/florimondmanca/msgpack-asgi" class="external-link" target="_blank">MessagePack</a> |
|||
|
|||
사용 가능한 다른 middleware를 보려면 <a href="https://www.starlette.dev/middleware/" class="external-link" target="_blank">Starlette의 Middleware 문서</a>와 <a href="https://github.com/florimondmanca/awesome-asgi" class="external-link" target="_blank">ASGI Awesome List</a>를 확인하세요. |
|||
@ -0,0 +1,186 @@ |
|||
# OpenAPI 콜백 { #openapi-callbacks } |
|||
|
|||
다른 사람이 만든 *external API*(아마도 당신의 API를 *사용*할 동일한 개발자)가 요청을 트리거하도록 만드는 *경로 처리*를 가진 API를 만들 수 있습니다. |
|||
|
|||
당신의 API 앱이 *external API*를 호출할 때 일어나는 과정을 "callback"이라고 합니다. 외부 개발자가 작성한 소프트웨어가 당신의 API로 요청을 보낸 다음, 당신의 API가 다시 *external API*로 요청을 보내 *되돌려 호출*하기 때문입니다(아마도 같은 개발자가 만든 API일 것입니다). |
|||
|
|||
이 경우, 그 *external API*가 어떤 형태여야 하는지 문서화하고 싶을 수 있습니다. 어떤 *경로 처리*를 가져야 하는지, 어떤 body를 기대하는지, 어떤 응답을 반환해야 하는지 등입니다. |
|||
|
|||
## 콜백이 있는 앱 { #an-app-with-callbacks } |
|||
|
|||
예시로 확인해 보겠습니다. |
|||
|
|||
청구서를 생성할 수 있는 앱을 개발한다고 가정해 보세요. |
|||
|
|||
이 청구서는 `id`, `title`(선택 사항), `customer`, `total`을 갖습니다. |
|||
|
|||
당신의 API 사용자(외부 개발자)는 POST 요청으로 당신의 API에서 청구서를 생성합니다. |
|||
|
|||
그 다음 당신의 API는(가정해 보면): |
|||
|
|||
* 청구서를 외부 개발자의 고객에게 전송합니다. |
|||
* 돈을 수금합니다. |
|||
* API 사용자(외부 개발자)의 API로 다시 알림을 보냅니다. |
|||
* 이는 (당신의 API에서) 그 외부 개발자가 제공하는 어떤 *external API*로 POST 요청을 보내는 방식으로 수행됩니다(이것이 "callback"입니다). |
|||
|
|||
## 일반적인 **FastAPI** 앱 { #the-normal-fastapi-app } |
|||
|
|||
먼저 콜백을 추가하기 전, 일반적인 API 앱이 어떻게 생겼는지 보겠습니다. |
|||
|
|||
`Invoice` body를 받는 *경로 처리*와, 콜백을 위한 URL을 담는 쿼리 파라미터 `callback_url`이 있을 것입니다. |
|||
|
|||
이 부분은 꽤 일반적이며, 대부분의 코드는 이미 익숙할 것입니다: |
|||
|
|||
{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[7:11,34:51] *} |
|||
|
|||
/// tip | 팁 |
|||
|
|||
`callback_url` 쿼리 파라미터는 Pydantic의 <a href="https://docs.pydantic.dev/latest/api/networks/" class="external-link" target="_blank">Url</a> 타입을 사용합니다. |
|||
|
|||
/// |
|||
|
|||
유일하게 새로운 것은 *경로 처리 데코레이터*의 인자로 `callbacks=invoices_callback_router.routes`가 들어간다는 점입니다. 이것이 무엇인지 다음에서 보겠습니다. |
|||
|
|||
## 콜백 문서화하기 { #documenting-the-callback } |
|||
|
|||
실제 콜백 코드는 당신의 API 앱에 크게 의존합니다. |
|||
|
|||
그리고 앱마다 많이 달라질 수 있습니다. |
|||
|
|||
다음처럼 한두 줄의 코드일 수도 있습니다: |
|||
|
|||
```Python |
|||
callback_url = "https://example.com/api/v1/invoices/events/" |
|||
httpx.post(callback_url, json={"description": "Invoice paid", "paid": True}) |
|||
``` |
|||
|
|||
하지만 콜백에서 가장 중요한 부분은, 당신의 API 사용자(외부 개발자)가 콜백 요청 body로 *당신의 API*가 보낼 데이터 등에 맞춰 *external API*를 올바르게 구현하도록 보장하는 것입니다. |
|||
|
|||
그래서 다음으로 할 일은, *당신의 API*에서 보내는 콜백을 받기 위해 그 *external API*가 어떤 형태여야 하는지 문서화하는 코드를 추가하는 것입니다. |
|||
|
|||
그 문서는 당신의 API에서 `/docs`의 Swagger UI에 표시되며, 외부 개발자들이 *external API*를 어떻게 만들어야 하는지 알 수 있게 해줍니다. |
|||
|
|||
이 예시는 콜백 자체(한 줄 코드로도 될 수 있음)를 구현하지 않고, 문서화 부분만 구현합니다. |
|||
|
|||
/// tip | 팁 |
|||
|
|||
실제 콜백은 단지 HTTP 요청입니다. |
|||
|
|||
콜백을 직접 구현할 때는 <a href="https://www.python-httpx.org" class="external-link" target="_blank">HTTPX</a>나 <a href="https://requests.readthedocs.io/" class="external-link" target="_blank">Requests</a> 같은 것을 사용할 수 있습니다. |
|||
|
|||
/// |
|||
|
|||
## 콜백 문서화 코드 작성하기 { #write-the-callback-documentation-code } |
|||
|
|||
이 코드는 앱에서 실행되지 않습니다. 그 *external API*가 어떤 형태여야 하는지 *문서화*하는 데만 필요합니다. |
|||
|
|||
하지만 **FastAPI**로 API의 자동 문서를 쉽게 생성하는 방법은 이미 알고 있습니다. |
|||
|
|||
따라서 그와 같은 지식을 사용해 *external API*가 어떻게 생겨야 하는지 문서화할 것입니다... 즉 외부 API가 구현해야 하는 *경로 처리(들)*(당신의 API가 호출할 것들)을 만들어서 말입니다. |
|||
|
|||
/// tip | 팁 |
|||
|
|||
콜백을 문서화하는 코드를 작성할 때는, 자신이 그 *외부 개발자*라고 상상하는 것이 유용할 수 있습니다. 그리고 지금은 *당신의 API*가 아니라 *external API*를 구현하고 있다고 생각해 보세요. |
|||
|
|||
이 관점(외부 개발자의 관점)을 잠시 채택하면, 그 *external API*를 위해 파라미터, body용 Pydantic 모델, 응답 등을 어디에 두어야 하는지가 더 명확하게 느껴질 수 있습니다. |
|||
|
|||
/// |
|||
|
|||
### 콜백 `APIRouter` 생성하기 { #create-a-callback-apirouter } |
|||
|
|||
먼저 하나 이상의 콜백을 담을 새 `APIRouter`를 만듭니다. |
|||
|
|||
{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[1,23] *} |
|||
|
|||
### 콜백 *경로 처리* 생성하기 { #create-the-callback-path-operation } |
|||
|
|||
콜백 *경로 처리*를 만들려면 위에서 만든 동일한 `APIRouter`를 사용합니다. |
|||
|
|||
일반적인 FastAPI *경로 처리*처럼 보일 것입니다: |
|||
|
|||
* 아마도 받아야 할 body 선언이 있을 것입니다(예: `body: InvoiceEvent`). |
|||
* 그리고 반환해야 할 응답 선언도 있을 수 있습니다(예: `response_model=InvoiceEventReceived`). |
|||
|
|||
{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[14:16,19:20,26:30] *} |
|||
|
|||
일반적인 *경로 처리*와의 주요 차이점은 2가지입니다: |
|||
|
|||
* 실제 코드를 가질 필요가 없습니다. 당신의 앱은 이 코드를 절대 호출하지 않기 때문입니다. 이는 *external API*를 문서화하는 데만 사용됩니다. 따라서 함수는 그냥 `pass`만 있어도 됩니다. |
|||
* *path*에는 <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression" class="external-link" target="_blank">OpenAPI 3 expression</a>(자세한 내용은 아래 참고)이 포함될 수 있으며, 이를 통해 *당신의 API*로 보내진 원래 요청의 파라미터와 일부 값을 변수로 사용할 수 있습니다. |
|||
|
|||
### 콜백 경로 표현식 { #the-callback-path-expression } |
|||
|
|||
콜백 *path*는 *당신의 API*로 보내진 원래 요청의 일부를 포함할 수 있는 <a href="https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression" class="external-link" target="_blank">OpenAPI 3 expression</a>을 가질 수 있습니다. |
|||
|
|||
이 경우, 다음 `str`입니다: |
|||
|
|||
```Python |
|||
"{$callback_url}/invoices/{$request.body.id}" |
|||
``` |
|||
|
|||
따라서 당신의 API 사용자(외부 개발자)가 *당신의 API*로 다음 요청을 보내고: |
|||
|
|||
``` |
|||
https://yourapi.com/invoices/?callback_url=https://www.external.org/events |
|||
``` |
|||
|
|||
JSON body가 다음과 같다면: |
|||
|
|||
```JSON |
|||
{ |
|||
"id": "2expen51ve", |
|||
"customer": "Mr. Richie Rich", |
|||
"total": "9999" |
|||
} |
|||
``` |
|||
|
|||
그러면 *당신의 API*는 청구서를 처리하고, 나중에 어느 시점에서 `callback_url`(즉 *external API*)로 콜백 요청을 보냅니다: |
|||
|
|||
``` |
|||
https://www.external.org/events/invoices/2expen51ve |
|||
``` |
|||
|
|||
그리고 다음과 같은 JSON body를 포함할 것입니다: |
|||
|
|||
```JSON |
|||
{ |
|||
"description": "Payment celebration", |
|||
"paid": true |
|||
} |
|||
``` |
|||
|
|||
또한 그 *external API*로부터 다음과 같은 JSON body 응답을 기대합니다: |
|||
|
|||
```JSON |
|||
{ |
|||
"ok": true |
|||
} |
|||
``` |
|||
|
|||
/// tip | 팁 |
|||
|
|||
콜백 URL에는 `callback_url` 쿼리 파라미터로 받은 URL(`https://www.external.org/events`)뿐 아니라, JSON body 안의 청구서 `id`(`2expen51ve`)도 함께 사용된다는 점에 주목하세요. |
|||
|
|||
/// |
|||
|
|||
### 콜백 라우터 추가하기 { #add-the-callback-router } |
|||
|
|||
이 시점에서, 위에서 만든 콜백 라우터 안에 *콜백 경로 처리(들)*(즉 *external developer*가 *external API*에 구현해야 하는 것들)을 준비했습니다. |
|||
|
|||
이제 *당신의 API 경로 처리 데코레이터*에서 `callbacks` 파라미터를 사용해, 그 콜백 라우터의 `.routes` 속성(실제로는 routes/*경로 처리*의 `list`)을 전달합니다: |
|||
|
|||
{* ../../docs_src/openapi_callbacks/tutorial001_py310.py hl[33] *} |
|||
|
|||
/// tip | 팁 |
|||
|
|||
`callback=`에 라우터 자체(`invoices_callback_router`)를 넘기는 것이 아니라, `invoices_callback_router.routes`처럼 `.routes` 속성을 넘긴다는 점에 주목하세요. |
|||
|
|||
/// |
|||
|
|||
### 문서 확인하기 { #check-the-docs } |
|||
|
|||
이제 앱을 실행하고 <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>로 이동하세요. |
|||
|
|||
*경로 처리*에 대해 "Callbacks" 섹션을 포함한 문서가 표시되며, *external API*가 어떤 형태여야 하는지 확인할 수 있습니다: |
|||
|
|||
<img src="/img/tutorial/openapi-callbacks/image01.png"> |
|||
@ -0,0 +1,55 @@ |
|||
# OpenAPI Webhooks { #openapi-webhooks } |
|||
|
|||
앱이 어떤 데이터와 함께 (요청을 보내서) *사용자의* 앱을 호출할 수 있고, 보통 어떤 **이벤트**를 **알리기** 위해 그렇게 할 수 있다는 것을 API **사용자**에게 알려야 하는 경우가 있습니다. |
|||
|
|||
이는 사용자가 여러분의 API로 요청을 보내는 일반적인 과정 대신, **여러분의 API**(또는 앱)가 **사용자의 시스템**(사용자의 API, 사용자의 앱)으로 **요청을 보낼 수 있다**는 의미입니다. |
|||
|
|||
이를 보통 **webhook**이라고 합니다. |
|||
|
|||
## Webhooks 단계 { #webhooks-steps } |
|||
|
|||
일반적인 과정은, 여러분이 코드에서 보낼 메시지, 즉 **요청 본문(body)**이 무엇인지 **정의**하는 것입니다. |
|||
|
|||
또한 여러분의 앱이 어떤 **시점**에 그 요청(또는 이벤트)을 보낼지도 어떤 방식으로든 정의합니다. |
|||
|
|||
그리고 **사용자**는 (예: 어딘가의 웹 대시보드에서) 여러분의 앱이 그 요청을 보내야 할 **URL**을 어떤 방식으로든 정의합니다. |
|||
|
|||
webhook의 URL을 등록하는 방법과 실제로 그 요청을 보내는 코드에 대한 모든 **로직**은 여러분에게 달려 있습니다. **여러분의 코드**에서 원하는 방식으로 작성하면 됩니다. |
|||
|
|||
## **FastAPI**와 OpenAPI로 webhooks 문서화하기 { #documenting-webhooks-with-fastapi-and-openapi } |
|||
|
|||
**FastAPI**에서는 OpenAPI를 사용해, 이러한 webhook의 이름, 여러분의 앱이 보낼 수 있는 HTTP 작업 타입(예: `POST`, `PUT` 등), 그리고 여러분의 앱이 보낼 요청 **본문(body)**을 정의할 수 있습니다. |
|||
|
|||
이렇게 하면 사용자가 여러분의 **webhook** 요청을 받기 위해 **자신들의 API를 구현**하기가 훨씬 쉬워지고, 경우에 따라서는 자신의 API 코드 일부를 자동 생성할 수도 있습니다. |
|||
|
|||
/// info | 정보 |
|||
|
|||
Webhooks는 OpenAPI 3.1.0 이상에서 사용할 수 있으며, FastAPI `0.99.0` 이상에서 지원됩니다. |
|||
|
|||
/// |
|||
|
|||
## webhooks가 있는 앱 { #an-app-with-webhooks } |
|||
|
|||
**FastAPI** 애플리케이션을 만들면, *경로 처리*를 정의하는 것과 같은 방식으로(예: `@app.webhooks.post()`), *webhooks*를 정의하는 데 사용할 수 있는 `webhooks` 속성이 있습니다. |
|||
|
|||
{* ../../docs_src/openapi_webhooks/tutorial001_py39.py hl[9:13,36:53] *} |
|||
|
|||
여러분이 정의한 webhook은 **OpenAPI** 스키마와 자동 **docs UI**에 포함됩니다. |
|||
|
|||
/// info | 정보 |
|||
|
|||
`app.webhooks` 객체는 실제로 `APIRouter`일 뿐이며, 여러 파일로 앱을 구조화할 때 사용하는 것과 동일한 타입입니다. |
|||
|
|||
/// |
|||
|
|||
webhook에서는 실제로(`/items/` 같은) *경로(path)*를 선언하지 않는다는 점에 유의하세요. 그곳에 전달하는 텍스트는 webhook의 **식별자**(이벤트 이름)일 뿐입니다. 예를 들어 `@app.webhooks.post("new-subscription")`에서 webhook 이름은 `new-subscription`입니다. |
|||
|
|||
이는 **사용자**가 webhook 요청을 받고 싶은 실제 **URL 경로**를 다른 방식(예: 웹 대시보드)으로 정의할 것이라고 기대하기 때문입니다. |
|||
|
|||
### 문서 확인하기 { #check-the-docs } |
|||
|
|||
이제 앱을 실행하고 <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>로 이동하세요. |
|||
|
|||
문서에 일반적인 *경로 처리*가 보이고, 이제는 일부 **webhooks**도 함께 보일 것입니다: |
|||
|
|||
<img src="/img/tutorial/openapi-webhooks/image01.png"> |
|||
@ -0,0 +1,172 @@ |
|||
# 경로 처리 고급 구성 { #path-operation-advanced-configuration } |
|||
|
|||
## OpenAPI operationId { #openapi-operationid } |
|||
|
|||
/// warning | 경고 |
|||
|
|||
OpenAPI “전문가”가 아니라면, 아마 이 내용은 필요하지 않을 것입니다. |
|||
|
|||
/// |
|||
|
|||
매개변수 `operation_id`를 사용해 *경로 처리*에 사용할 OpenAPI `operationId`를 설정할 수 있습니다. |
|||
|
|||
각 작업마다 고유하도록 보장해야 합니다. |
|||
|
|||
{* ../../docs_src/path_operation_advanced_configuration/tutorial001_py39.py hl[6] *} |
|||
|
|||
### *경로 처리 함수* 이름을 operationId로 사용하기 { #using-the-path-operation-function-name-as-the-operationid } |
|||
|
|||
API의 함수 이름을 `operationId`로 사용하고 싶다면, 모든 API를 순회하면서 `APIRoute.name`을 사용해 각 *경로 처리*의 `operation_id`를 덮어쓸 수 있습니다. |
|||
|
|||
모든 *경로 처리*를 추가한 뒤에 수행해야 합니다. |
|||
|
|||
{* ../../docs_src/path_operation_advanced_configuration/tutorial002_py39.py hl[2, 12:21, 24] *} |
|||
|
|||
/// tip | 팁 |
|||
|
|||
`app.openapi()`를 수동으로 호출한다면, 그 전에 `operationId`들을 업데이트해야 합니다. |
|||
|
|||
/// |
|||
|
|||
/// warning | 경고 |
|||
|
|||
이렇게 할 경우, 각 *경로 처리 함수*의 이름이 고유하도록 보장해야 합니다. |
|||
|
|||
서로 다른 모듈(파이썬 파일)에 있어도 마찬가지입니다. |
|||
|
|||
/// |
|||
|
|||
## OpenAPI에서 제외하기 { #exclude-from-openapi } |
|||
|
|||
생성된 OpenAPI 스키마(따라서 자동 문서화 시스템)에서 특정 *경로 처리*를 제외하려면, `include_in_schema` 매개변수를 `False`로 설정하세요: |
|||
|
|||
{* ../../docs_src/path_operation_advanced_configuration/tutorial003_py39.py hl[6] *} |
|||
|
|||
## docstring에서 고급 설명 가져오기 { #advanced-description-from-docstring } |
|||
|
|||
OpenAPI에 사용할 *경로 처리 함수*의 docstring 줄 수를 제한할 수 있습니다. |
|||
|
|||
`\f`(이스케이프된 "form feed" 문자)를 추가하면 **FastAPI**는 이 지점에서 OpenAPI에 사용할 출력 내용을 잘라냅니다. |
|||
|
|||
문서에는 표시되지 않지만, Sphinx 같은 다른 도구는 나머지 부분을 사용할 수 있습니다. |
|||
|
|||
{* ../../docs_src/path_operation_advanced_configuration/tutorial004_py310.py hl[17:27] *} |
|||
|
|||
## 추가 응답 { #additional-responses } |
|||
|
|||
*경로 처리*에 대해 `response_model`과 `status_code`를 선언하는 방법을 이미 보셨을 것입니다. |
|||
|
|||
이는 *경로 처리*의 기본 응답에 대한 메타데이터를 정의합니다. |
|||
|
|||
모델, 상태 코드 등과 함께 추가 응답도 선언할 수 있습니다. |
|||
|
|||
이에 대한 문서의 전체 장이 있으니, [OpenAPI의 추가 응답](additional-responses.md){.internal-link target=_blank}에서 읽어보세요. |
|||
|
|||
## OpenAPI Extra { #openapi-extra } |
|||
|
|||
애플리케이션에서 *경로 처리*를 선언하면, **FastAPI**는 OpenAPI 스키마에 포함될 해당 *경로 처리*의 관련 메타데이터를 자동으로 생성합니다. |
|||
|
|||
/// note | 기술 세부사항 |
|||
|
|||
OpenAPI 명세에서는 이를 <a href="https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#operation-object" class="external-link" target="_blank">Operation Object</a>라고 부릅니다. |
|||
|
|||
/// |
|||
|
|||
여기에는 *경로 처리*에 대한 모든 정보가 있으며, 자동 문서를 생성하는 데 사용됩니다. |
|||
|
|||
`tags`, `parameters`, `requestBody`, `responses` 등이 포함됩니다. |
|||
|
|||
이 *경로 처리* 전용 OpenAPI 스키마는 보통 **FastAPI**가 자동으로 생성하지만, 확장할 수도 있습니다. |
|||
|
|||
/// tip | 팁 |
|||
|
|||
이는 저수준 확장 지점입니다. |
|||
|
|||
추가 응답만 선언하면 된다면, 더 편리한 방법은 [OpenAPI의 추가 응답](additional-responses.md){.internal-link target=_blank}을 사용하는 것입니다. |
|||
|
|||
/// |
|||
|
|||
`openapi_extra` 매개변수를 사용해 *경로 처리*의 OpenAPI 스키마를 확장할 수 있습니다. |
|||
|
|||
### OpenAPI 확장 { #openapi-extensions } |
|||
|
|||
예를 들어 `openapi_extra`는 [OpenAPI Extensions](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#specificationExtensions)를 선언하는 데 도움이 될 수 있습니다: |
|||
|
|||
{* ../../docs_src/path_operation_advanced_configuration/tutorial005_py39.py hl[6] *} |
|||
|
|||
자동 API 문서를 열면, 해당 특정 *경로 처리*의 하단에 확장이 표시됩니다. |
|||
|
|||
<img src="/img/tutorial/path-operation-advanced-configuration/image01.png"> |
|||
|
|||
또한 API의 `/openapi.json`에서 결과 OpenAPI를 보면, 특정 *경로 처리*의 일부로 확장이 포함된 것도 확인할 수 있습니다: |
|||
|
|||
```JSON hl_lines="22" |
|||
{ |
|||
"openapi": "3.1.0", |
|||
"info": { |
|||
"title": "FastAPI", |
|||
"version": "0.1.0" |
|||
}, |
|||
"paths": { |
|||
"/items/": { |
|||
"get": { |
|||
"summary": "Read Items", |
|||
"operationId": "read_items_items__get", |
|||
"responses": { |
|||
"200": { |
|||
"description": "Successful Response", |
|||
"content": { |
|||
"application/json": { |
|||
"schema": {} |
|||
} |
|||
} |
|||
} |
|||
}, |
|||
"x-aperture-labs-portal": "blue" |
|||
} |
|||
} |
|||
} |
|||
} |
|||
``` |
|||
|
|||
### 사용자 정의 OpenAPI *경로 처리* 스키마 { #custom-openapi-path-operation-schema } |
|||
|
|||
`openapi_extra`의 딕셔너리는 *경로 처리*에 대해 자동으로 생성된 OpenAPI 스키마와 깊게 병합됩니다. |
|||
|
|||
따라서 자동 생성된 스키마에 추가 데이터를 더할 수 있습니다. |
|||
|
|||
예를 들어 Pydantic과 함께 FastAPI의 자동 기능을 사용하지 않고, 자체 코드로 요청을 읽고 검증하기로 결정할 수도 있지만, OpenAPI 스키마에는 여전히 그 요청을 정의하고 싶을 수 있습니다. |
|||
|
|||
그럴 때 `openapi_extra`를 사용할 수 있습니다: |
|||
|
|||
{* ../../docs_src/path_operation_advanced_configuration/tutorial006_py39.py hl[19:36, 39:40] *} |
|||
|
|||
이 예시에서는 어떤 Pydantic 모델도 선언하지 않았습니다. 사실 요청 바디는 JSON으로 <abbr title="converted from some plain format, like bytes, into Python objects - bytes 같은 일반 형식에서 Python 객체로 변환">parsed</abbr>되지도 않고, `bytes`로 직접 읽습니다. 그리고 함수 `magic_data_reader()`가 어떤 방식으로든 이를 파싱하는 역할을 담당합니다. |
|||
|
|||
그럼에도 불구하고, 요청 바디에 대해 기대하는 스키마를 선언할 수 있습니다. |
|||
|
|||
### 사용자 정의 OpenAPI 콘텐츠 타입 { #custom-openapi-content-type } |
|||
|
|||
같은 트릭을 사용하면, Pydantic 모델을 이용해 JSON Schema를 정의하고 이를 *경로 처리*의 사용자 정의 OpenAPI 스키마 섹션에 포함시킬 수 있습니다. |
|||
|
|||
요청의 데이터 타입이 JSON이 아니더라도 이렇게 할 수 있습니다. |
|||
|
|||
예를 들어 이 애플리케이션에서는 Pydantic 모델에서 JSON Schema를 추출하는 FastAPI의 통합 기능도, JSON에 대한 자동 검증도 사용하지 않습니다. 실제로 요청 콘텐츠 타입을 JSON이 아니라 YAML로 선언합니다: |
|||
|
|||
{* ../../docs_src/path_operation_advanced_configuration/tutorial007_py39.py hl[15:20, 22] *} |
|||
|
|||
그럼에도 기본 통합 기능을 사용하지 않더라도, YAML로 받고자 하는 데이터에 대한 JSON Schema를 수동으로 생성하기 위해 Pydantic 모델을 여전히 사용합니다. |
|||
|
|||
그 다음 요청을 직접 사용하고, 바디를 `bytes`로 추출합니다. 이는 FastAPI가 요청 페이로드를 JSON으로 파싱하려고 시도조차 하지 않는다는 뜻입니다. |
|||
|
|||
그리고 코드에서 YAML 콘텐츠를 직접 파싱한 뒤, 다시 같은 Pydantic 모델을 사용해 YAML 콘텐츠를 검증합니다: |
|||
|
|||
{* ../../docs_src/path_operation_advanced_configuration/tutorial007_py39.py hl[24:31] *} |
|||
|
|||
/// tip | 팁 |
|||
|
|||
여기서는 같은 Pydantic 모델을 재사용합니다. |
|||
|
|||
하지만 마찬가지로, 다른 방식으로 검증할 수도 있습니다. |
|||
|
|||
/// |
|||
@ -1,31 +1,31 @@ |
|||
# 응답 - 상태 코드 변경 |
|||
# 응답 - 상태 코드 변경 { #response-change-status-code } |
|||
|
|||
기본 [응답 상태 코드 설정](../tutorial/response-status-code.md){.internal-link target=_blank}이 가능하다는 걸 이미 알고 계실 겁니다. |
|||
|
|||
하지만 경우에 따라 기본 설정과 다른 상태 코드를 반환해야 할 때가 있습니다. |
|||
|
|||
## 사용 예 |
|||
## 사용 예 { #use-case } |
|||
|
|||
예를 들어 기본적으로 HTTP 상태 코드 "OK" `200`을 반환하고 싶다고 가정해 봅시다. |
|||
|
|||
하지만 데이터가 존재하지 않으면 이를 새로 생성하고, HTTP 상태 코드 "CREATED" `201`을 반환하고자 할 때가 있을 수 있습니다. |
|||
|
|||
이때도 여전히 `response_model`을 사용하여 반환하는 데이터를 필터링하고 변환하고 싶을 수 있습니다. |
|||
하지만 여전히 `response_model`을 사용하여 반환하는 데이터를 필터링하고 변환할 수 있기를 원합니다. |
|||
|
|||
이런 경우에는 `Response` 파라미터를 사용할 수 있습니다. |
|||
|
|||
## `Response` 파라미터 사용하기 |
|||
## `Response` 파라미터 사용하기 { #use-a-response-parameter } |
|||
|
|||
*경로 작동 함수*에 `Response` 타입의 파라미터를 선언할 수 있습니다. (쿠키와 헤더에 대해 선언하는 것과 유사하게) |
|||
*경로 처리 함수*에 `Response` 타입의 파라미터를 선언할 수 있습니다. (쿠키와 헤더에 대해 선언하는 것과 유사하게) |
|||
|
|||
그리고 이 *임시* 응답 객체에서 `status_code`를 설정할 수 있습니다. |
|||
|
|||
{* ../../docs_src/response_change_status_code/tutorial001.py hl[1,9,12] *} |
|||
{* ../../docs_src/response_change_status_code/tutorial001_py39.py hl[1,9,12] *} |
|||
|
|||
그리고 평소처럼 원하는 객체(`dict`, 데이터베이스 모델 등)를 반환할 수 있습니다. |
|||
그리고 평소처럼 필요한 어떤 객체든 반환할 수 있습니다(`dict`, 데이터베이스 모델 등). |
|||
|
|||
`response_model`을 선언했다면 반환된 객체는 여전히 필터링되고 변환됩니다. |
|||
|
|||
**FastAPI**는 이 *임시* 응답 객체에서 상태 코드(쿠키와 헤더 포함)를 추출하여, `response_model`로 필터링된 반환 값을 최종 응답에 넣습니다. |
|||
**FastAPI**는 이 *임시* 응답 객체에서 상태 코드(쿠키와 헤더 포함)를 추출하여, `response_model`로 필터링된 반환 값을 포함하는 최종 응답에 넣습니다. |
|||
|
|||
또한, 의존성에서도 `Response` 파라미터를 선언하고 그 안에서 상태 코드를 설정할 수 있습니다. 단, 마지막으로 설정된 상태 코드가 우선 적용된다는 점을 유의하세요. |
|||
|
|||
@ -1,49 +1,51 @@ |
|||
# 응답 쿠키 |
|||
# 응답 쿠키 { #response-cookies } |
|||
|
|||
## `Response` 매개변수 사용하기 |
|||
## `Response` 매개변수 사용하기 { #use-a-response-parameter } |
|||
|
|||
*경로 작동 함수*에서 `Response` 타입의 매개변수를 선언할 수 있습니다. |
|||
*경로 처리 함수*에서 `Response` 타입의 매개변수를 선언할 수 있습니다. |
|||
|
|||
그런 다음 해당 *임시* 응답 객체에서 쿠키를 설정할 수 있습니다. |
|||
|
|||
{* ../../docs_src/response_cookies/tutorial002.py hl[1,8:9] *} |
|||
{* ../../docs_src/response_cookies/tutorial002_py39.py hl[1, 8:9] *} |
|||
|
|||
그런 다음 필요한 객체(`dict`, 데이터베이스 모델 등)를 반환할 수 있습니다. |
|||
그런 다음 일반적으로 하듯이 필요한 어떤 객체든 반환할 수 있습니다(`dict`, 데이터베이스 모델 등). |
|||
|
|||
그리고 `response_model`을 선언했다면 반환한 객체를 거르고 변환하는 데 여전히 사용됩니다. |
|||
|
|||
**FastAPI**는 그 *임시* 응답에서 쿠키(또한 헤더 및 상태 코드)를 추출하고, 반환된 값이 포함된 최종 응답에 이를 넣습니다. 이 값은 `response_model`로 걸러지게 됩니다. |
|||
**FastAPI**는 그 *임시* 응답에서 쿠키(또한 헤더 및 상태 코드)를 추출하고, `response_model`로 필터링된 반환 값이 포함된 최종 응답에 이를 넣습니다. |
|||
|
|||
또한 의존관계에서 `Response` 매개변수를 선언하고, 해당 의존성에서 쿠키(및 헤더)를 설정할 수도 있습니다. |
|||
|
|||
## `Response`를 직접 반환하기 |
|||
## `Response`를 직접 반환하기 { #return-a-response-directly } |
|||
|
|||
코드에서 `Response`를 직접 반환할 때도 쿠키를 생성할 수 있습니다. |
|||
|
|||
이를 위해 [Response를 직접 반환하기](response-directly.md){.internal-link target=_blank}에서 설명한 대로 응답을 생성할 수 있습니다. |
|||
|
|||
그런 다음 쿠키를 설정하고 반환하면 됩니다: |
|||
{* ../../docs_src/response_directly/tutorial002.py hl[1,18] *} |
|||
/// tip |
|||
|
|||
{* ../../docs_src/response_cookies/tutorial001_py39.py hl[10:12] *} |
|||
|
|||
/// tip | 팁 |
|||
|
|||
`Response` 매개변수를 사용하지 않고 응답을 직접 반환하는 경우, FastAPI는 이를 직접 반환한다는 점에 유의하세요. |
|||
|
|||
따라서 데이터가 올바른 유형인지 확인해야 합니다. 예: `JSONResponse`를 반환하는 경우, JSON과 호환되는지 확인하세요. |
|||
|
|||
또한 `response_model`로 걸러져야 할 데이터가 전달되지 않도록 확인하세요. |
|||
또한 `response_model`로 필터링되어야 했던 데이터를 전송하지 않도록 하세요. |
|||
|
|||
/// |
|||
|
|||
### 추가 정보 |
|||
### 추가 정보 { #more-info } |
|||
|
|||
/// note | 기술적 세부사항 |
|||
/// note | 기술 세부사항 |
|||
|
|||
`from starlette.responses import Response` 또는 `from starlette.responses import JSONResponse`를 사용할 수도 있습니다. |
|||
|
|||
**FastAPI**는 개발자의 편의를 위해 `fastapi.responses`로 동일한 `starlette.responses`를 제공합니다. 그러나 대부분의 응답은 Starlette에서 직접 제공됩니다. |
|||
**FastAPI**는 개발자의 편의를 위해 `fastapi.responses`로 동일한 `starlette.responses`를 제공합니다. 하지만 사용 가능한 대부분의 응답은 Starlette에서 직접 제공됩니다. |
|||
|
|||
또한 `Response`는 헤더와 쿠키를 설정하는 데 자주 사용되므로, **FastAPI**는 이를 `fastapi.Response`로도 제공합니다. |
|||
|
|||
/// |
|||
|
|||
사용 가능한 모든 매개변수와 옵션은 <a href="https://www.starlette.dev/responses/#set-cookie" class="external-link" target="_blank">Starlette 문서</a>에서 확인할 수 있습니다. |
|||
사용 가능한 모든 매개변수와 옵션은 <a href="https://www.starlette.dev/responses/#set-cookie" class="external-link" target="_blank">Starlette의 문서</a>에서 확인할 수 있습니다. |
|||
|
|||
@ -0,0 +1,107 @@ |
|||
# HTTP Basic Auth { #http-basic-auth } |
|||
|
|||
가장 단순한 경우에는 HTTP Basic Auth를 사용할 수 있습니다. |
|||
|
|||
HTTP Basic Auth에서는 애플리케이션이 사용자명과 비밀번호가 들어 있는 헤더를 기대합니다. |
|||
|
|||
이를 받지 못하면 HTTP 401 "Unauthorized" 오류를 반환합니다. |
|||
|
|||
그리고 값이 `Basic`이고 선택적으로 `realm` 파라미터를 포함하는 `WWW-Authenticate` 헤더를 반환합니다. |
|||
|
|||
이는 브라우저가 사용자명과 비밀번호를 입력하는 통합 프롬프트를 표시하도록 알려줍니다. |
|||
|
|||
그다음 사용자명과 비밀번호를 입력하면, 브라우저가 자동으로 해당 값을 헤더에 담아 전송합니다. |
|||
|
|||
## 간단한 HTTP Basic Auth { #simple-http-basic-auth } |
|||
|
|||
* `HTTPBasic`과 `HTTPBasicCredentials`를 임포트합니다. |
|||
* `HTTPBasic`을 사용해 "`security` scheme"을 생성합니다. |
|||
* *경로 처리*에서 dependency로 해당 `security`를 사용합니다. |
|||
* `HTTPBasicCredentials` 타입의 객체를 반환합니다: |
|||
* 전송된 `username`과 `password`를 포함합니다. |
|||
|
|||
{* ../../docs_src/security/tutorial006_an_py39.py hl[4,8,12] *} |
|||
|
|||
처음으로 URL을 열어보면(또는 문서에서 "Execute" 버튼을 클릭하면) 브라우저가 사용자명과 비밀번호를 물어봅니다: |
|||
|
|||
<img src="/img/tutorial/security/image12.png"> |
|||
|
|||
## 사용자명 확인하기 { #check-the-username } |
|||
|
|||
더 완전한 예시입니다. |
|||
|
|||
dependency를 사용해 사용자명과 비밀번호가 올바른지 확인하세요. |
|||
|
|||
이를 위해 Python 표준 모듈 <a href="https://docs.python.org/3/library/secrets.html" class="external-link" target="_blank">`secrets`</a>를 사용해 사용자명과 비밀번호를 확인합니다. |
|||
|
|||
`secrets.compare_digest()`는 `bytes` 또는 ASCII 문자(영어에서 사용하는 문자)만 포함한 `str`을 받아야 합니다. 즉, `Sebastián`의 `á` 같은 문자가 있으면 동작하지 않습니다. |
|||
|
|||
이를 처리하기 위해 먼저 `username`과 `password`를 UTF-8로 인코딩해서 `bytes`로 변환합니다. |
|||
|
|||
그런 다음 `secrets.compare_digest()`를 사용해 `credentials.username`이 `"stanleyjobson"`이고 `credentials.password`가 `"swordfish"`인지 확실히 확인할 수 있습니다. |
|||
|
|||
{* ../../docs_src/security/tutorial007_an_py39.py hl[1,12:24] *} |
|||
|
|||
이는 다음과 비슷합니다: |
|||
|
|||
```Python |
|||
if not (credentials.username == "stanleyjobson") or not (credentials.password == "swordfish"): |
|||
# Return some error |
|||
... |
|||
``` |
|||
|
|||
하지만 `secrets.compare_digest()`를 사용하면 "timing attacks"라고 불리는 한 유형의 공격에 대해 안전해집니다. |
|||
|
|||
### Timing Attacks { #timing-attacks } |
|||
|
|||
그렇다면 "timing attack"이란 무엇일까요? |
|||
|
|||
공격자들이 사용자명과 비밀번호를 추측하려고 한다고 가정해봅시다. |
|||
|
|||
그리고 사용자명 `johndoe`, 비밀번호 `love123`으로 요청을 보냅니다. |
|||
|
|||
그러면 애플리케이션의 Python 코드는 대략 다음과 같을 것입니다: |
|||
|
|||
```Python |
|||
if "johndoe" == "stanleyjobson" and "love123" == "swordfish": |
|||
... |
|||
``` |
|||
|
|||
하지만 Python이 `johndoe`의 첫 글자 `j`를 `stanleyjobson`의 첫 글자 `s`와 비교하는 순간, 두 문자열이 같지 않다는 것을 이미 알게 되어 `False`를 반환합니다. 이는 “나머지 글자들을 비교하느라 계산을 더 낭비할 필요가 없다”고 판단하기 때문입니다. 그리고 애플리케이션은 "Incorrect username or password"라고 말합니다. |
|||
|
|||
그런데 공격자들이 사용자명을 `stanleyjobsox`, 비밀번호를 `love123`으로 다시 시도합니다. |
|||
|
|||
그러면 애플리케이션 코드는 다음과 비슷하게 동작합니다: |
|||
|
|||
```Python |
|||
if "stanleyjobsox" == "stanleyjobson" and "love123" == "swordfish": |
|||
... |
|||
``` |
|||
|
|||
Python은 두 문자열이 같지 않다는 것을 알아차리기 전까지 `stanleyjobsox`와 `stanleyjobson` 양쪽의 `stanleyjobso` 전체를 비교해야 합니다. 그래서 "Incorrect username or password"라고 응답하기까지 추가로 몇 마이크로초가 더 걸릴 것입니다. |
|||
|
|||
#### 응답 시간은 공격자에게 도움이 됩니다 { #the-time-to-answer-helps-the-attackers } |
|||
|
|||
이 시점에서 서버가 "Incorrect username or password" 응답을 보내는 데 몇 마이크로초 더 걸렸다는 것을 알아채면, 공격자들은 _무언가_ 맞았다는 것(초기 몇 글자가 맞았다는 것)을 알게 됩니다. |
|||
|
|||
그리고 `johndoe`보다는 `stanleyjobsox`에 더 가까운 값을 시도해야 한다는 것을 알고 다시 시도할 수 있습니다. |
|||
|
|||
#### "전문적인" 공격 { #a-professional-attack } |
|||
|
|||
물론 공격자들은 이런 작업을 손으로 하지 않습니다. 보통 초당 수천~수백만 번 테스트할 수 있는 프로그램을 작성할 것이고, 한 번에 정답 글자 하나씩 추가로 얻어낼 수 있습니다. |
|||
|
|||
그렇게 하면 몇 분 또는 몇 시간 만에, 응답에 걸린 시간만을 이용해(우리 애플리케이션의 “도움”을 받아) 올바른 사용자명과 비밀번호를 추측할 수 있게 됩니다. |
|||
|
|||
#### `secrets.compare_digest()`로 해결하기 { #fix-it-with-secrets-compare-digest } |
|||
|
|||
하지만 우리 코드는 실제로 `secrets.compare_digest()`를 사용하고 있습니다. |
|||
|
|||
요약하면, `stanleyjobsox`와 `stanleyjobson`을 비교하는 데 걸리는 시간은 `johndoe`와 `stanleyjobson`을 비교하는 데 걸리는 시간과 같아집니다. 비밀번호도 마찬가지입니다. |
|||
|
|||
이렇게 애플리케이션 코드에서 `secrets.compare_digest()`를 사용하면, 이러한 범위의 보안 공격 전반에 대해 안전해집니다. |
|||
|
|||
### 오류 반환하기 { #return-the-error } |
|||
|
|||
자격 증명이 올바르지 않다고 판단되면, 상태 코드 401(자격 증명이 제공되지 않았을 때와 동일)을 사용하는 `HTTPException`을 반환하고 브라우저가 로그인 프롬프트를 다시 표시하도록 `WWW-Authenticate` 헤더를 추가하세요: |
|||
|
|||
{* ../../docs_src/security/tutorial007_an_py39.py hl[26:30] *} |
|||
@ -0,0 +1,19 @@ |
|||
# 고급 보안 { #advanced-security } |
|||
|
|||
## 추가 기능 { #additional-features } |
|||
|
|||
[튜토리얼 - 사용자 가이드: 보안](../../tutorial/security/index.md){.internal-link target=_blank}에서 다룬 내용 외에도, 보안을 처리하기 위한 몇 가지 추가 기능이 있습니다. |
|||
|
|||
/// tip | 팁 |
|||
|
|||
다음 섹션들은 **반드시 "고급"이라고 할 수는 없습니다**. |
|||
|
|||
그리고 사용 사례에 따라, 그중 하나에 해결책이 있을 수도 있습니다. |
|||
|
|||
/// |
|||
|
|||
## 먼저 튜토리얼 읽기 { #read-the-tutorial-first } |
|||
|
|||
다음 섹션은 주요 [튜토리얼 - 사용자 가이드: 보안](../../tutorial/security/index.md){.internal-link target=_blank}을 이미 읽었다고 가정합니다. |
|||
|
|||
모두 동일한 개념을 기반으로 하지만, 몇 가지 추가 기능을 사용할 수 있게 해줍니다. |
|||
@ -0,0 +1,274 @@ |
|||
# OAuth2 스코프 { #oauth2-scopes } |
|||
|
|||
**FastAPI**에서 OAuth2 스코프를 직접 사용할 수 있으며, 자연스럽게 동작하도록 통합되어 있습니다. |
|||
|
|||
이를 통해 OAuth2 표준을 따르는 더 세밀한 권한 시스템을 OpenAPI 애플리케이션(및 API 문서)에 통합할 수 있습니다. |
|||
|
|||
스코프를 사용하는 OAuth2는 Facebook, Google, GitHub, Microsoft, X(Twitter) 등 많은 대형 인증 제공자가 사용하는 메커니즘입니다. 이들은 이를 통해 사용자와 애플리케이션에 특정 권한을 제공합니다. |
|||
|
|||
Facebook, Google, GitHub, Microsoft, X(Twitter)로 “로그인”할 때마다, 해당 애플리케이션은 스코프가 있는 OAuth2를 사용하고 있습니다. |
|||
|
|||
이 섹션에서는 **FastAPI** 애플리케이션에서 동일한 “스코프가 있는 OAuth2”로 인증(Authentication)과 인가(Authorization)를 관리하는 방법을 확인합니다. |
|||
|
|||
/// warning | 경고 |
|||
|
|||
이 섹션은 다소 고급 내용입니다. 이제 막 시작했다면 건너뛰어도 됩니다. |
|||
|
|||
OAuth2 스코프가 반드시 필요한 것은 아니며, 인증과 인가는 원하는 방식으로 처리할 수 있습니다. |
|||
|
|||
하지만 스코프가 있는 OAuth2는 (OpenAPI와 함께) API 및 API 문서에 깔끔하게 통합될 수 있습니다. |
|||
|
|||
그럼에도 불구하고, 해당 스코프(또는 그 밖의 어떤 보안/인가 요구사항이든)는 코드에서 필요에 맞게 직접 강제해야 합니다. |
|||
|
|||
많은 경우 스코프가 있는 OAuth2는 과한 선택일 수 있습니다. |
|||
|
|||
하지만 필요하다고 알고 있거나 궁금하다면 계속 읽어보세요. |
|||
|
|||
/// |
|||
|
|||
## OAuth2 스코프와 OpenAPI { #oauth2-scopes-and-openapi } |
|||
|
|||
OAuth2 사양은 “스코프(scopes)”를 공백으로 구분된 문자열 목록으로 정의합니다. |
|||
|
|||
각 문자열의 내용은 어떤 형식이든 될 수 있지만, 공백을 포함하면 안 됩니다. |
|||
|
|||
이 스코프들은 “권한”을 나타냅니다. |
|||
|
|||
OpenAPI(예: API 문서)에서는 “security schemes”를 정의할 수 있습니다. |
|||
|
|||
이 security scheme 중 하나가 OAuth2를 사용한다면, 스코프도 선언하고 사용할 수 있습니다. |
|||
|
|||
각 “스코프”는 (공백 없는) 문자열일 뿐입니다. |
|||
|
|||
보통 다음과 같이 특정 보안 권한을 선언하는 데 사용합니다: |
|||
|
|||
* `users:read` 또는 `users:write` 는 흔한 예시입니다. |
|||
* `instagram_basic` 는 Facebook/Instagram에서 사용합니다. |
|||
* `https://www.googleapis.com/auth/drive` 는 Google에서 사용합니다. |
|||
|
|||
/// info | 정보 |
|||
|
|||
OAuth2에서 “스코프”는 필요한 특정 권한을 선언하는 문자열일 뿐입니다. |
|||
|
|||
`:` 같은 다른 문자가 있거나 URL이어도 상관없습니다. |
|||
|
|||
그런 세부사항은 구현에 따라 달라집니다. |
|||
|
|||
OAuth2 입장에서는 그저 문자열입니다. |
|||
|
|||
/// |
|||
|
|||
## 전체 개요 { #global-view } |
|||
|
|||
먼저, 메인 **튜토리얼 - 사용자 가이드**의 [비밀번호(및 해싱)를 사용하는 OAuth2, JWT 토큰을 사용하는 Bearer](../../tutorial/security/oauth2-jwt.md){.internal-link target=_blank} 예제에서 어떤 부분이 바뀌는지 빠르게 살펴보겠습니다. 이제 OAuth2 스코프를 사용합니다: |
|||
|
|||
{* ../../docs_src/security/tutorial005_an_py310.py hl[5,9,13,47,65,106,108:116,122:126,130:136,141,157] *} |
|||
|
|||
이제 변경 사항을 단계별로 살펴보겠습니다. |
|||
|
|||
## OAuth2 보안 스킴 { #oauth2-security-scheme } |
|||
|
|||
첫 번째 변경 사항은 이제 사용 가능한 스코프 2개(`me`, `items`)로 OAuth2 보안 스킴을 선언한다는 점입니다. |
|||
|
|||
`scopes` 매개변수는 각 스코프를 키로 하고, 설명을 값으로 하는 `dict`를 받습니다: |
|||
|
|||
{* ../../docs_src/security/tutorial005_an_py310.py hl[63:66] *} |
|||
|
|||
이제 스코프를 선언했기 때문에, 로그인/인가할 때 API 문서에 스코프가 표시됩니다. |
|||
|
|||
그리고 접근을 허용할 스코프를 선택할 수 있게 됩니다: `me`와 `items`. |
|||
|
|||
이는 Facebook, Google, GitHub 등으로 로그인하면서 권한을 부여할 때 사용되는 것과 동일한 메커니즘입니다: |
|||
|
|||
<img src="/img/tutorial/security/image11.png"> |
|||
|
|||
## 스코프를 포함한 JWT 토큰 { #jwt-token-with-scopes } |
|||
|
|||
이제 토큰 *경로 처리*를 수정해, 요청된 스코프를 반환하도록 합니다. |
|||
|
|||
여전히 동일한 `OAuth2PasswordRequestForm`을 사용합니다. 여기에는 요청에서 받은 각 스코프를 담는 `scopes` 속성이 있으며, 타입은 `str`의 `list`입니다. |
|||
|
|||
그리고 JWT 토큰의 일부로 스코프를 반환합니다. |
|||
|
|||
/// danger | 위험 |
|||
|
|||
단순화를 위해, 여기서는 요청으로 받은 스코프를 그대로 토큰에 추가하고 있습니다. |
|||
|
|||
하지만 실제 애플리케이션에서는 보안을 위해, 사용자가 실제로 가질 수 있는 스코프만(또는 미리 정의한 것만) 추가하도록 반드시 확인해야 합니다. |
|||
|
|||
/// |
|||
|
|||
{* ../../docs_src/security/tutorial005_an_py310.py hl[157] *} |
|||
|
|||
## *경로 처리*와 의존성에서 스코프 선언하기 { #declare-scopes-in-path-operations-and-dependencies } |
|||
|
|||
이제 `/users/me/items/`에 대한 *경로 처리*가 스코프 `items`를 요구한다고 선언합니다. |
|||
|
|||
이를 위해 `fastapi`에서 `Security`를 import하여 사용합니다. |
|||
|
|||
`Security`는 (`Depends`처럼) 의존성을 선언하는 데 사용할 수 있지만, `Security`는 스코프(문자열) 목록을 받는 `scopes` 매개변수도 받습니다. |
|||
|
|||
이 경우, 의존성 함수 `get_current_active_user`를 `Security`에 전달합니다(`Depends`로 할 때와 같은 방식). |
|||
|
|||
하지만 스코프 `list`도 함께 전달합니다. 여기서는 스코프 하나만: `items`(더 많을 수도 있습니다). |
|||
|
|||
또한 의존성 함수 `get_current_active_user`는 `Depends`뿐 아니라 `Security`로도 하위 의존성을 선언할 수 있습니다. 자체 하위 의존성 함수(`get_current_user`)와 추가 스코프 요구사항을 선언합니다. |
|||
|
|||
이 경우에는 스코프 `me`를 요구합니다(여러 스코프를 요구할 수도 있습니다). |
|||
|
|||
/// note | 참고 |
|||
|
|||
반드시 서로 다른 곳에 서로 다른 스코프를 추가해야 하는 것은 아닙니다. |
|||
|
|||
여기서는 **FastAPI**가 서로 다른 레벨에서 선언된 스코프를 어떻게 처리하는지 보여주기 위해 이렇게 합니다. |
|||
|
|||
/// |
|||
|
|||
{* ../../docs_src/security/tutorial005_an_py310.py hl[5,141,172] *} |
|||
|
|||
/// info | 기술 세부사항 |
|||
|
|||
`Security`는 실제로 `Depends`의 서브클래스이며, 나중에 보게 될 추가 매개변수 하나만 더 있습니다. |
|||
|
|||
하지만 `Depends` 대신 `Security`를 사용하면, **FastAPI**는 보안 스코프를 선언할 수 있음을 알고 내부적으로 이를 사용하며, OpenAPI로 API를 문서화할 수 있습니다. |
|||
|
|||
하지만 `fastapi`에서 `Query`, `Path`, `Depends`, `Security` 등을 import할 때, 이것들은 실제로 특수한 클래스를 반환하는 함수입니다. |
|||
|
|||
/// |
|||
|
|||
## `SecurityScopes` 사용하기 { #use-securityscopes } |
|||
|
|||
이제 의존성 `get_current_user`를 업데이트합니다. |
|||
|
|||
이는 위의 의존성들이 사용하는 것입니다. |
|||
|
|||
여기에서 앞서 만든 동일한 OAuth2 스킴을 의존성으로 선언하여 사용합니다: `oauth2_scheme`. |
|||
|
|||
이 의존성 함수 자체에는 스코프 요구사항이 없기 때문에, `oauth2_scheme`와 함께 `Depends`를 사용할 수 있습니다. 보안 스코프를 지정할 필요가 없을 때는 `Security`를 쓸 필요가 없습니다. |
|||
|
|||
또한 `fastapi.security`에서 import한 `SecurityScopes` 타입의 특별한 매개변수를 선언합니다. |
|||
|
|||
이 `SecurityScopes` 클래스는 `Request`와 비슷합니다(`Request`는 요청 객체를 직접 얻기 위해 사용했습니다). |
|||
|
|||
{* ../../docs_src/security/tutorial005_an_py310.py hl[9,106] *} |
|||
|
|||
## `scopes` 사용하기 { #use-the-scopes } |
|||
|
|||
매개변수 `security_scopes`의 타입은 `SecurityScopes`입니다. |
|||
|
|||
여기에는 `scopes` 속성이 있으며, 자기 자신과 이 함수를 하위 의존성으로 사용하는 모든 의존성이 요구하는 스코프 전체를 담은 `list`를 가집니다. 즉, 모든 “dependants”... 다소 헷갈릴 수 있는데, 아래에서 다시 설명합니다. |
|||
|
|||
`security_scopes` 객체(`SecurityScopes` 클래스)에는 또한 `scope_str` 속성이 있는데, 공백으로 구분된 단일 문자열로 스코프들을 담고 있습니다(이를 사용할 것입니다). |
|||
|
|||
나중에 여러 지점에서 재사용(`raise`)할 수 있는 `HTTPException`을 생성합니다. |
|||
|
|||
이 예외에는 필요한 스코프(있다면)를 공백으로 구분된 문자열(`scope_str`)로 포함합니다. 그리고 그 스코프 문자열을 `WWW-Authenticate` 헤더에 넣습니다(이는 사양의 일부입니다). |
|||
|
|||
{* ../../docs_src/security/tutorial005_an_py310.py hl[106,108:116] *} |
|||
|
|||
## `username`과 데이터 형태 검증하기 { #verify-the-username-and-data-shape } |
|||
|
|||
`username`을 얻었는지 확인하고, 스코프를 추출합니다. |
|||
|
|||
그런 다음 Pydantic 모델로 데이터를 검증합니다(`ValidationError` 예외를 잡습니다). JWT 토큰을 읽거나 Pydantic으로 데이터를 검증하는 과정에서 오류가 나면, 앞에서 만든 `HTTPException`을 raise합니다. |
|||
|
|||
이를 위해 Pydantic 모델 `TokenData`에 새 속성 `scopes`를 추가합니다. |
|||
|
|||
Pydantic으로 데이터를 검증하면, 예를 들어 스코프가 정확히 `str`의 `list`이고 `username`이 `str`인지 등을 보장할 수 있습니다. |
|||
|
|||
예를 들어 `dict`나 다른 형태라면, 나중에 애플리케이션이 어느 시점에 깨지면서 보안 위험이 될 수 있습니다. |
|||
|
|||
또한 해당 username을 가진 사용자가 있는지 확인하고, 없다면 앞에서 만든 동일한 예외를 raise합니다. |
|||
|
|||
{* ../../docs_src/security/tutorial005_an_py310.py hl[47,117:129] *} |
|||
|
|||
## `scopes` 검증하기 { #verify-the-scopes } |
|||
|
|||
이제 이 의존성과 모든 dependant( *경로 처리* 포함)가 요구하는 모든 스코프가, 받은 토큰의 스코프에 포함되어 있는지 확인합니다. 그렇지 않으면 `HTTPException`을 raise합니다. |
|||
|
|||
이를 위해, 모든 스코프를 `str`로 담고 있는 `security_scopes.scopes`를 사용합니다. |
|||
|
|||
{* ../../docs_src/security/tutorial005_an_py310.py hl[130:136] *} |
|||
|
|||
## 의존성 트리와 스코프 { #dependency-tree-and-scopes } |
|||
|
|||
이 의존성 트리와 스코프를 다시 살펴보겠습니다. |
|||
|
|||
`get_current_active_user` 의존성은 `get_current_user`를 하위 의존성으로 가지므로, `get_current_active_user`에서 선언된 스코프 `"me"`는 `get_current_user`에 전달되는 `security_scopes.scopes`의 요구 스코프 목록에 포함됩니다. |
|||
|
|||
*경로 처리* 자체도 스코프 `"items"`를 선언하므로, 이것 또한 `get_current_user`에 전달되는 `security_scopes.scopes` 목록에 포함됩니다. |
|||
|
|||
의존성과 스코프의 계층 구조는 다음과 같습니다: |
|||
|
|||
* *경로 처리* `read_own_items`는: |
|||
* 의존성과 함께 요구 스코프 `["items"]`를 가집니다: |
|||
* `get_current_active_user`: |
|||
* 의존성 함수 `get_current_active_user`는: |
|||
* 의존성과 함께 요구 스코프 `["me"]`를 가집니다: |
|||
* `get_current_user`: |
|||
* 의존성 함수 `get_current_user`는: |
|||
* 자체적으로는 요구 스코프가 없습니다. |
|||
* `oauth2_scheme`를 사용하는 의존성이 있습니다. |
|||
* `SecurityScopes` 타입의 `security_scopes` 매개변수가 있습니다: |
|||
* 이 `security_scopes` 매개변수는 위에서 선언된 모든 스코프를 담은 `list`인 `scopes` 속성을 가지므로: |
|||
* *경로 처리* `read_own_items`의 경우 `security_scopes.scopes`에는 `["me", "items"]`가 들어갑니다. |
|||
* *경로 처리* `read_users_me`의 경우 `security_scopes.scopes`에는 `["me"]`가 들어갑니다. 이는 의존성 `get_current_active_user`에서 선언되기 때문입니다. |
|||
* *경로 처리* `read_system_status`의 경우 `security_scopes.scopes`에는 `[]`(없음)가 들어갑니다. `scopes`가 있는 `Security`를 선언하지 않았고, 그 의존성인 `get_current_user`도 `scopes`를 선언하지 않았기 때문입니다. |
|||
|
|||
/// tip | 팁 |
|||
|
|||
여기서 중요한 “마법 같은” 점은 `get_current_user`가 각 *경로 처리*마다 검사해야 하는 `scopes` 목록이 달라진다는 것입니다. |
|||
|
|||
이는 특정 *경로 처리*에 대한 의존성 트리에서, 각 *경로 처리*와 각 의존성에 선언된 `scopes`에 따라 달라집니다. |
|||
|
|||
/// |
|||
|
|||
## `SecurityScopes`에 대한 추가 설명 { #more-details-about-securityscopes } |
|||
|
|||
`SecurityScopes`는 어느 지점에서든, 그리고 여러 곳에서 사용할 수 있으며, “루트” 의존성에만 있어야 하는 것은 아닙니다. |
|||
|
|||
`SecurityScopes`는 **해당 특정** *경로 처리*와 **해당 특정** 의존성 트리에 대해, 현재 `Security` 의존성과 모든 dependant에 선언된 보안 스코프를 항상 갖고 있습니다. |
|||
|
|||
`SecurityScopes`에는 dependant가 선언한 모든 스코프가 포함되므로, 중앙의 의존성 함수에서 토큰이 필요한 스코프를 가지고 있는지 검증한 다음, 서로 다른 *경로 처리*에서 서로 다른 스코프 요구사항을 선언할 수 있습니다. |
|||
|
|||
이들은 각 *경로 처리*마다 독립적으로 검사됩니다. |
|||
|
|||
## 확인하기 { #check-it } |
|||
|
|||
API 문서를 열면, 인증하고 인가할 스코프를 지정할 수 있습니다. |
|||
|
|||
<img src="/img/tutorial/security/image11.png"> |
|||
|
|||
어떤 스코프도 선택하지 않으면 “인증”은 되지만, `/users/me/` 또는 `/users/me/items/`에 접근하려고 하면 권한이 충분하지 않다는 오류가 발생합니다. `/status/`에는 여전히 접근할 수 있습니다. |
|||
|
|||
그리고 스코프 `me`는 선택했지만 스코프 `items`는 선택하지 않았다면, `/users/me/`에는 접근할 수 있지만 `/users/me/items/`에는 접근할 수 없습니다. |
|||
|
|||
이는 사용자가 애플리케이션에 얼마나 많은 권한을 부여했는지에 따라, 제3자 애플리케이션이 사용자로부터 제공받은 토큰으로 이 *경로 처리*들 중 하나에 접근하려고 할 때 발생하는 상황과 같습니다. |
|||
|
|||
## 제3자 통합에 대해 { #about-third-party-integrations } |
|||
|
|||
이 예제에서는 OAuth2 “password” 플로우를 사용하고 있습니다. |
|||
|
|||
이는 보통 자체 프론트엔드가 있는 우리 애플리케이션에 로그인할 때 적합합니다. |
|||
|
|||
우리가 이를 통제하므로 `username`과 `password`를 받는 것을 신뢰할 수 있기 때문입니다. |
|||
|
|||
하지만 다른 사람들이 연결할 OAuth2 애플리케이션(즉, Facebook, Google, GitHub 등과 동등한 인증 제공자를 만들고 있다면)을 구축한다면, 다른 플로우 중 하나를 사용해야 합니다. |
|||
|
|||
가장 흔한 것은 implicit 플로우입니다. |
|||
|
|||
가장 안전한 것은 code 플로우이지만, 더 많은 단계가 필요해 구현이 더 복잡합니다. 복잡하기 때문에 많은 제공자는 implicit 플로우를 권장하게 됩니다. |
|||
|
|||
/// note | 참고 |
|||
|
|||
인증 제공자마다 자신들의 브랜드의 일부로 만들기 위해, 각 플로우를 서로 다른 방식으로 이름 붙이는 경우가 흔합니다. |
|||
|
|||
하지만 결국, 동일한 OAuth2 표준을 구현하고 있는 것입니다. |
|||
|
|||
/// |
|||
|
|||
**FastAPI**는 `fastapi.security.oauth2`에 이러한 모든 OAuth2 인증 플로우를 위한 유틸리티를 포함합니다. |
|||
|
|||
## 데코레이터 `dependencies`에서의 `Security` { #security-in-decorator-dependencies } |
|||
|
|||
[경로 처리 데코레이터의 의존성](../../tutorial/dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}에서 설명한 것처럼 데코레이터의 `dependencies` 매개변수에 `Depends`의 `list`를 정의할 수 있는 것과 같은 방식으로, 거기에서 `scopes`와 함께 `Security`를 사용할 수도 있습니다. |
|||
@ -0,0 +1,302 @@ |
|||
# 설정과 환경 변수 { #settings-and-environment-variables } |
|||
|
|||
많은 경우 애플리케이션에는 외부 설정이나 구성(예: secret key, 데이터베이스 자격 증명, 이메일 서비스 자격 증명 등)이 필요할 수 있습니다. |
|||
|
|||
이러한 설정 대부분은 데이터베이스 URL처럼 변동 가능(변경될 수 있음)합니다. 그리고 많은 설정은 secret처럼 민감할 수 있습니다. |
|||
|
|||
이 때문에 보통 애플리케이션이 읽어들이는 환경 변수로 이를 제공하는 것이 일반적입니다. |
|||
|
|||
/// tip | 팁 |
|||
|
|||
환경 변수를 이해하려면 [환경 변수](../environment-variables.md){.internal-link target=_blank}를 읽어보세요. |
|||
|
|||
/// |
|||
|
|||
## 타입과 검증 { #types-and-validation } |
|||
|
|||
이 환경 변수들은 Python 외부에 있으며 다른 프로그램 및 시스템의 나머지 부분(그리고 Linux, Windows, macOS 같은 서로 다른 운영체제와도)과 호환되어야 하므로, 텍스트 문자열만 다룰 수 있습니다. |
|||
|
|||
즉, Python에서 환경 변수로부터 읽어온 어떤 값이든 `str`이 되며, 다른 타입으로의 변환이나 검증은 코드에서 수행해야 합니다. |
|||
|
|||
## Pydantic `Settings` { #pydantic-settings } |
|||
|
|||
다행히 Pydantic은 <a href="https://docs.pydantic.dev/latest/concepts/pydantic_settings/" class="external-link" target="_blank">Pydantic: Settings management</a>를 통해 환경 변수에서 오는 이러한 설정을 처리할 수 있는 훌륭한 유틸리티를 제공합니다. |
|||
|
|||
### `pydantic-settings` 설치하기 { #install-pydantic-settings } |
|||
|
|||
먼저 [가상 환경](../virtual-environments.md){.internal-link target=_blank}을 만들고 활성화한 다음, `pydantic-settings` 패키지를 설치하세요: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ pip install pydantic-settings |
|||
---> 100% |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
또는 다음처럼 `all` extras를 설치하면 함께 포함됩니다: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ pip install "fastapi[all]" |
|||
---> 100% |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
### `Settings` 객체 만들기 { #create-the-settings-object } |
|||
|
|||
Pydantic에서 `BaseSettings`를 import하고, Pydantic 모델과 매우 비슷하게 서브클래스를 만드세요. |
|||
|
|||
Pydantic 모델과 같은 방식으로, 타입 어노테이션(그리고 필요하다면 기본값)과 함께 클래스 속성을 선언합니다. |
|||
|
|||
다양한 데이터 타입, `Field()`로 추가 검증 등 Pydantic 모델에서 사용하는 동일한 검증 기능과 도구를 모두 사용할 수 있습니다. |
|||
|
|||
{* ../../docs_src/settings/tutorial001_py39.py hl[2,5:8,11] *} |
|||
|
|||
/// tip | 팁 |
|||
|
|||
빠르게 복사/붙여넣기할 예시가 필요하다면, 이 예시는 사용하지 말고 아래의 마지막 예시를 사용하세요. |
|||
|
|||
/// |
|||
|
|||
그 다음, 해당 `Settings` 클래스의 인스턴스(여기서는 `settings` 객체)를 생성하면 Pydantic이 대소문자를 구분하지 않고 환경 변수를 읽습니다. 따라서 대문자 변수 `APP_NAME`도 `app_name` 속성에 대해 읽힙니다. |
|||
|
|||
이후 데이터를 변환하고 검증합니다. 그래서 그 `settings` 객체를 사용할 때는 선언한 타입의 데이터를 갖게 됩니다(예: `items_per_user`는 `int`가 됩니다). |
|||
|
|||
### `settings` 사용하기 { #use-the-settings } |
|||
|
|||
이제 애플리케이션에서 새 `settings` 객체를 사용할 수 있습니다: |
|||
|
|||
{* ../../docs_src/settings/tutorial001_py39.py hl[18:20] *} |
|||
|
|||
### 서버 실행하기 { #run-the-server } |
|||
|
|||
다음으로 환경 변수를 통해 구성을 전달하면서 서버를 실행합니다. 예를 들어 다음처럼 `ADMIN_EMAIL`과 `APP_NAME`을 설정할 수 있습니다: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ ADMIN_EMAIL="[email protected]" APP_NAME="ChimichangApp" fastapi run main.py |
|||
|
|||
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
/// tip | 팁 |
|||
|
|||
하나의 명령에 여러 env var를 설정하려면 공백으로 구분하고, 모두 명령 앞에 두세요. |
|||
|
|||
/// |
|||
|
|||
그러면 `admin_email` 설정은 `"[email protected]"`으로 설정됩니다. |
|||
|
|||
`app_name`은 `"ChimichangApp"`이 됩니다. |
|||
|
|||
그리고 `items_per_user`는 기본값 `50`을 유지합니다. |
|||
|
|||
## 다른 모듈의 설정 { #settings-in-another-module } |
|||
|
|||
[Bigger Applications - Multiple Files](../tutorial/bigger-applications.md){.internal-link target=_blank}에서 본 것처럼, 설정을 다른 모듈 파일에 넣을 수도 있습니다. |
|||
|
|||
예를 들어 `config.py` 파일을 다음처럼 만들 수 있습니다: |
|||
|
|||
{* ../../docs_src/settings/app01_py39/config.py *} |
|||
|
|||
그리고 `main.py` 파일에서 이를 사용합니다: |
|||
|
|||
{* ../../docs_src/settings/app01_py39/main.py hl[3,11:13] *} |
|||
|
|||
/// tip | 팁 |
|||
|
|||
[Bigger Applications - Multiple Files](../tutorial/bigger-applications.md){.internal-link target=_blank}에서 본 것처럼 `__init__.py` 파일도 필요합니다. |
|||
|
|||
/// |
|||
|
|||
## 의존성에서 설정 사용하기 { #settings-in-a-dependency } |
|||
|
|||
어떤 경우에는 어디서나 사용되는 전역 `settings` 객체를 두는 대신, 의존성에서 설정을 제공하는 것이 유용할 수 있습니다. |
|||
|
|||
이는 특히 테스트 중에 유용할 수 있는데, 사용자 정의 설정으로 의존성을 override하기가 매우 쉽기 때문입니다. |
|||
|
|||
### config 파일 { #the-config-file } |
|||
|
|||
이전 예시에서 이어서, `config.py` 파일은 다음과 같을 수 있습니다: |
|||
|
|||
{* ../../docs_src/settings/app02_an_py39/config.py hl[10] *} |
|||
|
|||
이제는 기본 인스턴스 `settings = Settings()`를 생성하지 않는다는 점에 유의하세요. |
|||
|
|||
### 메인 앱 파일 { #the-main-app-file } |
|||
|
|||
이제 새로운 `config.Settings()`를 반환하는 의존성을 생성합니다. |
|||
|
|||
{* ../../docs_src/settings/app02_an_py39/main.py hl[6,12:13] *} |
|||
|
|||
/// tip | 팁 |
|||
|
|||
`@lru_cache`는 조금 뒤에 다룹니다. |
|||
|
|||
지금은 `get_settings()`가 일반 함수라고 가정해도 됩니다. |
|||
|
|||
/// |
|||
|
|||
그 다음 *경로 처리 함수*에서 이를 의존성으로 요구하고, 필요한 어디서든 사용할 수 있습니다. |
|||
|
|||
{* ../../docs_src/settings/app02_an_py39/main.py hl[17,19:21] *} |
|||
|
|||
### 설정과 테스트 { #settings-and-testing } |
|||
|
|||
그 다음, `get_settings`에 대한 의존성 override를 만들어 테스트 중에 다른 설정 객체를 제공하기가 매우 쉬워집니다: |
|||
|
|||
{* ../../docs_src/settings/app02_an_py39/test_main.py hl[9:10,13,21] *} |
|||
|
|||
의존성 override에서는 새 `Settings` 객체를 생성할 때 `admin_email`의 새 값을 설정하고, 그 새 객체를 반환합니다. |
|||
|
|||
그 다음 그것이 사용되는지 테스트할 수 있습니다. |
|||
|
|||
## `.env` 파일 읽기 { #reading-a-env-file } |
|||
|
|||
많이 바뀔 수 있는 설정이 많고, 서로 다른 환경에서 사용한다면, 이를 파일에 넣어 환경 변수인 것처럼 읽는 것이 유용할 수 있습니다. |
|||
|
|||
이 관행은 충분히 흔해서 이름도 있는데, 이러한 환경 변수들은 보통 `.env` 파일에 두며, 그 파일을 "dotenv"라고 부릅니다. |
|||
|
|||
/// tip | 팁 |
|||
|
|||
점(`.`)으로 시작하는 파일은 Linux, macOS 같은 Unix 계열 시스템에서 숨김 파일입니다. |
|||
|
|||
하지만 dotenv 파일이 꼭 그 정확한 파일명을 가져야 하는 것은 아닙니다. |
|||
|
|||
/// |
|||
|
|||
Pydantic은 외부 라이브러리를 사용해 이런 유형의 파일에서 읽는 기능을 지원합니다. 자세한 내용은 <a href="https://docs.pydantic.dev/latest/concepts/pydantic_settings/#dotenv-env-support" class="external-link" target="_blank">Pydantic Settings: Dotenv (.env) support</a>를 참고하세요. |
|||
|
|||
/// tip | 팁 |
|||
|
|||
이를 사용하려면 `pip install python-dotenv`가 필요합니다. |
|||
|
|||
/// |
|||
|
|||
### `.env` 파일 { #the-env-file } |
|||
|
|||
다음과 같은 `.env` 파일을 둘 수 있습니다: |
|||
|
|||
```bash |
|||
ADMIN_EMAIL="[email protected]" |
|||
APP_NAME="ChimichangApp" |
|||
``` |
|||
|
|||
### `.env`에서 설정 읽기 { #read-settings-from-env } |
|||
|
|||
그리고 `config.py`를 다음처럼 업데이트합니다: |
|||
|
|||
{* ../../docs_src/settings/app03_an_py39/config.py hl[9] *} |
|||
|
|||
/// tip | 팁 |
|||
|
|||
`model_config` 속성은 Pydantic 설정을 위한 것입니다. 자세한 내용은 <a href="https://docs.pydantic.dev/latest/concepts/config/" class="external-link" target="_blank">Pydantic: Concepts: Configuration</a>을 참고하세요. |
|||
|
|||
/// |
|||
|
|||
여기서는 Pydantic `Settings` 클래스 안에 config `env_file`을 정의하고, 사용하려는 dotenv 파일의 파일명을 값으로 설정합니다. |
|||
|
|||
### `lru_cache`로 `Settings`를 한 번만 생성하기 { #creating-the-settings-only-once-with-lru-cache } |
|||
|
|||
디스크에서 파일을 읽는 것은 보통 비용이 큰(느린) 작업이므로, 각 요청마다 읽기보다는 한 번만 수행하고 동일한 settings 객체를 재사용하는 것이 좋습니다. |
|||
|
|||
하지만 매번 다음을 수행하면: |
|||
|
|||
```Python |
|||
Settings() |
|||
``` |
|||
|
|||
새 `Settings` 객체가 생성되고, 생성 시점에 `.env` 파일을 다시 읽게 됩니다. |
|||
|
|||
의존성 함수가 단순히 다음과 같다면: |
|||
|
|||
```Python |
|||
def get_settings(): |
|||
return Settings() |
|||
``` |
|||
|
|||
요청마다 객체를 생성하게 되고, 요청마다 `.env` 파일을 읽게 됩니다. ⚠️ |
|||
|
|||
하지만 위에 `@lru_cache` 데코레이터를 사용하고 있으므로, `Settings` 객체는 최초 호출 시 딱 한 번만 생성됩니다. ✔️ |
|||
|
|||
{* ../../docs_src/settings/app03_an_py39/main.py hl[1,11] *} |
|||
|
|||
그 다음 요청들에서 의존성으로 `get_settings()`가 다시 호출될 때마다, `get_settings()`의 내부 코드를 실행해서 새 `Settings` 객체를 만드는 대신, 첫 호출에서 반환된 동일한 객체를 계속 반환합니다. |
|||
|
|||
#### `lru_cache` Technical Details { #lru-cache-technical-details } |
|||
|
|||
`@lru_cache`는 데코레이션한 함수가 매번 다시 계산하는 대신, 첫 번째에 반환된 동일한 값을 반환하도록 함수를 수정합니다(즉, 매번 함수 코드를 실행하지 않습니다). |
|||
|
|||
따라서 아래의 함수는 인자 조합마다 한 번씩 실행됩니다. 그리고 각각의 인자 조합에 대해 반환된 값은, 함수가 정확히 같은 인자 조합으로 호출될 때마다 반복해서 사용됩니다. |
|||
|
|||
예를 들어 다음 함수가 있다면: |
|||
|
|||
```Python |
|||
@lru_cache |
|||
def say_hi(name: str, salutation: str = "Ms."): |
|||
return f"Hello {salutation} {name}" |
|||
``` |
|||
|
|||
프로그램은 다음과 같이 실행될 수 있습니다: |
|||
|
|||
```mermaid |
|||
sequenceDiagram |
|||
|
|||
participant code as Code |
|||
participant function as say_hi() |
|||
participant execute as Execute function |
|||
|
|||
rect rgba(0, 255, 0, .1) |
|||
code ->> function: say_hi(name="Camila") |
|||
function ->> execute: execute function code |
|||
execute ->> code: return the result |
|||
end |
|||
|
|||
rect rgba(0, 255, 255, .1) |
|||
code ->> function: say_hi(name="Camila") |
|||
function ->> code: return stored result |
|||
end |
|||
|
|||
rect rgba(0, 255, 0, .1) |
|||
code ->> function: say_hi(name="Rick") |
|||
function ->> execute: execute function code |
|||
execute ->> code: return the result |
|||
end |
|||
|
|||
rect rgba(0, 255, 0, .1) |
|||
code ->> function: say_hi(name="Rick", salutation="Mr.") |
|||
function ->> execute: execute function code |
|||
execute ->> code: return the result |
|||
end |
|||
|
|||
rect rgba(0, 255, 255, .1) |
|||
code ->> function: say_hi(name="Rick") |
|||
function ->> code: return stored result |
|||
end |
|||
|
|||
rect rgba(0, 255, 255, .1) |
|||
code ->> function: say_hi(name="Camila") |
|||
function ->> code: return stored result |
|||
end |
|||
``` |
|||
|
|||
우리의 의존성 `get_settings()`의 경우, 함수가 어떤 인자도 받지 않으므로 항상 같은 값을 반환합니다. |
|||
|
|||
이렇게 하면 거의 전역 변수처럼 동작합니다. 하지만 의존성 함수를 사용하므로 테스트를 위해 쉽게 override할 수 있습니다. |
|||
|
|||
`@lru_cache`는 Python 표준 라이브러리의 `functools`에 포함되어 있으며, 자세한 내용은 <a href="https://docs.python.org/3/library/functools.html#functools.lru_cache" class="external-link" target="_blank">`@lru_cache`에 대한 Python 문서</a>에서 확인할 수 있습니다. |
|||
|
|||
## 정리 { #recap } |
|||
|
|||
Pydantic Settings를 사용하면 Pydantic 모델의 모든 강력한 기능을 활용해 애플리케이션의 설정 또는 구성을 처리할 수 있습니다. |
|||
|
|||
* 의존성을 사용하면 테스트를 단순화할 수 있습니다. |
|||
* `.env` 파일을 사용할 수 있습니다. |
|||
* `@lru_cache`를 사용하면 각 요청마다 dotenv 파일을 반복해서 읽는 것을 피하면서도, 테스트 중에는 이를 override할 수 있습니다. |
|||
@ -1,67 +1,67 @@ |
|||
# 하위 응용프로그램 - 마운트 |
|||
# 하위 응용프로그램 - 마운트 { #sub-applications-mounts } |
|||
|
|||
만약 각각의 독립적인 OpenAPI와 문서 UI를 갖는 두 개의 독립적인 FastAPI 응용프로그램이 필요하다면, 메인 어플리케이션에 하나 (또는 그 이상의) 하위-응용프로그램(들)을 “마운트"해서 사용할 수 있습니다. |
|||
각각의 독립적인 OpenAPI와 문서 UI를 갖는 두 개의 독립적인 FastAPI 애플리케이션이 필요하다면, 메인 앱을 두고 하나(또는 그 이상)의 하위 응용프로그램을 "마운트"할 수 있습니다. |
|||
|
|||
## **FastAPI** 응용프로그램 마운트 |
|||
## **FastAPI** 애플리케이션 마운트 { #mounting-a-fastapi-application } |
|||
|
|||
“마운트"이란 완전히 “독립적인" 응용프로그램을 특정 경로에 추가하여 해당 하위 응용프로그램에서 선언된 *경로 동작*을 통해 해당 경로 아래에 있는 모든 작업들을 처리할 수 있도록 하는 것을 의미합니다. |
|||
"마운트"란 완전히 "독립적인" 애플리케이션을 특정 경로에 추가하고, 그 하위 응용프로그램에 선언된 _경로 처리_로 해당 경로 아래의 모든 것을 처리하도록 하는 것을 의미합니다. |
|||
|
|||
### 최상단 응용프로그램 |
|||
### 최상위 애플리케이션 { #top-level-application } |
|||
|
|||
먼저, 메인, 최상단의 **FastAPI** 응용프로그램과 이것의 *경로 동작*을 생성합니다: |
|||
먼저, 메인 최상위 **FastAPI** 애플리케이션과 그 *경로 처리*를 생성합니다: |
|||
|
|||
{* ../../docs_src/sub_applications/tutorial001.py hl[3, 6:8] *} |
|||
{* ../../docs_src/sub_applications/tutorial001_py39.py hl[3, 6:8] *} |
|||
|
|||
### 하위 응용프로그램 |
|||
### 하위 응용프로그램 { #sub-application } |
|||
|
|||
다음으로, 하위 응용프로그램과 이것의 *경로 동작*을 생성합니다: |
|||
그 다음, 하위 응용프로그램과 그 *경로 처리*를 생성합니다. |
|||
|
|||
이 하위 응용프로그램은 또 다른 표준 FastAPI 응용프로그램입니다. 다만 이것은 “마운트”될 것입니다: |
|||
이 하위 응용프로그램은 또 다른 표준 FastAPI 애플리케이션이지만, "마운트"될 애플리케이션입니다: |
|||
|
|||
{* ../../docs_src/sub_applications/tutorial001.py hl[11, 14:16] *} |
|||
{* ../../docs_src/sub_applications/tutorial001_py39.py hl[11, 14:16] *} |
|||
|
|||
### 하위 응용프로그램 마운트 |
|||
### 하위 응용프로그램 마운트 { #mount-the-sub-application } |
|||
|
|||
최상단 응용프로그램, `app`에 하위 응용프로그램, `subapi`를 마운트합니다. |
|||
최상위 애플리케이션 `app`에서 하위 응용프로그램 `subapi`를 마운트합니다. |
|||
|
|||
이 예시에서, 하위 응용프로그램션은 `/subapi` 경로에 마운트 될 것입니다: |
|||
이 경우 `/subapi` 경로에 마운트됩니다: |
|||
|
|||
{* ../../docs_src/sub_applications/tutorial001.py hl[11, 19] *} |
|||
{* ../../docs_src/sub_applications/tutorial001_py39.py hl[11, 19] *} |
|||
|
|||
### 자동으로 생성된 API 문서 확인 |
|||
### 자동 API 문서 확인 { #check-the-automatic-api-docs } |
|||
|
|||
이제, `uvicorn`으로 메인 응용프로그램을 실행하십시오. 당신의 파일이 `main.py`라면, 이렇게 실행합니다: |
|||
이제 파일과 함께 `fastapi` 명령을 실행하세요: |
|||
|
|||
<div class="termy"> |
|||
|
|||
```console |
|||
$ uvicorn main:app --reload |
|||
$ fastapi dev main.py |
|||
|
|||
<span style="color: green;">INFO</span>: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) |
|||
``` |
|||
|
|||
</div> |
|||
|
|||
그리고 <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>에서 문서를 여십시오. |
|||
그리고 <a href="http://127.0.0.1:8000/docs" class="external-link" target="_blank">http://127.0.0.1:8000/docs</a>에서 문서를 여세요. |
|||
|
|||
메인 응용프로그램의 *경로 동작*만을 포함하는, 메인 응용프로그램에 대한 자동 API 문서를 확인할 수 있습니다: |
|||
메인 앱의 자동 API 문서를 보게 될 것이며, 메인 앱 자체의 _경로 처리_만 포함됩니다: |
|||
|
|||
<img src="https://fastapi.tiangolo.com//img/tutorial/sub-applications/image01.png"> |
|||
<img src="/img/tutorial/sub-applications/image01.png"> |
|||
|
|||
다음으로, <a href="http://127.0.0.1:8000/subapi/docs" class="external-link" target="_blank">http://127.0.0.1:8000/subapi/docs</a>에서 하위 응용프로그램의 문서를 여십시오. |
|||
그 다음, <a href="http://127.0.0.1:8000/subapi/docs" class="external-link" target="_blank">http://127.0.0.1:8000/subapi/docs</a>에서 하위 응용프로그램의 문서를 여세요. |
|||
|
|||
하위 경로 접두사 `/subapi` 아래에 선언된 *경로 동작* 을 포함하는, 하위 응용프로그램에 대한 자동 API 문서를 확인할 수 있습니다: |
|||
하위 응용프로그램의 자동 API 문서를 보게 될 것이며, 하위 경로 접두사 `/subapi` 아래에 올바르게 포함된 하위 응용프로그램 자체의 _경로 처리_만 포함됩니다: |
|||
|
|||
<img src="https://fastapi.tiangolo.com//img/tutorial/sub-applications/image02.png"> |
|||
<img src="/img/tutorial/sub-applications/image02.png"> |
|||
|
|||
두 사용자 인터페이스 중 어느 하나를 사용해야하는 경우, 브라우저는 특정 응용프로그램 또는 하위 응용프로그램과 각각 통신할 수 있기 때문에 올바르게 동작할 것입니다. |
|||
두 사용자 인터페이스 중 어느 것과 상호작용을 시도하더라도 올바르게 동작할 것입니다. 브라우저가 각 특정 앱 또는 하위 앱과 통신할 수 있기 때문입니다. |
|||
|
|||
### 기술적 세부사항: `root_path` |
|||
### 기술적 세부사항: `root_path` { #technical-details-root-path } |
|||
|
|||
위에 설명된 것과 같이 하위 응용프로그램을 마운트하는 경우, FastAPI는 `root_path`라고 하는 ASGI 명세의 매커니즘을 사용하여 하위 응용프로그램에 대한 마운트 경로 통신을 처리합니다. |
|||
위에서 설명한 대로 하위 응용프로그램을 마운트하면, FastAPI는 ASGI 명세의 메커니즘인 `root_path`를 사용해 하위 응용프로그램에 대한 마운트 경로를 전달하는 작업을 처리합니다. |
|||
|
|||
이를 통해, 하위 응용프로그램은 문서 UI를 위해 경로 접두사를 사용해야 한다는 사실을 인지합니다. |
|||
이렇게 하면 하위 응용프로그램은 문서 UI를 위해 해당 경로 접두사를 사용해야 한다는 것을 알게 됩니다. |
|||
|
|||
하위 응용프로그램에도 역시 다른 하위 응용프로그램을 마운트하는 것이 가능하며 FastAPI가 모든 `root_path` 들을 자동적으로 처리하기 때문에 모든 것은 올바르게 동작할 것입니다. |
|||
또한 하위 응용프로그램도 자체적으로 하위 앱을 마운트할 수 있으며, FastAPI가 이 모든 `root_path`를 자동으로 처리하기 때문에 모든 것이 올바르게 동작합니다. |
|||
|
|||
`root_path`와 이것을 사용하는 방법에 대해서는 [프록시의 뒷단](./behind-a-proxy.md){.internal-link target=_blank} 섹션에서 배울 수 있습니다. |
|||
`root_path`와 이를 명시적으로 사용하는 방법에 대해서는 [프록시 뒤](behind-a-proxy.md){.internal-link target=_blank} 섹션에서 더 알아볼 수 있습니다. |
|||
|
|||
Some files were not shown because too many files changed in this diff
Loading…
Reference in new issue