diff --git a/docs/zh-hant/docs/advanced/additional-responses.md b/docs/zh-hant/docs/advanced/additional-responses.md index bb2bf259bd..118c65e044 100644 --- a/docs/zh-hant/docs/advanced/additional-responses.md +++ b/docs/zh-hant/docs/advanced/additional-responses.md @@ -243,5 +243,5 @@ new_dict = {**old_dict, "new key": "new value"} 若要查看回應中究竟可以包含哪些內容，你可以參考 OpenAPI 規範中的這些章節： -* OpenAPI Responses 物件，其中包含 `Response Object`。 -* OpenAPI Response 物件，你可以把這裡的任何內容直接放到 `responses` 參數內各個回應中。包含 `description`、`headers`、`content`（在其中宣告不同的媒體型別與 JSON Schemas）、以及 `links`。 +* [OpenAPI Responses 物件](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#responses-object)，其中包含 `Response Object`。 +* [OpenAPI Response 物件](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#response-object)，你可以把這裡的任何內容直接放到 `responses` 參數內各個回應中。包含 `description`、`headers`、`content`（在其中宣告不同的媒體型別與 JSON Schemas）、以及 `links`。 diff --git a/docs/zh-hant/docs/advanced/advanced-dependencies.md b/docs/zh-hant/docs/advanced/advanced-dependencies.md index 472cf470b1..559ca245fa 100644 --- a/docs/zh-hant/docs/advanced/advanced-dependencies.md +++ b/docs/zh-hant/docs/advanced/advanced-dependencies.md @@ -132,7 +132,7 @@ checker(q="somequery") 如此一來，該 session 就會釋放資料庫連線，讓其他請求可以使用。 -如果你有不同的情境，需要從含有 `yield` 的相依中提早結束，請建立一個 GitHub 討論問題，描述你的具體情境，以及為何提早關閉含有 `yield` 的相依對你有幫助。 +如果你有不同的情境，需要從含有 `yield` 的相依中提早結束，請建立一個 [GitHub 討論問題](https://github.com/fastapi/fastapi/discussions/new?category=questions)，描述你的具體情境，以及為何提早關閉含有 `yield` 的相依對你有幫助。 如果有令人信服的案例需要在含有 `yield` 的相依中提前關閉，我會考慮加入一種新的選項，讓你可以選擇性啟用提前關閉。 @@ -144,7 +144,7 @@ checker(q="somequery") ### 背景任務與含有 `yield` 的相依，技術細節 { #background-tasks-and-dependencies-with-yield-technical-details } -在 FastAPI 0.106.0 之前，不可能在 `yield` 之後拋出例外；含有 `yield` 的相依的結束程式碼會在回應送出之後才執行，因此[例外處理器](../tutorial/handling-errors.md#install-custom-exception-handlers){.internal-link target=_blank} 早就已經跑完了。 +在 FastAPI 0.106.0 之前，不可能在 `yield` 之後拋出例外；含有 `yield` 的相依的結束程式碼會在回應送出之後才執行，因此[例外處理器](../tutorial/handling-errors.md#install-custom-exception-handlers) 早就已經跑完了。 當初這樣設計主要是為了允許在背景任務中使用由相依「yield」出來的同一組物件，因為結束程式碼會在背景任務結束後才執行。 diff --git a/docs/zh-hant/docs/advanced/async-tests.md b/docs/zh-hant/docs/advanced/async-tests.md index cb7430bf6e..639c42b7db 100644 --- a/docs/zh-hant/docs/advanced/async-tests.md +++ b/docs/zh-hant/docs/advanced/async-tests.md @@ -16,11 +16,11 @@ `TestClient` 在內部做了一些魔法，讓我們能在一般的 `def` 測試函式中，使用標準 pytest 來呼叫非同步的 FastAPI 應用。但當我們在非同步函式中使用它時，這個魔法就不再奏效了。也就是說，當以非同步方式執行測試時，就不能在測試函式內使用 `TestClient`。 -`TestClient` 是建立在 HTTPX 之上，所幸我們可以直接使用它來測試 API。 +`TestClient` 是建立在 [HTTPX](https://www.python-httpx.org) 之上，所幸我們可以直接使用它來測試 API。 ## 範例 { #example } -作為簡單範例，讓我們考慮與[更大型的應用](../tutorial/bigger-applications.md){.internal-link target=_blank}與[測試](../tutorial/testing.md){.internal-link target=_blank}中描述的類似檔案結構： +作為簡單範例，讓我們考慮與[更大型的應用](../tutorial/bigger-applications.md)與[測試](../tutorial/testing.md)中描述的類似檔案結構： ``` . @@ -84,7 +84,7 @@ response = client.get('/') /// warning -如果你的應用仰賴 lifespan 事件，`AsyncClient` 不會觸發這些事件。若要確保它們被觸發，請使用 florimondmanca/asgi-lifespan 的 `LifespanManager`。 +如果你的應用仰賴 lifespan 事件，`AsyncClient` 不會觸發這些事件。若要確保它們被觸發，請使用 [florimondmanca/asgi-lifespan](https://github.com/florimondmanca/asgi-lifespan#usage) 的 `LifespanManager`。 /// @@ -94,6 +94,6 @@ response = client.get('/') /// tip -如果在將非同步呼叫整合進測試時遇到 `RuntimeError: Task attached to a different loop`（例如使用 MongoDB 的 MotorClient 時），請記得：需要事件迴圈的物件只應在非同步函式內實例化，例如在 `@app.on_event("startup")` 回呼中。 +如果在將非同步呼叫整合進測試時遇到 `RuntimeError: Task attached to a different loop`（例如使用 [MongoDB 的 MotorClient](https://stackoverflow.com/questions/41584243/runtimeerror-task-attached-to-a-different-loop) 時），請記得：需要事件迴圈的物件只應在非同步函式內實例化，例如在 `@app.on_event("startup")` 回呼中。 /// diff --git a/docs/zh-hant/docs/advanced/behind-a-proxy.md b/docs/zh-hant/docs/advanced/behind-a-proxy.md index 71a0557afd..a7f4b83b33 100644 --- a/docs/zh-hant/docs/advanced/behind-a-proxy.md +++ b/docs/zh-hant/docs/advanced/behind-a-proxy.md @@ -16,9 +16,9 @@ 代理相關的標頭有： -* 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) /// @@ -60,7 +60,7 @@ https://mysuperapp.com/items/ /// tip -如果你想了解更多 HTTPS 的內容，請參考指南［[關於 HTTPS](../deployment/https.md){.internal-link target=_blank}］。 +如果你想了解更多 HTTPS 的內容，請參考指南［[關於 HTTPS](../deployment/https.md)］。 /// @@ -228,7 +228,7 @@ $ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 請記住，伺服器（Uvicorn）除了把 `root_path` 傳給應用之外，不會拿它做其他用途。 -但如果你用瀏覽器前往 http://127.0.0.1:8000/app，你會看到一般的回應： +但如果你用瀏覽器前往 [http://127.0.0.1:8000/app](http://127.0.0.1:8000/app) ，你會看到一般的回應： ```JSON { @@ -251,9 +251,9 @@ Uvicorn 會預期代理以 `http://127.0.0.1:8000/app` 來存取 Uvicorn，而 ## 在本機使用 Traefik 測試 { #testing-locally-with-traefik } -你可以很容易地用 Traefik 在本機跑一個「移除路徑前綴」的測試。 +你可以很容易地用 [Traefik](https://docs.traefik.io/) 在本機跑一個「移除路徑前綴」的測試。 -下載 Traefik，它是一個單一的執行檔，你可以解壓縮後直接在終端機執行。 +[下載 Traefik](https://github.com/containous/traefik/releases)，它是一個單一的執行檔，你可以解壓縮後直接在終端機執行。 然後建立一個 `traefik.toml` 檔案，內容如下： @@ -330,7 +330,7 @@ $ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 ### 檢查回應 { #check-the-responses } -現在，如果你前往 Uvicorn 的埠：http://127.0.0.1:8000/app，你會看到一般的回應： +現在，如果你前往 Uvicorn 的埠：[http://127.0.0.1:8000/app](http://127.0.0.1:8000/app)，你會看到一般的回應： ```JSON { @@ -345,7 +345,7 @@ $ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 /// -接著打開使用 Traefik 埠且包含路徑前綴的 URL：http://127.0.0.1:9999/api/v1/app。 +接著打開使用 Traefik 埠且包含路徑前綴的 URL：[http://127.0.0.1:9999/api/v1/app](http://127.0.0.1:9999/api/v1/app)。 我們會得到相同的回應： @@ -370,13 +370,13 @@ $ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 「正式」的存取方式應該是透過我們定義了路徑前綴的代理。因此，如我們預期，如果你直接透過 Uvicorn 供應的文件 UI、而 URL 中沒有該路徑前綴，那它不會運作，因為它預期要透過代理來存取。 -你可以在 http://127.0.0.1:8000/docs 檢查： +你可以在 [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs) 檢查： 但如果我們改用「正式」的 URL，也就是使用埠號 `9999` 的代理、並在 `/api/v1/docs`，它就能正確運作了！🎉 -你可以在 http://127.0.0.1:9999/api/v1/docs 檢查： +你可以在 [http://127.0.0.1:9999/api/v1/docs](http://127.0.0.1:9999/api/v1/docs) 檢查： @@ -433,7 +433,7 @@ $ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 /// -在位於 http://127.0.0.1:9999/api/v1/docs 的文件 UI 中看起來會像這樣： +在位於 [http://127.0.0.1:9999/api/v1/docs](http://127.0.0.1:9999/api/v1/docs) 的文件 UI 中看起來會像這樣： @@ -461,6 +461,6 @@ OpenAPI 規格中的 `servers` 屬性是可選的。 ## 掛載子應用 { #mounting-a-sub-application } -如果你需要在同時使用具有 `root_path` 的代理時，掛載一個子應用（如［[子應用 - 掛載](sub-applications.md){.internal-link target=_blank}］中所述），可以像平常一樣操作，正如你所預期的那樣。 +如果你需要在同時使用具有 `root_path` 的代理時，掛載一個子應用（如［[子應用 - 掛載](sub-applications.md)］中所述），可以像平常一樣操作，正如你所預期的那樣。 FastAPI 會在內部智慧地使用 `root_path`，所以一切都能順利運作。✨ diff --git a/docs/zh-hant/docs/advanced/custom-response.md b/docs/zh-hant/docs/advanced/custom-response.md index b723aa82f6..c8355937c8 100644 --- a/docs/zh-hant/docs/advanced/custom-response.md +++ b/docs/zh-hant/docs/advanced/custom-response.md @@ -1,52 +1,36 @@ # 自訂回應——HTML、串流、檔案與其他 { #custom-response-html-stream-file-others } -預設情況下，**FastAPI** 會使用 `JSONResponse` 傳回回應。 +預設情況下，**FastAPI** 會回傳 JSON 回應。 -你可以像在[直接回傳 Response](response-directly.md){.internal-link target=_blank} 中所示，直接回傳一個 `Response` 來覆寫它。 +你可以像在[直接回傳 Response](response-directly.md)中所示，直接回傳一個 `Response` 來覆寫它。 -但如果你直接回傳一個 `Response`（或其子類別，如 `JSONResponse`），資料將不會被自動轉換（即使你宣告了 `response_model`），而且文件也不會自動產生（例如，在產生的 OpenAPI 中包含 HTTP 標頭 `Content-Type` 的特定「media type」）。 +但如果你直接回傳一個 `Response`（或其子類別，例如 `JSONResponse`），資料將不會被自動轉換（即使你宣告了 `response_model`），而且文件也不會自動產生（例如，在產生的 OpenAPI 中包含 HTTP 標頭 `Content-Type` 的特定「media type」）。 你也可以在「路徑操作裝飾器」中使用 `response_class` 參數，宣告要使用的 `Response`（例如任意 `Response` 子類別）。 你從「路徑操作函式」回傳的內容，會被放進該 `Response` 中。 -若該 `Response` 的 media type 是 JSON（`application/json`），像 `JSONResponse` 與 `UJSONResponse`，則你回傳的資料會自動以你在「路徑操作裝飾器」中宣告的 Pydantic `response_model` 進行轉換（與過濾）。 - /// note 若你使用的回應類別沒有 media type，FastAPI 會假設你的回應沒有內容，因此不會在產生的 OpenAPI 文件中記錄回應格式。 /// -## 使用 `ORJSONResponse` { #use-orjsonresponse } - -例如，若你在追求效能，你可以安裝並使用 `orjson`，並將回應設為 `ORJSONResponse`。 - -匯入你想使用的 `Response` 類別（子類），並在「路徑操作裝飾器」中宣告它。 - -對於大型回應，直接回傳 `Response` 會比回傳 `dict` 快得多。 - -這是因為預設情況下，FastAPI 會檢查每個項目並確認它能被序列化為 JSON，使用與教學中說明的相同[JSON 相容編碼器](../tutorial/encoder.md){.internal-link target=_blank}。這使你可以回傳「任意物件」，例如資料庫模型。 - -但如果你確定你回傳的內容「可以用 JSON 序列化」，你可以直接將它傳給回應類別，避免 FastAPI 在把你的回傳內容交給回應類別之前，先經過 `jsonable_encoder` 所帶來的額外開銷。 +## JSON 回應 { #json-responses } -{* ../../docs_src/custom_response/tutorial001b_py310.py hl[2,7] *} +FastAPI 預設回傳 JSON 回應。 -/// info - -參數 `response_class` 也會用來定義回應的「media type」。 +如果你宣告了[回應模型](../tutorial/response-model.md)，FastAPI 會使用 Pydantic 將資料序列化為 JSON。 -在此情況下，HTTP 標頭 `Content-Type` 會被設為 `application/json`。 +如果你沒有宣告回應模型，FastAPI 會使用在[JSON 相容編碼器](../tutorial/encoder.md)中解釋的 `jsonable_encoder`，並將結果放進 `JSONResponse`。 -而且它會以此形式被記錄到 OpenAPI 中。 +如果你宣告的 `response_class` 具有 JSON 的 media type（`application/json`），像 `JSONResponse`，你回傳的資料會自動以你在「路徑操作裝飾器」中宣告的任何 Pydantic `response_model` 進行轉換（與過濾）。但資料不會由 Pydantic 直接序列化成 JSON 位元組；取而代之，會先經由 `jsonable_encoder` 轉換，然後交給 `JSONResponse` 類別，該類別會使用 Python 標準的 JSON 函式庫將其序列化為位元組。 -/// +### JSON 效能 { #json-performance } -/// tip +簡而言之，若你想要最佳效能，請使用[回應模型](../tutorial/response-model.md)，並且不要在「路徑操作裝飾器」中宣告 `response_class`。 -`ORJSONResponse` 只在 FastAPI 中可用，在 Starlette 中不可用。 - -/// +{* ../../docs_src/response_model/tutorial001_01_py310.py ln[15:17] hl[16] *} ## HTML 回應 { #html-response } @@ -69,7 +53,7 @@ ### 回傳 `Response` { #return-a-response } -如[直接回傳 Response](response-directly.md){.internal-link target=_blank} 所示，你也可以在「路徑操作」中直接回傳以覆寫回應。 +如[直接回傳 Response](response-directly.md)所示，你也可以在「路徑操作」中直接回傳以覆寫回應。 上面的相同範例，回傳 `HTMLResponse`，可以像這樣： @@ -154,37 +138,11 @@ FastAPI（實際上是 Starlette）會自動包含 Content-Length 標頭。也 這是 **FastAPI** 的預設回應，如上所述。 -### `ORJSONResponse` { #orjsonresponse } - -使用 `orjson` 的快速替代 JSON 回應，如上所述。 - -/// info - -這需要安裝 `orjson`，例如使用 `pip install orjson`。 - -/// - -### `UJSONResponse` { #ujsonresponse } - -使用 `ujson` 的替代 JSON 回應。 - -/// info - -這需要安裝 `ujson`，例如使用 `pip install ujson`。 - -/// - -/// warning - -`ujson` 在處理某些邊界情況時，沒那麼嚴謹，較 Python 內建實作更「隨意」。 - -/// - -{* ../../docs_src/custom_response/tutorial001_py310.py hl[2,7] *} +/// note | 技術細節 -/// tip +但如果你宣告了回應模型或回傳型別，將會直接用它來把資料序列化為 JSON，並直接回傳具有正確 JSON media type 的回應，而不會使用 `JSONResponse` 類別。 -`ORJSONResponse` 可能是更快的替代方案。 +這是取得最佳效能的理想方式。 /// @@ -214,31 +172,25 @@ FastAPI（實際上是 Starlette）會自動包含 Content-Length 標頭。也 ### `StreamingResponse` { #streamingresponse } -接收一個 async 產生器或一般的產生器／疊代器，並以串流方式傳送回應本文。 - -{* ../../docs_src/custom_response/tutorial007_py310.py hl[2,14] *} - -#### 對「類檔案物件」使用 `StreamingResponse` { #using-streamingresponse-with-file-like-objects } +接收一個 async 產生器或一般的產生器／疊代器（帶有 `yield` 的函式），並以串流方式傳送回應本文。 -如果你有一個類檔案（file-like）物件（例如 `open()` 回傳的物件），你可以建立一個產生器函式來疊代該類檔案物件。 +{* ../../docs_src/custom_response/tutorial007_py310.py hl[3,16] *} -如此一來，你不必先把它全部讀進記憶體，就能將那個產生器函式傳給 `StreamingResponse` 並回傳。 - -這也包含許多用於雲端儲存、影像／影音處理等的函式庫。 +/// note | 技術細節 -{* ../../docs_src/custom_response/tutorial008_py310.py hl[2,10:12,14] *} +一個 `async` 任務只能在抵達某個 `await` 時才能被取消。如果沒有 `await`，該產生器（帶有 `yield` 的函式）將無法被正確取消，甚至在請求取消後仍可能持續執行。 -1. 這是產生器函式。因為它內含 `yield` 陳述式，所以是「產生器函式」。 -2. 透過 `with` 區塊，我們確保在產生器函式結束後關閉類檔案物件。因此，在完成傳送回應後就會關閉。 -3. 這個 `yield from` 告訴函式去疊代名為 `file_like` 的東西。對於每個被疊代到的部分，就把該部分當作此產生器函式（`iterfile`）的輸出進行 `yield`。 +因為這個小範例不需要任何 `await` 陳述式，我們加入 `await anyio.sleep(0)`，讓事件迴圈有機會處理取消。 - 因此，這是一個把「生成」工作在內部轉交給其他東西的產生器函式。 +對於大型或無限的串流來說，這點更為重要。 - 透過這樣做，我們可以把它放進 `with` 區塊，藉此確保在完成後關閉類檔案物件。 +/// /// tip -注意，這裡我們使用的是標準的 `open()`，它不支援 `async` 與 `await`，因此我們用一般的 `def` 來宣告路徑操作。 +與其直接回傳 `StreamingResponse`，你大概會想遵循[資料串流](./stream-data.md)中的作法，這樣更方便，並且會在底層幫你處理取消。 + +如果你要串流 JSON Lines，請參考教學：[串流 JSON Lines](../tutorial/stream-json-lines.md)。 /// @@ -267,7 +219,7 @@ FastAPI（實際上是 Starlette）會自動包含 Content-Length 標頭。也 你可以建立自己的自訂回應類別，繼承自 `Response` 並加以使用。 -例如，假設你要使用 `orjson`，但想套用一些未包含在 `ORJSONResponse` 類別中的自訂設定。 +例如，假設你要使用 [`orjson`](https://github.com/ijl/orjson) 並套用一些設定。 假設你想回傳縮排且格式化的 JSON，因此要使用 orjson 選項 `orjson.OPT_INDENT_2`。 @@ -281,7 +233,7 @@ FastAPI（實際上是 Starlette）會自動包含 Content-Length 標頭。也 {"message": "Hello World"} ``` -……這個回應會回傳： +...這個回應會回傳： ```json { @@ -291,13 +243,21 @@ FastAPI（實際上是 Starlette）會自動包含 Content-Length 標頭。也 當然，你大概能找到比格式化 JSON 更好的方式來利用這個能力。😉 +### `orjson` 或回應模型 { #orjson-or-response-model } + +如果你追求效能，使用[回應模型](../tutorial/response-model.md) 大概會比使用 `orjson` 回應更好。 + +有了回應模型，FastAPI 會使用 Pydantic 直接將資料序列化為 JSON，而不需要像其他情況那樣先經過 `jsonable_encoder` 之類的中介步驟。 + +而且在底層，Pydantic 用來序列化為 JSON 的 Rust 機制和 `orjson` 相同，因此用回應模型已經能獲得最佳效能。 + ## 預設回應類別 { #default-response-class } 在建立 **FastAPI** 類別實例或 `APIRouter` 時，你可以指定預設要使用哪個回應類別。 用來設定的是 `default_response_class` 參數。 -在下面的例子中，**FastAPI** 會在所有「路徑操作」中預設使用 `ORJSONResponse`，而不是 `JSONResponse`。 +在下面的例子中，**FastAPI** 會在所有「路徑操作」中預設使用 `HTMLResponse`，而不是 JSON。 {* ../../docs_src/custom_response/tutorial010_py310.py hl[2,4] *} @@ -309,4 +269,4 @@ FastAPI（實際上是 Starlette）會自動包含 Content-Length 標頭。也 ## 其他文件化選項 { #additional-documentation } -你也可以在 OpenAPI 中使用 `responses` 宣告 media type 與其他許多細節：[在 OpenAPI 中的額外回應](additional-responses.md){.internal-link target=_blank}。 +你也可以在 OpenAPI 中使用 `responses` 宣告 media type 與其他許多細節：[在 OpenAPI 中的額外回應](additional-responses.md)。 diff --git a/docs/zh-hant/docs/advanced/dataclasses.md b/docs/zh-hant/docs/advanced/dataclasses.md index d586bd6844..a18b421c42 100644 --- a/docs/zh-hant/docs/advanced/dataclasses.md +++ b/docs/zh-hant/docs/advanced/dataclasses.md @@ -2,11 +2,11 @@ FastAPI 建立在 **Pydantic** 之上，我之前示範過如何使用 Pydantic 模型來宣告請求與回應。 -但 FastAPI 也同樣支援以相同方式使用 `dataclasses`： +但 FastAPI 也同樣支援以相同方式使用 [`dataclasses`](https://docs.python.org/3/library/dataclasses.html)： {* ../../docs_src/dataclasses_/tutorial001_py310.py hl[1,6:11,18:19] *} -這之所以可行，要感謝 **Pydantic**，因為它 內建支援 `dataclasses`。 +這之所以可行，要感謝 **Pydantic**，因為它 [內建支援 `dataclasses`](https://docs.pydantic.dev/latest/concepts/dataclasses/#use-of-stdlib-dataclasses-with-basemodel)。 所以，即使上面的程式碼沒有明確使用 Pydantic，FastAPI 仍會使用 Pydantic 將那些標準的 dataclass 轉換為 Pydantic 版本的 dataclass。 @@ -67,7 +67,7 @@ FastAPI 建立在 **Pydantic** 之上，我之前示範過如何使用 Pydantic 一如往常，在 FastAPI 中你可以視需要混用 `def` 與 `async def`。 - 如果需要複習何時用哪個，請參考文件中關於 [`async` 與 `await`](../async.md#in-a-hurry){.internal-link target=_blank} 的章節「In a hurry?」。 + 如果需要複習何時用哪個，請參考文件中關於 [`async` 與 `await`](../async.md#in-a-hurry) 的章節「In a hurry?」。 9. 這個「路徑操作函式」回傳的不是 dataclass（雖然也可以），而是一個包含內部資料的字典清單。 FastAPI 會使用 `response_model` 參數（其中包含 dataclass）來轉換回應。 @@ -80,7 +80,7 @@ FastAPI 建立在 **Pydantic** 之上，我之前示範過如何使用 Pydantic 你也可以將 `dataclasses` 與其他 Pydantic 模型結合、從它們繼承、把它們包含進你的自訂模型等。 -想了解更多，請參考 Pydantic 關於 dataclasses 的文件。 +想了解更多，請參考 [Pydantic 關於 dataclasses 的文件](https://docs.pydantic.dev/latest/concepts/dataclasses/)。 ## 版本 { #version } diff --git a/docs/zh-hant/docs/advanced/events.md b/docs/zh-hant/docs/advanced/events.md index e5c0afe48f..7def525fa6 100644 --- a/docs/zh-hant/docs/advanced/events.md +++ b/docs/zh-hant/docs/advanced/events.md @@ -150,11 +150,11 @@ async with lifespan(app): 給有興趣鑽研的同好一點技術細節。🤓 -在底層的 ASGI 技術規範中，這屬於 Lifespan Protocol 的一部分，並定義了 `startup` 與 `shutdown` 兩種事件。 +在底層的 ASGI 技術規範中，這屬於 [Lifespan Protocol](https://asgi.readthedocs.io/en/latest/specs/lifespan.html) 的一部分，並定義了 `startup` 與 `shutdown` 兩種事件。 /// info -你可以在 Starlette 的 Lifespan 文件 讀到更多關於 Starlette `lifespan` 處理器的資訊。 +你可以在 [Starlette 的 Lifespan 文件](https://www.starlette.dev/lifespan/) 讀到更多關於 Starlette `lifespan` 處理器的資訊。 也包含如何處理可在程式其他區域使用的 lifespan 狀態。 @@ -162,4 +162,4 @@ async with lifespan(app): ## 子應用程式 { #sub-applications } -🚨 請記住，這些生命週期事件（startup 與 shutdown）只會在主應用程式上執行，不會在[子應用程式 - 掛載](sub-applications.md){.internal-link target=_blank}上執行。 +🚨 請記住，這些生命週期事件（startup 與 shutdown）只會在主應用程式上執行，不會在[子應用程式 - 掛載](sub-applications.md)上執行。 diff --git a/docs/zh-hant/docs/advanced/index.md b/docs/zh-hant/docs/advanced/index.md index cfbc17afec..9b1cb539ae 100644 --- a/docs/zh-hant/docs/advanced/index.md +++ b/docs/zh-hant/docs/advanced/index.md @@ -2,13 +2,13 @@ ## 更多功能 { #additional-features } -主要的[教學 - 使用者指南](../tutorial/index.md){.internal-link target=_blank} 應足以帶你快速瀏覽 **FastAPI** 的所有核心功能。 +主要的[教學 - 使用者指南](../tutorial/index.md) 應足以帶你快速瀏覽 **FastAPI** 的所有核心功能。 在接下來的章節中，你會看到其他選項、設定，以及更多功能。 /// tip -接下來的章節不一定「進階」。 +接下來的章節**不一定是「進階」**。 而且對於你的使用情境，解法很可能就在其中某一節。 @@ -16,6 +16,6 @@ ## 先閱讀教學 { #read-the-tutorial-first } -只要掌握主要[教學 - 使用者指南](../tutorial/index.md){.internal-link target=_blank} 的內容，你就能使用 **FastAPI** 的大多數功能。 +只要掌握主要[教學 - 使用者指南](../tutorial/index.md) 的內容，你就能使用 **FastAPI** 的大多數功能。 接下來的章節也假設你已經讀過，並已了解那些主要觀念。 diff --git a/docs/zh-hant/docs/advanced/middleware.md b/docs/zh-hant/docs/advanced/middleware.md index 80cda345c3..d8a53394c7 100644 --- a/docs/zh-hant/docs/advanced/middleware.md +++ b/docs/zh-hant/docs/advanced/middleware.md @@ -1,8 +1,8 @@ # 進階中介軟體 { #advanced-middleware } -在主要教學中你已學過如何將[自訂中介軟體](../tutorial/middleware.md){.internal-link target=_blank}加入到你的應用程式。 +在主要教學中你已學過如何將[自訂中介軟體](../tutorial/middleware.md)加入到你的應用程式。 -你也讀過如何使用 `CORSMiddleware` 處理 [CORS](../tutorial/cors.md){.internal-link target=_blank}。 +你也讀過如何處理 [使用 `CORSMiddleware` 的 CORS](../tutorial/cors.md)。 本節將示範如何使用其他中介軟體。 @@ -91,7 +91,7 @@ app.add_middleware(UnicornMiddleware, some_config="rainbow") 例如： -- Uvicorn 的 `ProxyHeadersMiddleware` -- MessagePack +- [Uvicorn 的 `ProxyHeadersMiddleware`](https://github.com/encode/uvicorn/blob/master/uvicorn/middleware/proxy_headers.py) +- [MessagePack](https://github.com/florimondmanca/msgpack-asgi) -想瞭解更多可用的中介軟體，請參考 Starlette 的中介軟體文件 與 ASGI 精選清單。 +想瞭解更多可用的中介軟體，請參考 [Starlette 的中介軟體文件](https://www.starlette.dev/middleware/) 與 [ASGI 精選清單](https://github.com/florimondmanca/awesome-asgi)。 diff --git a/docs/zh-hant/docs/advanced/openapi-callbacks.md b/docs/zh-hant/docs/advanced/openapi-callbacks.md index b1a16be249..3b01f42016 100644 --- a/docs/zh-hant/docs/advanced/openapi-callbacks.md +++ b/docs/zh-hant/docs/advanced/openapi-callbacks.md @@ -35,7 +35,7 @@ /// tip -`callback_url` 查詢參數使用的是 Pydantic 的 Url 型別。 +`callback_url` 查詢參數使用的是 Pydantic 的 [Url](https://docs.pydantic.dev/latest/api/networks/) 型別。 /// @@ -66,7 +66,7 @@ httpx.post(callback_url, json={"description": "Invoice paid", "paid": True}) 實際的回呼就是一個 HTTP 請求。 -當你自己實作回呼時，可以使用像是 HTTPX 或 Requests。 +當你自己實作回呼時，可以使用像是 [HTTPX](https://www.python-httpx.org) 或 [Requests](https://requests.readthedocs.io/)。 /// @@ -106,11 +106,11 @@ httpx.post(callback_url, json={"description": "Invoice paid", "paid": True}) 和一般「路徑操作」相比有兩個主要差異： * 不需要任何實際程式碼，因為你的應用永遠不會呼叫這段程式。它只用來文件化「外部 API」。因此函式可以只有 `pass`。 -* 「路徑」可以包含一個 OpenAPI 3 表達式（見下文），可使用參數與原始送到「你的 API」的請求中的部分欄位。 +* 「路徑」可以包含一個 [OpenAPI 3 表達式](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression)（見下文），可使用參數與原始送到「你的 API」的請求中的部分欄位。 ### 回呼路徑表達式 { #the-callback-path-expression } -回呼的「路徑」可以包含一個 OpenAPI 3 表達式，能引用原本送到「你的 API」的請求中的部分內容。 +回呼的「路徑」可以包含一個 [OpenAPI 3 表達式](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression)，能引用原本送到「你的 API」的請求中的部分內容。 在這個例子中，它是一個 `str`： @@ -179,7 +179,7 @@ https://www.external.org/events/invoices/2expen51ve ### 檢查文件 { #check-the-docs } -現在你可以啟動應用，並前往 http://127.0.0.1:8000/docs。 +現在你可以啟動應用，並前往 [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs)。 你會在文件中看到你的「路徑操作」包含一個「Callbacks」區塊，顯示「外部 API」應該長什麼樣子： diff --git a/docs/zh-hant/docs/advanced/openapi-webhooks.md b/docs/zh-hant/docs/advanced/openapi-webhooks.md index ef52c3884f..18206c447b 100644 --- a/docs/zh-hant/docs/advanced/openapi-webhooks.md +++ b/docs/zh-hant/docs/advanced/openapi-webhooks.md @@ -48,7 +48,7 @@ Webhook 功能自 OpenAPI 3.1.0 起提供，FastAPI `0.99.0` 以上版本支援 ### 查看文件 { #check-the-docs } -現在你可以啟動應用，然後前往 http://127.0.0.1:8000/docs。 +現在你可以啟動應用，然後前往 [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs)。 你會在文件中看到一般的路徑操作，另外還有一些 webhook： diff --git a/docs/zh-hant/docs/advanced/path-operation-advanced-configuration.md b/docs/zh-hant/docs/advanced/path-operation-advanced-configuration.md index 4f25eb9878..f1607a1da5 100644 --- a/docs/zh-hant/docs/advanced/path-operation-advanced-configuration.md +++ b/docs/zh-hant/docs/advanced/path-operation-advanced-configuration.md @@ -60,7 +60,7 @@ 你也可以宣告額外的回應及其模型、狀態碼等。 -文件中有完整章節說明，請見 [OpenAPI 中的額外回應](additional-responses.md){.internal-link target=_blank}。 +文件中有完整章節說明，請見 [OpenAPI 中的額外回應](additional-responses.md)。 ## OpenAPI 額外資訊 { #openapi-extra } @@ -68,7 +68,7 @@ /// note | 技術細節 -在 OpenAPI 規格中，這稱為 Operation 物件。 +在 OpenAPI 規格中，這稱為 [Operation 物件](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.3.md#operation-object)。 /// @@ -82,7 +82,7 @@ 這是一個較低階的擴充介面。 -如果你只需要宣告額外回應，更方便的方式是使用 [OpenAPI 中的額外回應](additional-responses.md){.internal-link target=_blank}。 +如果你只需要宣告額外回應，更方便的方式是使用 [OpenAPI 中的額外回應](additional-responses.md)。 /// diff --git a/docs/zh-hant/docs/advanced/response-change-status-code.md b/docs/zh-hant/docs/advanced/response-change-status-code.md index 4b8d459ca2..31b688512e 100644 --- a/docs/zh-hant/docs/advanced/response-change-status-code.md +++ b/docs/zh-hant/docs/advanced/response-change-status-code.md @@ -1,6 +1,6 @@ # 回應 - 變更狀態碼 { #response-change-status-code } -你可能已經讀過，可以設定預設的[回應狀態碼](../tutorial/response-status-code.md){.internal-link target=_blank}。 +你可能已經讀過，可以設定預設的[回應狀態碼](../tutorial/response-status-code.md)。 但有些情況你需要回傳與預設不同的狀態碼。 @@ -26,6 +26,6 @@ 若你宣告了 `response_model`，它仍會被用來過濾並轉換你回傳的物件。 -FastAPI 會使用那個「*暫時的*」回應來取得狀態碼（以及 Cookies 和標頭），並將它們放入最終回應中；最終回應包含你回傳的值，且會被任何 `response_model` 過濾。 +**FastAPI** 會使用那個「*暫時的*」回應來取得狀態碼（以及 Cookies 和標頭），並將它們放入最終回應中；最終回應包含你回傳的值，且會被任何 `response_model` 過濾。 你也可以在相依性（dependencies）中宣告 `Response` 參數，並在其中設定狀態碼。但請注意，最後被設定的值會生效。 diff --git a/docs/zh-hant/docs/advanced/settings.md b/docs/zh-hant/docs/advanced/settings.md index 1ee5ad7cc2..9892f8f000 100644 --- a/docs/zh-hant/docs/advanced/settings.md +++ b/docs/zh-hant/docs/advanced/settings.md @@ -8,7 +8,7 @@ /// tip -若想了解環境變數，你可以閱讀[環境變數](../environment-variables.md){.internal-link target=_blank}。 +若想了解環境變數，你可以閱讀[環境變數](../environment-variables.md)。 /// @@ -20,11 +20,11 @@ ## Pydantic `Settings` { #pydantic-settings } -幸好，Pydantic 提供了很好的工具，可用來處理由環境變數而來的設定：Pydantic：設定管理。 +幸好，Pydantic 提供了很好的工具，可用來處理由環境變數而來的設定：[Pydantic：設定管理](https://docs.pydantic.dev/latest/concepts/pydantic_settings/)。 ### 安裝 `pydantic-settings` { #install-pydantic-settings } -首先，請先建立你的[虛擬環境](../virtual-environments.md){.internal-link target=_blank}，啟用它，然後安裝 `pydantic-settings` 套件： +首先，請先建立你的[虛擬環境](../virtual-environments.md)，啟用它，然後安裝 `pydantic-settings` 套件：
@@ -100,7 +100,7 @@ $ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.p ## 在另一個模組中的設定 { #settings-in-another-module } -你也可以把這些設定放在另一個模組檔案中，就像在[更大的應用程式 - 多個檔案](../tutorial/bigger-applications.md){.internal-link target=_blank}所示。 +你也可以把這些設定放在另一個模組檔案中，就像在[更大的應用程式 - 多個檔案](../tutorial/bigger-applications.md)所示。 例如，你可以有一個 `config.py` 檔案如下： @@ -112,7 +112,7 @@ $ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.p /// tip -你也需要一個 `__init__.py` 檔案，詳見[更大的應用程式 - 多個檔案](../tutorial/bigger-applications.md){.internal-link target=_blank}。 +你也需要一個 `__init__.py` 檔案，詳見[更大的應用程式 - 多個檔案](../tutorial/bigger-applications.md)。 /// @@ -172,7 +172,7 @@ $ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.p /// -Pydantic 透過外部函式庫支援讀取這類型的檔案。你可以閱讀更多：Pydantic Settings：Dotenv (.env) 支援。 +Pydantic 透過外部函式庫支援讀取這類型的檔案。你可以閱讀更多：[Pydantic Settings：Dotenv (.env) 支援](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#dotenv-env-support)。 /// tip @@ -197,7 +197,7 @@ APP_NAME="ChimichangApp" /// tip -`model_config` 屬性僅用於 Pydantic 的設定。你可以閱讀更多：Pydantic：概念：設定。 +`model_config` 屬性僅用於 Pydantic 的設定。你可以閱讀更多：[Pydantic：概念：設定](https://docs.pydantic.dev/latest/concepts/config/)。 /// @@ -291,7 +291,7 @@ participant execute as Execute function 如此一來，它的行為幾乎就像全域變數。但因為它使用相依函式，因此我們可以在測試時輕鬆將其覆寫。 -`@lru_cache` 是 `functools` 的一部分，而 `functools` 是 Python 標準程式庫的一部分。你可以在Python 文件中閱讀 `@lru_cache` 以了解更多。 +`@lru_cache` 是 `functools` 的一部分，而 `functools` 是 Python 標準程式庫的一部分。你可以在[Python 文件中閱讀 `@lru_cache`](https://docs.python.org/3/library/functools.html#functools.lru_cache) 以了解更多。 ## 回顧 { #recap } diff --git a/docs/zh-hant/docs/advanced/sub-applications.md b/docs/zh-hant/docs/advanced/sub-applications.md index 773bc4b886..7199e6d629 100644 --- a/docs/zh-hant/docs/advanced/sub-applications.md +++ b/docs/zh-hant/docs/advanced/sub-applications.md @@ -30,25 +30,25 @@ ### 檢查自動 API 文件 { #check-the-automatic-api-docs } -現在，用你的檔案執行 `fastapi` 指令： +現在，執行 `fastapi` 指令：
```console -$ fastapi dev main.py +$ fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ```
-然後開啟位於 http://127.0.0.1:8000/docs 的文件。 +然後開啟位於 [http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs) 的文件。 你會看到主應用的自動 API 文件，只包含它自己的*路徑操作*： -接著，開啟子應用程式的文件：http://127.0.0.1:8000/subapi/docs。 +接著，開啟子應用程式的文件：[http://127.0.0.1:8000/subapi/docs](http://127.0.0.1:8000/subapi/docs)。 你會看到子應用程式的自動 API 文件，只包含它自己的*路徑操作*，而且都在正確的子路徑前綴 `/subapi` 之下： @@ -64,4 +64,4 @@ $ fastapi dev main.py 而且子應用程式也能再掛載自己的子應用程式，一切都能正確運作，因為 FastAPI 會自動處理所有這些 `root_path`。 -你可以在[在代理伺服器之後](behind-a-proxy.md){.internal-link target=_blank}一節中進一步了解 `root_path` 與如何顯式使用它。 +你可以在[在代理伺服器之後](behind-a-proxy.md)一節中進一步了解 `root_path` 與如何顯式使用它。 diff --git a/docs/zh-hant/docs/advanced/templates.md b/docs/zh-hant/docs/advanced/templates.md index ffc7599ae2..6e622d5a77 100644 --- a/docs/zh-hant/docs/advanced/templates.md +++ b/docs/zh-hant/docs/advanced/templates.md @@ -8,7 +8,7 @@ ## 安裝相依套件 { #install-dependencies } -請先建立一個[虛擬環境](../virtual-environments.md){.internal-link target=_blank}、啟用它，然後安裝 `jinja2`： +請先建立一個[虛擬環境](../virtual-environments.md)、啟用它，然後安裝 `jinja2`：
@@ -123,4 +123,4 @@ Item ID: 42 ## 更多細節 { #more-details } -想了解更多細節（包含如何測試模板），請參考 Starlette 的模板說明文件。 +想了解更多細節（包含如何測試模板），請參考 [Starlette 的模板說明文件](https://www.starlette.dev/templates/)。 diff --git a/docs/zh-hant/docs/advanced/testing-websockets.md b/docs/zh-hant/docs/advanced/testing-websockets.md index 7348e60fdf..caedc11dbd 100644 --- a/docs/zh-hant/docs/advanced/testing-websockets.md +++ b/docs/zh-hant/docs/advanced/testing-websockets.md @@ -8,6 +8,6 @@ /// note | 注意 -想了解更多，請參考 Starlette 的 測試 WebSocket 文件。 +想了解更多，請參考 Starlette 的[測試 WebSocket](https://www.starlette.dev/testclient/#testing-websocket-sessions)文件。 /// diff --git a/docs/zh-hant/docs/advanced/websockets.md b/docs/zh-hant/docs/advanced/websockets.md index 22e3fdcb9e..57f51bcfbe 100644 --- a/docs/zh-hant/docs/advanced/websockets.md +++ b/docs/zh-hant/docs/advanced/websockets.md @@ -1,10 +1,10 @@ # WebSockets { #websockets } -你可以在 **FastAPI** 中使用 WebSockets。 +你可以在 **FastAPI** 中使用 [WebSockets](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API)。 ## 安裝 `websockets` { #install-websockets } -請先建立[虛擬環境](../virtual-environments.md){.internal-link target=_blank}、啟用它，然後安裝 `websockets`（一個讓你更容易使用「WebSocket」通訊協定的 Python 套件）： +請先建立[虛擬環境](../virtual-environments.md)、啟用它，然後安裝 `websockets`（一個讓你更容易使用「WebSocket」通訊協定的 Python 套件）：
@@ -69,14 +69,14 @@ $ pip install websockets
```console -$ fastapi dev main.py +$ fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ```
-在瀏覽器開啟 http://127.0.0.1:8000。 +在瀏覽器開啟 [http://127.0.0.1:8000](http://127.0.0.1:8000)。 你會看到一個像這樣的簡單頁面： @@ -115,25 +115,25 @@ $ fastapi dev main.py 因為這是 WebSocket，拋出 `HTTPException` 並沒有意義，因此我們改為拋出 `WebSocketException`。 -你可以使用規範中定義的有效關閉代碼之一。 +你可以使用規範中定義的[有效關閉代碼](https://tools.ietf.org/html/rfc6455#section-7.4.1)之一。 /// ### 用依賴試用 WebSocket { #try-the-websockets-with-dependencies } -如果你的檔案名為 `main.py`，用以下指令執行應用： +執行你的應用：
```console -$ fastapi dev main.py +$ fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ```
-在瀏覽器開啟 http://127.0.0.1:8000。 +在瀏覽器開啟 [http://127.0.0.1:8000](http://127.0.0.1:8000)。 在那裡你可以設定： @@ -174,7 +174,7 @@ Client #1596980209979 left the chat 但請注意，因為所有狀態都在記憶體中的單一 list 裡管理，它只會在該程序執行期間生效，且僅適用於單一程序。 -如果你需要一個容易與 FastAPI 整合、但更健壯，且可由 Redis、PostgreSQL 等後端支援的方案，請參考 encode/broadcaster。 +如果你需要一個容易與 FastAPI 整合、但更健壯，且可由 Redis、PostgreSQL 等後端支援的方案，請參考 [encode/broadcaster](https://github.com/encode/broadcaster)。 /// @@ -182,5 +182,5 @@ Client #1596980209979 left the chat 想了解更多選項，請參考 Starlette 的文件： -* `WebSocket` 類別。 -* 以類別為基礎的 WebSocket 處理。 +* [`WebSocket` 類別](https://www.starlette.dev/websockets/)。 +* [以類別為基礎的 WebSocket 處理](https://www.starlette.dev/endpoints/#websocketendpoint)。 diff --git a/docs/zh-hant/docs/advanced/wsgi.md b/docs/zh-hant/docs/advanced/wsgi.md index 9d03b56924..c1baff34ed 100644 --- a/docs/zh-hant/docs/advanced/wsgi.md +++ b/docs/zh-hant/docs/advanced/wsgi.md @@ -1,6 +1,6 @@ # 包含 WSGI：Flask、Django 等 { #including-wsgi-flask-django-others } -你可以像在 [子應用程式 - 掛載](sub-applications.md){.internal-link target=_blank}、[在 Proxy 後方](behind-a-proxy.md){.internal-link target=_blank} 中所見那樣掛載 WSGI 應用。 +你可以像在 [子應用程式 - 掛載](sub-applications.md)、[在 Proxy 後方](behind-a-proxy.md) 中所見那樣掛載 WSGI 應用。 為此，你可以使用 `WSGIMiddleware` 來包住你的 WSGI 應用，例如 Flask、Django 等。 @@ -36,13 +36,13 @@ 其餘則由 **FastAPI** 處理。 -如果你啟動它並前往 http://localhost:8000/v1/，你會看到來自 Flask 的回應： +如果你啟動它並前往 [http://localhost:8000/v1/](http://localhost:8000/v1/)，你會看到來自 Flask 的回應： ```txt Hello, World from Flask! ``` -如果你前往 http://localhost:8000/v2，你會看到來自 FastAPI 的回應： +如果你前往 [http://localhost:8000/v2](http://localhost:8000/v2)，你會看到來自 FastAPI 的回應： ```JSON { diff --git a/docs/zh-hant/docs/tutorial/background-tasks.md b/docs/zh-hant/docs/tutorial/background-tasks.md index 63e4e5a160..216ec88689 100644 --- a/docs/zh-hant/docs/tutorial/background-tasks.md +++ b/docs/zh-hant/docs/tutorial/background-tasks.md @@ -61,7 +61,7 @@ ## 技術細節 { #technical-details } -類別 `BackgroundTasks` 直接來自 `starlette.background`。 +類別 `BackgroundTasks` 直接來自 [`starlette.background`](https://www.starlette.dev/background/)。 它被直接匯入/包含到 FastAPI 中，因此你可以從 `fastapi` 匯入它，並避免不小心從 `starlette.background` 匯入另一個同名的 `BackgroundTask`（結尾沒有 s）。 @@ -69,11 +69,11 @@ 在 FastAPI 中仍可單獨使用 `BackgroundTask`，但你需要在程式碼中自行建立該物件，並回傳包含它的 Starlette `Response`。 -更多細節請參閱 Starlette 官方的 Background Tasks 文件。 +更多細節請參閱 [Starlette 官方的 Background Tasks 文件](https://www.starlette.dev/background/)。 ## 注意事項 { #caveat } -如果你需要執行繁重的背景計算，且不一定要由同一個行程執行（例如不需要共用記憶體、變數等），可以考慮使用更大型的工具，例如 Celery。 +如果你需要執行繁重的背景計算，且不一定要由同一個行程執行（例如不需要共用記憶體、變數等），可以考慮使用更大型的工具，例如 [Celery](https://docs.celeryq.dev)。 這類工具通常需要較複雜的設定，以及訊息/工作佇列管理器（如 RabbitMQ 或 Redis），但它們允許你在多個行程，甚至多台伺服器上執行背景任務。 diff --git a/docs/zh-hant/docs/tutorial/body-nested-models.md b/docs/zh-hant/docs/tutorial/body-nested-models.md index df4aff6972..f7b8627b4b 100644 --- a/docs/zh-hant/docs/tutorial/body-nested-models.md +++ b/docs/zh-hant/docs/tutorial/body-nested-models.md @@ -95,7 +95,7 @@ my_list: list[str] 除了 `str`、`int`、`float` 等一般的單一型別外，你也可以使用繼承自 `str` 的更複雜單一型別。 -若要查看所有可用選項，請參閱 Pydantic 的型別總覽。你會在下一章看到一些範例。 +若要查看所有可用選項，請參閱 [Pydantic 的型別總覽](https://docs.pydantic.dev/latest/concepts/types/)。你會在下一章看到一些範例。 例如，在 `Image` 模型中有一個 `url` 欄位，我們可以將其宣告為 Pydantic 的 `HttpUrl`，而不是 `str`： diff --git a/docs/zh-hant/docs/tutorial/body.md b/docs/zh-hant/docs/tutorial/body.md index bddcbbf434..08246f513b 100644 --- a/docs/zh-hant/docs/tutorial/body.md +++ b/docs/zh-hant/docs/tutorial/body.md @@ -6,7 +6,7 @@ 你的 API 幾乎總是需要傳回**回應**本文。但用戶端不一定每次都要送出**請求本文**，有時只會請求某個路徑，可能帶一些查詢參數，但不會傳送本文。 -要宣告**請求**本文，你會使用 Pydantic 模型，享受其完整的功能與優點。 +要宣告**請求**本文，你會使用 [Pydantic](https://docs.pydantic.dev/) 模型，享受其完整的功能與優點。 /// info @@ -72,7 +72,7 @@ - 若資料無效，會回傳清楚易懂的錯誤，指出哪裡、哪筆資料不正確。 - 把接收到的資料放在參數 `item` 中提供給你。 - 由於你在函式中將其宣告為 `Item` 型別，你也會獲得完整的編輯器支援（自動完成等）以及所有屬性與其型別。 -- 為你的模型產生 JSON Schema 定義，如有需要，你也可以在專案中的其他地方使用。 +- 為你的模型產生 [JSON Schema](https://json-schema.org) 定義，如有需要，你也可以在專案中的其他地方使用。 - 這些 schema 會成為產生的 OpenAPI schema 的一部分，並由自動文件 UIs 使用。 ## 自動文件 { #automatic-docs } @@ -101,15 +101,15 @@ 甚至為了支援這點，Pydantic 本身也做了些修改。 -前面的螢幕截圖是使用 Visual Studio Code 拍的。 +前面的螢幕截圖是使用 [Visual Studio Code](https://code.visualstudio.com) 拍的。 -但你在 PyCharm 與大多數其它 Python 編輯器中也會得到相同的編輯器支援： +但你在 [PyCharm](https://www.jetbrains.com/pycharm/) 與大多數其它 Python 編輯器中也會得到相同的編輯器支援： /// tip -如果你使用 PyCharm 作為編輯器，可以安裝 Pydantic PyCharm Plugin。 +如果你使用 [PyCharm](https://www.jetbrains.com/pycharm/) 作為編輯器，可以安裝 [Pydantic PyCharm Plugin](https://github.com/koxudaxi/pydantic-pycharm-plugin/)。 它能增強 Pydantic 模型的編輯器支援，包含： @@ -161,4 +161,4 @@ FastAPI 會因為預設值 `= None` 而知道 `q` 的值不是必填。 ## 不使用 Pydantic { #without-pydantic } -若你不想使用 Pydantic 模型，也可以使用 **Body** 參數。請參考[Body - 多個參數：本文中的單一值](body-multiple-params.md#singular-values-in-body){.internal-link target=_blank}。 +若你不想使用 Pydantic 模型，也可以使用 **Body** 參數。請參考[Body - 多個參數：本文中的單一值](body-multiple-params.md#singular-values-in-body)。 diff --git a/docs/zh-hant/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md b/docs/zh-hant/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md index e30c385375..bd57116245 100644 --- a/docs/zh-hant/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md +++ b/docs/zh-hant/docs/tutorial/dependencies/dependencies-in-path-operation-decorators.md @@ -32,7 +32,7 @@ 在這個範例中我們使用了自訂的（虛構的）標頭 `X-Key` 與 `X-Token`。 -但在實際情況下，當你實作安全機制時，使用整合的 [Security utilities（下一章）](../security/index.md){.internal-link target=_blank} 會獲得更多好處。 +但在實際情況下，當你實作安全機制時，使用整合的 [Security utilities（下一章）](../security/index.md) 會獲得更多好處。 /// @@ -62,7 +62,7 @@ ## 一組路徑操作的依賴 { #dependencies-for-a-group-of-path-operations } -之後在閱讀如何組織較大的應用程式（[較大型應用程式——多個檔案](../../tutorial/bigger-applications.md){.internal-link target=_blank}）時，你會學到如何為一組路徑操作宣告一個共同的 `dependencies` 參數。 +之後在閱讀如何組織較大的應用程式（[較大型應用程式——多個檔案](../../tutorial/bigger-applications.md)）時，你會學到如何為一組路徑操作宣告一個共同的 `dependencies` 參數。 ## 全域依賴 { #global-dependencies } diff --git a/docs/zh-hant/docs/tutorial/dependencies/dependencies-with-yield.md b/docs/zh-hant/docs/tutorial/dependencies/dependencies-with-yield.md index 2339c6ef30..8174dca40b 100644 --- a/docs/zh-hant/docs/tutorial/dependencies/dependencies-with-yield.md +++ b/docs/zh-hant/docs/tutorial/dependencies/dependencies-with-yield.md @@ -14,8 +14,8 @@ FastAPI 支援在完成後執行一些`@contextlib.contextmanager` 或 -* `@contextlib.asynccontextmanager` +* [`@contextlib.contextmanager`](https://docs.python.org/3/library/contextlib.html#contextlib.contextmanager) 或 +* [`@contextlib.asynccontextmanager`](https://docs.python.org/3/library/contextlib.html#contextlib.asynccontextmanager) 都可以作為 **FastAPI** 的相依。 @@ -87,7 +87,7 @@ FastAPI 支援在完成後執行一些Context Managers。 +這能運作，多虧了 Python 的 [Context Managers](https://docs.python.org/3/library/contextlib.html)。 **FastAPI** 在內部使用它們來達成這點。 @@ -111,7 +111,7 @@ FastAPI 支援在完成後執行一些你可以用 `with` 來讀取檔案： +例如，[你可以用 `with` 來讀取檔案](https://docs.python.org/3/tutorial/inputoutput.html#reading-and-writing-files)： ```Python with open("./somefile.txt") as f: @@ -264,7 +264,7 @@ with open("./somefile.txt") as f: /// -在 Python 中，你可以透過建立一個擁有 `__enter__()` 與 `__exit__()` 兩個方法的類別來建立情境管理器。 +在 Python 中，你可以透過[建立一個擁有 `__enter__()` 與 `__exit__()` 兩個方法的類別](https://docs.python.org/3/reference/datamodel.html#context-managers)來建立情境管理器。 你也可以在 **FastAPI** 的含 `yield` 相依中，於相依函式內使用 `with` 或 `async with` 陳述式來使用它們： @@ -274,8 +274,8 @@ with open("./somefile.txt") as f: 建立情境管理器的另一種方式是： -* `@contextlib.contextmanager` 或 -* `@contextlib.asynccontextmanager` +* [`@contextlib.contextmanager`](https://docs.python.org/3/library/contextlib.html#contextlib.contextmanager) 或 +* [`@contextlib.asynccontextmanager`](https://docs.python.org/3/library/contextlib.html#contextlib.asynccontextmanager) 用它們裝飾一個只包含單一 `yield` 的函式。 diff --git a/docs/zh-hant/docs/tutorial/dependencies/global-dependencies.md b/docs/zh-hant/docs/tutorial/dependencies/global-dependencies.md index 3aac1a228b..e73cf935e2 100644 --- a/docs/zh-hant/docs/tutorial/dependencies/global-dependencies.md +++ b/docs/zh-hant/docs/tutorial/dependencies/global-dependencies.md @@ -2,14 +2,14 @@ 在某些類型的應用程式中，你可能想為整個應用程式新增依賴。 -類似於你可以在[路徑操作（path operation）的裝飾器中新增 `dependencies`](dependencies-in-path-operation-decorators.md){.internal-link target=_blank} 的方式，你也可以把它們加到 `FastAPI` 應用程式上。 +類似於你可以在[路徑操作（path operation）的裝飾器中新增 `dependencies`](dependencies-in-path-operation-decorators.md) 的方式，你也可以把它們加到 `FastAPI` 應用程式上。 在這種情況下，它們會套用到應用程式中的所有路徑操作： {* ../../docs_src/dependencies/tutorial012_an_py310.py hl[17] *} -而且，在[將 `dependencies` 新增到路徑操作裝飾器](dependencies-in-path-operation-decorators.md){.internal-link target=_blank} 那一節中的所有概念依然適用，只是這裡是套用到整個應用中的所有路徑操作。 +而且，在[將 `dependencies` 新增到路徑操作裝飾器](dependencies-in-path-operation-decorators.md) 那一節中的所有概念依然適用，只是這裡是套用到整個應用中的所有路徑操作。 ## 路徑操作群組的依賴 { #dependencies-for-groups-of-path-operations } -之後，在閱讀如何組織更大的應用程式（[更大的應用程式 - 多個檔案](../../tutorial/bigger-applications.md){.internal-link target=_blank}）時，可能會有多個檔案，你將會學到如何為一組路徑操作宣告單一的 `dependencies` 參數。 +之後，在閱讀如何組織更大的應用程式（[更大的應用程式 - 多個檔案](../../tutorial/bigger-applications.md)）時，可能會有多個檔案，你將會學到如何為一組路徑操作宣告單一的 `dependencies` 參數。 diff --git a/docs/zh-hant/docs/tutorial/dependencies/index.md b/docs/zh-hant/docs/tutorial/dependencies/index.md index 39c05ab056..86aea50f0a 100644 --- a/docs/zh-hant/docs/tutorial/dependencies/index.md +++ b/docs/zh-hant/docs/tutorial/dependencies/index.md @@ -55,7 +55,7 @@ FastAPI 在 0.95.0 版新增了對 `Annotated` 的支援（並開始建議使用 如果你使用較舊的版本，嘗試使用 `Annotated` 時會出現錯誤。 -在使用 `Annotated` 之前，請先[升級 FastAPI 版本](../../deployment/versions.md#upgrading-the-fastapi-versions){.internal-link target=_blank}到至少 0.95.1。 +在使用 `Annotated` 之前，請先[升級 FastAPI 版本](../../deployment/versions.md#upgrading-the-fastapi-versions)到至少 0.95.1。 /// @@ -150,7 +150,7 @@ commons: Annotated[dict, Depends(common_parameters)] /// note | 注意 -如果你不熟悉，請參考文件中的 [Async: "In a hurry?"](../../async.md#in-a-hurry){.internal-link target=_blank} 一節，瞭解 `async` 與 `await`。 +如果你不熟悉，請參考文件中的 [Async: "In a hurry?"](../../async.md#in-a-hurry) 一節，瞭解 `async` 與 `await`。 /// diff --git a/docs/zh-hant/docs/tutorial/metadata.md b/docs/zh-hant/docs/tutorial/metadata.md index 3243efa89c..720b5d87cb 100644 --- a/docs/zh-hant/docs/tutorial/metadata.md +++ b/docs/zh-hant/docs/tutorial/metadata.md @@ -14,7 +14,7 @@ | `version` | `string` | API 的版本號。這是你自己的應用程式版本，不是 OpenAPI 的版本，例如 `2.5.0`。 | | `terms_of_service` | `str` | 指向 API 服務條款的 URL。若提供，必須是 URL。 | | `contact` | `dict` | 對外公開的 API 聯絡資訊。可包含多個欄位。
contact 欄位
參數型別說明
namestr聯絡人／組織的識別名稱。
urlstr指向聯絡資訊的 URL。必須是 URL 格式。
emailstr聯絡人／組織的電子郵件地址。必須是電子郵件格式。
| -| `license_info` | `dict` | 對外公開的 API 授權資訊。可包含多個欄位。
license_info 欄位
參數型別說明
namestr必填（若有設定 license_info）。API 使用的授權名稱。
identifierstrAPI 的 SPDX 授權表示式。identifier 欄位與 url 欄位互斥。自 OpenAPI 3.1.0、FastAPI 0.99.0 起可用。
urlstrAPI 所採用授權的 URL。必須是 URL 格式。
| +| `license_info` | `dict` | 對外公開的 API 授權資訊。可包含多個欄位。
license_info 欄位
參數型別說明
namestr必填（若有設定 license_info）。API 使用的授權名稱。
identifierstrAPI 的 [SPDX](https://spdx.org/licenses/) 授權表示式。identifier 欄位與 url 欄位互斥。自 OpenAPI 3.1.0、FastAPI 0.99.0 起可用。
urlstrAPI 所採用授權的 URL。必須是 URL 格式。
| 你可以這樣設定它們： @@ -76,7 +76,7 @@ /// info | 資訊 -在［路徑操作設定］中閱讀更多關於標籤的內容：[Path Operation Configuration](path-operation-configuration.md#tags){.internal-link target=_blank}。 +在 [Path Operation Configuration](path-operation-configuration.md#tags) 中閱讀更多關於標籤的內容。 /// diff --git a/docs/zh-hant/docs/tutorial/path-operation-configuration.md b/docs/zh-hant/docs/tutorial/path-operation-configuration.md index 45c101434d..9ca738a98d 100644 --- a/docs/zh-hant/docs/tutorial/path-operation-configuration.md +++ b/docs/zh-hant/docs/tutorial/path-operation-configuration.md @@ -58,7 +58,7 @@ 由於描述常常較長、跨越多行，你可以在函式的 文件字串（docstring） 中宣告「路徑操作」的描述，**FastAPI** 會從那裡讀取。 -你可以在 docstring 中書寫 Markdown，它會被正確解析並顯示（會考慮 docstring 的縮排）。 +你可以在 docstring 中書寫 [Markdown](https://en.wikipedia.org/wiki/Markdown)，它會被正確解析並顯示（會考慮 docstring 的縮排）。 {* ../../docs_src/path_operation_configuration/tutorial004_py310.py hl[17:25] *} diff --git a/docs/zh-hant/docs/tutorial/path-params-numeric-validations.md b/docs/zh-hant/docs/tutorial/path-params-numeric-validations.md index a07f825b05..68eb837e94 100644 --- a/docs/zh-hant/docs/tutorial/path-params-numeric-validations.md +++ b/docs/zh-hant/docs/tutorial/path-params-numeric-validations.md @@ -14,7 +14,7 @@ FastAPI 在 0.95.0 版加入並開始推薦使用 `Annotated`。 如果你使用更舊的版本，嘗試使用 `Annotated` 會出錯。 -請確保在使用 `Annotated` 前，先[升級 FastAPI 版本](../deployment/versions.md#upgrading-the-fastapi-versions){.internal-link target=_blank}到至少 0.95.1。 +請確保在使用 `Annotated` 前，先[升級 FastAPI 版本](../deployment/versions.md#upgrading-the-fastapi-versions)到至少 0.95.1。 /// @@ -122,7 +122,7 @@ Python 不會對這個 `*` 做任何事，但它會知道後續的所有參數 ## 小結 { #recap } -使用 `Query`、`Path`（以及你尚未看到的其他類別）時，你可以像在[查詢參數與字串驗證](query-params-str-validations.md){.internal-link target=_blank}中一樣，宣告中繼資料與字串驗證。 +使用 `Query`、`Path`（以及你尚未看到的其他類別）時，你可以像在[查詢參數與字串驗證](query-params-str-validations.md)中一樣，宣告中繼資料與字串驗證。 你也可以宣告數值驗證： diff --git a/docs/zh-hant/docs/tutorial/query-params.md b/docs/zh-hant/docs/tutorial/query-params.md index f21bf40506..89c0834565 100644 --- a/docs/zh-hant/docs/tutorial/query-params.md +++ b/docs/zh-hant/docs/tutorial/query-params.md @@ -182,6 +182,6 @@ http://127.0.0.1:8000/items/foo-item?needy=sooooneedy /// tip | 提示 -你也可以像在[路徑參數](path-params.md#predefined-values){.internal-link target=_blank}中一樣使用 `Enum`。 +你也可以像在[路徑參數](path-params.md#predefined-values)中一樣使用 `Enum`。 /// diff --git a/docs/zh-hant/docs/tutorial/request-files.md b/docs/zh-hant/docs/tutorial/request-files.md index c8606a3f23..4e20544ea4 100644 --- a/docs/zh-hant/docs/tutorial/request-files.md +++ b/docs/zh-hant/docs/tutorial/request-files.md @@ -4,9 +4,9 @@ /// info -若要接收上傳的檔案，請先安裝 `python-multipart`。 +若要接收上傳的檔案，請先安裝 [`python-multipart`](https://github.com/Kludex/python-multipart)。 -請先建立並啟用一個[虛擬環境](../virtual-environments.md){.internal-link target=_blank}，然後安裝，例如： +請先建立並啟用一個[虛擬環境](../virtual-environments.md)，然後安裝，例如： ```console $ pip install python-multipart @@ -63,8 +63,8 @@ $ pip install python-multipart * 檔案在記憶體中保存到某個大小上限，超過上限後會存到磁碟。 * 因此適合處理大型檔案（例如圖片、影片、大型二進位檔等），而不會耗盡記憶體。 * 你可以取得上傳檔案的中繼資料。 -* 它提供一個類檔案的 `async` 介面。 -* 它會提供實際的 Python `SpooledTemporaryFile` 物件，你可以直接傳給需要類檔案物件的其他函式或函式庫。 +* 它提供一個[file-like](https://docs.python.org/3/glossary.html#term-file-like-object) 的 `async` 介面。 +* 它會提供實際的 Python [`SpooledTemporaryFile`](https://docs.python.org/3/library/tempfile.html#tempfile.SpooledTemporaryFile) 物件，你可以直接傳給需要類檔案物件的其他函式或函式庫。 ### `UploadFile` { #uploadfile } @@ -72,13 +72,13 @@ $ pip install python-multipart * `filename`：一個 `str`，為上傳的原始檔名（例如 `myimage.jpg`）。 * `content_type`：一個 `str`，為內容類型（MIME type / media type）（例如 `image/jpeg`）。 -* `file`：一個 `SpooledTemporaryFile`（類檔案物件）。這是真正的 Python 檔案物件，你可以直接傳給期待「類檔案」物件的其他函式或函式庫。 +* `file`：一個 [`SpooledTemporaryFile`](https://docs.python.org/3/library/tempfile.html#tempfile.SpooledTemporaryFile)（一個[file-like](https://docs.python.org/3/glossary.html#term-file-like-object) 物件）。這是真正的 Python 檔案物件，你可以直接傳給期待「類檔案」物件的其他函式或函式庫。 `UploadFile` 有以下 `async` 方法。它們底層會呼叫對應的檔案方法（使用內部的 `SpooledTemporaryFile`）。 -* `write(data)`：將 `data`（`str` 或 `bytes`）寫入檔案。 -* `read(size)`：讀取檔案的 `size`（`int`）個位元組/字元。 -* `seek(offset)`：移動到檔案中的位元組位置 `offset`（`int`）。 +* `write(data)`：將 `data` (`str` 或 `bytes`) 寫入檔案。 +* `read(size)`：讀取檔案的 `size` (`int`) 個位元組/字元。 +* `seek(offset)`：移動到檔案中的位元組位置 `offset` (`int`)。 * 例如，`await myfile.seek(0)` 會移到檔案開頭。 * 當你已經執行過 `await myfile.read()`，之後需要再次讀取內容時特別有用。 * `close()`：關閉檔案。 @@ -121,7 +121,7 @@ HTML 表單（`
`）送到伺服器的資料通常使用一種「特 但當表單包含檔案時，會使用 `multipart/form-data` 編碼。若你使用 `File`，**FastAPI** 會知道要從請求本文的正確部分取得檔案。 -若想進一步了解這些編碼與表單欄位，請參考 MDN Web Docs 的 POST。 +若想進一步了解這些編碼與表單欄位，請參考 [MDN web docs 的 `POST`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/POST)。 /// diff --git a/docs/zh-hant/docs/tutorial/request-form-models.md b/docs/zh-hant/docs/tutorial/request-form-models.md index 8cf4a7c5e8..f8a0e8c6c5 100644 --- a/docs/zh-hant/docs/tutorial/request-form-models.md +++ b/docs/zh-hant/docs/tutorial/request-form-models.md @@ -4,9 +4,9 @@ /// info | 說明 -要使用表單，首先安裝 `python-multipart`。 +要使用表單，首先安裝 [`python-multipart`](https://github.com/Kludex/python-multipart)。 -請先建立[虛擬環境](../virtual-environments.md){.internal-link target=_blank}、啟用後再安裝，例如： +請先建立[虛擬環境](../virtual-environments.md)、啟用後再安裝，例如： ```console $ pip install python-multipart diff --git a/docs/zh-hant/docs/tutorial/request-forms-and-files.md b/docs/zh-hant/docs/tutorial/request-forms-and-files.md index 6dcc1c260f..c508bf7f7b 100644 --- a/docs/zh-hant/docs/tutorial/request-forms-and-files.md +++ b/docs/zh-hant/docs/tutorial/request-forms-and-files.md @@ -4,9 +4,9 @@ /// info -要接收上傳的檔案與/或表單資料，請先安裝 `python-multipart`。 +要接收上傳的檔案與/或表單資料，請先安裝 [`python-multipart`](https://github.com/Kludex/python-multipart)。 -請先建立並啟用一個 [虛擬環境](../virtual-environments.md){.internal-link target=_blank}，然後再安裝，例如： +請先建立並啟用一個 [虛擬環境](../virtual-environments.md)，然後再安裝，例如： ```console $ pip install python-multipart diff --git a/docs/zh-hant/docs/tutorial/schema-extra-example.md b/docs/zh-hant/docs/tutorial/schema-extra-example.md index 661938ac26..1c2caef85b 100644 --- a/docs/zh-hant/docs/tutorial/schema-extra-example.md +++ b/docs/zh-hant/docs/tutorial/schema-extra-example.md @@ -12,7 +12,7 @@ 這些額外資訊會原封不動加入該模型輸出的 JSON Schema，並且會用在 API 文件裡。 -你可以使用屬性 `model_config`（接收一個 `dict`），詳見 Pydantic 文件：Configuration。 +你可以使用屬性 `model_config`（接收一個 `dict`），詳見 [Pydantic 文件：Configuration](https://docs.pydantic.dev/latest/api/config/)。 你可以將 `"json_schema_extra"` 設為一個 `dict`，其中包含你想在產生的 JSON Schema 中出現的任何額外資料，包括 `examples`。 @@ -145,12 +145,12 @@ OpenAPI 3.1.0（自 FastAPI 0.99.0 起使用）新增了對 `examples` 的支援 OpenAPI 也在規範的其他部分新增了 `example` 與 `examples` 欄位： -* `Parameter Object`（規範），對應到 FastAPI 的： +* [`Parameter Object`（規範）](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#parameter-object)，對應到 FastAPI 的： * `Path()` * `Query()` * `Header()` * `Cookie()` -* `Request Body Object` 中的 `content` 欄位裡的 `Media Type Object`（規範），對應到 FastAPI 的： +* [`Request Body Object` 中的 `content` 欄位裡的 `Media Type Object`（規範）](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#media-type-object)，對應到 FastAPI 的： * `Body()` * `File()` * `Form()` @@ -163,7 +163,7 @@ OpenAPI 也在規範的其他部分新增了 `example` 與 `examples` 欄位： ### JSON Schema 的 `examples` 欄位 { #json-schemas-examples-field } -後來 JSON Schema 在新版本規範中新增了 `examples` 欄位。 +後來 JSON Schema 在新版本規範中新增了 [`examples`](https://json-schema.org/draft/2019-09/json-schema-validation.html#rfc.section.9.5) 欄位。 接著新的 OpenAPI 3.1.0 以最新版本（JSON Schema 2020-12）為基礎，該版本就包含這個新的 `examples` 欄位。 diff --git a/docs/zh-hant/docs/tutorial/security/first-steps.md b/docs/zh-hant/docs/tutorial/security/first-steps.md index 109f59a37a..7f12ec1a3a 100644 --- a/docs/zh-hant/docs/tutorial/security/first-steps.md +++ b/docs/zh-hant/docs/tutorial/security/first-steps.md @@ -26,11 +26,11 @@ /// info -當你使用 `pip install "fastapi[standard]"` 指令安裝時，`python-multipart` 套件會隨 FastAPI 自動安裝。 +當你使用 `pip install "fastapi[standard]"` 指令安裝時，[`python-multipart`](https://github.com/Kludex/python-multipart) 套件會隨 FastAPI 自動安裝。 不過若只執行 `pip install fastapi`，預設不會包含 `python-multipart`。 -若要手動安裝，請先建立並啟用一個[虛擬環境](../../virtual-environments.md){.internal-link target=_blank}，接著執行： +若要手動安裝，請先建立並啟用一個[虛擬環境](../../virtual-environments.md)，接著執行： ```console $ pip install python-multipart @@ -45,7 +45,7 @@ $ pip install python-multipart
```console -$ fastapi dev main.py +$ fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -54,7 +54,7 @@ $ fastapi dev main.py ## 檢查 { #check-it } -開啟互動式文件：http://127.0.0.1:8000/docs。 +開啟互動式文件：[http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs)。 你會看到類似這樣： @@ -140,7 +140,7 @@ FastAPI 提供多層抽象的工具來實作這些安全機制。 由於使用了相對 URL，若你的 API 位於 `https://example.com/`，那它會指向 `https://example.com/token`；但若你的 API 位於 `https://example.com/api/v1/`，那它會指向 `https://example.com/api/v1/token`。 -使用相對 URL 很重要，能確保你的應用在像是[在 Proxy 後方](../../advanced/behind-a-proxy.md){.internal-link target=_blank}這類進階情境中仍能正常運作。 +使用相對 URL 很重要，能確保你的應用在像是[在 Proxy 後方](../../advanced/behind-a-proxy.md)這類進階情境中仍能正常運作。 /// diff --git a/docs/zh-hant/docs/tutorial/security/oauth2-jwt.md b/docs/zh-hant/docs/tutorial/security/oauth2-jwt.md index d6761a0051..abd920ce6f 100644 --- a/docs/zh-hant/docs/tutorial/security/oauth2-jwt.md +++ b/docs/zh-hant/docs/tutorial/security/oauth2-jwt.md @@ -24,13 +24,13 @@ eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4 一週後，權杖會過期，使用者就不再被授權，需要再次登入以取得新的權杖。而如果使用者（或第三方）試圖修改權杖來改變有效期，你也能發現，因為簽名不會相符。 -如果你想玩玩看 JWT 權杖並了解其運作，請參考 https://jwt.io。 +如果你想玩玩看 JWT 權杖並了解其運作，請參考 [https://jwt.io](https://jwt.io/)。 ## 安裝 `PyJWT` { #install-pyjwt } 我們需要安裝 `PyJWT` 才能在 Python 中產生與驗證 JWT 權杖。 -請先建立並啟用一個[虛擬環境](../../virtual-environments.md){.internal-link target=_blank}，然後安裝 `pyjwt`： +請先建立並啟用一個[虛擬環境](../../virtual-environments.md)，然後安裝 `pyjwt`：
@@ -46,7 +46,7 @@ $ pip install pyjwt 如果你打算使用像 RSA 或 ECDSA 這類的數位簽章演算法，應該安裝帶有加密函式庫相依的 `pyjwt[crypto]`。 -更多內容可參考 PyJWT 安裝文件。 +更多內容可參考 [PyJWT 安裝文件](https://pyjwt.readthedocs.io/en/latest/installation.html)。 /// @@ -72,7 +72,7 @@ pwdlib 是一個很棒的 Python 套件，用來處理密碼雜湊。 建議使用的演算法是「Argon2」。 -請先建立並啟用一個[虛擬環境](../../virtual-environments.md){.internal-link target=_blank}，然後以 Argon2 支援安裝 pwdlib： +請先建立並啟用一個[虛擬環境](../../virtual-environments.md)，然後以 Argon2 支援安裝 pwdlib：
@@ -200,7 +200,7 @@ JWT 除了用來識別使用者並允許他直接對你的 API 執行操作外 ## 試試看 { #check-it } -啟動伺服器並前往文件頁：http://127.0.0.1:8000/docs。 +啟動伺服器並前往文件頁：[http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs)。 你會看到這樣的介面： diff --git a/docs/zh-hant/docs/tutorial/security/simple-oauth2.md b/docs/zh-hant/docs/tutorial/security/simple-oauth2.md index 3b9aae3416..5b0b13ec3c 100644 --- a/docs/zh-hant/docs/tutorial/security/simple-oauth2.md +++ b/docs/zh-hant/docs/tutorial/security/simple-oauth2.md @@ -216,7 +216,7 @@ UserInDB( ## 實際操作看看 { #see-it-in-action } -開啟互動式文件：http://127.0.0.1:8000/docs。 +開啟互動式文件：[http://127.0.0.1:8000/docs](http://127.0.0.1:8000/docs)。 ### 驗證身分 { #authenticate } diff --git a/docs/zh-hant/docs/tutorial/sql-databases.md b/docs/zh-hant/docs/tutorial/sql-databases.md index 930dc4e8a5..a37e164321 100644 --- a/docs/zh-hant/docs/tutorial/sql-databases.md +++ b/docs/zh-hant/docs/tutorial/sql-databases.md @@ -2,9 +2,9 @@ FastAPI 不強制你使用 SQL（關聯式）資料庫。你可以使用任何你想要的資料庫。 -這裡我們會用 SQLModel 作為範例。 +這裡我們會用 [SQLModel](https://sqlmodel.tiangolo.com/) 作為範例。 -SQLModel 建立在 SQLAlchemy 與 Pydantic 之上。它由 FastAPI 的作者開發，非常適合需要使用 SQL 資料庫的 FastAPI 應用。 +SQLModel 建立在 [SQLAlchemy](https://www.sqlalchemy.org/) 與 Pydantic 之上。它由 FastAPI 的作者開發，非常適合需要使用 SQL 資料庫的 FastAPI 應用。 /// tip | 提示 @@ -26,15 +26,15 @@ SQLModel 建立在 https://github.com/fastapi/full-stack-fastapi-template +有一個包含 FastAPI 與 PostgreSQL 的官方專案腳手架，還有前端與更多工具：[https://github.com/fastapi/full-stack-fastapi-template](https://github.com/fastapi/full-stack-fastapi-template) /// -這是一份非常簡短的教學，如果你想更全面學習資料庫、SQL，或更進階的功能，請參考 SQLModel 文件。 +這是一份非常簡短的教學，如果你想更全面學習資料庫、SQL，或更進階的功能，請參考 [SQLModel 文件](https://sqlmodel.tiangolo.com/)。 ## 安裝 `SQLModel` { #install-sqlmodel } -首先，請先建立你的[虛擬環境](../virtual-environments.md){.internal-link target=_blank}、啟用它，然後安裝 `sqlmodel`： +首先，請先建立你的[虛擬環境](../virtual-environments.md)、啟用它，然後安裝 `sqlmodel`：
@@ -65,7 +65,7 @@ $ pip install sqlmodel * `Field(primary_key=True)` 告訴 SQLModel，`id` 是 SQL 資料庫中的「主鍵」。 （你可以在 SQLModel 文件中進一步了解 SQL 主鍵） - 注意：我們在主鍵欄位使用 `int | None`，這樣在 Python 程式碼中我們可以「在沒有 `id` 的情況下建立物件」（`id=None`），假設資料庫在儲存時會「自動產生」。SQLModel 瞭解資料庫會提供 `id`，並且在資料庫綱要中「將該欄位定義為非空的 `INTEGER`」。詳情請見 SQLModel 文件：主鍵。 + 注意：我們在主鍵欄位使用 `int | None`，這樣在 Python 程式碼中我們可以「在沒有 `id` 的情況下建立物件」（`id=None`），假設資料庫在儲存時會「自動產生」。SQLModel 瞭解資料庫會提供 `id`，並且在資料庫綱要中「將該欄位定義為非空的 `INTEGER`」。詳情請見 [SQLModel 文件：主鍵](https://sqlmodel.tiangolo.com/tutorial/create-db-and-table/#primary-key-id)。 * `Field(index=True)` 告訴 SQLModel 應為此欄位建立「SQL 索引」，以便在用此欄位過濾讀取資料時更快查詢。 @@ -111,7 +111,7 @@ SQLModel 的 `engine`（底層實際上是 SQLAlchemy 的 `engine`）是用來 /// tip | 提示 -SQLModel 之後會提供包裝 Alembic 的遷移工具，但目前你可以直接使用 Alembic。 +SQLModel 之後會提供包裝 Alembic 的遷移工具，但目前你可以直接使用 [Alembic](https://alembic.sqlalchemy.org/en/latest/)。 /// @@ -152,7 +152,7 @@ SQLModel 之後會提供包裝 Alembic 的遷移工具，但目前你可以直
```console -$ fastapi dev main.py +$ fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -337,7 +337,7 @@ $ fastapi dev main.py
```console -$ fastapi dev main.py +$ fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -352,6 +352,6 @@ $ fastapi dev main.py ## 總結 { #recap } -你可以使用 SQLModel 與 SQL 資料庫互動，並用「資料模型」與「資料表模型」讓程式碼更簡潔。 +你可以使用 [SQLModel](https://sqlmodel.tiangolo.com/) 與 SQL 資料庫互動，並用「資料模型」與「資料表模型」讓程式碼更簡潔。 -你可以在 SQLModel 文件學到更多內容，這裡還有一份更長的 使用 SQLModel 與 FastAPI 的教學。🚀 +你可以在 SQLModel 文件學到更多內容，這裡還有一份更長的 [使用 SQLModel 與 FastAPI 的教學](https://sqlmodel.tiangolo.com/tutorial/fastapi/)。🚀 diff --git a/docs/zh-hant/docs/tutorial/static-files.md b/docs/zh-hant/docs/tutorial/static-files.md index 06b6176760..1b9e92a1c9 100644 --- a/docs/zh-hant/docs/tutorial/static-files.md +++ b/docs/zh-hant/docs/tutorial/static-files.md @@ -23,7 +23,7 @@ 這與使用 `APIRouter` 不同，因為被掛載的應用是完全獨立的。主應用的 OpenAPI 與文件不會包含掛載應用的任何內容，等等。 -你可以在[進階使用者指南](../advanced/index.md){.internal-link target=_blank}中閱讀更多相關內容。 +你可以在[進階使用者指南](../advanced/index.md)中閱讀更多相關內容。 ## 細節 { #details } @@ -37,4 +37,4 @@ ## 更多資訊 { #more-info } -如需更多細節與選項，請參考 Starlette 關於靜態檔案的文件。 +如需更多細節與選項，請參考 [Starlette 關於靜態檔案的文件](https://www.starlette.dev/staticfiles/)。 diff --git a/docs/zh-hant/docs/tutorial/testing.md b/docs/zh-hant/docs/tutorial/testing.md index 0d49fd5d7b..f6bef5d962 100644 --- a/docs/zh-hant/docs/tutorial/testing.md +++ b/docs/zh-hant/docs/tutorial/testing.md @@ -1,18 +1,18 @@ # 測試 { #testing } -多虧了 Starlette，測試 **FastAPI** 應用既簡單又好用。 +多虧了 [Starlette](https://www.starlette.dev/testclient/)，測試 **FastAPI** 應用既簡單又好用。 -它是基於 HTTPX 打造，而 HTTPX 的設計又參考了 Requests，所以用起來非常熟悉、直覺。 +它是基於 [HTTPX](https://www.python-httpx.org) 打造，而 HTTPX 的設計又參考了 Requests，所以用起來非常熟悉、直覺。 -借助它，你可以直接用 pytest 來測試 **FastAPI**。 +借助它，你可以直接用 [pytest](https://docs.pytest.org/) 來測試 **FastAPI**。 ## 使用 `TestClient` { #using-testclient } /// info -要使用 `TestClient`，請先安裝 `httpx`。 +要使用 `TestClient`，請先安裝 [`httpx`](https://www.python-httpx.org)。 -請先建立並啟用一個[虛擬環境](../virtual-environments.md){.internal-link target=_blank}，然後安裝，例如： +請先建立並啟用一個[虛擬環境](../virtual-environments.md)，然後安裝，例如： ```console $ pip install httpx @@ -52,7 +52,7 @@ $ pip install httpx /// tip -如果你想在測試中呼叫其他 `async` 函式，而不只是對 FastAPI 應用發送請求（例如非同步的資料庫函式），請參考進階教學中的[非同步測試](../advanced/async-tests.md){.internal-link target=_blank}。 +如果你想在測試中呼叫其他 `async` 函式，而不只是對 FastAPI 應用發送請求（例如非同步的資料庫函式），請參考進階教學中的[非同步測試](../advanced/async-tests.md)。 /// @@ -64,7 +64,7 @@ $ pip install httpx ### **FastAPI** 應用檔案 { #fastapi-app-file } -假設你的檔案結構如[更大型的應用](bigger-applications.md){.internal-link target=_blank}所述： +假設你的檔案結構如[更大型的應用](bigger-applications.md)所述： ``` . @@ -142,13 +142,13 @@ $ pip install httpx * 要傳遞標頭（headers），在 `headers` 參數中放一個 `dict`。 * 對於 Cookie（cookies），在 `cookies` 參數中放一個 `dict`。 -關於如何把資料傳給後端（使用 `httpx` 或 `TestClient`），更多資訊請參考 HTTPX 文件。 +關於如何把資料傳給後端（使用 `httpx` 或 `TestClient`），更多資訊請參考 [HTTPX 文件](https://www.python-httpx.org)。 /// info 請注意，`TestClient` 接收的是可轉為 JSON 的資料，而不是 Pydantic models。 -如果你的測試裡有一個 Pydantic model，並想在測試時把它的資料送給應用，你可以使用[JSON 相容編碼器](encoder.md){.internal-link target=_blank}中介紹的 `jsonable_encoder`。 +如果你的測試裡有一個 Pydantic model，並想在測試時把它的資料送給應用，你可以使用[JSON 相容編碼器](encoder.md)中介紹的 `jsonable_encoder`。 /// @@ -156,7 +156,7 @@ $ pip install httpx 接下來，你只需要安裝 `pytest`。 -請先建立並啟用一個[虛擬環境](../virtual-environments.md){.internal-link target=_blank}，然後安裝，例如： +請先建立並啟用一個[虛擬環境](../virtual-environments.md)，然後安裝，例如：