diff --git a/docs/zh-hant/docs/advanced/additional-status-codes.md b/docs/zh-hant/docs/advanced/additional-status-codes.md index 450a4705aa..0e5941a8d6 100644 --- a/docs/zh-hant/docs/advanced/additional-status-codes.md +++ b/docs/zh-hant/docs/advanced/additional-status-codes.md @@ -26,7 +26,7 @@ /// -/// note | 注意 +/// note | 技術細節 你也可以使用 `from starlette.responses import JSONResponse`。 @@ -38,4 +38,4 @@ 如果你直接回傳額外的狀態碼與回應，它們不會被包含進 OpenAPI 綱要（API 文件）中，因為 FastAPI 無法事先知道你會回傳什麼。 -但你可以在程式碼中補充文件，使用：[額外的回應](additional-responses.md){.internal-link target=_blank}。 +但你可以在程式碼中補充文件，使用：[額外的回應](additional-responses.md)。 diff --git a/docs/zh-hant/docs/advanced/generate-clients.md b/docs/zh-hant/docs/advanced/generate-clients.md index 8d374566cd..c069a8034f 100644 --- a/docs/zh-hant/docs/advanced/generate-clients.md +++ b/docs/zh-hant/docs/advanced/generate-clients.md @@ -8,11 +8,11 @@ ## 開源 SDK 產生器 { #open-source-sdk-generators } -其中一個相當萬用的選擇是 OpenAPI Generator，它支援**多種程式語言**，並能從你的 OpenAPI 規格產生 SDK。 +其中一個相當萬用的選擇是 [OpenAPI Generator](https://openapi-generator.tech/)，它支援**多種程式語言**，並能從你的 OpenAPI 規格產生 SDK。 -針對 **TypeScript 用戶端**，Hey API 是專門打造的解決方案，為 TypeScript 生態系提供最佳化的體驗。 +針對 **TypeScript 用戶端**，[Hey API](https://heyapi.dev/) 是專門打造的解決方案，為 TypeScript 生態系提供最佳化的體驗。 -你可以在 OpenAPI.Tools 找到更多 SDK 產生器。 +你可以在 [OpenAPI.Tools](https://openapi.tools/#sdk) 找到更多 SDK 產生器。 /// tip @@ -24,15 +24,15 @@ FastAPI 會自動產生 **OpenAPI 3.1** 規格，因此你使用的任何工具 本節重點介紹由贊助 FastAPI 的公司提供的**創投支持**與**公司維運**的解決方案。這些產品在高品質的自動產生 SDK 之外，還提供**額外功能**與**整合**。 -透過 ✨ [**贊助 FastAPI**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨，這些公司幫助確保框架與其**生態系**維持健康且**永續**。 +透過 ✨ [**贊助 FastAPI**](../help-fastapi.md#sponsor-the-author) ✨，這些公司幫助確保框架與其**生態系**維持健康且**永續**。 他們的贊助也展現對 FastAPI **社群**（你）的高度承諾，不僅關心提供**優良服務**，也支持 **FastAPI** 作為一個**穩健且蓬勃的框架**。🙇 例如，你可以嘗試： -* Speakeasy -* Stainless -* liblab +* [Speakeasy](https://speakeasy.com/editor?utm_source=fastapi+repo&utm_medium=github+sponsorship) +* [Stainless](https://www.stainless.com/?utm_source=fastapi&utm_medium=referral) +* [liblab](https://developers.liblab.com/tutorials/sdk-for-fastapi?utm_source=fastapi) 其中有些方案也可能是開源或提供免費方案，讓你不需財務承諾就能試用。其他商業的 SDK 產生器也不少，你可以在網路上找到。🤓 @@ -66,7 +66,7 @@ npx @hey-api/openapi-ts -i http://localhost:8000/openapi.json -o src/client 這會在 `./src/client` 產生一個 TypeScript SDK。 -你可以在他們的網站了解如何安裝 `@hey-api/openapi-ts`，以及閱讀產生的輸出內容。 +你可以在他們的網站了解如何[安裝 `@hey-api/openapi-ts`](https://heyapi.dev/openapi-ts/get-started)，以及閱讀[產生的輸出內容](https://heyapi.dev/openapi-ts/output)。 ### 使用 SDK { #using-the-sdk } @@ -121,7 +121,7 @@ npx @hey-api/openapi-ts -i http://localhost:8000/openapi.json -o src/client ItemsService.createItemItemsPost({name: "Plumbus", price: 5}) ``` -……那是因為用戶端產生器對每個 *路徑操作* 都使用 OpenAPI 內部的**操作 ID（operation ID）**。 +...那是因為用戶端產生器對每個 *路徑操作* 都使用 OpenAPI 內部的**操作 ID（operation ID）**。 OpenAPI 要求每個操作 ID 在所有 *路徑操作* 之間必須唯一，因此 FastAPI 會用**函式名稱**、**路徑**與 **HTTP 方法/操作**來產生該操作 ID，如此便能確保操作 ID 的唯一性。 diff --git a/docs/zh-hant/docs/advanced/response-cookies.md b/docs/zh-hant/docs/advanced/response-cookies.md index b7225d571c..2ba14c3f6f 100644 --- a/docs/zh-hant/docs/advanced/response-cookies.md +++ b/docs/zh-hant/docs/advanced/response-cookies.md @@ -20,7 +20,7 @@ FastAPI 會使用那個暫時的 `Response` 取出 Cookie（以及標頭與狀 當你在程式碼中直接回傳 `Response` 時，也可以建立 Cookie。 -要這麼做，你可以依照 [直接回傳 Response](response-directly.md){.internal-link target=_blank} 中的說明建立一個回應。 +要這麼做，你可以依照 [直接回傳 Response](response-directly.md) 中的說明建立一個回應。 接著在其中設定 Cookie，然後回傳它： @@ -48,4 +48,4 @@ FastAPI 會使用那個暫時的 `Response` 取出 Cookie（以及標頭與狀 /// -想查看所有可用的參數與選項，請參閱 Starlette 文件。 +想查看所有可用的參數與選項，請參閱 [Starlette 文件](https://www.starlette.dev/responses/#set-cookie)。 diff --git a/docs/zh-hant/docs/advanced/response-directly.md b/docs/zh-hant/docs/advanced/response-directly.md index 5603548934..16face2612 100644 --- a/docs/zh-hant/docs/advanced/response-directly.md +++ b/docs/zh-hant/docs/advanced/response-directly.md @@ -2,19 +2,23 @@ 當你建立一個 **FastAPI** 的路徑操作 (path operation) 時，通常可以從中回傳任何資料：`dict`、`list`、Pydantic 模型、資料庫模型等。 -預設情況下，**FastAPI** 會使用在[JSON 相容編碼器](../tutorial/encoder.md){.internal-link target=_blank}中說明的 `jsonable_encoder`，自動將回傳值轉為 JSON。 +如果你宣告了 [回應模型](../tutorial/response-model.md)，FastAPI 會用 Pydantic 將資料序列化為 JSON。 -然後在幕後，它會把這些與 JSON 相容的資料（例如 `dict`）放進 `JSONResponse`，用來把回應傳回給用戶端。 +如果你沒有宣告回應模型，FastAPI 會使用在[JSON 相容編碼器](../tutorial/encoder.md)中說明的 `jsonable_encoder`，並把它放進 `JSONResponse`。 但你也可以直接從路徑操作回傳 `JSONResponse`。 -例如，當你需要回傳自訂的 headers 或 cookies 時就很有用。 +/// tip + +通常使用 [回應模型](../tutorial/response-model.md) 會有更好的效能，因為那樣會在 Rust 端使用 Pydantic 來序列化資料，而不是直接回傳 `JSONResponse`。 + +/// ## 回傳 `Response` { #return-a-response } 其實，你可以回傳任何 `Response`，或其任何子類別。 -/// tip +/// info `JSONResponse` 本身就是 `Response` 的子類別。 @@ -26,6 +30,8 @@ 這給了你很大的彈性。你可以回傳任何資料型別、覆寫任何資料宣告或驗證等。 +同時也帶來了很大的責任。你必須確保你回傳的資料是正確的、格式正確、可被序列化等。 + ## 在 `Response` 中使用 `jsonable_encoder` { #using-the-jsonable-encoder-in-a-response } 因為 **FastAPI** 不會對你回傳的 `Response` 做任何更動，你需要自行確保它的內容已經準備好。 @@ -50,16 +56,28 @@ 現在來看看如何用它來回傳自訂回應。 -假設你想要回傳一個 XML 回應。 +假設你想要回傳一個 [XML](https://en.wikipedia.org/wiki/XML) 回應。 你可以把 XML 內容放進一個字串，把它放進 `Response`，然後回傳它： {* ../../docs_src/response_directly/tutorial002_py310.py hl[1,18] *} +## 回應模型如何運作 { #how-a-response-model-works } + +當你在路徑操作中宣告 [回應模型 - 回傳型別](../tutorial/response-model.md) 時，**FastAPI** 會用 Pydantic 將資料序列化為 JSON。 + +{* ../../docs_src/response_model/tutorial001_01_py310.py hl[16,21] *} + +由於這會在 Rust 端發生，效能會比用一般的 Python 與 `JSONResponse` 類別來完成好得多。 + +當使用 `response_model` 或回傳型別時，FastAPI 不會使用 `jsonable_encoder` 來轉換資料（那會較慢），也不會使用 `JSONResponse` 類別。 + +相反地，它會取用用回應模型（或回傳型別）透過 Pydantic 產生的 JSON 位元組，並直接回傳具備正確 JSON 媒體型別（`application/json`）的 `Response`。 + ## 注意事項 { #notes } 當你直接回傳 `Response` 時，其資料不會自動被驗證、轉換（序列化）或文件化。 -但你仍然可以依照[在 OpenAPI 中的額外回應](additional-responses.md){.internal-link target=_blank}中的說明進行文件化。 +但你仍然可以依照[在 OpenAPI 中的額外回應](additional-responses.md)中的說明進行文件化。 在後續章節中，你會看到如何在仍保有自動資料轉換、文件化等的同時，使用／宣告這些自訂的 `Response`。 diff --git a/docs/zh-hant/docs/advanced/response-headers.md b/docs/zh-hant/docs/advanced/response-headers.md index 6e32ca1b39..4f7494a8b3 100644 --- a/docs/zh-hant/docs/advanced/response-headers.md +++ b/docs/zh-hant/docs/advanced/response-headers.md @@ -20,7 +20,7 @@ FastAPI 會使用那個暫時性的回應來擷取標頭（還有 Cookie 與狀 當你直接回傳 `Response` 時，也能加入標頭。 -依照[直接回傳 Response](response-directly.md){.internal-link target=_blank}中的說明建立回應，並把標頭作為額外參數傳入： +依照[直接回傳 Response](response-directly.md)中的說明建立回應，並把標頭作為額外參數傳入： {* ../../docs_src/response_headers/tutorial001_py310.py hl[10:12] *} @@ -36,6 +36,6 @@ FastAPI 會使用那個暫時性的回應來擷取標頭（還有 Cookie 與狀 ## 自訂標頭 { #custom-headers } -請記住，專有的自訂標頭可以使用 `X-` 前綴來新增。 +請記住，專有的自訂標頭可以[使用 `X-` 前綴](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers)來新增。 -但如果你有自訂標頭並希望瀏覽器端的客戶端能看見它們，你需要把這些標頭加入到 CORS 設定中（詳見 [CORS（跨來源資源共用）](../tutorial/cors.md){.internal-link target=_blank}），使用在Starlette 的 CORS 文件中記載的 `expose_headers` 參數。 +但如果你有自訂標頭並希望瀏覽器端的客戶端能看見它們，你需要把這些標頭加入到 CORS 設定中（詳見 [CORS（跨來源資源共用）](../tutorial/cors.md)），使用在[Starlette 的 CORS 文件](https://www.starlette.dev/middleware/#corsmiddleware)中記載的 `expose_headers` 參數。 diff --git a/docs/zh-hant/docs/advanced/security/http-basic-auth.md b/docs/zh-hant/docs/advanced/security/http-basic-auth.md index ea3d528292..817cf166b9 100644 --- a/docs/zh-hant/docs/advanced/security/http-basic-auth.md +++ b/docs/zh-hant/docs/advanced/security/http-basic-auth.md @@ -32,7 +32,7 @@ 使用一個依賴來檢查使用者名稱與密碼是否正確。 -為此，使用 Python 標準模組 `secrets` 來比對使用者名稱與密碼。 +為此，使用 Python 標準模組 [`secrets`](https://docs.python.org/3/library/secrets.html) 來比對使用者名稱與密碼。 `secrets.compare_digest()` 需要接收 `bytes`，或是只包含 ASCII 字元（英文字符）的 `str`。這表示它無法處理像 `á` 這樣的字元，例如 `Sebastián`。 diff --git a/docs/zh-hant/docs/advanced/security/index.md b/docs/zh-hant/docs/advanced/security/index.md index 9a4cfbbfd6..ab8bcdcbad 100644 --- a/docs/zh-hant/docs/advanced/security/index.md +++ b/docs/zh-hant/docs/advanced/security/index.md @@ -6,7 +6,7 @@ /// tip -以下各節不一定是「進階」內容。 +以下各節**不一定是「進階」**內容。 而且你的情境很可能可以在其中找到解決方案。 diff --git a/docs/zh-hant/docs/advanced/security/oauth2-scopes.md b/docs/zh-hant/docs/advanced/security/oauth2-scopes.md index 029572d433..05088be7ed 100644 --- a/docs/zh-hant/docs/advanced/security/oauth2-scopes.md +++ b/docs/zh-hant/docs/advanced/security/oauth2-scopes.md @@ -60,7 +60,7 @@ OAuth2 規格將「scopes」定義為以空白分隔的一串字串列表。 ## 全局概觀 { #global-view } -先快速看看相對於主教學「使用密碼（與雜湊）、Bearer 與 JWT token 的 OAuth2」的差異（[OAuth2 with Password (and hashing), Bearer with JWT tokens](../../tutorial/security/oauth2-jwt.md){.internal-link target=_blank}）。現在加入了 OAuth2 scopes： +先快速看看相對於主教學「使用密碼（與雜湊）、Bearer 與 JWT token 的 OAuth2」的差異（[OAuth2 with Password (and hashing), Bearer with JWT tokens](../../tutorial/security/oauth2-jwt.md)）。現在加入了 OAuth2 scopes： {* ../../docs_src/security/tutorial005_an_py310.py hl[5,9,13,47,65,106,108:116,122:126,130:136,141,157] *} @@ -271,4 +271,4 @@ FastAPI 在 `fastapi.security.oauth2` 中提供了所有這些 OAuth2 驗證流 ## 在裝飾器 `dependencies` 中使用 `Security` { #security-in-decorator-dependencies } -就像你可以在裝飾器的 `dependencies` 參數中定義一個 `Depends` 的 `list` 一樣（詳見[路徑操作裝飾器中的相依性](../../tutorial/dependencies/dependencies-in-path-operation-decorators.md){.internal-link target=_blank}），你也可以在那裡使用帶有 `scopes` 的 `Security`。 +就像你可以在裝飾器的 `dependencies` 參數中定義一個 `Depends` 的 `list` 一樣（詳見[路徑操作裝飾器中的相依性](../../tutorial/dependencies/dependencies-in-path-operation-decorators.md)），你也可以在那裡使用帶有 `scopes` 的 `Security`。 diff --git a/docs/zh-hant/docs/advanced/using-request-directly.md b/docs/zh-hant/docs/advanced/using-request-directly.md index f1dae9bf29..2c355982de 100644 --- a/docs/zh-hant/docs/advanced/using-request-directly.md +++ b/docs/zh-hant/docs/advanced/using-request-directly.md @@ -15,7 +15,7 @@ ## 關於 `Request` 物件的細節 { #details-about-the-request-object } -由於 FastAPI 底層其實是 Starlette，再加上一層工具，因此在需要時你可以直接使用 Starlette 的 `Request` 物件。 +由於 FastAPI 底層其實是 Starlette，再加上一層工具，因此在需要時你可以直接使用 Starlette 的 [`Request`](https://www.starlette.dev/requests/) 物件。 同時也代表，如果你直接從 `Request` 物件取得資料（例如讀取 body），FastAPI 不會替它做驗證、轉換或文件化（透過 OpenAPI 為自動化的 API 介面產生文件）。 @@ -45,7 +45,7 @@ ## `Request` 文件 { #request-documentation } -你可以在 Starlette 官方文件站點中的 `Request` 物件 了解更多細節。 +你可以在 [Starlette 官方文件站點中的 `Request` 物件](https://www.starlette.dev/requests/) 了解更多細節。 /// note | 技術細節 diff --git a/docs/zh-hant/docs/deployment/cloud.md b/docs/zh-hant/docs/deployment/cloud.md index fffb2fcfeb..86d216ca6f 100644 --- a/docs/zh-hant/docs/deployment/cloud.md +++ b/docs/zh-hant/docs/deployment/cloud.md @@ -6,7 +6,7 @@ ## FastAPI Cloud { #fastapi-cloud } -**FastAPI Cloud** 由 **FastAPI** 的同一位作者與團隊打造。 +**[FastAPI Cloud](https://fastapicloud.com)** 由 **FastAPI** 的同一位作者與團隊打造。 它讓你以最少的投入，簡化 **建置**、**部署** 與 **存取** API 的流程。 @@ -16,9 +16,9 @@ FastAPI Cloud 是 *FastAPI and friends* 開源專案的主要贊助與資金提 ## 雲端供應商 - 贊助商 { #cloud-providers-sponsors } -其他一些雲端供應商也會 ✨ [**贊助 FastAPI**](../help-fastapi.md#sponsor-the-author){.internal-link target=_blank} ✨。🙇 +其他一些雲端供應商也會 ✨ [**贊助 FastAPI**](../help-fastapi.md#sponsor-the-author) ✨。🙇 你也可以參考他們的指南並試用其服務： -* Render -* Railway +* [Render](https://docs.render.com/deploy-fastapi?utm_source=deploydoc&utm_medium=referral&utm_campaign=fastapi) +* [Railway](https://docs.railway.com/guides/fastapi?utm_medium=integration&utm_source=docs&utm_campaign=fastapi) diff --git a/docs/zh-hant/docs/deployment/concepts.md b/docs/zh-hant/docs/deployment/concepts.md index 0cca31d260..0b8677bfd3 100644 --- a/docs/zh-hant/docs/deployment/concepts.md +++ b/docs/zh-hant/docs/deployment/concepts.md @@ -25,7 +25,7 @@ ## 安全性 - HTTPS { #security-https } -在[前一章關於 HTTPS](https.md){.internal-link target=_blank} 中，我們學到 HTTPS 如何為你的 API 提供加密。 +在[前一章關於 HTTPS](https.md) 中，我們學到 HTTPS 如何為你的 API 提供加密。 我們也看到，HTTPS 通常由應用伺服器外部的元件提供，即 TLS Termination Proxy。 @@ -190,7 +190,7 @@ ### 工作行程與連接埠 { #worker-processes-and-ports } -還記得文件中[關於 HTTPS](https.md){.internal-link target=_blank} 的說明嗎：在一台伺服器上，一組 IP 與連接埠的組合只能由「一個行程」監聽？ +還記得文件中[關於 HTTPS](https.md) 的說明嗎：在一台伺服器上，一組 IP 與連接埠的組合只能由「一個行程」監聽？ 這裡同樣適用。 @@ -243,7 +243,7 @@ 先別擔心這裡提到的「容器」、Docker 或 Kubernetes 如果現在還不太懂。 -我會在未來的章節進一步說明容器映像、Docker、Kubernetes 等等：[容器中的 FastAPI - Docker](docker.md){.internal-link target=_blank}。 +我會在未來的章節進一步說明容器映像、Docker、Kubernetes 等等：[容器中的 FastAPI - Docker](docker.md)。 /// @@ -281,7 +281,7 @@ /// tip -我會在未來關於容器的章節提供更具體的範例：[容器中的 FastAPI - Docker](docker.md){.internal-link target=_blank}。 +我會在未來關於容器的章節提供更具體的範例：[容器中的 FastAPI - Docker](docker.md)。 /// diff --git a/docs/zh-hant/docs/deployment/docker.md b/docs/zh-hant/docs/deployment/docker.md index 87f4e6f9f0..03b9f2f76e 100644 --- a/docs/zh-hant/docs/deployment/docker.md +++ b/docs/zh-hant/docs/deployment/docker.md @@ -1,6 +1,6 @@ # 在容器中使用 FastAPI - Docker { #fastapi-in-containers-docker } -部署 FastAPI 應用時，一個常見做法是建置一個「Linux 容器映像（container image）」。通常使用 Docker 來完成。之後你可以用多種方式部署該容器映像。 +部署 FastAPI 應用時，一個常見做法是建置一個「Linux 容器映像（container image）」。通常使用 [Docker](https://www.docker.com/) 來完成。之後你可以用多種方式部署該容器映像。 使用 Linux 容器有多種優點，包括安全性、可重現性、簡單性等。 @@ -60,16 +60,16 @@ Linux 容器使用與主機（機器、虛擬機、雲端伺服器等）相同 Docker 是用來建立與管理容器映像與容器的主要工具之一。 -也有一個公開的 Docker Hub，內含許多工具、環境、資料庫與應用的預先製作「官方映像」。 +也有一個公開的 [Docker Hub](https://hub.docker.com/)，內含許多工具、環境、資料庫與應用的預先製作「官方映像」。 -例如，有官方的 Python 映像。 +例如，有官方的 [Python 映像](https://hub.docker.com/_/python)。 也有許多其他針對不同用途的映像，例如資料庫： -* PostgreSQL -* MySQL -* MongoDB -* Redis 等。 +* [PostgreSQL](https://hub.docker.com/_/postgres) +* [MySQL](https://hub.docker.com/_/mysql) +* [MongoDB](https://hub.docker.com/_/mongo) +* [Redis](https://hub.docker.com/_/redis) 等。 使用預製的容器映像很容易「組合」並使用不同工具。例如，嘗試一個新資料庫。多數情況下，你可以使用官方映像，並僅用環境變數加以設定。 @@ -111,7 +111,7 @@ Docker 是用來建立與管理容器映像與容器的主要工具之一。 最常見的方式是準備一個 `requirements.txt` 檔案，逐行列出套件名稱與版本。 -當然，你會用與在 [關於 FastAPI 版本](versions.md){.internal-link target=_blank} 中讀到的相同概念，來設定版本範圍。 +當然，你會用與在 [關於 FastAPI 版本](versions.md) 中讀到的相同概念，來設定版本範圍。 例如，你的 `requirements.txt` 可能像這樣： @@ -238,7 +238,7 @@ CMD ["fastapi", "run", "app/main.py", "--port", "80"] #### 使用 `CMD` 的 Exec 形式 { #use-cmd-exec-form } -Docker 的 `CMD` 指令可以有兩種寫法： +Docker 的 [`CMD`](https://docs.docker.com/reference/dockerfile/#cmd) 指令可以有兩種寫法： ✅ Exec 形式： @@ -254,11 +254,11 @@ CMD ["fastapi", "run", "app/main.py", "--port", "80"] CMD fastapi run app/main.py --port 80 ``` -務必總是使用 exec 形式，以確保 FastAPI 能夠優雅地關閉，並觸發 [lifespan events](../advanced/events.md){.internal-link target=_blank}。 +務必總是使用 exec 形式，以確保 FastAPI 能夠優雅地關閉，並觸發 [lifespan events](../advanced/events.md)。 -你可以在 Docker 關於 shell 與 exec 形式的文件閱讀更多。 +你可以在 [Docker 關於 shell 與 exec 形式的文件](https://docs.docker.com/reference/dockerfile/#shell-and-exec-form) 閱讀更多。 -使用 `docker compose` 時這會特別明顯。技術細節請見這段 Docker Compose 常見問題：為什麼我的服務要花 10 秒才重新建立或停止？ +使用 `docker compose` 時這會特別明顯。技術細節請見這段 Docker Compose 常見問題：[為什麼我的服務要花 10 秒才重新建立或停止？](https://docs.docker.com/compose/faq/#why-do-my-services-take-10-seconds-to-recreate-or-stop) #### 目錄結構 { #directory-structure } @@ -352,7 +352,7 @@ $ docker run -d --name mycontainer -p 80:80 myimage ## 檢查 { #check-it } -你應該可以透過 Docker 容器的網址檢查，例如：http://192.168.99.100/items/5?q=somequery 或 http://127.0.0.1/items/5?q=somequery（或等效的、使用你的 Docker 主機）。 +你應該可以透過 Docker 容器的網址檢查，例如：[http://192.168.99.100/items/5?q=somequery](http://192.168.99.100/items/5?q=somequery) 或 [http://127.0.0.1/items/5?q=somequery](http://127.0.0.1/items/5?q=somequery)（或等效的、使用你的 Docker 主機）。 你會看到類似這樣： @@ -362,17 +362,17 @@ $ docker run -d --name mycontainer -p 80:80 myimage ## 互動式 API 文件 { #interactive-api-docs } -現在你可以前往 http://192.168.99.100/docs 或 http://127.0.0.1/docs（或等效的、使用你的 Docker 主機）。 +現在你可以前往 [http://192.168.99.100/docs](http://192.168.99.100/docs) 或 [http://127.0.0.1/docs](http://127.0.0.1/docs)（或等效的、使用你的 Docker 主機）。 -你會看到自動產生的互動式 API 文件（由 Swagger UI 提供）： +你會看到自動產生的互動式 API 文件（由 [Swagger UI](https://github.com/swagger-api/swagger-ui) 提供）： ![Swagger UI](https://fastapi.tiangolo.com/img/index/index-01-swagger-ui-simple.png) ## 替代的 API 文件 { #alternative-api-docs } -你也可以前往 http://192.168.99.100/redoc 或 http://127.0.0.1/redoc（或等效的、使用你的 Docker 主機）。 +你也可以前往 [http://192.168.99.100/redoc](http://192.168.99.100/redoc) 或 [http://127.0.0.1/redoc](http://127.0.0.1/redoc)（或等效的、使用你的 Docker 主機）。 -你會看到另一種自動產生的文件（由 ReDoc 提供）： +你會看到另一種自動產生的文件（由 [ReDoc](https://github.com/Rebilly/ReDoc) 提供）： ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) @@ -413,7 +413,7 @@ CMD ["fastapi", "run", "main.py", "--port", "80"] ## 部署概念 { #deployment-concepts } -我們用容器的角度再談一次部分相同的[部署概念](concepts.md){.internal-link target=_blank}。 +我們用容器的角度再談一次部分相同的[部署概念](concepts.md)。 容器主要是簡化應用「建置與部署」流程的工具，但它們不強制特定的方式來處理這些「部署概念」，而是有多種策略可選。 @@ -432,7 +432,7 @@ CMD ["fastapi", "run", "main.py", "--port", "80"] 若僅聚焦於 FastAPI 應用的「容器映像」（以及稍後的執行中「容器」），HTTPS 通常會由另一個工具在「外部」處理。 -它可以是另一個容器，例如使用 Traefik，來處理「HTTPS」以及「自動」取得「憑證」。 +它可以是另一個容器，例如使用 [Traefik](https://traefik.io/)，來處理「HTTPS」以及「自動」取得「憑證」。 /// tip | 提示 @@ -454,7 +454,7 @@ Traefik 與 Docker、Kubernetes 等整合良好，因此為你的容器設定與 ## 複本 - 行程數量 { #replication-number-of-processes } -如果你在有 Kubernetes、Docker Swarm Mode、Nomad，或其他類似的分散式容器管理系統的「叢集」上運作，那你大概會希望在「叢集層級」處理「複本」，而不是在每個容器內使用「行程管理器」（例如帶有 workers 的 Uvicorn）。 +如果你在有 Kubernetes、Docker Swarm Mode、Nomad，或其他類似的分散式容器管理系統的「叢集」上運作，那你大概會希望在「叢集層級」處理「複本」，而不是在每個容器內使用「行程管理器」（例如帶有 workers 的 Uvicorn）。 像 Kubernetes 這類的分散式容器管理系統，通常內建處理「容器複本」以及支援進入請求的「負載平衡」的能力——全部都在「叢集層級」。 @@ -558,7 +558,7 @@ CMD ["fastapi", "run", "app/main.py", "--port", "80", "--workers", "4"] /// info | 資訊 -如果你使用 Kubernetes，這大概會是一個 Init Container。 +如果你使用 Kubernetes，這大概會是一個 [Init Container](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/)。 /// @@ -570,7 +570,7 @@ CMD ["fastapi", "run", "app/main.py", "--port", "80", "--workers", "4"] ### 基底 Docker 映像 { #base-docker-image } -曾經有一個官方的 FastAPI Docker 映像：tiangolo/uvicorn-gunicorn-fastapi。但現在已被棄用。⛔️ +曾經有一個官方的 FastAPI Docker 映像：[tiangolo/uvicorn-gunicorn-fastapi](https://github.com/tiangolo/uvicorn-gunicorn-fastapi-docker)。但現在已被棄用。⛔️ 你大概「不應該」使用這個基底 Docker 映像（或其他類似的）。 @@ -600,7 +600,7 @@ CMD ["fastapi", "run", "app/main.py", "--port", "80", "--workers", "4"] ## 使用 `uv` 的 Docker 映像 { #docker-image-with-uv } -如果你使用 uv 來安裝與管理專案，你可以參考他們的 uv Docker 指南。 +如果你使用 [uv](https://github.com/astral-sh/uv) 來安裝與管理專案，你可以參考他們的 [uv Docker 指南](https://docs.astral.sh/uv/guides/integration/docker/)。 ## 總結 { #recap } diff --git a/docs/zh-hant/docs/deployment/fastapicloud.md b/docs/zh-hant/docs/deployment/fastapicloud.md index 5663590d14..4b6fb86b47 100644 --- a/docs/zh-hant/docs/deployment/fastapicloud.md +++ b/docs/zh-hant/docs/deployment/fastapicloud.md @@ -1,6 +1,6 @@ # FastAPI Cloud { #fastapi-cloud } -你可以用「一行指令」把你的 FastAPI 應用程式部署到 FastAPI Cloud。如果你還沒加入，快去登記等候名單吧！🚀 +你可以用「一行指令」把你的 FastAPI 應用程式部署到 [FastAPI Cloud](https://fastapicloud.com)。如果你還沒加入，快去登記等候名單吧！🚀 ## 登入 { #login } @@ -40,7 +40,7 @@ Deploying to FastAPI Cloud... ## 關於 FastAPI Cloud { #about-fastapi-cloud } -**FastAPI Cloud** 由 **FastAPI** 的作者與團隊打造。 +**[FastAPI Cloud](https://fastapicloud.com)** 由 **FastAPI** 的作者與團隊打造。 它以最少的心力，精簡化建立、部署與存取 API 的流程。 diff --git a/docs/zh-hant/docs/deployment/https.md b/docs/zh-hant/docs/deployment/https.md index 0934b02831..ddafcb34b1 100644 --- a/docs/zh-hant/docs/deployment/https.md +++ b/docs/zh-hant/docs/deployment/https.md @@ -10,7 +10,7 @@ /// -想從使用者角度學習 HTTPS 基礎，請參考 https://howhttps.works/。 +想從使用者角度學習 HTTPS 基礎，請參考 [https://howhttps.works/](https://howhttps.works/)。 接著以開發者角度，談幾個關於 HTTPS 需要注意的重點： @@ -28,13 +28,13 @@ * **預設**情況下，這表示你每個 IP 位址**只能**使用**一張 HTTPS 憑證**。 * 不論你的伺服器多強或你在上面跑的應用多小。 * 不過，這是有**解法**的。 -* 在 **TLS** 協定（在 HTTP 之前於 TCP 層處理加密的協定）上有個**擴充**稱為 **SNI**。 +* 在 **TLS** 協定（在 HTTP 之前於 TCP 層處理加密的協定）上有個**擴充**稱為 **[SNI](https://en.wikipedia.org/wiki/Server_Name_Indication)**。 * 這個 SNI 擴充讓單一伺服器（單一 IP 位址）可以擁有**多張 HTTPS 憑證**，並服務**多個 HTTPS 網域／應用**。 * 要讓它運作，伺服器上必須有一個**單一**的元件（程式）在**公用 IP**上監聽，且持有伺服器上的**所有 HTTPS 憑證**。 * 在取得安全連線**之後**，通訊協定**仍然是 HTTP**。 * 雖然透過 **HTTP 協定**傳送，但內容是**加密**的。 -常見做法是讓伺服器（機器、主機等）上跑**一個程式／HTTP 伺服器**來**管理所有 HTTPS 相關工作**：接收**加密的 HTTPS 請求**、將其**解密**成**純 HTTP 請求**轉交給同台伺服器上實際運行的 HTTP 應用（本例為 **FastAPI** 應用）、從應用取得 **HTTP 回應**、再用合適的 **HTTPS 憑證**將其**加密**並以 **HTTPS** 傳回給用戶端。這類伺服器常被稱為 **TLS 終止代理 (TLS Termination Proxy)**。 +常見做法是讓伺服器（機器、主機等）上跑**一個程式／HTTP 伺服器**來**管理所有 HTTPS 相關工作**：接收**加密的 HTTPS 請求**、將其**解密**成**純 HTTP 請求**轉交給同台伺服器上實際運行的 HTTP 應用（本例為 **FastAPI** 應用）、從應用取得 **HTTP 回應**、再用合適的 **HTTPS 憑證**將其**加密**並以 **HTTPS** 傳回給用戶端。這類伺服器常被稱為 **[TLS 終止代理](https://en.wikipedia.org/wiki/TLS_termination_proxy)**。 可作為 TLS 終止代理的選項包括： @@ -49,7 +49,7 @@ 取得這些憑證的流程過去相當繁瑣，需要許多手續，且憑證相當昂貴。 -之後出現了 **Let's Encrypt**。 +之後出現了 **[Let's Encrypt](https://letsencrypt.org/)**。 它是 Linux Foundation 的專案，能**免費**且自動化地提供 **HTTPS 憑證**。這些憑證採用標準的密碼學安全機制，且有效期較短（約 3 個月），因此因為壽命短，**安全性其實更好**。 @@ -200,9 +200,9 @@ TLS 終止代理接著會依照先前協商（起點是 `someapp.example.com` 這些代理標頭包括： -* X-Forwarded-For -* X-Forwarded-Proto -* X-Forwarded-Host +* [X-Forwarded-For](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Forwarded-For) +* [X-Forwarded-Proto](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Forwarded-Proto) +* [X-Forwarded-Host](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/X-Forwarded-Host) /// @@ -218,7 +218,7 @@ TLS 終止代理接著會依照先前協商（起點是 `someapp.example.com` /// tip -你可以在文件 [在代理後方 - 啟用代理轉發標頭](../advanced/behind-a-proxy.md#enable-proxy-forwarded-headers){.internal-link target=_blank} 中了解更多。 +你可以在文件 [在代理後方 - 啟用代理轉發標頭](../advanced/behind-a-proxy.md#enable-proxy-forwarded-headers) 中了解更多。 /// diff --git a/docs/zh-hant/docs/deployment/index.md b/docs/zh-hant/docs/deployment/index.md index ddf533efc9..c9d474cacb 100644 --- a/docs/zh-hant/docs/deployment/index.md +++ b/docs/zh-hant/docs/deployment/index.md @@ -16,7 +16,7 @@ 你可以使用一些工具自行**部署伺服器**，你也可以使用能為你完成部分工作的**雲端服務**，或其他可能的選項。 -例如，我們（FastAPI 的團隊）打造了 **FastAPI Cloud**，讓將 FastAPI 應用程式部署到雲端變得盡可能流暢，並保持與使用 FastAPI 開發時相同的開發者體驗。 +例如，我們（FastAPI 的團隊）打造了 [**FastAPI Cloud**](https://fastapicloud.com)，讓 FastAPI 應用程式部署到雲端變得盡可能流暢，並保持與使用 FastAPI 開發時相同的開發者體驗。 我將向你展示在部署 **FastAPI** 應用程式時你可能應該記住的一些主要概念（儘管其中大部分適用於任何其他類型的 Web 應用程式）。 diff --git a/docs/zh-hant/docs/deployment/manually.md b/docs/zh-hant/docs/deployment/manually.md index bf9f6a93f4..71e9e27c87 100644 --- a/docs/zh-hant/docs/deployment/manually.md +++ b/docs/zh-hant/docs/deployment/manually.md @@ -52,11 +52,11 @@ FastAPI 採用建立 Python 網頁框架與伺服器的標準 Uvicorn：高效能 ASGI 伺服器。 -* Hypercorn：支援 HTTP/2 與 Trio 等功能的 ASGI 伺服器。 -* Daphne：為 Django Channels 打造的 ASGI 伺服器。 -* Granian：針對 Python 應用的 Rust HTTP 伺服器。 -* NGINX Unit：NGINX Unit 是輕量且多功能的網頁應用執行環境。 +* [Uvicorn](https://www.uvicorn.dev/)：高效能 ASGI 伺服器。 +* [Hypercorn](https://hypercorn.readthedocs.io/)：支援 HTTP/2 與 Trio 等功能的 ASGI 伺服器。 +* [Daphne](https://github.com/django/daphne)：為 Django Channels 打造的 ASGI 伺服器。 +* [Granian](https://github.com/emmett-framework/granian)：針對 Python 應用的 Rust HTTP 伺服器。 +* [NGINX Unit](https://unit.nginx.org/howto/fastapi/)：NGINX Unit 是輕量且多功能的網頁應用執行環境。 ## 伺服器機器與伺服器程式 { #server-machine-and-server-program } @@ -74,7 +74,7 @@ FastAPI 採用建立 Python 網頁框架與伺服器的標準 fastapi run --workers 4 INFO Started server process [27369] INFO Started server process [27370] INFO Started server process [27367] - INFO Waiting for application startup. - INFO Waiting for application startup. - INFO Waiting for application startup. - INFO Waiting for application startup. - INFO Application startup complete. - INFO Application startup complete. - INFO Application startup complete. - INFO Application startup complete. + INFO Waiting for application startup. + INFO Waiting for application startup. + INFO Waiting for application startup. + INFO Waiting for application startup. + INFO Application startup complete. + INFO Application startup complete. + INFO Application startup complete. + INFO Application startup complete. ``` @@ -126,7 +126,7 @@ $ uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4 ## 容器與 Docker { #containers-and-docker } -在下一章 [容器中的 FastAPI - Docker](docker.md){.internal-link target=_blank} 我會說明一些策略，幫你處理其他的**部署概念**。 +在下一章 [容器中的 FastAPI - Docker](docker.md) 我會說明一些策略，幫你處理其他的**部署概念**。 我會示範如何**從零建立你的映像檔**來執行單一 Uvicorn 處理序。這個流程相當簡單，而且在使用像 **Kubernetes** 這類分散式容器管理系統時，大多情況也會這麼做。 diff --git a/docs/zh-hant/docs/deployment/versions.md b/docs/zh-hant/docs/deployment/versions.md index c4f9c52624..37d3dd3e24 100644 --- a/docs/zh-hant/docs/deployment/versions.md +++ b/docs/zh-hant/docs/deployment/versions.md @@ -4,7 +4,7 @@ 經常加入新功能、定期修復錯誤，程式碼也在持續改進。 -這就是為什麼目前版本仍為 `0.x.x`，這表示每個版本都可能包含破壞性變更。這遵循 語意化版本（Semantic Versioning） 的慣例。 +這就是為什麼目前版本仍為 `0.x.x`，這表示每個版本都可能包含破壞性變更。這遵循 [語意化版本（Semantic Versioning）](https://semver.org/) 的慣例。 你現在就可以用 **FastAPI** 建置生產環境的應用（而且你可能已經這麼做一段時間了），只要確保你使用的版本能與其餘程式碼正確相容。 @@ -34,7 +34,7 @@ fastapi[standard]>=0.112.0,<0.113.0 ## 可用版本 { #available-versions } -你可以在 [發行說明](../release-notes.md){.internal-link target=_blank} 查看可用版本（例如用來確認目前最新版本）。 +你可以在 [發行說明](../release-notes.md) 查看可用版本（例如用來確認目前最新版本）。 ## 關於版本 { #about-versions } @@ -66,7 +66,7 @@ fastapi>=0.45.0,<0.46.0 你應該為你的應用撰寫測試。 -在 **FastAPI** 中這很容易（感謝 Starlette），請參考文件：[測試](../tutorial/testing.md){.internal-link target=_blank} +在 **FastAPI** 中這很容易（感謝 Starlette），請參考文件：[測試](../tutorial/testing.md) 有了測試之後，你就可以將 **FastAPI** 升級到較新的版本，並透過執行測試來確保所有程式碼都能正確運作。 diff --git a/docs/zh-hant/docs/how-to/authentication-error-status-code.md b/docs/zh-hant/docs/how-to/authentication-error-status-code.md index 9a8de4c910..beea430707 100644 --- a/docs/zh-hant/docs/how-to/authentication-error-status-code.md +++ b/docs/zh-hant/docs/how-to/authentication-error-status-code.md @@ -2,7 +2,7 @@ 在 FastAPI 版本 `0.122.0` 之前，當內建的安全工具在身分驗證失敗後回傳錯誤給用戶端時，會使用 HTTP 狀態碼 `403 Forbidden`。 -從 FastAPI 版本 `0.122.0` 起，改為使用更合適的 HTTP 狀態碼 `401 Unauthorized`，並在回應中依據 HTTP 規範加上合理的 `WWW-Authenticate` 標頭，參考 RFC 7235、RFC 9110。 +從 FastAPI 版本 `0.122.0` 起，改為使用更合適的 HTTP 狀態碼 `401 Unauthorized`，並在回應中依據 HTTP 規範加上合理的 `WWW-Authenticate` 標頭，參考 [RFC 7235](https://datatracker.ietf.org/doc/html/rfc7235#section-3.1)、[RFC 9110](https://datatracker.ietf.org/doc/html/rfc9110#name-401-unauthorized)。 但如果你的用戶端因某些原因依賴於舊行為，你可以在你的 security 類別中覆寫 `make_not_authenticated_error` 方法以恢復舊的行為。 diff --git a/docs/zh-hant/docs/how-to/conditional-openapi.md b/docs/zh-hant/docs/how-to/conditional-openapi.md index 5c091e5b7b..485a7d11d7 100644 --- a/docs/zh-hant/docs/how-to/conditional-openapi.md +++ b/docs/zh-hant/docs/how-to/conditional-openapi.md @@ -10,7 +10,7 @@ 若你的程式碼有安全性缺陷，它依然會存在。 -隱藏文件只會讓他人更難理解如何與你的 API 互動，也可能讓你在正式環境除錯更困難。這通常僅被視為一種 以隱匿求安全。 +隱藏文件只會讓他人更難理解如何與你的 API 互動，也可能讓你在正式環境除錯更困難。這通常僅被視為一種 [以隱匿求安全](https://en.wikipedia.org/wiki/Security_through_obscurity)。 如果你想保護 API，有許多更好的作法，例如： diff --git a/docs/zh-hant/docs/how-to/configure-swagger-ui.md b/docs/zh-hant/docs/how-to/configure-swagger-ui.md index e5b6d7d1e3..cbb63ef5e6 100644 --- a/docs/zh-hant/docs/how-to/configure-swagger-ui.md +++ b/docs/zh-hant/docs/how-to/configure-swagger-ui.md @@ -1,12 +1,12 @@ # 設定 Swagger UI { #configure-swagger-ui } -你可以設定一些額外的 Swagger UI 參數。 +你可以設定一些額外的 [Swagger UI 參數](https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/)。 要設定它們，建立 `FastAPI()` 應用物件時，或呼叫 `get_swagger_ui_html()` 函式時，傳入參數 `swagger_ui_parameters`。 `swagger_ui_parameters` 接受一個 dict，內容會直接傳給 Swagger UI 作為設定。 -FastAPI 會把這些設定轉換成 JSON，以便與 JavaScript 相容，因為 Swagger UI 需要的是這種格式。 +FastAPI 會把這些設定轉換成 **JSON**，以便與 JavaScript 相容，因為 Swagger UI 需要的是這種格式。 ## 停用語法醒目提示 { #disable-syntax-highlighting } @@ -50,11 +50,11 @@ FastAPI 內建一些預設參數，適用於大多數情境。 ## 其他 Swagger UI 參數 { #other-swagger-ui-parameters } -若要查看所有可用的設定，請參考官方的 Swagger UI 參數文件。 +若要查看所有可用的設定，請參考官方的 [Swagger UI 參數文件](https://swagger.io/docs/open-source-tools/swagger-ui/usage/configuration/)。 ## 僅限 JavaScript 的設定 { #javascript-only-settings } -Swagger UI 也允許某些設定是僅限 JavaScript 的物件（例如 JavaScript 函式）。 +Swagger UI 也允許某些設定是**僅限 JavaScript** 的物件（例如 JavaScript 函式）。 FastAPI 也包含以下僅限 JavaScript 的 `presets` 設定： diff --git a/docs/zh-hant/docs/how-to/custom-docs-ui-assets.md b/docs/zh-hant/docs/how-to/custom-docs-ui-assets.md index 4b53945891..e690e55c96 100644 --- a/docs/zh-hant/docs/how-to/custom-docs-ui-assets.md +++ b/docs/zh-hant/docs/how-to/custom-docs-ui-assets.md @@ -54,7 +54,7 @@ Swagger UI 會在背後幫你處理，不過它需要這個「redirect」輔助 ### 測試 { #test-it } -現在你應該能造訪 http://127.0.0.1:8000/docs，重新載入頁面後，資源會從新的 CDN 載入。 +現在你應該能造訪 [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs)，重新載入頁面後，資源會從新的 CDN 載入。 ## 自行託管文件所需的 JavaScript 與 CSS { #self-hosting-javascript-and-css-for-docs } @@ -93,12 +93,12 @@ Swagger UI 會在背後幫你處理，不過它需要這個「redirect」輔助 Swagger UI 需要以下檔案： -* `swagger-ui-bundle.js` -* `swagger-ui.css` +* [`swagger-ui-bundle.js`](https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js) +* [`swagger-ui.css`](https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css) 而 ReDoc 需要以下檔案： -* `redoc.standalone.js` +* [`redoc.standalone.js`](https://cdn.jsdelivr.net/npm/redoc@2/bundles/redoc.standalone.js) 之後，你的檔案結構可能如下： @@ -122,7 +122,7 @@ Swagger UI 需要以下檔案： ### 測試靜態檔案 { #test-the-static-files } -啟動你的應用並前往 http://127.0.0.1:8000/static/redoc.standalone.js。 +啟動你的應用並前往 [http://127.0.0.1:8000/static/redoc.standalone.js](http://127.0.0.1:8000/static/redoc.standalone.js)。 你應該會看到一個很長的 **ReDoc** JavaScript 檔案。 @@ -180,6 +180,6 @@ Swagger UI 會在背後幫你處理，不過它需要這個「redirect」輔助 ### 測試使用靜態檔案的 UI { #test-static-files-ui } -現在，你應該可以關閉 WiFi，造訪你的文件 http://127.0.0.1:8000/docs，並重新載入頁面。 +現在，你應該可以關閉 WiFi，造訪你的文件 [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs)，並重新載入頁面。 即使沒有網際網路，也能看到你的 API 文件並與之互動。 diff --git a/docs/zh-hant/docs/how-to/custom-request-and-route.md b/docs/zh-hant/docs/how-to/custom-request-and-route.md index 99c3410e47..00031fcaad 100644 --- a/docs/zh-hant/docs/how-to/custom-request-and-route.md +++ b/docs/zh-hant/docs/how-to/custom-request-and-route.md @@ -18,7 +18,7 @@ 可能的使用情境包括： -* 將非 JSON 的請求本文轉換為 JSON（例如 `msgpack`）。 +* 將非 JSON 的請求本文轉換為 JSON（例如 [`msgpack`](https://msgpack.org/index.html)）。 * 解壓縮以 gzip 壓縮的請求本文。 * 自動記錄所有請求本文。 @@ -32,7 +32,7 @@ /// tip -這是一個示範用的簡化範例；如果你需要 Gzip 支援，可以直接使用提供的 [`GzipMiddleware`](../advanced/middleware.md#gzipmiddleware){.internal-link target=_blank}。 +這是一個示範用的簡化範例；如果你需要 Gzip 支援，可以直接使用提供的 [`GzipMiddleware`](../advanced/middleware.md#gzipmiddleware)。 /// @@ -40,7 +40,7 @@ 如果標頭中沒有 `gzip`，它就不會嘗試解壓縮本文。 -如此一來，相同的路由類別即可同時處理經 gzip 壓縮與未壓縮的請求. +如此一來，相同的路由類別即可同時處理經 gzip 壓縮與未壓縮的請求。 {* ../../docs_src/custom_request_and_route/tutorial001_an_py310.py hl[9:16] *} @@ -66,7 +66,7 @@ 而 `scope` 與 `receive` 這兩者，就是建立一個新的 `Request` 實例所需的資料。 -想了解更多 `Request`，請參考 Starlette 的 Request 文件。 +想了解更多 `Request`，請參考 [Starlette 的 Request 文件](https://www.starlette.dev/requests/)。 /// @@ -82,7 +82,7 @@ /// tip -要解決相同問題，使用針對 `RequestValidationError` 的自訂處理器來讀取 `body` 通常更簡單（[處理錯誤](../tutorial/handling-errors.md#use-the-requestvalidationerror-body){.internal-link target=_blank}）。 +要解決相同問題，使用針對 `RequestValidationError` 的自訂處理器來讀取 `body` 通常更簡單（[處理錯誤](../tutorial/handling-errors.md#use-the-requestvalidationerror-body)）。 但本範例仍然有效，並示範了如何與內部元件互動。 diff --git a/docs/zh-hant/docs/how-to/extending-openapi.md b/docs/zh-hant/docs/how-to/extending-openapi.md index c51e896f32..b5adca0f76 100644 --- a/docs/zh-hant/docs/how-to/extending-openapi.md +++ b/docs/zh-hant/docs/how-to/extending-openapi.md @@ -37,7 +37,7 @@ 基於上述資訊，你可以用相同的工具函式來產生 OpenAPI 結構，並覆寫你需要客製的部分。 -例如，我們要加入 ReDoc 的 OpenAPI 擴充，插入自訂 logo。 +例如，我們要加入 [ReDoc 的 OpenAPI 擴充，插入自訂 logo](https://github.com/Rebilly/ReDoc/blob/master/docs/redoc-vendor-extensions.md#x-logo)。 ### 一般的 **FastAPI** { #normal-fastapi } @@ -75,6 +75,6 @@ ### 檢查看看 { #check-it } -造訪 http://127.0.0.1:8000/redoc 後，你會看到自訂的 logo（此例為 **FastAPI** 的 logo）： +造訪 [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc) 後，你會看到自訂的 logo（此例為 **FastAPI** 的 logo）： diff --git a/docs/zh-hant/docs/how-to/general.md b/docs/zh-hant/docs/how-to/general.md index 96a71d62dd..13d4d7d3ee 100644 --- a/docs/zh-hant/docs/how-to/general.md +++ b/docs/zh-hant/docs/how-to/general.md @@ -4,36 +4,40 @@ ## 篩選資料 - 安全性 { #filter-data-security } -為確保你不會回傳超出應有的資料，請參閱[教學 - 回應模型 - 回傳型別](../tutorial/response-model.md){.internal-link target=_blank}。 +為確保你不會回傳超出應有的資料，請參閱[教學 - 回應模型 - 回傳型別](../tutorial/response-model.md)。 + +## 最佳化回應效能 - 回應模型 - 回傳型別 { #optimize-response-performance-response-model-return-type } + +為了在回傳 JSON 資料時最佳化效能，請使用回傳型別或回應模型，如此 Pydantic 會在 Rust 端處理序列化為 JSON，而不經過 Python。更多內容請參閱[教學 - 回應模型 - 回傳型別](../tutorial/response-model.md)。 ## 文件標籤 - OpenAPI { #documentation-tags-openapi } -要在你的*路徑操作（path operation）*加入標籤，並在文件 UI 中分組，請參閱[教學 - 路徑操作設定 - 標籤](../tutorial/path-operation-configuration.md#tags){.internal-link target=_blank}。 +要在你的*路徑操作（path operation）*加入標籤，並在文件 UI 中分組，請參閱[教學 - 路徑操作設定 - 標籤](../tutorial/path-operation-configuration.md#tags)。 ## 文件摘要與描述 - OpenAPI { #documentation-summary-and-description-openapi } -要為你的*路徑操作*加入摘要與描述，並在文件 UI 中顯示，請參閱[教學 - 路徑操作設定 - 摘要與描述](../tutorial/path-operation-configuration.md#summary-and-description){.internal-link target=_blank}。 +要為你的*路徑操作*加入摘要與描述，並在文件 UI 中顯示，請參閱[教學 - 路徑操作設定 - 摘要與描述](../tutorial/path-operation-configuration.md#summary-and-description)。 ## 文件回應描述 - OpenAPI { #documentation-response-description-openapi } -要定義在文件 UI 中顯示的回應描述，請參閱[教學 - 路徑操作設定 - 回應描述](../tutorial/path-operation-configuration.md#response-description){.internal-link target=_blank}。 +要定義在文件 UI 中顯示的回應描述，請參閱[教學 - 路徑操作設定 - 回應描述](../tutorial/path-operation-configuration.md#response-description)。 ## 文件將*路徑操作*標記為已棄用 - OpenAPI { #documentation-deprecate-a-path-operation-openapi } -要將*路徑操作*標記為已棄用，並在文件 UI 中顯示，請參閱[教學 - 路徑操作設定 - 棄用](../tutorial/path-operation-configuration.md#deprecate-a-path-operation){.internal-link target=_blank}。 +要將*路徑操作*標記為已棄用，並在文件 UI 中顯示，請參閱[教學 - 路徑操作設定 - 棄用](../tutorial/path-operation-configuration.md#deprecate-a-path-operation)。 ## 將任意資料轉換為 JSON 相容格式 { #convert-any-data-to-json-compatible } -要將任意資料轉換為 JSON 相容格式，請參閱[教學 - JSON 相容編碼器](../tutorial/encoder.md){.internal-link target=_blank}。 +要將任意資料轉換為 JSON 相容格式，請參閱[教學 - JSON 相容編碼器](../tutorial/encoder.md)。 ## OpenAPI 中繼資料 - 文件 { #openapi-metadata-docs } -要在你的 OpenAPI 綱要中加入中繼資料（包含授權、版本、聯絡方式等），請參閱[教學 - 中繼資料與文件 URL](../tutorial/metadata.md){.internal-link target=_blank}。 +要在你的 OpenAPI 綱要中加入中繼資料（包含授權、版本、聯絡方式等），請參閱[教學 - 中繼資料與文件 URL](../tutorial/metadata.md)。 ## 自訂 OpenAPI URL { #openapi-custom-url } -要自訂（或移除）OpenAPI 的 URL，請參閱[教學 - 中繼資料與文件 URL](../tutorial/metadata.md#openapi-url){.internal-link target=_blank}。 +要自訂（或移除）OpenAPI 的 URL，請參閱[教學 - 中繼資料與文件 URL](../tutorial/metadata.md#openapi-url)。 ## OpenAPI 文件 URL { #openapi-docs-urls } -要更新自動產生的文件使用者介面所使用的 URL，請參閱[教學 - 中繼資料與文件 URL](../tutorial/metadata.md#docs-urls){.internal-link target=_blank}。 +要更新自動產生的文件使用者介面所使用的 URL，請參閱[教學 - 中繼資料與文件 URL](../tutorial/metadata.md#docs-urls)。 diff --git a/docs/zh-hant/docs/how-to/graphql.md b/docs/zh-hant/docs/how-to/graphql.md index 51933210c5..24e4d89792 100644 --- a/docs/zh-hant/docs/how-to/graphql.md +++ b/docs/zh-hant/docs/how-to/graphql.md @@ -18,18 +18,18 @@ GraphQL 解決某些非常特定的使用情境。 下面是支援 ASGI 的部分 GraphQL 函式庫，你可以與 FastAPI 一起使用： -* Strawberry 🍓 - * 提供 FastAPI 文件 -* Ariadne - * 提供 FastAPI 文件 -* Tartiflette - * 使用 Tartiflette ASGI 提供 ASGI 整合 -* Graphene - * 搭配 starlette-graphene3 +* [Strawberry](https://strawberry.rocks/) 🍓 + * 提供 [FastAPI 文件](https://strawberry.rocks/docs/integrations/fastapi) +* [Ariadne](https://ariadnegraphql.org/) + * 提供 [FastAPI 文件](https://ariadnegraphql.org/docs/fastapi-integration) +* [Tartiflette](https://tartiflette.io/) + * 使用 [Tartiflette ASGI](https://tartiflette.github.io/tartiflette-asgi/) 提供 ASGI 整合 +* [Graphene](https://graphene-python.org/) + * 搭配 [starlette-graphene3](https://github.com/ciscorn/starlette-graphene3) ## 使用 Strawberry 的 GraphQL { #graphql-with-strawberry } -如果你需要或想使用 GraphQL，Strawberry 是推薦的函式庫，因為它的設計與 FastAPI 最接近，全部都基於型別註解 (type annotations)。 +如果你需要或想使用 GraphQL，[Strawberry](https://strawberry.rocks/) 是推薦的函式庫，因為它的設計與 FastAPI 最接近，全部都基於型別註解 (type annotations)。 視你的使用情境而定，你可能會偏好其他函式庫，但如果你問我，我大概會建議你先試試 Strawberry。 @@ -37,24 +37,24 @@ GraphQL 解決某些非常特定的使用情境。 {* ../../docs_src/graphql_/tutorial001_py310.py hl[3,22,25] *} -你可以在 Strawberry 文件 中進一步了解 Strawberry。 +你可以在 [Strawberry 文件](https://strawberry.rocks/) 中進一步了解 Strawberry。 -也可以參考關於 Strawberry 與 FastAPI 的文件。 +也可以參考關於 [Strawberry 與 FastAPI](https://strawberry.rocks/docs/integrations/fastapi) 的文件。 ## 來自 Starlette 的較舊 `GraphQLApp` { #older-graphqlapp-from-starlette } -早期版本的 Starlette 提供 `GraphQLApp` 類別以整合 Graphene。 +早期版本的 Starlette 提供 `GraphQLApp` 類別以整合 [Graphene](https://graphene-python.org/)。 -它已在 Starlette 中被棄用，但如果你的程式碼使用了它，可以輕鬆遷移到 starlette-graphene3，涵蓋相同的使用情境，且介面幾乎相同。 +它已在 Starlette 中被棄用，但如果你的程式碼使用了它，可以輕鬆遷移到 [starlette-graphene3](https://github.com/ciscorn/starlette-graphene3)，涵蓋相同的使用情境，且介面幾乎相同。 /// tip -如果你需要 GraphQL，我仍建議你看看 Strawberry，因為它基於型別註解，而不是自訂的類別與型別。 +如果你需要 GraphQL，我仍建議你看看 [Strawberry](https://strawberry.rocks/)，因為它基於型別註解，而不是自訂的類別與型別。 /// ## 進一步了解 { #learn-more } -你可以在 官方 GraphQL 文件 中進一步了解 GraphQL。 +你可以在 [官方 GraphQL 文件](https://graphql.org/) 中進一步了解 GraphQL。 你也可以透過上述連結閱讀各個函式庫的更多內容。 diff --git a/docs/zh-hant/docs/how-to/index.md b/docs/zh-hant/docs/how-to/index.md index 6c9a8202c0..c08bd3d663 100644 --- a/docs/zh-hant/docs/how-to/index.md +++ b/docs/zh-hant/docs/how-to/index.md @@ -8,6 +8,6 @@ /// tip -如果你想要以結構化的方式**學習 FastAPI**（推薦），請前往[教學 - 使用者指南](../tutorial/index.md){.internal-link target=_blank}逐章閱讀。 +如果你想要以結構化的方式**學習 FastAPI**（推薦），請前往[教學 - 使用者指南](../tutorial/index.md)逐章閱讀。 /// diff --git a/docs/zh-hant/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md b/docs/zh-hant/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md index 109e57bc81..4495e3dd70 100644 --- a/docs/zh-hant/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md +++ b/docs/zh-hant/docs/how-to/migrate-from-pydantic-v1-to-pydantic-v2.md @@ -22,7 +22,7 @@ Pydantic 團隊自 **Python 3.14** 起，已停止在最新的 Python 版本中 ## 官方指南 { #official-guide } -Pydantic 提供從 v1 遷移到 v2 的官方遷移指南。 +Pydantic 提供從 v1 遷移到 v2 的官方[遷移指南](https://docs.pydantic.dev/latest/migration/)。 其中包含變更內容、驗證如何更正確且更嚴格、可能的注意事項等。 @@ -30,7 +30,7 @@ Pydantic 提供從 v1 遷移到 v2 的官方`bump-pydantic`。 +你可以使用 Pydantic 團隊提供的 [`bump-pydantic`](https://github.com/pydantic/bump-pydantic)。 這個工具會自動修改大部分需要變更的程式碼。 diff --git a/docs/zh-hant/docs/how-to/testing-database.md b/docs/zh-hant/docs/how-to/testing-database.md index cbaecc2389..cf1ed9d36a 100644 --- a/docs/zh-hant/docs/how-to/testing-database.md +++ b/docs/zh-hant/docs/how-to/testing-database.md @@ -1,7 +1,7 @@ # 測試資料庫 { #testing-a-database } -你可以在 SQLModel 文件 中學習關於資料庫、SQL 與 SQLModel。 🤓 +你可以在 [SQLModel 文件](https://sqlmodel.tiangolo.com/) 中學習關於資料庫、SQL 與 SQLModel。 🤓 -有一個迷你 將 SQLModel 與 FastAPI 搭配使用的教學。 ✨ +有一個迷你 [將 SQLModel 與 FastAPI 搭配使用的教學](https://sqlmodel.tiangolo.com/tutorial/fastapi/)。 ✨ -該教學包含一節介紹 測試 SQL 資料庫。 😎 +該教學包含一節介紹 [測試 SQL 資料庫](https://sqlmodel.tiangolo.com/tutorial/fastapi/tests/)。 😎