diff --git a/docs/en/docs/release-notes.md b/docs/en/docs/release-notes.md index 7c78bff9a..375e179ec 100644 --- a/docs/en/docs/release-notes.md +++ b/docs/en/docs/release-notes.md @@ -32,6 +32,9 @@ hide: ### Translations +* ๐ Add Portuguese translation for `docs/pt/docs/advanced/benchmarks.md`. PR [#11713](https://github.com/tiangolo/fastapi/pull/11713) by [@ceb10n](https://github.com/ceb10n). +* ๐ Fix Korean translation for `docs/ko/docs/tutorial/response-status-code.md`. PR [#11718](https://github.com/tiangolo/fastapi/pull/11718) by [@nayeonkinn](https://github.com/nayeonkinn). +* ๐ Add Korean translation for `docs/ko/docs/tutorial/extra-data-types.md`. PR [#11711](https://github.com/tiangolo/fastapi/pull/11711) by [@nayeonkinn](https://github.com/nayeonkinn). * ๐ Fix Korean translation for `docs/ko/docs/tutorial/body-nested-models.md`. PR [#11710](https://github.com/tiangolo/fastapi/pull/11710) by [@nayeonkinn](https://github.com/nayeonkinn). * ๐ Add Portuguese translation for `docs/pt/docs/advanced/fastapi-cli.md`. PR [#11641](https://github.com/tiangolo/fastapi/pull/11641) by [@ayr-ton](https://github.com/ayr-ton). * ๐ Add Traditional Chinese translation for `docs/zh-hant/docs/fastapi-people.md`. PR [#11639](https://github.com/tiangolo/fastapi/pull/11639) by [@hsuanchi](https://github.com/hsuanchi). diff --git a/docs/ko/docs/tutorial/extra-data-types.md b/docs/ko/docs/tutorial/extra-data-types.md new file mode 100644 index 000000000..673cf5b73 --- /dev/null +++ b/docs/ko/docs/tutorial/extra-data-types.md @@ -0,0 +1,130 @@ +# ์ถ๊ฐ ๋ฐ์ดํฐ ์๋ฃํ + +์ง๊ธ๊น์ง ์ผ๋ฐ์ ์ธ ๋ฐ์ดํฐ ์๋ฃํ์ ์ฌ์ฉํ์ต๋๋ค. ์๋ฅผ ๋ค๋ฉด ๋ค์๊ณผ ๊ฐ์ต๋๋ค: + +* `int` +* `float` +* `str` +* `bool` + +ํ์ง๋ง ๋ ๋ณต์กํ ๋ฐ์ดํฐ ์๋ฃํ ๋ํ ์ฌ์ฉํ ์ ์์ต๋๋ค. + +๊ทธ๋ฆฌ๊ณ ์ง๊ธ๊น์ง์ ๊ฐ์ ๊ธฐ๋ฅ๋ค์ ์ฌ์ ํ ์ฌ์ฉํ ์ ์์ต๋๋ค. + +* ํ๋ฅญํ ํธ์ง๊ธฐ ์ง์. +* ๋ค์ด์ค๋ ์์ฒญ์ ๋ฐ์ดํฐ ๋ณํ. +* ์๋ต ๋ฐ์ดํฐ์ ๋ฐ์ดํฐ ๋ณํ. +* ๋ฐ์ดํฐ ๊ฒ์ฆ. +* ์๋ ์ด๋ ธํ ์ด์ ๊ณผ ๋ฌธ์ํ. + +## ๋ค๋ฅธ ๋ฐ์ดํฐ ์๋ฃํ + +์๋์ ์ถ๊ฐ์ ์ธ ๋ฐ์ดํฐ ์๋ฃํ์ ์ฌ์ฉํ ์ ์์ต๋๋ค: + +* `UUID`: + * ํ์ค "๋ฒ์ฉ ๊ณ ์ ์๋ณ์"๋ก, ๋ง์ ๋ฐ์ดํฐ๋ฒ ์ด์ค์ ์์คํ ์์ ID๋ก ์ฌ์ฉ๋ฉ๋๋ค. + * ์์ฒญ๊ณผ ์๋ต์์ `str`๋ก ํํ๋ฉ๋๋ค. +* `datetime.datetime`: + * ํ์ด์ฌ์ `datetime.datetime`. + * ์์ฒญ๊ณผ ์๋ต์์ `2008-09-15T15:53:00+05:00`์ ๊ฐ์ ISO 8601 ํ์์ `str`๋ก ํํ๋ฉ๋๋ค. +* `datetime.date`: + * ํ์ด์ฌ์ `datetime.date`. + * ์์ฒญ๊ณผ ์๋ต์์ `2008-09-15`์ ๊ฐ์ ISO 8601 ํ์์ `str`๋ก ํํ๋ฉ๋๋ค. +* `datetime.time`: + * ํ์ด์ฌ์ `datetime.time`. + * ์์ฒญ๊ณผ ์๋ต์์ `14:23:55.003`์ ๊ฐ์ ISO 8601 ํ์์ `str`๋ก ํํ๋ฉ๋๋ค. +* `datetime.timedelta`: + * ํ์ด์ฌ์ `datetime.timedelta`. + * ์์ฒญ๊ณผ ์๋ต์์ ์ ์ฒด ์ด(seconds)์ `float`๋ก ํํ๋ฉ๋๋ค. + * Pydantic์ "ISO 8601 ์์ฐจ ์ธ์ฝ๋ฉ"์ผ๋ก ํํํ๋ ๊ฒ ๋ํ ํ์ฉํฉ๋๋ค. <a href="https://docs.pydantic.dev/latest/concepts/serialization/#json_encoders" class="external-link" target="_blank">๋ ๋ง์ ์ ๋ณด๋ ์ด ๋ฌธ์์์ ํ์ธํ์ญ์์ค.</a>. +* `frozenset`: + * ์์ฒญ๊ณผ ์๋ต์์ `set`์ ๋์ผํ๊ฒ ์ทจ๊ธ๋ฉ๋๋ค: + * ์์ฒญ ์, ๋ฆฌ์คํธ๋ฅผ ์ฝ์ด ์ค๋ณต์ ์ ๊ฑฐํ๊ณ `set`๋ก ๋ณํํฉ๋๋ค. + * ์๋ต ์, `set`๋ `list`๋ก ๋ณํ๋ฉ๋๋ค. + * ์์ฑ๋ ์คํค๋ง๋ (JSON ์คํค๋ง์ `uniqueItems`๋ฅผ ์ด์ฉํด) `set`์ ๊ฐ์ด ๊ณ ์ ํจ์ ๋ช ์ํฉ๋๋ค. +* `bytes`: + * ํ์ค ํ์ด์ฌ์ `bytes`. + * ์์ฒญ๊ณผ ์๋ต์์ `str`๋ก ์ทจ๊ธ๋ฉ๋๋ค. + * ์์ฑ๋ ์คํค๋ง๋ ์ด๊ฒ์ด `binary` "ํ์"์ `str`์์ ๋ช ์ํฉ๋๋ค. +* `Decimal`: + * ํ์ค ํ์ด์ฌ์ `Decimal`. + * ์์ฒญ๊ณผ ์๋ต์์ `float`์ ๋์ผํ๊ฒ ๋ค๋ค์ง๋๋ค. +* ์ฌ๊ธฐ์์ ๋ชจ๋ ์ ํจํ pydantic ๋ฐ์ดํฐ ์๋ฃํ์ ํ์ธํ ์ ์์ต๋๋ค: <a href="https://docs.pydantic.dev/latest/usage/types/types/" class="external-link" target="_blank">Pydantic ๋ฐ์ดํฐ ์๋ฃํ</a>. + +## ์์ + +์์ ๋ช๋ช ์๋ฃํ์ ๋งค๊ฐ๋ณ์๋ก ์ฌ์ฉํ๋ *๊ฒฝ๋ก ์๋* ์์์ ๋๋ค. + +=== "Python 3.10+" + + ```Python hl_lines="1 3 12-16" + {!> ../../../docs_src/extra_data_types/tutorial001_an_py310.py!} + ``` + +=== "Python 3.9+" + + ```Python hl_lines="1 3 12-16" + {!> ../../../docs_src/extra_data_types/tutorial001_an_py39.py!} + ``` + +=== "Python 3.8+" + + ```Python hl_lines="1 3 13-17" + {!> ../../../docs_src/extra_data_types/tutorial001_an.py!} + ``` + +=== "Python 3.10+ non-Annotated" + + !!! tip + Prefer to use the `Annotated` version if possible. + + ```Python hl_lines="1 2 11-15" + {!> ../../../docs_src/extra_data_types/tutorial001_py310.py!} + ``` + +=== "Python 3.8+ non-Annotated" + + !!! tip + Prefer to use the `Annotated` version if possible. + + ```Python hl_lines="1 2 12-16" + {!> ../../../docs_src/extra_data_types/tutorial001.py!} + ``` + +ํจ์ ์์ ๋งค๊ฐ๋ณ์๊ฐ ๊ทธ๋ค๋ง์ ๋ฐ์ดํฐ ์๋ฃํ์ ๊ฐ์ง๊ณ ์์ผ๋ฉฐ, ์๋ฅผ ๋ค์ด, ๋ค์๊ณผ ๊ฐ์ด ๋ ์ง๋ฅผ ์กฐ์ํ ์ ์์์ ์ฐธ๊ณ ํ์ญ์์ค: + +=== "Python 3.10+" + + ```Python hl_lines="18-19" + {!> ../../../docs_src/extra_data_types/tutorial001_an_py310.py!} + ``` + +=== "Python 3.9+" + + ```Python hl_lines="18-19" + {!> ../../../docs_src/extra_data_types/tutorial001_an_py39.py!} + ``` + +=== "Python 3.8+" + + ```Python hl_lines="19-20" + {!> ../../../docs_src/extra_data_types/tutorial001_an.py!} + ``` + +=== "Python 3.10+ non-Annotated" + + !!! tip + Prefer to use the `Annotated` version if possible. + + ```Python hl_lines="17-18" + {!> ../../../docs_src/extra_data_types/tutorial001_py310.py!} + ``` + +=== "Python 3.8+ non-Annotated" + + !!! tip + Prefer to use the `Annotated` version if possible. + + ```Python hl_lines="18-19" + {!> ../../../docs_src/extra_data_types/tutorial001.py!} + ``` diff --git a/docs/ko/docs/tutorial/response-status-code.md b/docs/ko/docs/tutorial/response-status-code.md index f92c057be..e6eed5120 100644 --- a/docs/ko/docs/tutorial/response-status-code.md +++ b/docs/ko/docs/tutorial/response-status-code.md @@ -43,16 +43,16 @@ HTTP๋ ์ธ์๋ฆฌ์ ์ซ์ ์ํ ์ฝ๋๋ฅผ ์๋ต์ ์ผ๋ถ๋ก ์ ์กํฉ๋๋ค ์์ฝํ์๋ฉด: -* `**1xx**` ์ํ ์ฝ๋๋ "์ ๋ณด"์ฉ์ ๋๋ค. ์ด๋ค์ ์ง์ ์ ์ผ๋ก๋ ์ ์ฌ์ฉ๋์ง๋ ์์ต๋๋ค. ์ด ์ํ ์ฝ๋๋ฅผ ๊ฐ๋ ์๋ต๋ค์ ๋ณธ๋ฌธ์ ๊ฐ์ง ์ ์์ต๋๋ค. -* `**2xx**` ์ํ ์ฝ๋๋ "์ฑ๊ณต์ ์ธ" ์๋ต์ ์ํด ์ฌ์ฉ๋ฉ๋๋ค. ๊ฐ์ฅ ๋ง์ด ์ฌ์ฉ๋๋ ์ ํ์ ๋๋ค. +* `1xx` ์ํ ์ฝ๋๋ "์ ๋ณด"์ฉ์ ๋๋ค. ์ด๋ค์ ์ง์ ์ ์ผ๋ก๋ ์ ์ฌ์ฉ๋์ง๋ ์์ต๋๋ค. ์ด ์ํ ์ฝ๋๋ฅผ ๊ฐ๋ ์๋ต๋ค์ ๋ณธ๋ฌธ์ ๊ฐ์ง ์ ์์ต๋๋ค. +* **`2xx`** ์ํ ์ฝ๋๋ "์ฑ๊ณต์ ์ธ" ์๋ต์ ์ํด ์ฌ์ฉ๋ฉ๋๋ค. ๊ฐ์ฅ ๋ง์ด ์ฌ์ฉ๋๋ ์ ํ์ ๋๋ค. * `200` ์ ๋ํดํธ ์ํ ์ฝ๋๋ก, ๋ชจ๋ ๊ฒ์ด "์ฑ๊ณต์ ์"์ ์๋ฏธํฉ๋๋ค. * ๋ค๋ฅธ ์๋ก๋ `201` "์์ฑ๋จ"์ด ์์ต๋๋ค. ์ผ๋ฐ์ ์ผ๋ก ๋ฐ์ดํฐ๋ฒ ์ด์ค์ ์๋ก์ด ๋ ์ฝ๋๋ฅผ ์์ฑํ ํ ์ฌ์ฉํฉ๋๋ค. * ๋จ, `204` "๋ด์ฉ ์์"์ ํน๋ณํ ๊ฒฝ์ฐ์ ๋๋ค. ์ด๊ฒ์ ํด๋ผ์ด์ธํธ์๊ฒ ๋ฐํํ ๋ด์ฉ์ด ์๋ ๊ฒฝ์ฐ ์ฌ์ฉํฉ๋๋ค. ๋ฐ๋ผ์ ์๋ต์ ๋ณธ๋ฌธ์ ๊ฐ์ง ์ ์์ต๋๋ค. -* `**3xx**` ์ํ ์ฝ๋๋ "๋ฆฌ๋ค์ด๋ ์ "์ฉ์ ๋๋ค. ๋ณธ๋ฌธ์ ๊ฐ์ง ์ ์๋ `304` "์์ ๋์ง ์์"์ ์ ์ธํ๊ณ , ์ด ์ํ ์ฝ๋๋ฅผ ๊ฐ๋ ์๋ต์๋ ๋ณธ๋ฌธ์ด ์์ ์๋, ์์ ์๋ ์์ต๋๋ค. -* `**4xx**` ์ํ ์ฝ๋๋ "ํด๋ผ์ด์ธํธ ์ค๋ฅ" ์๋ต์ ์ํด ์ฌ์ฉ๋ฉ๋๋ค. ์ด๊ฒ์ ์๋ง ๊ฐ์ฅ ๋ง์ด ์ฌ์ฉํ๊ฒ ๋ ๋๋ฒ์งธ ์ ํ์ ๋๋ค. +* **`3xx`** ์ํ ์ฝ๋๋ "๋ฆฌ๋ค์ด๋ ์ "์ฉ์ ๋๋ค. ๋ณธ๋ฌธ์ ๊ฐ์ง ์ ์๋ `304` "์์ ๋์ง ์์"์ ์ ์ธํ๊ณ , ์ด ์ํ ์ฝ๋๋ฅผ ๊ฐ๋ ์๋ต์๋ ๋ณธ๋ฌธ์ด ์์ ์๋, ์์ ์๋ ์์ต๋๋ค. +* **`4xx`** ์ํ ์ฝ๋๋ "ํด๋ผ์ด์ธํธ ์ค๋ฅ" ์๋ต์ ์ํด ์ฌ์ฉ๋ฉ๋๋ค. ์ด๊ฒ์ ์๋ง ๊ฐ์ฅ ๋ง์ด ์ฌ์ฉํ๊ฒ ๋ ๋๋ฒ์งธ ์ ํ์ ๋๋ค. * ์ผ๋ก๋ก `404` ๋ "์ฐพ์ ์ ์์" ์๋ต์ ์ํด ์ฌ์ฉํฉ๋๋ค. * ์ผ๋ฐ์ ์ธ ํด๋ผ์ด์ธํธ ์ค๋ฅ์ ๊ฒฝ์ฐ `400` ์ ์ฌ์ฉํ ์ ์์ต๋๋ค. -* `**5xx**` ์ํ ์ฝ๋๋ ์๋ฒ ์ค๋ฅ์ ์ฌ์ฉ๋ฉ๋๋ค. ์ด๊ฒ๋ค์ ์ง์ ์ฌ์ฉํ ์ผ์ ๊ฑฐ์ ์์ต๋๋ค. ์์ฉ ํ๋ก๊ทธ๋จ ์ฝ๋๋ ์๋ฒ์ ์ผ๋ถ์์ ๋ฌธ์ ๊ฐ ๋ฐ์ํ๋ฉด ์๋์ผ๋ก ์ด๋ค ์ํ ์ฝ๋ ์ค ํ๋๋ฅผ ๋ฐํํฉ๋๋ค. +* `5xx` ์ํ ์ฝ๋๋ ์๋ฒ ์ค๋ฅ์ ์ฌ์ฉ๋ฉ๋๋ค. ์ด๊ฒ๋ค์ ์ง์ ์ฌ์ฉํ ์ผ์ ๊ฑฐ์ ์์ต๋๋ค. ์์ฉ ํ๋ก๊ทธ๋จ ์ฝ๋๋ ์๋ฒ์ ์ผ๋ถ์์ ๋ฌธ์ ๊ฐ ๋ฐ์ํ๋ฉด ์๋์ผ๋ก ์ด๋ค ์ํ ์ฝ๋ ์ค ํ๋๋ฅผ ๋ฐํํฉ๋๋ค. !!! tip "ํ" ๊ฐ๊ฐ์ ์ํ ์ฝ๋์ ์ด๋ค์ด ์๋ฏธํ๋ ๋ด์ฉ์ ๋ํด ๋ ์๊ณ ์ถ๋ค๋ฉด <a href="https://developer.mozilla.org/en-US/docs/Web/HTTP/Status" class="external-link" target="_blank"><abbr title="Mozilla Developer Network">MDN</abbr> HTTP ์ํ ์ฝ๋์ ๊ดํ ๋ฌธ์</a> ๋ฅผ ํ์ธํ์ญ์์ค. @@ -82,7 +82,7 @@ HTTP๋ ์ธ์๋ฆฌ์ ์ซ์ ์ํ ์ฝ๋๋ฅผ ์๋ต์ ์ผ๋ถ๋ก ์ ์กํฉ๋๋ค !!! note "๊ธฐ์ ์ ์ธ๋ถ์ฌํญ" `from starlette import status` ์ญ์ ์ฌ์ฉํ ์ ์์ต๋๋ค. - **FastAPI**๋ ๊ฐ๋ฐ์์ธ ๋น์ ์ ํธ์๋ฅผ ์ํด `fastapi.status` ์ ๋์ผํ `starlette.status` ๋ ์ ๊ณตํฉ๋๋ค. ํ์ง๋ง ์ด๊ฒ์ Starlette๋ก๋ถํฐ ์ง์ ์ ๊ณต๋ฉ๋๋ค. + **FastAPI**๋ ๊ฐ๋ฐ์์ธ ์ฌ๋ฌ๋ถ์ ํธ์๋ฅผ ์ํด `fastapi.status` ์ ๋์ผํ `starlette.status` ๋ ์ ๊ณตํฉ๋๋ค. ํ์ง๋ง ์ด๊ฒ์ Starlette๋ก๋ถํฐ ์ง์ ์ ๊ณต๋ฉ๋๋ค. ## ๊ธฐ๋ณธ๊ฐ ๋ณ๊ฒฝ diff --git a/docs/pt/docs/advanced/benchmarks.md b/docs/pt/docs/advanced/benchmarks.md new file mode 100644 index 000000000..72ef1e444 --- /dev/null +++ b/docs/pt/docs/advanced/benchmarks.md @@ -0,0 +1,34 @@ +# Benchmarks + +Benchmarks independentes da TechEmpower mostram que aplicaรงรตes **FastAPI** rodando com o Uvicorn como <a href="https://www.techempower.com/benchmarks/#section=test&runid=7464e520-0dc2-473d-bd34-dbdfd7e85911&hw=ph&test=query&l=zijzen-7" class="external-link" target="_blank">um dos frameworks Python mais rรกpidos disponรญveis</a>, ficando atrรกs apenas do Starlette e Uvicorn (utilizado internamente pelo FastAPI). + +Porรฉm, ao verificar benchmarks e comparaรงรตes vocรช deve prestar atenรงรฃo ao seguinte: + +## Benchmarks e velocidade + +Quando vocรช verifica os benchmarks, รฉ comum ver diversas ferramentas de diferentes tipos comparados como se fossem equivalentes. + +Especificamente, para ver o Uvicorn, Starlette e FastAPI comparados entre si (entre diversas outras ferramentas). + +Quanto mais simples o problema resolvido pela ferramenta, melhor serรก a performance. E a maioria das anรกlises nรฃo testa funcionalidades adicionais que sรฃo oferecidas pela ferramenta. + +A hierarquia รฉ: + +* **Uvicorn**: um servidor ASGI + * **Starlette**: (utiliza Uvicorn) um microframework web + * **FastAPI**: (utiliza Starlette) um microframework para APIs com diversas funcionalidades adicionais para a construรงรฃo de APIs, com validaรงรฃo de dados, etc. + +* **Uvicorn**: + * Terรก a melhor performance, pois nรฃo possui muito cรณdigo alรฉm do prรณprio servidor. + * Vocรช nรฃo escreveria uma aplicaรงรฃo utilizando o Uvicorn diretamente. Isso significaria que o seu cรณdigo teria que incluir pelo menos todo o cรณdigo fornecido pelo Starlette (ou o **FastAPI**). E caso vocรช fizesse isso, a sua aplicaรงรฃo final teria a mesma sobrecarga que teria se utilizasse um framework, minimizando o cรณdigo e os bugs. + * Se vocรช estรก comparando o Uvicorn, compare com os servidores de aplicaรงรฃo Daphne, Hypercorn, uWSGI, etc. +* **Starlette**: + * Terรก o melhor desempenho, depois do Uvicorn. Na verdade, o Starlette utiliza o Uvicorn para rodar. Portanto, ele pode ficar mais "devagar" que o Uvicorn apenas por ter que executar mais cรณdigo. + * Mas ele fornece as ferramentas para construir aplicaรงรตes web simples, com roteamento baseado em caminhos, etc. + * Se vocรช estรก comparando o Starlette, compare-o com o Sanic, Flask, Django, etc. Frameworks web (ou microframeworks). +* **FastAPI**: + * Da mesma forma que o Starlette utiliza o Uvicorn e nรฃo consegue ser mais rรกpido que ele, o **FastAPI** utiliza o Starlette, portanto, ele nรฃo consegue ser mais rรกpido que ele. + * O FastAPI provรช mais funcionalidades em cima do Starlette. Funcionalidades que vocรช quase sempre precisarรก quando estiver construindo APIs, como validaรงรฃo de dados e serializaรงรฃo. E ao utilizรก-lo, vocรช obtรฉm documentaรงรฃo automรกtica sem custo nenhum (a documentaรงรฃo automรกtica sequer adiciona sobrecarga nas aplicaรงรตes rodando, pois ela รฉ gerada na inicializaรงรฃo). + * Caso vocรช nรฃo utilize o FastAPI e faz uso do Starlette diretamente (ou outra ferramenta, como o Sanic, Flask, Responder, etc) vocรช mesmo teria que implementar toda a validaรงรฃo de dados e serializaรงรฃo. Entรฃo, a sua aplicaรงรฃo final ainda teria a mesma sobrecarga caso estivesse usando o FastAPI. E em muitos casos, validaรงรฃo de dados e serializaรงรฃo รฉ a maior parte do cรณdigo escrito em aplicaรงรตes. + * Entรฃo, ao utilizar o FastAPI, vocรช estรก economizando tempo de programaรงรฃo, evitando bugs, linhas de cรณdigo, e provavelmente terรก a mesma performance (ou atรฉ melhor) do que teria caso vocรช nรฃo o utilizasse (jรก que vocรช teria que implementar tudo no seu cรณdigo). + * Se vocรช estรก comparando o FastAPI, compare-o com frameworks de aplicaรงรตes web (ou conjunto de ferramentas) que oferecem validaรงรฃo de dados, serializaรงรฃo e documentaรงรฃo, como por exemplo o Flask-apispec, NestJS, Molten, etc. Frameworks que possuem validaรงรฃo integrada de dados, serializaรงรฃo e documentaรงรฃo.