diff --git a/docs/zh-hant/docs/advanced/additional-responses.md b/docs/zh-hant/docs/advanced/additional-responses.md index 552ce2e235..9bcfd7046a 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 物件](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`。 +* [OpenAPI Responses 物件](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#responses-object)，其中包含 `Response Object`。 +* [OpenAPI Response 物件](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#response-object)，你可以把這裡的任何內容直接放到 `responses` 參數內各個回應中。包含 `description`、`headers`、`content`（在其中宣告不同的媒體型別與 JSON Schemas）、以及 `links`。 diff --git a/docs/zh-hant/docs/advanced/async-tests.md b/docs/zh-hant/docs/advanced/async-tests.md index 639c42b7db..6ea583fa33 100644 --- a/docs/zh-hant/docs/advanced/async-tests.md +++ b/docs/zh-hant/docs/advanced/async-tests.md @@ -1,6 +1,6 @@ # 非同步測試 { #async-tests } -你已經看過如何使用提供的 `TestClient` 來測試你的 FastAPI 應用。到目前為止，你只看到如何撰寫同步測試，沒有使用 `async` 函式。 +你已經看過如何使用提供的 `TestClient` 來測試你的 **FastAPI** 應用。到目前為止，你只看到如何撰寫同步測試，沒有使用 `async` 函式。 在測試中能使用非同步函式會很有用，例如當你以非同步方式查詢資料庫時。想像你想測試發送請求到 FastAPI 應用，然後在使用非同步資料庫函式庫時，驗證後端是否成功把正確資料寫入資料庫。 @@ -12,7 +12,7 @@ ## HTTPX { #httpx } -即使你的 FastAPI 應用使用一般的 `def` 函式而非 `async def`，它在底層仍然是個 `async` 應用。 +即使你的 **FastAPI** 應用使用一般的 `def` 函式而非 `async def`，它在底層仍然是個 `async` 應用。 `TestClient` 在內部做了一些魔法，讓我們能在一般的 `def` 測試函式中，使用標準 pytest 來呼叫非同步的 FastAPI 應用。但當我們在非同步函式中使用它時，這個魔法就不再奏效了。也就是說，當以非同步方式執行測試時，就不能在測試函式內使用 `TestClient`。 @@ -40,12 +40,12 @@ ## 執行 { #run-it } -如常執行測試： +你可以像往常一樣透過以下方式執行測試：
```console -$ pytest +$ uv run pytest ---> 100% ``` @@ -74,7 +74,7 @@ $ pytest response = client.get('/') ``` -也就是先前用 `TestClient` 發送請求時所用的寫法。 +...也就是我們先前用 `TestClient` 發送請求時所用的寫法。 /// tip @@ -90,7 +90,7 @@ response = client.get('/') ## 其他非同步函式呼叫 { #other-asynchronous-function-calls } -由於測試函式現在是非同步的，你也可以在測試中呼叫（並 `await`）其他 `async` 函式，和在程式碼其他地方一樣。 +由於測試函式現在是非同步的，除了在測試中向你的 FastAPI 應用發送請求之外，你也可以呼叫（並 `await`）其他 `async` 函式，就像在程式碼其他地方呼叫它們一樣。 /// tip diff --git a/docs/zh-hant/docs/advanced/behind-a-proxy.md b/docs/zh-hant/docs/advanced/behind-a-proxy.md index a7f4b83b33..feb3bab74a 100644 --- a/docs/zh-hant/docs/advanced/behind-a-proxy.md +++ b/docs/zh-hant/docs/advanced/behind-a-proxy.md @@ -33,7 +33,7 @@
```console -$ fastapi run --forwarded-allow-ips="*" +$ uv run fastapi run --forwarded-allow-ips="*" INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -170,7 +170,7 @@ IP `0.0.0.0` 通常用來表示程式在該機器／伺服器上的所有可用
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -200,7 +200,7 @@ ASGI 規格針對這種用例定義了 `root_path`。
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -253,7 +253,7 @@ Uvicorn 會預期代理以 `http://127.0.0.1:8000/app` 來存取 Uvicorn，而 你可以很容易地用 [Traefik](https://docs.traefik.io/) 在本機跑一個「移除路徑前綴」的測試。 -[下載 Traefik](https://github.com/containous/traefik/releases)，它是一個單一的執行檔，你可以解壓縮後直接在終端機執行。 +[下載 Traefik](https://github.com/traefik/traefik/releases)，它是一個單一的執行檔，你可以解壓縮後直接在終端機執行。 然後建立一個 `traefik.toml` 檔案，內容如下： @@ -321,7 +321,7 @@ INFO[0000] Configuration loaded from file: /home/user/awesomeapi/traefik.toml
```console -$ fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 +$ uv run fastapi run main.py --forwarded-allow-ips="*" --root-path /api/v1 INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/zh-hant/docs/advanced/dataclasses.md b/docs/zh-hant/docs/advanced/dataclasses.md index 64ba7dde2b..4866046db1 100644 --- a/docs/zh-hant/docs/advanced/dataclasses.md +++ b/docs/zh-hant/docs/advanced/dataclasses.md @@ -6,15 +6,15 @@ FastAPI 建立在 **Pydantic** 之上，我之前示範過如何使用 Pydantic {* ../../docs_src/dataclasses_/tutorial001_py310.py hl[1,6:11,18:19] *} -這之所以可行，要感謝 **Pydantic**，因為它 [內建支援 `dataclasses`](https://docs.pydantic.dev/latest/concepts/dataclasses/#use-of-stdlib-dataclasses-with-basemodel)。 +這之所以可行，要感謝 **Pydantic**，因為它 [內建支援 `dataclasses`](https://pydantic.dev/docs/validation/latest/concepts/dataclasses/#usage-of-stdlib-dataclasses-with-basemodel)。 所以，即使上面的程式碼沒有明確使用 Pydantic，FastAPI 仍會使用 Pydantic 將那些標準的 dataclass 轉換為 Pydantic 版本的 dataclass。 而且當然一樣支援： -- 資料驗證 -- 資料序列化 -- 資料文件化等 +* 資料驗證 +* 資料序列化 +* 資料文件化等 它的運作方式與 Pydantic 模型相同；實際上，底層就是透過 Pydantic 達成的。 @@ -51,26 +51,34 @@ FastAPI 建立在 **Pydantic** 之上，我之前示範過如何使用 Pydantic {* ../../docs_src/dataclasses_/tutorial003_py310.py hl[1,4,7:10,13:16,22:24,27] *} 1. 我們仍然從標準的 `dataclasses` 匯入 `field`。 + 2. `pydantic.dataclasses` 是 `dataclasses` 的可直接替換版本。 + 3. `Author` dataclass 內含一個 `Item` dataclass 的清單。 + 4. `Author` dataclass 被用作 `response_model` 參數。 + 5. 你可以將其他標準型別註記與 dataclass 一起用作請求本文。 - 在此例中，它是 `Item` dataclass 的清單。 + 在此例中，它是 `Item` dataclass 的清單。 + 6. 這裡我們回傳一個字典，其中的 `items` 是一個 dataclass 清單。 - FastAPI 仍能將資料序列化為 JSON。 + FastAPI 仍能將資料序列化為 JSON。 + 7. 這裡 `response_model` 使用的是「`Author` dataclass 的清單」這種型別註記。 - 同樣地，你可以把 `dataclasses` 與標準型別註記組合使用。 + 同樣地，你可以把 `dataclasses` 與標準型別註記組合使用。 + 8. 注意這個*路徑操作函式*使用的是一般的 `def` 而非 `async def`。 - 一如往常，在 FastAPI 中你可以視需要混用 `def` 與 `async def`。 + 一如往常，在 FastAPI 中你可以視需要混用 `def` 與 `async def`。 + + 如果需要複習何時用哪個，請參考文件中關於 [`async` 與 `await`](../async.md#in-a-hurry) 的章節 _「趕時間？」_。 - 如果需要複習何時用哪個，請參考文件中關於 [`async` 與 `await`](../async.md#in-a-hurry) 的章節 _「趕時間？」_。 9. 這個*路徑操作函式*回傳的不是 dataclass（雖然也可以），而是一個包含內部資料的字典清單。 - FastAPI 會使用 `response_model` 參數（其中包含 dataclass）來轉換回應。 + FastAPI 會使用 `response_model` 參數（其中包含 dataclass）來轉換回應。 你可以把 `dataclasses` 與其他型別註記以多種方式組合，形成複雜的資料結構。 @@ -80,7 +88,7 @@ FastAPI 建立在 **Pydantic** 之上，我之前示範過如何使用 Pydantic 你也可以將 `dataclasses` 與其他 Pydantic 模型結合、從它們繼承、把它們包含進你的自訂模型等。 -想了解更多，請參考 [Pydantic 關於 dataclasses 的文件](https://docs.pydantic.dev/latest/concepts/dataclasses/)。 +想了解更多，請參考 [Pydantic 關於 dataclasses 的文件](https://pydantic.dev/docs/validation/latest/concepts/dataclasses/)。 ## 版本 { #version } diff --git a/docs/zh-hant/docs/advanced/events.md b/docs/zh-hant/docs/advanced/events.md index e132d9f3dd..c6dda915bf 100644 --- a/docs/zh-hant/docs/advanced/events.md +++ b/docs/zh-hant/docs/advanced/events.md @@ -155,7 +155,7 @@ async with lifespan(app): /// note -你可以在 [Starlette 的 Lifespan 文件](https://www.starlette.dev/lifespan/) 讀到更多關於 Starlette `lifespan` 處理器的資訊。 +你可以在 [Starlette 的 Lifespan 文件](https://starlette.dev/lifespan/) 讀到更多關於 Starlette `lifespan` 處理器的資訊。 也包含如何處理可在程式其他區域使用的 lifespan 狀態。 diff --git a/docs/zh-hant/docs/advanced/generate-clients.md b/docs/zh-hant/docs/advanced/generate-clients.md index cc7a6865a9..4c2846b996 100644 --- a/docs/zh-hant/docs/advanced/generate-clients.md +++ b/docs/zh-hant/docs/advanced/generate-clients.md @@ -12,7 +12,7 @@ 針對 **TypeScript 用戶端**，[Hey API](https://heyapi.dev/) 是專門打造的解決方案，為 TypeScript 生態系提供最佳化的體驗。 -你可以在 [OpenAPI.Tools](https://openapi.tools/#sdk) 找到更多 SDK 產生器。 +你可以在 [OpenAPI.Tools](https://openapi.tools/categories/sdk-generators) 找到更多 SDK 產生器。 /// tip @@ -179,9 +179,9 @@ npx @hey-api/openapi-ts -i ./openapi.json -o src/client 使用自動產生的用戶端時，你會得到以下項目的**自動完成**： -* 方法 -* Body 中的請求有效載荷、查詢參數等 -* 回應的有效載荷 +* 方法。 +* Body 中的請求有效載荷、查詢參數等。 +* 回應的有效載荷。 你也會對所有內容獲得**行內錯誤**提示。 diff --git a/docs/zh-hant/docs/advanced/middleware.md b/docs/zh-hant/docs/advanced/middleware.md index d8a53394c7..a11d4ebbe0 100644 --- a/docs/zh-hant/docs/advanced/middleware.md +++ b/docs/zh-hant/docs/advanced/middleware.md @@ -91,7 +91,7 @@ app.add_middleware(UnicornMiddleware, some_config="rainbow") 例如： -- [Uvicorn 的 `ProxyHeadersMiddleware`](https://github.com/encode/uvicorn/blob/master/uvicorn/middleware/proxy_headers.py) +- [Uvicorn 的 `ProxyHeadersMiddleware`](https://github.com/Kludex/uvicorn/blob/main/uvicorn/middleware/proxy_headers.py) - [MessagePack](https://github.com/florimondmanca/msgpack-asgi) -想瞭解更多可用的中介軟體，請參考 [Starlette 的中介軟體文件](https://www.starlette.dev/middleware/) 與 [ASGI 精選清單](https://github.com/florimondmanca/awesome-asgi)。 +想瞭解更多可用的中介軟體，請參考 [Starlette 的中介軟體文件](https://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 6ab869accb..a1ea394059 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](https://docs.pydantic.dev/latest/api/networks/) 型別。 +`callback_url` 查詢參數使用的是 Pydantic 的 [Url](https://pydantic.dev/docs/validation/latest/api/pydantic/networks/) 型別。 /// @@ -106,11 +106,11 @@ httpx.post(callback_url, json={"description": "Invoice paid", "paid": True}) 和一般「路徑操作」相比有兩個主要差異： * 不需要任何實際程式碼，因為你的應用永遠不會呼叫這段程式。它只用來文件化「外部 API」。因此函式可以只有 `pass`。 -* 「路徑」可以包含一個 [OpenAPI 3 表達式](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression)（見下文），可使用參數與原始送到「你的 API」的請求中的部分欄位。 +* 「路徑」可以包含一個 [OpenAPI 3 表達式](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#key-expression)（見下文），可使用參數與原始送到「你的 API」的請求中的部分欄位。 ### 回呼路徑表達式 { #the-callback-path-expression } -回呼的「路徑」可以包含一個 [OpenAPI 3 表達式](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md#key-expression)，能引用原本送到「你的 API」的請求中的部分內容。 +回呼的「路徑」可以包含一個 [OpenAPI 3 表達式](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#key-expression)，能引用原本送到「你的 API」的請求中的部分內容。 在這個例子中，它是一個 `str`： diff --git a/docs/zh-hant/docs/advanced/response-cookies.md b/docs/zh-hant/docs/advanced/response-cookies.md index b275523300..ef471aa88f 100644 --- a/docs/zh-hant/docs/advanced/response-cookies.md +++ b/docs/zh-hant/docs/advanced/response-cookies.md @@ -48,4 +48,4 @@ /// -想查看所有可用的參數與選項，請參閱 [Starlette 文件](https://www.starlette.dev/responses/#set-cookie)。 +想查看所有可用的參數與選項，請參閱 [Starlette 文件](https://starlette.dev/responses/#set-cookie)。 diff --git a/docs/zh-hant/docs/advanced/response-headers.md b/docs/zh-hant/docs/advanced/response-headers.md index 002fb0e547..9612e6b5e4 100644 --- a/docs/zh-hant/docs/advanced/response-headers.md +++ b/docs/zh-hant/docs/advanced/response-headers.md @@ -38,4 +38,4 @@ 請記住，專有的自訂標頭可以[使用 `X-` 前綴](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers)來新增。 -但如果你有自訂標頭並希望瀏覽器端的客戶端能看見它們，你需要把這些標頭加入到 CORS 設定中（詳見 [CORS（跨來源資源共用）](../tutorial/cors.md)），使用在[Starlette 的 CORS 文件](https://www.starlette.dev/middleware/#corsmiddleware)中記載的 `expose_headers` 參數。 +但如果你有自訂標頭並希望瀏覽器端的客戶端能看見它們，你需要把這些標頭加入到 CORS 設定中（詳見 [CORS（跨來源資源共用）](../tutorial/cors.md)），使用在[Starlette 的 CORS 文件](https://starlette.dev/middleware/#corsmiddleware)中記載的 `expose_headers` 參數。 diff --git a/docs/zh-hant/docs/advanced/settings.md b/docs/zh-hant/docs/advanced/settings.md index 4ec1ea6726..912f42fe46 100644 --- a/docs/zh-hant/docs/advanced/settings.md +++ b/docs/zh-hant/docs/advanced/settings.md @@ -6,9 +6,13 @@ 因此，通常會透過環境變數提供這些設定，讓應用程式去讀取。 +**環境變數**（也稱為 **env var**）是存在於 Python 程式碼之外、作業系統中的值，並可由你的應用程式與其他程式讀取。 + +你可以在執行指令時為該指令建立環境變數。你會在下方看到各平台專用的指令。 + /// tip -若想了解環境變數，你可以閱讀[環境變數](../environment-variables.md)。 +請閱讀[環境變數指南](https://tiangolo.com/guides/environment-variables/)以詳細了解環境變數的運作方式。 /// @@ -20,27 +24,27 @@ ## Pydantic `Settings` { #pydantic-settings } -幸好，Pydantic 提供了很好的工具，可用來處理由環境變數而來的設定：[Pydantic：設定管理](https://docs.pydantic.dev/latest/concepts/pydantic_settings/)。 +幸好，Pydantic 提供了很好的工具，可用來處理由環境變數而來的設定：[Pydantic：設定管理](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/)。 ### 安裝 `pydantic-settings` { #install-pydantic-settings } -首先，請先建立你的[虛擬環境](../virtual-environments.md)，啟用它，然後安裝 `pydantic-settings` 套件： +將 `pydantic-settings` 套件加入你的專案：
```console -$ pip install pydantic-settings +$ uv add pydantic-settings ---> 100% ```
-當你用 `all` extras 安裝時，它也會一併包含在內： +當你用以下方式安裝 `all` extras 時，它也會一併包含在內：
```console -$ pip install "fastapi[all]" +$ uv add "fastapi[all]" ---> 100% ``` @@ -74,21 +78,41 @@ $ pip install "fastapi[all]" ### 執行伺服器 { #run-the-server } -接下來，你可以在啟動伺服器時，將設定以環境變數傳入。舉例來說，你可以設定 `ADMIN_EMAIL` 與 `APP_NAME`： +接下來，你可以在啟動伺服器時，將設定以環境變數傳入。例如，你可以用以下方式設定 `ADMIN_EMAIL` 與 `APP_NAME`： + +//// tab | Linux, macOS, Windows Bash
```console -$ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.py +$ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" uv run fastapi run main.py INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ```
+//// + +//// tab | Windows PowerShell + +
+ +```console +$ $Env:ADMIN_EMAIL = "deadpool@example.com" +$ $Env:APP_NAME = "ChimichangApp" +$ uv run fastapi run main.py + +INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) +``` + +
+ +//// + /// tip -要為單一指令設定多個環境變數，只要用空白分隔它們，並全部放在指令前面即可。 +在 Bash 中，要為單一指令設定多個環境變數，只要用空白分隔它們，並全部放在指令前面即可。 /// @@ -172,11 +196,11 @@ $ ADMIN_EMAIL="deadpool@example.com" APP_NAME="ChimichangApp" fastapi run main.p /// -Pydantic 透過外部函式庫支援讀取這類型的檔案。你可以閱讀更多：[Pydantic Settings：Dotenv (.env) 支援](https://docs.pydantic.dev/latest/concepts/pydantic_settings/#dotenv-env-support)。 +Pydantic 透過外部函式庫支援讀取這類型的檔案。你可以閱讀更多：[Pydantic Settings：Dotenv (.env) 支援](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/#dotenv-env-support)。 /// tip -要讓這個功能運作，你需要 `pip install python-dotenv`。 +要讓這個功能運作，請用 `uv add python-dotenv` 將 `python-dotenv` 加入你的專案。 /// @@ -197,7 +221,7 @@ APP_NAME="ChimichangApp" /// tip -`model_config` 屬性僅用於 Pydantic 的設定。你可以閱讀更多：[Pydantic：概念：設定](https://docs.pydantic.dev/latest/concepts/config/)。 +`model_config` 屬性僅用於 Pydantic 的設定。你可以閱讀更多：[Pydantic：概念：設定](https://pydantic.dev/docs/validation/latest/concepts/config/)。 /// diff --git a/docs/zh-hant/docs/advanced/sub-applications.md b/docs/zh-hant/docs/advanced/sub-applications.md index 7199e6d629..1afef7d4b9 100644 --- a/docs/zh-hant/docs/advanced/sub-applications.md +++ b/docs/zh-hant/docs/advanced/sub-applications.md @@ -35,7 +35,7 @@
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/zh-hant/docs/advanced/templates.md b/docs/zh-hant/docs/advanced/templates.md index 6e622d5a77..2f200edc51 100644 --- a/docs/zh-hant/docs/advanced/templates.md +++ b/docs/zh-hant/docs/advanced/templates.md @@ -8,12 +8,12 @@ ## 安裝相依套件 { #install-dependencies } -請先建立一個[虛擬環境](../virtual-environments.md)、啟用它，然後安裝 `jinja2`： +將 `jinja2` 加入你的專案：
```console -$ pip install jinja2 +$ uv add jinja2 ---> 100% ``` @@ -22,10 +22,10 @@ $ pip install jinja2 ## 使用 `Jinja2Templates` { #using-jinja2templates } -- 匯入 `Jinja2Templates`。 -- 建立一個可重複使用的 `templates` 物件。 -- 在會回傳模板的「*路徑操作（path operation）*」中宣告一個 `Request` 參數。 -- 使用你建立的 `templates` 來渲染並回傳 `TemplateResponse`，傳入模板名稱、`request` 物件，以及在 Jinja2 模板中使用的「context」鍵值對字典。 +* 匯入 `Jinja2Templates`。 +* 建立一個可重複使用的 `templates` 物件。 +* 在會回傳模板的「*路徑操作（path operation）*」中宣告一個 `Request` 參數。 +* 使用你建立的 `templates` 來渲染並回傳 `TemplateResponse`，傳入模板名稱、`request` 物件，以及在 Jinja2 模板中使用的「context」鍵值對字典。 {* ../../docs_src/templates/tutorial001_py310.py hl[4,11,15:18] *} @@ -123,4 +123,4 @@ Item ID: 42 ## 更多細節 { #more-details } -想了解更多細節（包含如何測試模板），請參考 [Starlette 的模板說明文件](https://www.starlette.dev/templates/)。 +想了解更多細節（包含如何測試模板），請參考 [Starlette 的模板說明文件](https://starlette.dev/templates/)。 diff --git a/docs/zh-hant/docs/advanced/testing-events.md b/docs/zh-hant/docs/advanced/testing-events.md index db678977a3..f880885df4 100644 --- a/docs/zh-hant/docs/advanced/testing-events.md +++ b/docs/zh-hant/docs/advanced/testing-events.md @@ -1,11 +1,12 @@ # 測試事件：lifespan 與 startup - shutdown { #testing-events-lifespan-and-startup-shutdown } -當你需要在測試中執行 lifespan（生命週期）時，你可以使用 TestClient 並搭配 with 陳述式： +當你需要在測試中執行 `lifespan` 時，你可以使用 `TestClient` 並搭配 `with` 陳述式： {* ../../docs_src/app_testing/tutorial004_py310.py hl[9:15,18,27:28,30:32,41:43] *} -你可以閱讀更多細節：[在測試中執行 lifespan](https://www.starlette.dev/lifespan/#running-lifespan-in-tests)（Starlette 官方文件）。 -對於已棄用的 `startup` 和 `shutdown` 事件，你可以這樣使用 TestClient： +你可以閱讀更多關於[「在官方 Starlette 文件網站中在測試中執行 lifespan。」](https://starlette.dev/lifespan/#running-lifespan-in-tests)的細節 + +對於已棄用的 `startup` 和 `shutdown` 事件，你可以這樣使用 `TestClient`： {* ../../docs_src/app_testing/tutorial003_py310.py hl[9:12,20:24] *} diff --git a/docs/zh-hant/docs/advanced/testing-websockets.md b/docs/zh-hant/docs/advanced/testing-websockets.md index caedc11dbd..6053717d6b 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](https://www.starlette.dev/testclient/#testing-websocket-sessions)文件。 +想了解更多，請參考 Starlette 的[測試 WebSocket](https://starlette.dev/testclient/#testing-websocket-sessions)文件。 /// diff --git a/docs/zh-hant/docs/advanced/using-request-directly.md b/docs/zh-hant/docs/advanced/using-request-directly.md index 2c355982de..dd6544af90 100644 --- a/docs/zh-hant/docs/advanced/using-request-directly.md +++ b/docs/zh-hant/docs/advanced/using-request-directly.md @@ -4,18 +4,18 @@ 例如從以下來源取得資料： -- 路徑中的參數。 -- 標頭。 -- Cookies。 -- 等等。 +* 路徑中的參數。 +* 標頭。 +* Cookies。 +* 等等。 -這麼做時，FastAPI 會自動驗證並轉換這些資料，還會為你的 API 產生文件。 +這麼做時，**FastAPI** 會自動驗證並轉換這些資料，還會為你的 API 產生文件。 但有些情況你可能需要直接存取 `Request` 物件。 ## 關於 `Request` 物件的細節 { #details-about-the-request-object } -由於 FastAPI 底層其實是 Starlette，再加上一層工具，因此在需要時你可以直接使用 Starlette 的 [`Request`](https://www.starlette.dev/requests/) 物件。 +由於 **FastAPI** 底層其實是 **Starlette**，再加上一層工具，因此在需要時你可以直接使用 Starlette 的 [`Request`](https://starlette.dev/requests/) 物件。 同時也代表，如果你直接從 `Request` 物件取得資料（例如讀取 body），FastAPI 不會替它做驗證、轉換或文件化（透過 OpenAPI 為自動化的 API 介面產生文件）。 @@ -25,13 +25,13 @@ ## 直接使用 `Request` 物件 { #use-the-request-object-directly } -假設你想在你的 路徑操作函式（path operation function） 中取得用戶端的 IP 位址／主機。 +假設你想在你的 *路徑操作函式* 中取得用戶端的 IP 位址／主機。 為此，你需要直接存取請求。 {* ../../docs_src/using_request_directly/tutorial001_py310.py hl[1,7:8] *} -只要在 路徑操作函式 中宣告一個型別為 `Request` 的參數，FastAPI 就會將當前的 `Request` 傳入該參數。 +只要在 *路徑操作函式* 中宣告一個型別為 `Request` 的參數，**FastAPI** 就會將當前的 `Request` 傳入該參數。 /// tip @@ -45,12 +45,12 @@ ## `Request` 文件 { #request-documentation } -你可以在 [Starlette 官方文件站點中的 `Request` 物件](https://www.starlette.dev/requests/) 了解更多細節。 +你可以在 [Starlette 官方文件站點中的 `Request` 物件](https://starlette.dev/requests/) 了解更多細節。 /// note | 技術細節 你也可以使用 `from starlette.requests import Request`。 -FastAPI 之所以直接提供它，是為了讓開發者更方便；但它本身是來自 Starlette。 +**FastAPI** 之所以直接提供它，是為了讓開發者更方便；但它本身是來自 Starlette。 /// diff --git a/docs/zh-hant/docs/advanced/websockets.md b/docs/zh-hant/docs/advanced/websockets.md index 29a95498c9..73294dfcd7 100644 --- a/docs/zh-hant/docs/advanced/websockets.md +++ b/docs/zh-hant/docs/advanced/websockets.md @@ -4,12 +4,12 @@ ## 安裝 `websockets` { #install-websockets } -請先建立[虛擬環境](../virtual-environments.md)、啟用它，然後安裝 `websockets`（一個讓你更容易使用「WebSocket」通訊協定的 Python 套件）： +將 `websockets`（一個讓你更容易使用「WebSocket」通訊協定的 Python 套件）加入你的專案：
```console -$ pip install websockets +$ uv add websockets ---> 100% ``` @@ -64,12 +64,12 @@ $ pip install websockets ## 試試看 { #try-it } -如果你的檔案名為 `main.py`，用以下指令執行應用： +將你的程式碼放在 `main.py` 檔案中，然後執行你的應用：
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -126,7 +126,7 @@ $ fastapi dev
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -182,5 +182,5 @@ Client #1596980209979 left the chat 想了解更多選項，請參考 Starlette 的文件： -* [`WebSocket` 類別](https://www.starlette.dev/websockets/)。 -* [以類別為基礎的 WebSocket 處理](https://www.starlette.dev/endpoints/#websocketendpoint)。 +* [`WebSocket` 類別](https://starlette.dev/websockets/)。 +* [以類別為基礎的 WebSocket 處理](https://starlette.dev/endpoints/#websocketendpoint)。 diff --git a/docs/zh-hant/docs/advanced/wsgi.md b/docs/zh-hant/docs/advanced/wsgi.md index 161496a982..aac3359032 100644 --- a/docs/zh-hant/docs/advanced/wsgi.md +++ b/docs/zh-hant/docs/advanced/wsgi.md @@ -9,7 +9,7 @@ /// note -這需要先安裝 `a2wsgi`，例如使用 `pip install a2wsgi`。 +這需要將 `a2wsgi` 加入你的專案，例如使用 `uv add a2wsgi`。 /// diff --git a/docs/zh-hant/docs/alternatives.md b/docs/zh-hant/docs/alternatives.md index d9573892e6..166f3f6c68 100644 --- a/docs/zh-hant/docs/alternatives.md +++ b/docs/zh-hant/docs/alternatives.md @@ -24,7 +24,7 @@ ### [Django REST Framework](https://www.django-rest-framework.org/) { #django-rest-framework } -Django REST framework 的目標是成為一套在 Django 之上構建 Web API 的彈性工具組，以強化其 API 能力。 +Django REST Framework 被創建為一套在 Django 之上構建 Web API 的彈性工具組，以強化其 API 能力。 它被 Mozilla、Red Hat、Eventbrite 等眾多公司使用。 @@ -125,7 +125,7 @@ def read_url(): 並整合基於標準的使用者介面工具： * [Swagger UI](https://github.com/swagger-api/swagger-ui) -* [ReDoc](https://github.com/Rebilly/ReDoc) +* [ReDoc](https://github.com/Redocly/redoc) 選擇這兩個是因為它們相當受歡迎且穩定，但稍加搜尋，你會發現有數十種 OpenAPI 的替代使用者介面（都能與 **FastAPI** 一起使用）。 @@ -237,7 +237,7 @@ Flask-apispec 由與 Marshmallow 相同的開發者創建。 /// -### [NestJS](https://nestjs.com/)（與 [Angular](https://angular.io/)） { #nestjs-and-angular } +### [NestJS](https://nestjs.com/)（與 [Angular](https://angular.dev/)） { #nestjs-and-angular } 這甚至不是 Python。NestJS 是受 Angular 啟發的 JavaScript（TypeScript）NodeJS 框架。 @@ -337,7 +337,7 @@ Hug 是最早使用 Python 型別提示來宣告 API 參數型別的框架之一 /// note -Hug 由 Timothy Crosley 創建，他同時也是 [`isort`](https://github.com/timothycrosley/isort) 的作者，一個自動排序 Python 匯入的好工具。 +Hug 由 Timothy Crosley 創建，他同時也是 [`isort`](https://github.com/PyCQA/isort) 的作者，一個能自動排序 Python 檔案中 import 的好工具。 /// @@ -401,7 +401,7 @@ APIStar 由 Tom Christie 創建。他也創建了： ## **FastAPI** 所採用的工具 { #used-by-fastapi } -### [Pydantic](https://docs.pydantic.dev/) { #pydantic } +### [Pydantic](https://pydantic.dev/docs/) { #pydantic } Pydantic 是基於 Python 型別提示，定義資料驗證、序列化與文件（使用 JSON Schema）的函式庫。 @@ -417,7 +417,7 @@ Pydantic 是基於 Python 型別提示，定義資料驗證、序列化與文件 /// -### [Starlette](https://www.starlette.dev/) { #starlette } +### [Starlette](https://starlette.dev/) { #starlette } Starlette 是一個輕量的 ASGI 框架／工具集，非常適合用來建構高效能的 asyncio 服務。 @@ -462,7 +462,7 @@ ASGI 是由 Django 核心團隊成員正在開發的新「標準」。它尚未 /// -### [Uvicorn](https://www.uvicorn.dev/) { #uvicorn } +### [Uvicorn](https://uvicorn.dev) { #uvicorn } Uvicorn 是基於 uvloop 與 httptools 的極速 ASGI 伺服器。 diff --git a/docs/zh-hant/docs/deployment/docker.md b/docs/zh-hant/docs/deployment/docker.md index b10299def8..7b058be282 100644 --- a/docs/zh-hant/docs/deployment/docker.md +++ b/docs/zh-hant/docs/deployment/docker.md @@ -105,40 +105,36 @@ Docker 是用來建立與管理容器映像與容器的主要工具之一。 ### 套件需求 { #package-requirements } -你的應用通常會把「套件需求」放在某個檔案中。 +當你使用 `uv` 管理專案時，它的直接相依會宣告在 `pyproject.toml` 中，而精確解析出的版本會儲存在 `uv.lock`。 -這主要取決於你用什麼工具來安裝那些需求。 +你可以用以下指令加入你的應用需要的套件： -最常見的方式是準備一個 `requirements.txt` 檔案，逐行列出套件名稱與版本。 +
-當然，你會用與在 [關於 FastAPI 版本](versions.md) 中讀到的相同概念，來設定版本範圍。 +```console +$ uv add "fastapi[standard]" pydantic +---> 100% +``` -例如，你的 `requirements.txt` 可能像這樣： +
-``` -fastapi[standard]>=0.113.0,<0.114.0 -pydantic>=2.7.0,<3.0.0 -``` +/// note | 注意 -接著你通常會用 `pip` 來安裝這些套件相依，例如： +下面的 Dockerfile 會在容器內使用 `pip`。你可以從你的 uv 專案匯出鎖定的相依，轉成它預期的 `requirements.txt` 格式：
```console -$ pip install -r requirements.txt ----> 100% -Successfully installed fastapi pydantic +$ uv export --format requirements-txt --no-dev --no-emit-project --output-file requirements.txt ```
-/// note | 注意 - -還有其他格式與工具可以用來定義與安裝套件相依。 +產生的 `requirements.txt` 是用於容器建置的匯出檔。請繼續使用 `uv add` 管理相依，並在 `uv.lock` 變更時重新產生它。 /// -### 建立 FastAPI 程式碼 { #create-the-fastapi-code } +### 建立 **FastAPI** 程式碼 { #create-the-fastapi-code } * 建立一個 `app` 目錄並進入。 * 建立一個空的 `__init__.py` 檔案。 @@ -372,7 +368,7 @@ $ docker run -d --name mycontainer -p 80:80 myimage 你也可以前往 [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](https://github.com/Rebilly/ReDoc) 提供）： +你會看到另一種自動產生的文件（由 [ReDoc](https://github.com/Redocly/redoc) 提供）： ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) diff --git a/docs/zh-hant/docs/deployment/fastapicloud.md b/docs/zh-hant/docs/deployment/fastapicloud.md index 0d5c5e7b1d..ecd3309fa8 100644 --- a/docs/zh-hant/docs/deployment/fastapicloud.md +++ b/docs/zh-hant/docs/deployment/fastapicloud.md @@ -5,7 +5,7 @@
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... @@ -24,9 +24,9 @@ CLI 會自動偵測你的 FastAPI 應用並將其部署到雲端。若你尚未 **[FastAPI Cloud](https://fastapicloud.com)** 由 **FastAPI** 的作者與團隊打造。 -它以最少的心力，精簡化建立、部署與存取 API 的流程。 +它以最少的心力，精簡化**建立**、**部署**與**存取** API 的流程。 -它把使用 FastAPI 開發應用的優異開發體驗，延伸到將它們部署到雲端。🎉 +它把使用 FastAPI 開發應用的優異**開發體驗**，延伸到將它們**部署**到雲端。🎉 它也會為你處理部署應用時多數需要面對的事項，例如： diff --git a/docs/zh-hant/docs/deployment/manually.md b/docs/zh-hant/docs/deployment/manually.md index 590d0b011c..5cf240f330 100644 --- a/docs/zh-hant/docs/deployment/manually.md +++ b/docs/zh-hant/docs/deployment/manually.md @@ -52,7 +52,7 @@ FastAPI 採用建立 Python 網頁框架與伺服器的標準 ```console -$ pip install "uvicorn[standard]" +$ uv add "uvicorn[standard]" ---> 100% ``` @@ -95,7 +95,7 @@ $ pip install "uvicorn[standard]" 其中包含 `uvloop`，它是 `asyncio` 的高效能替代實作，可大幅提升並行效能。 -當你用 `pip install "fastapi[standard]"` 安裝 FastAPI 時，也會一併取得 `uvicorn[standard]`。 +當你用像 `uv add "fastapi[standard]"` 這樣加入 FastAPI 時，也會一併取得 `uvicorn[standard]`。 /// @@ -106,7 +106,7 @@ $ pip install "uvicorn[standard]"
```console -$ uvicorn main:app --host 0.0.0.0 --port 80 +$ uv run uvicorn main:app --host 0.0.0.0 --port 80 INFO: Uvicorn running on http://0.0.0.0:80 (Press CTRL+C to quit) ``` diff --git a/docs/zh-hant/docs/deployment/server-workers.md b/docs/zh-hant/docs/deployment/server-workers.md index 82ffa0fa26..070f75a6b5 100644 --- a/docs/zh-hant/docs/deployment/server-workers.md +++ b/docs/zh-hant/docs/deployment/server-workers.md @@ -9,19 +9,19 @@ * 記憶體 * 啟動前的前置作業 -到目前為止，依照文件中的教學，你大多是透過 `fastapi` 指令啟動一個執行 Uvicorn 的伺服器程式，且只跑單一處理序。 +到目前為止，依照文件中的教學，你大多是透過 `fastapi` 指令啟動一個執行 Uvicorn 的**伺服器程式**，且只跑**單一處理序**。 -在部署應用時，你通常會希望有一些處理序的複製來善用多核心，並能處理更多請求。 +在部署應用時，你通常會希望有一些**處理序的複製**來善用**多核心**，並能處理更多請求。 如同前一章關於 [部署概念](concepts.md) 所示，你可以採用多種策略。 -這裡會示範如何使用 `fastapi` 指令或直接使用 `uvicorn` 指令，搭配 Uvicorn 的工作處理序（worker processes）。 +這裡會示範如何使用 `fastapi` 指令或直接使用 `uvicorn` 指令，搭配 **Uvicorn** 的**工作處理序**（worker processes）。 /// note 如果你使用容器（例如 Docker 或 Kubernetes），我會在下一章說明更多：[容器中的 FastAPI - Docker](docker.md)。 -特別是，在 **Kubernetes** 上執行時，你多半會選擇不要使用 workers，而是每個容器只跑一個 **Uvicorn 單一處理序**。我會在該章節中進一步說明。 +特別是，在 **Kubernetes** 上執行時，你多半會**不要**使用 workers，而是每個容器只跑一個 **Uvicorn 單一處理序**。我會在該章節中進一步說明。 /// @@ -86,7 +86,7 @@ $ fastapi run --workers 4 ```console -$ uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4 +$ uv run uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4 INFO: Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit) INFO: Started parent process [27365] INFO: Started server process [27368] @@ -109,7 +109,7 @@ $ uvicorn main:app --host 0.0.0.0 --port 8080 --workers 4 這裡唯一新增的選項是 `--workers`，告訴 Uvicorn 要啟動 4 個工作處理序。 -你也會看到它顯示每個處理序的 **PID**，`27365` 是父處理序（這是**處理序管理器**），另外每個工作處理序各有一個：`27368`、`27369`、`27370`、`27367`。 +你也會看到它顯示每個處理序的 **PID**，`27365` 是父處理序（這是**處理序管理器**），另外每個工作處理序各有一個：`27368`、`27369`、`27370` 和 `27367`。 ## 部署概念 { #deployment-concepts } diff --git a/docs/zh-hant/docs/environment-variables.md b/docs/zh-hant/docs/environment-variables.md index 71248ac638..91d7a7f176 100644 --- a/docs/zh-hant/docs/environment-variables.md +++ b/docs/zh-hant/docs/environment-variables.md @@ -1,299 +1,11 @@ # 環境變數 { #environment-variables } +**環境變數**（也稱為 **env var**）是存在於 Python 程式碼之外、作業系統中的值，可以被你的應用程式和其他程式讀取。 -/// tip +FastAPI 應用程式通常使用環境變數進行設定，例如資料庫 URL、電子郵件憑證和秘密金鑰。 -如果你已經知道什麼是「環境變數」並且知道如何使用它們，你可以放心跳過這一部分。 +你將在[設定與環境變數](advanced/settings.md)中學習如何將它們用於應用程式設定。 -/// +## 了解更多 { #learn-more } -環境變數（也稱為「**env var**」）是一個獨立於 Python 程式碼**之外**的變數，它存在於**作業系統**中，可以被你的 Python 程式碼（或其他程式）讀取。 - -環境變數對於處理應用程式**設定**（作為 Python **安裝**的一部分等方面）非常有用。 - -## 建立和使用環境變數 { #create-and-use-env-vars } - -你在 **shell（終端機）**中就可以**建立**和使用環境變數，並不需要用到 Python： - -//// tab | Linux, macOS, Windows Bash - -
- -```console -// 你可以使用以下指令建立一個名為 MY_NAME 的環境變數 -$ export MY_NAME="Wade Wilson" - -// 然後，你可以在其他程式中使用它，例如 -$ echo "Hello $MY_NAME" - -Hello Wade Wilson -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -// 建立一個名為 MY_NAME 的環境變數 -$ $Env:MY_NAME = "Wade Wilson" - -// 在其他程式中使用它，例如 -$ echo "Hello $Env:MY_NAME" - -Hello Wade Wilson -``` - -
- -//// - -## 在 Python 中讀取環境變數 { #read-env-vars-in-python } - -你也可以在 Python **之外**的終端機中建立環境變數（或使用其他方法），然後在 Python 中**讀取**它們。 - -例如，你可以建立一個名為 `main.py` 的檔案，其中包含以下內容： - -```Python hl_lines="3" -import os - -name = os.getenv("MY_NAME", "World") -print(f"Hello {name} from Python") -``` - -/// tip - -第二個參數是 [`os.getenv()`](https://docs.python.org/3.8/library/os.html#os.getenv) 的預設回傳值。 - -如果沒有提供，預設值為 `None`，這裡我們提供 `"World"` 作為預設值。 - -/// - -然後你可以呼叫這個 Python 程式： - -//// tab | Linux, macOS, Windows Bash - -
- -```console -// 這裡我們還沒有設定環境變數 -$ python main.py - -// 因為我們沒有設定環境變數，所以我們得到的是預設值 - -Hello World from Python - -// 但是如果我們事先建立過一個環境變數 -$ export MY_NAME="Wade Wilson" - -// 然後再次呼叫程式 -$ python main.py - -// 現在就可以讀取到環境變數了 - -Hello Wade Wilson from Python -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -// 這裡我們還沒有設定環境變數 -$ python main.py - -// 因為我們沒有設定環境變數，所以我們得到的是預設值 - -Hello World from Python - -// 但是如果我們事先建立過一個環境變數 -$ $Env:MY_NAME = "Wade Wilson" - -// 然後再次呼叫程式 -$ python main.py - -// 現在就可以讀取到環境變數了 - -Hello Wade Wilson from Python -``` - -
- -//// - -由於環境變數可以在程式碼之外設定，但可以被程式碼讀取，並且不必與其他檔案一起儲存（提交到 `git`），因此通常用於配置或**設定**。 - -你還可以為**特定的程式呼叫**建立特定的環境變數，該環境變數僅對該程式可用，且僅在其執行期間有效。 - -要實現這一點，只需在同一行內（程式本身之前）建立它： - -
- -```console -// 在這個程式呼叫的同一行中建立一個名為 MY_NAME 的環境變數 -$ MY_NAME="Wade Wilson" python main.py - -// 現在就可以讀取到環境變數了 - -Hello Wade Wilson from Python - -// 在此之後這個環境變數將不再存在 -$ python main.py - -Hello World from Python -``` - -
- -/// tip - -你可以在 [The Twelve-Factor App: 配置](https://12factor.net/config) 中了解更多資訊。 - -/// - -## 型別和驗證 { #types-and-validation } - -這些環境變數只能處理**文字字串**，因為它們是位於 Python 範疇之外的，必須與其他程式和作業系統的其餘部分相容（甚至與不同的作業系統相容，如 Linux、Windows、macOS）。 - -這意味著從環境變數中讀取的**任何值**在 Python 中都將是一個 `str`，任何型別轉換或驗證都必須在程式碼中完成。 - -你將在[進階使用者指南 - 設定和環境變數](./advanced/settings.md)中了解更多關於使用環境變數處理**應用程式設定**的資訊。 - -## `PATH` 環境變數 { #path-environment-variable } - -有一個**特殊的**環境變數稱為 **`PATH`**，作業系統（Linux、macOS、Windows）用它來查找要執行的程式。 - -`PATH` 變數的值是一個長字串，由 Linux 和 macOS 上的冒號 `:` 分隔的目錄組成，而在 Windows 上則是由分號 `;` 分隔的。 - -例如，`PATH` 環境變數可能如下所示： - -//// tab | Linux, macOS - -```plaintext -/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin -``` - -這意味著系統應該在以下目錄中查找程式： - -- `/usr/local/bin` -- `/usr/bin` -- `/bin` -- `/usr/sbin` -- `/sbin` - -//// - -//// tab | Windows - -```plaintext -C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32 -``` - -這意味著系統應該在以下目錄中查找程式： - -- `C:\Program Files\Python312\Scripts` -- `C:\Program Files\Python312` -- `C:\Windows\System32` - -//// - -當你在終端機中輸入一個**指令**時，作業系統會在 `PATH` 環境變數中列出的**每個目錄**中**查找**程式。 - -例如，當你在終端機中輸入 `python` 時，作業系統會在該列表中的**第一個目錄**中查找名為 `python` 的程式。 - -如果找到了，那麼作業系統將**使用它**；否則，作業系統會繼續在**其他目錄**中查找。 - -### 安裝 Python 並更新 `PATH` { #installing-python-and-updating-the-path } - -安裝 Python 時，可能會詢問你是否要更新 `PATH` 環境變數。 - -//// tab | Linux, macOS - -假設你安裝了 Python，並將其安裝在目錄 `/opt/custompython/bin` 中。 - -如果你選擇更新 `PATH` 環境變數，那麼安裝程式會將 `/opt/custompython/bin` 加入到 `PATH` 環境變數中。 - -它看起來大致會是這樣： - -```plaintext -/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin:/opt/custompython/bin -``` - -如此一來，當你在終端機輸入 `python` 時，系統會在 `/opt/custompython/bin` 中找到 Python 程式（最後一個目錄）並使用它。 - -//// - -//// tab | Windows - -假設你安裝了 Python，並將其安裝在目錄 `C:\opt\custompython\bin` 中。 - -如果你選擇更新 `PATH` 環境變數，那麼安裝程式會將 `C:\opt\custompython\bin` 加入到 `PATH` 環境變數中。 - -```plaintext -C:\Program Files\Python312\Scripts;C:\Program Files\Python312;C:\Windows\System32;C:\opt\custompython\bin -``` - -如此一來，當你在終端機輸入 `python` 時，系統會在 `C:\opt\custompython\bin` 中找到 Python 程式（最後一個目錄）並使用它。 - -//// - -因此，如果你輸入： - -
- -```console -$ python -``` - -
- -//// tab | Linux, macOS - -系統會在 `/opt/custompython/bin` 中**找到** `python` 程式並執行它。 - -這大致等同於輸入以下指令： - -
- -```console -$ /opt/custompython/bin/python -``` - -
- -//// - -//// tab | Windows - -系統會在 `C:\opt\custompython\bin\python` 中**找到** `python` 程式並執行它。 - -這大致等同於輸入以下指令： - -
- -```console -$ C:\opt\custompython\bin\python -``` - -
- -//// - -當學習[虛擬環境](virtual-environments.md)時，這些資訊將會很有用。 - -## 結論 { #conclusion } - -透過這個教學，你應該對**環境變數**是什麼以及如何在 Python 中使用它們有了基本的了解。 - -你也可以在 [環境變數的維基百科條目](https://en.wikipedia.org/wiki/Environment_variable) 中閱讀更多。 - -在許多情況下，環境變數的用途和適用性可能不會立刻顯現。但是在開發過程中，它們會在許多不同的場景中出現，因此瞭解它們是非常必要的。 - -例如，你在接下來的[虛擬環境](virtual-environments.md)章節中將需要這些資訊。 +閱讀[環境變數指南](https://tiangolo.com/guides/environment-variables/)以取得詳細的跨平台說明，包括如何建立和讀取環境變數，以及 `PATH` 環境變數的運作方式。 diff --git a/docs/zh-hant/docs/fastapi-cli.md b/docs/zh-hant/docs/fastapi-cli.md index 55220afe12..e92998b9ea 100644 --- a/docs/zh-hant/docs/fastapi-cli.md +++ b/docs/zh-hant/docs/fastapi-cli.md @@ -2,7 +2,7 @@ **FastAPI CLI** 是一個命令列程式，你可以用它來啟動你的 FastAPI 應用程式、管理你的 FastAPI 專案，等等。 -當你安裝 FastAPI（例如使用 `pip install "fastapi[standard]"`）時，會附帶一個可以在終端機執行的命令列程式。 +當你將 FastAPI 加入專案（例如使用 `uv add "fastapi[standard]"`）時，會附帶一個可以在終端機執行的命令列程式。 要在開發時運行你的 FastAPI 應用程式，你可以使用 `fastapi dev` 指令： @@ -52,7 +52,7 @@ $ fastapi dev /// -在內部，**FastAPI CLI** 使用 [Uvicorn](https://www.uvicorn.dev)，這是一個高效能、適用於生產環境的 ASGI 伺服器。😎 +在內部，**FastAPI CLI** 使用 [Uvicorn](https://uvicorn.dev)，這是一個高效能、適用於生產環境的 ASGI 伺服器。😎 `fastapi` CLI 會嘗試自動偵測要執行的 FastAPI 應用程式，預設假設它是檔案 `main.py` 中名為 `app` 的物件（或其他幾種變體）。 @@ -100,13 +100,13 @@ from backend.main import app 你也可以把檔案路徑傳給 `fastapi dev` 指令，它會推測要使用的 FastAPI app 物件： ```console -$ fastapi dev main.py +$ uv run fastapi dev main.py ``` 或者，你也可以把 `--entrypoint` 選項傳給 `fastapi dev` 指令： ```console -$ fastapi dev --entrypoint main:app +$ uv run fastapi dev --entrypoint main:app ``` 但這樣每次呼叫 `fastapi` 指令時都得記得傳入正確的路徑或 entrypoint。 @@ -119,6 +119,10 @@ $ fastapi dev --entrypoint main:app 預設情況下，**auto-reload** 功能是啟用的，當你對程式碼進行修改時，伺服器會自動重新載入。這會消耗較多資源，並且可能比禁用時更不穩定。因此，你應該只在開發環境中使用此功能。它也會在 IP 位址 `127.0.0.1` 上監聽，這是用於你的機器與自身通訊的 IP 位址（`localhost`）。 +在匯入你的 app 之前，`fastapi dev` 會將 `FASTAPI_ENV` 環境變數設為 `development`。如果 `FASTAPI_ENV` 已經設定，則會保留其既有值。這讓 app 啟動程式碼可以選擇適合開發的行為，同時允許你提供 app 專用的環境，例如 `staging`。 + +慣例的 `FASTAPI_ENV` 值是 `development` 和 `production`。`fastapi run` 目前會讓 `FASTAPI_ENV` 保持不變，因此如果你的 app 需要偵測生產模式，請明確設定它。 + ## `fastapi run` { #fastapi-run } 執行 `fastapi run` 會以生產模式啟動 FastAPI。 diff --git a/docs/zh-hant/docs/features.md b/docs/zh-hant/docs/features.md index 193e4a1d6e..aa2b684ea3 100644 --- a/docs/zh-hant/docs/features.md +++ b/docs/zh-hant/docs/features.md @@ -19,7 +19,7 @@ ![Swagger UI interaction](https://fastapi.tiangolo.com/img/index/index-03-swagger-02.png) -* 使用 [**ReDoc**](https://github.com/Rebilly/ReDoc) 的替代 API 文件。 +* 使用 [**ReDoc**](https://github.com/Redocly/redoc) 的替代 API 文件。 ![ReDoc](https://fastapi.tiangolo.com/img/index/index-06-redoc-02.png) @@ -159,7 +159,7 @@ FastAPI 有一個使用簡單，但是非常強大的 ORMs 和 ODMs。 diff --git a/docs/zh-hant/docs/help-fastapi.md b/docs/zh-hant/docs/help-fastapi.md index 4a4a4fda59..f4cc8ae859 100644 --- a/docs/zh-hant/docs/help-fastapi.md +++ b/docs/zh-hant/docs/help-fastapi.md @@ -46,20 +46,6 @@ * [**Bluesky** 上的 @tiangolo.com](https://bsky.app/profile/tiangolo.com) * [**LinkedIn** 上的 @tiangolo](https://www.linkedin.com/in/tiangolo/)。 -## 在 GitHub 幫助他人解答問題 { #help-others-with-questions-in-github } - -你可以嘗試在 [GitHub Discussions](https://github.com/fastapi/fastapi/discussions/categories/questions?discussions_q=category%3AQuestions+is%3Aunanswered) 幫助他人回答問題。 - -很多時候你可能已經知道這些問題的答案。🤓 - -如果你經常幫大家解決問題，你會成為官方的 [FastAPI 專家](fastapi-people.md#fastapi-experts)。🎉 - -請記得，最重要的是：盡量友善。🤗 - -### 如何協助 { #how-to-help } - -請依照這裡的[協助指南](https://tiangolo.com/open-source/help/#help-others-with-questions-in-github)。 - ## 提問 { #ask-questions } 你可以在 GitHub 儲存庫[建立一個新的問題（Question）](https://github.com/fastapi/fastapi/discussions/new?category=questions)，例如用來： @@ -69,7 +55,7 @@ ## 加入聊天室 { #join-the-chat } -加入 👥 [Discord 聊天伺服器](https://discord.gg/VQjSZaeJmf) 👥，與 FastAPI 社群的其他人一起交流。 +加入 👥 [Discord 聊天伺服器](https://discord.com/invite/VQjSZaeJmf) 👥，與 FastAPI 社群的其他人一起交流。 /// tip @@ -86,3 +72,9 @@ 在 GitHub 上，模板會引導你寫出合適的提問，讓你更容易得到好的解答，甚至在提問前就自己解決問題。 聊天系統中的對話也不像 GitHub 那樣容易被搜尋，常常會淹沒在對話中。 + +## 試用 FastAPI Cloud { #try-fastapi-cloud } + +FastAPI 與夥伴的主要資金來自 [**FastAPI Cloud**](https://fastapicloud.com)，這是一個能以簡單快速的方式部署 FastAPI 應用程式的平台，只需一個指令 `fastapi deploy`。 + +FastAPI Cloud 由 FastAPI 背後的同一個團隊打造。你可以試用它，並考慮在你的專案中使用。 diff --git a/docs/zh-hant/docs/history-design-future.md b/docs/zh-hant/docs/history-design-future.md index f3c733330a..8911b80136 100644 --- a/docs/zh-hant/docs/history-design-future.md +++ b/docs/zh-hant/docs/history-design-future.md @@ -54,11 +54,11 @@ ## 需求 { #requirements } -在測試多種替代方案後，我決定採用 [**Pydantic**](https://docs.pydantic.dev/)，因為它的優勢。 +在測試多種替代方案後，我決定採用 [**Pydantic**](https://pydantic.dev/docs/)，因為它的優勢。 隨後我也對它做出貢獻，使其完全符合 JSON Schema、支援以不同方式定義約束，並依據在多款編輯器中的測試結果改進編輯器支援（型別檢查、自動補全）。 -在開發過程中，我也對 [**Starlette**](https://www.starlette.dev/)（另一個關鍵依賴）做出貢獻。 +在開發過程中，我也對 [**Starlette**](https://starlette.dev/)（另一個關鍵依賴）做出貢獻。 ## 開發 { #development } 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 afd097f51c..e118ed0102 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 @@ -66,7 +66,7 @@ 而 `scope` 與 `receive` 這兩者，就是建立一個新的 `Request` 實例所需的資料。 -想了解更多 `Request`，請參考 [Starlette 的 Request 文件](https://www.starlette.dev/requests/)。 +想了解更多 `Request`，請參考 [Starlette 的 Request 文件](https://starlette.dev/requests/)。 /// diff --git a/docs/zh-hant/docs/how-to/extending-openapi.md b/docs/zh-hant/docs/how-to/extending-openapi.md index 0a6ba5a591..0b68c54eba 100644 --- a/docs/zh-hant/docs/how-to/extending-openapi.md +++ b/docs/zh-hant/docs/how-to/extending-openapi.md @@ -45,7 +45,7 @@ 基於上述資訊，你可以用相同的工具函式來產生 OpenAPI 結構，並覆寫你需要客製的部分。 -例如，我們要加入 [ReDoc 的 OpenAPI 擴充，插入自訂 logo](https://github.com/Rebilly/ReDoc/blob/master/docs/redoc-vendor-extensions.md#x-logo)。 +例如，我們要加入 [ReDoc 的 OpenAPI 擴充，插入自訂 logo](https://github.com/Redocly/redoc/blob/main/docs/redoc-vendor-extensions.md#x-logo)。 ### 一般的 **FastAPI** { #normal-fastapi } diff --git a/docs/zh-hant/docs/how-to/graphql.md b/docs/zh-hant/docs/how-to/graphql.md index fce5f41190..b2ad5966b9 100644 --- a/docs/zh-hant/docs/how-to/graphql.md +++ b/docs/zh-hant/docs/how-to/graphql.md @@ -21,7 +21,7 @@ * [Strawberry](https://strawberry.rocks/) 🍓 * 提供 [FastAPI 文件](https://strawberry.rocks/docs/integrations/fastapi) * [Ariadne](https://ariadnegraphql.org/) - * 提供 [FastAPI 文件](https://ariadnegraphql.org/docs/fastapi-integration) + * 提供 [FastAPI 文件](https://ariadnegraphql.org/server/Integrations/fastapi-integration) * [Tartiflette](https://tartiflette.io/) * 使用 [Tartiflette ASGI](https://tartiflette.github.io/tartiflette-asgi/) 提供 ASGI 整合 * [Graphene](https://graphene-python.org/) 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 77a58251e2..6941ddbaa9 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 @@ -24,7 +24,7 @@ Pydantic 團隊自 **Python 3.14** 起，已停止在最新的 Python 版本中 ## 官方指南 { #official-guide } -Pydantic 提供從 v1 遷移到 v2 的官方[遷移指南](https://docs.pydantic.dev/latest/migration/)。 +Pydantic 提供從 v1 遷移到 v2 的官方[遷移指南](https://pydantic.dev/docs/validation/latest/get-started/migration/)。 其中包含變更內容、驗證如何更正確且更嚴格、可能的注意事項等。 diff --git a/docs/zh-hant/docs/index.md b/docs/zh-hant/docs/index.md index 743357b96c..27f506be7c 100644 --- a/docs/zh-hant/docs/index.md +++ b/docs/zh-hant/docs/index.md @@ -110,7 +110,7 @@ FastAPI 是一個現代、快速（高效能）的 Web 框架，用於以 Python
-## FastAPI 大會 { #fastapi-conf } - -[**FastAPI Conf '26**](https://fastapiconf.com) 將於 **2026 年 10 月 28 日** 在 **荷蘭阿姆斯特丹** 舉行。全部關於 FastAPI，來自第一手來源。🎤 - -FastAPI Conf '26 - October 28, 2026 - Amsterdam, NL - ## FastAPI 迷你紀錄片 { #fastapi-mini-documentary } 在 2025 年底發布了一支 [FastAPI 迷你紀錄片](https://www.youtube.com/watch?v=mpR8ngthqiE)，你可以在線上觀看： @@ -175,17 +169,17 @@ FastAPI 是一個現代、快速（高效能）的 Web 框架，用於以 Python FastAPI 是站在以下巨人的肩膀上： -* [Starlette](https://www.starlette.dev/) 負責 Web 部分。 -* [Pydantic](https://docs.pydantic.dev/) 負責資料部分。 +* [Starlette](https://starlette.dev/) 負責 Web 部分。 +* [Pydantic](https://pydantic.dev/docs/) 負責資料部分。 ## 安裝 { #installation } -建立並啟用一個[虛擬環境](https://fastapi.tiangolo.com/zh-hant/virtual-environments/)，然後安裝 FastAPI： +首先，[安裝 `uv`](https://docs.astral.sh/uv/getting-started/installation/)，然後將 FastAPI 加入你的專案：
```console -$ pip install "fastapi[standard]" +$ uv add "fastapi[standard]" ---> 100% ``` @@ -194,6 +188,8 @@ $ pip install "fastapi[standard]" **注意**：請務必將 `"fastapi[standard]"` 用引號包起來，以確保在所有終端機中都能正常運作。 +如果你偏好使用 `pip`，請在虛擬環境中安裝 `fastapi[standard]`。請參閱[安裝指南](tutorial/#install-fastapi)了解替代步驟。 + ## 範例 { #example } ### 建立 { #create-it } @@ -250,7 +246,7 @@ async def read_item(item_id: int, q: str | None = None):
```console -$ fastapi dev +$ uv run fastapi dev ╭────────── FastAPI CLI - Development mode ───────────╮ │ │ @@ -277,7 +273,7 @@ INFO: Application startup complete.
關於指令 fastapi dev... -指令 `fastapi dev` 會自動讀取你的 `main.py`，偵測其中的 **FastAPI** 應用，並使用 [Uvicorn](https://www.uvicorn.dev) 啟動伺服器。 +指令 `fastapi dev` 會自動讀取你的 `main.py`，偵測其中的 **FastAPI** 應用，並使用 [Uvicorn](https://uvicorn.dev) 啟動伺服器。 預設情況下，`fastapi dev` 會在本機開發時啟用自動重新載入。 @@ -314,7 +310,7 @@ INFO: Application startup complete. 現在前往 [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc)。 -你會看到另一種自動文件（由 [ReDoc](https://github.com/Rebilly/ReDoc) 提供）： +你會看到另一種自動文件（由 [ReDoc](https://github.com/Redocly/redoc) 提供）： ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) @@ -400,7 +396,7 @@ item_id: int item: Item ``` -…透過一次宣告，你將獲得： +...透過一次宣告，你將獲得： * 編輯器支援，包括： * 自動補全。 @@ -457,19 +453,19 @@ item: Item return {"item_name": item.name, "item_id": item_id} ``` -…從： +...從： ```Python ... "item_name": item.name ... ``` -…改為： +...改為： ```Python ... "item_price": item.price ... ``` -…然後看看你的編輯器如何自動補全屬性並知道它們的型別： +...然後看看你的編輯器如何自動補全屬性並知道它們的型別： ![editor support](https://fastapi.tiangolo.com/img/vscode-completion.png) @@ -497,7 +493,7 @@ item: Item
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... @@ -540,7 +536,7 @@ FastAPI 依賴 Pydantic 與 Starlette。 ### `standard` 依賴套件 { #standard-dependencies } -當你以 `pip install "fastapi[standard]"` 安裝 FastAPI 時，會包含 `standard` 這組可選依賴套件： +當你以 `uv add "fastapi[standard]"` 安裝 FastAPI 時，會包含 `standard` 這組可選依賴套件： Pydantic 會使用： @@ -554,17 +550,17 @@ Starlette 會使用： FastAPI 會使用： -* [`uvicorn`](https://www.uvicorn.dev) - 用於載入並服務你的應用的伺服器。這包含 `uvicorn[standard]`，其中含有一些高效能服務所需的依賴（例如 `uvloop`）。 +* [`uvicorn`](https://uvicorn.dev) - 用於載入並服務你的應用的伺服器。這包含 `uvicorn[standard]`，其中含有一些高效能服務所需的依賴（例如 `uvloop`）。 * `fastapi-cli[standard]` - 提供 `fastapi` 指令。 * 其中包含 `fastapi-cloud-cli`，可讓你將 FastAPI 應用部署到 [FastAPI Cloud](https://fastapicloud.com)。 ### 不含 `standard` 依賴套件 { #without-standard-dependencies } -如果你不想包含 `standard` 可選依賴，可以改用 `pip install fastapi`（而不是 `pip install "fastapi[standard]"`）。 +如果你不想包含 `standard` 可選依賴，可以改用 `uv add fastapi`（而不是 `uv add "fastapi[standard]"`）。 ### 不含 `fastapi-cloud-cli` { #without-fastapi-cloud-cli } -如果你想安裝帶有 standard 依賴、但不包含 `fastapi-cloud-cli`，可以使用 `pip install "fastapi[standard-no-fastapi-cloud-cli]"`。 +如果你想安裝帶有 standard 依賴、但不包含 `fastapi-cloud-cli`，可以使用 `uv add "fastapi[standard-no-fastapi-cloud-cli]"`。 ### 額外可選依賴套件 { #additional-optional-dependencies } @@ -572,13 +568,13 @@ FastAPI 會使用： Pydantic 的額外可選依賴： -* [`pydantic-settings`](https://docs.pydantic.dev/latest/usage/pydantic_settings/) - 設定管理。 -* [`pydantic-extra-types`](https://docs.pydantic.dev/latest/usage/types/extra_types/extra_types/) - 與 Pydantic 一起使用的額外型別。 +* [`pydantic-settings`](https://pydantic.dev/docs/validation/latest/concepts/pydantic_settings/) - 設定管理。 +* [`pydantic-extra-types`](https://github.com/pydantic/pydantic-extra-types) - 與 Pydantic 一起使用的額外型別。 FastAPI 的額外可選依賴： * [`orjson`](https://github.com/ijl/orjson) - 若要使用 `ORJSONResponse` 必須安裝。 -* [`ujson`](https://github.com/esnme/ultrajson) - 若要使用 `UJSONResponse` 必須安裝。 +* [`ujson`](https://github.com/ultrajson/ultrajson) - 若要使用 `UJSONResponse` 必須安裝。 ## 授權 { #license } diff --git a/docs/zh-hant/docs/project-generation.md b/docs/zh-hant/docs/project-generation.md index 862417affb..e6743c5966 100644 --- a/docs/zh-hant/docs/project-generation.md +++ b/docs/zh-hant/docs/project-generation.md @@ -5,13 +5,13 @@ 你可以使用此範本快速起步，裡面已替你完成大量初始設定、安全性、資料庫，以及部分 API 端點。 -GitHub 儲存庫：[全端 FastAPI 範本](https://github.com/tiangolo/full-stack-fastapi-template) +GitHub 儲存庫：[全端 FastAPI 範本](https://github.com/fastapi/full-stack-fastapi-template) ## 全端 FastAPI 範本 - 技術堆疊與功能 { #full-stack-fastapi-template-technology-stack-and-features } - ⚡ [**FastAPI**](https://fastapi.tiangolo.com/zh-hant) 作為 Python 後端 API。 - 🧰 [SQLModel](https://sqlmodel.tiangolo.com) 作為 Python 與 SQL 資料庫互動（ORM）。 - - 🔍 [Pydantic](https://docs.pydantic.dev)（由 FastAPI 使用）用於資料驗證與設定管理。 + - 🔍 [Pydantic](https://pydantic.dev/docs/)（由 FastAPI 使用）用於資料驗證與設定管理。 - 💾 [PostgreSQL](https://www.postgresql.org) 作為 SQL 資料庫。 - 🚀 [React](https://react.dev) 作為前端。 - 💃 使用 TypeScript、hooks、Vite，以及現代前端技術堆疊的其他組件。 diff --git a/docs/zh-hant/docs/python-types.md b/docs/zh-hant/docs/python-types.md index 2959217604..8ecc12d470 100644 --- a/docs/zh-hant/docs/python-types.md +++ b/docs/zh-hant/docs/python-types.md @@ -269,7 +269,7 @@ def some_function(data: Any): ## Pydantic 模型 { #pydantic-models } -[Pydantic](https://docs.pydantic.dev/) 是一個用來做資料驗證的 Python 程式庫。 +[Pydantic](https://pydantic.dev/docs/) 是一個用來做資料驗證的 Python 程式庫。 你以帶有屬性的類別來宣告資料的「形狀」。 @@ -285,7 +285,7 @@ def some_function(data: Any): /// note | 注意 -想了解更多 [Pydantic，請查看它的文件](https://docs.pydantic.dev/)。 +想了解更多 [Pydantic，請查看它的文件](https://pydantic.dev/docs/)。 /// diff --git a/docs/zh-hant/docs/tutorial/background-tasks.md b/docs/zh-hant/docs/tutorial/background-tasks.md index 216ec88689..49cfdde55b 100644 --- a/docs/zh-hant/docs/tutorial/background-tasks.md +++ b/docs/zh-hant/docs/tutorial/background-tasks.md @@ -1,6 +1,6 @@ # 背景任務 { #background-tasks } -你可以定義背景任務，讓它們在傳回回應之後執行。 +你可以定義背景任務，讓它們在傳回回應*之後*執行。 這對於那些需要在請求之後發生、但用戶端其實不必在收到回應前等它完成的操作很有用。 @@ -13,11 +13,11 @@ ## 使用 `BackgroundTasks` { #using-backgroundtasks } -首先，匯入 `BackgroundTasks`，並在你的路徑操作函式中定義一個型別為 `BackgroundTasks` 的參數： +首先，匯入 `BackgroundTasks`，並在你的*路徑操作函式*中定義一個型別宣告為 `BackgroundTasks` 的參數： {* ../../docs_src/background_tasks/tutorial001_py310.py hl[1,13] *} -**FastAPI** 會為你建立 `BackgroundTasks` 物件，並以該參數傳入。 +**FastAPI** 會為你建立 `BackgroundTasks` 型別的物件，並以該參數傳入。 ## 建立任務函式 { #create-a-task-function } @@ -35,7 +35,7 @@ ## 新增背景任務 { #add-the-background-task } -在路徑操作函式內，使用 `.add_task()` 將任務函式加入背景任務物件： +在你的*路徑操作函式*內，使用 `.add_task()` 將任務函式傳給*背景任務*物件： {* ../../docs_src/background_tasks/tutorial001_py310.py hl[14] *} @@ -47,29 +47,31 @@ ## 相依性注入 { #dependency-injection } -在相依性注入系統中也可使用 `BackgroundTasks`。你可以在多個層級宣告 `BackgroundTasks` 型別的參數：路徑操作函式、相依項（dependable）、次級相依項等。 +在相依性注入系統中也可使用 `BackgroundTasks`。你可以在多個層級宣告 `BackgroundTasks` 型別的參數：*路徑操作函式*、相依項（dependable）、次級相依項等。 **FastAPI** 會在各種情況下正確處理並重用同一個物件，將所有背景任務合併，並在之後於背景執行： + {* ../../docs_src/background_tasks/tutorial002_an_py310.py hl[13,15,22,25] *} -在此範例中，訊息會在回應送出之後寫入 `log.txt` 檔案。 + +在此範例中，訊息會在回應送出*之後*寫入 `log.txt` 檔案。 如果請求中有查詢參數，會以背景任務寫入日誌。 -接著，在路徑操作函式中建立的另一個背景任務會使用 `email` 路徑參數寫入訊息。 +接著，在*路徑操作函式*中建立的另一個背景任務會使用 `email` 路徑參數寫入訊息。 ## 技術細節 { #technical-details } -類別 `BackgroundTasks` 直接來自 [`starlette.background`](https://www.starlette.dev/background/)。 +類別 `BackgroundTasks` 直接來自 [`starlette.background`](https://starlette.dev/background/)。 -它被直接匯入/包含到 FastAPI 中，因此你可以從 `fastapi` 匯入它，並避免不小心從 `starlette.background` 匯入另一個同名的 `BackgroundTask`（結尾沒有 s）。 +它被直接匯入/包含到 FastAPI 中，因此你可以從 `fastapi` 匯入它，並避免不小心從 `starlette.background` 匯入替代的 `BackgroundTask`（結尾沒有 `s`）。 -只使用 `BackgroundTasks`（而非 `BackgroundTask`）時，你就能把它當作路徑操作函式的參數，並讓 **FastAPI** 幫你處理其餘部分，就像直接使用 `Request` 物件一樣。 +只使用 `BackgroundTasks`（而非 `BackgroundTask`）時，你就能把它當作*路徑操作函式*的參數，並讓 **FastAPI** 幫你處理其餘部分，就像直接使用 `Request` 物件一樣。 在 FastAPI 中仍可單獨使用 `BackgroundTask`，但你需要在程式碼中自行建立該物件，並回傳包含它的 Starlette `Response`。 -更多細節請參閱 [Starlette 官方的 Background Tasks 文件](https://www.starlette.dev/background/)。 +更多細節請參閱 [Starlette 官方的 Background Tasks 文件](https://starlette.dev/background/)。 ## 注意事項 { #caveat } @@ -81,4 +83,4 @@ ## 重點回顧 { #recap } -在路徑操作函式與相依項中匯入並使用 `BackgroundTasks` 參數，以新增背景任務。 +在*路徑操作函式*與相依項中匯入並使用 `BackgroundTasks` 參數，以新增背景任務。 diff --git a/docs/zh-hant/docs/tutorial/bigger-applications.md b/docs/zh-hant/docs/tutorial/bigger-applications.md index 624b2c2bc2..20441af25b 100644 --- a/docs/zh-hant/docs/tutorial/bigger-applications.md +++ b/docs/zh-hant/docs/tutorial/bigger-applications.md @@ -487,7 +487,7 @@ from app.main import app 你也可以把路徑直接傳給指令，例如： ```console -$ fastapi dev app/main.py +$ uv run fastapi dev app/main.py ``` 但你每次呼叫 `fastapi` 指令時都得記得傳入正確的路徑。 @@ -503,7 +503,7 @@ $ fastapi dev app/main.py
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/zh-hant/docs/tutorial/body-nested-models.md b/docs/zh-hant/docs/tutorial/body-nested-models.md index 4e2e6427cb..02c13e0a7f 100644 --- a/docs/zh-hant/docs/tutorial/body-nested-models.md +++ b/docs/zh-hant/docs/tutorial/body-nested-models.md @@ -96,7 +96,7 @@ my_list: list[str] 除了 `str`、`int`、`float` 等一般的單一型別外，你也可以使用繼承自 `str` 的更複雜單一型別。 -若要查看所有可用選項，請參閱 [Pydantic 的型別總覽](https://docs.pydantic.dev/latest/concepts/types/)。你會在下一章看到一些範例。 +若要查看所有可用選項，請參閱 [Pydantic 的型別總覽](https://pydantic.dev/docs/validation/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 f1ba8e954f..0dc4df28ad 100644 --- a/docs/zh-hant/docs/tutorial/body.md +++ b/docs/zh-hant/docs/tutorial/body.md @@ -6,7 +6,7 @@ 你的 API 幾乎總是需要傳回**回應**本文。但用戶端不一定每次都要送出**請求本文**，有時只會請求某個路徑，可能帶一些查詢參數，但不會傳送本文。 -要宣告**請求**本文，你會使用 [Pydantic](https://docs.pydantic.dev/) 模型，享受其完整的功能與優點。 +要宣告**請求**本文，你會使用 [Pydantic](https://pydantic.dev/docs/) 模型，享受其完整的功能與優點。 /// note diff --git a/docs/zh-hant/docs/tutorial/debugging.md b/docs/zh-hant/docs/tutorial/debugging.md index a3254e3d19..c15df5641e 100644 --- a/docs/zh-hant/docs/tutorial/debugging.md +++ b/docs/zh-hant/docs/tutorial/debugging.md @@ -16,7 +16,7 @@
```console -$ python myapp.py +$ uv run python myapp.py ```
@@ -36,7 +36,7 @@ from myapp import app
```console -$ python myapp.py +$ uv run python myapp.py ```
diff --git a/docs/zh-hant/docs/tutorial/extra-data-types.md b/docs/zh-hant/docs/tutorial/extra-data-types.md index 23c7532327..b04d986196 100644 --- a/docs/zh-hant/docs/tutorial/extra-data-types.md +++ b/docs/zh-hant/docs/tutorial/extra-data-types.md @@ -37,7 +37,7 @@ * `datetime.timedelta`： * Python 的 `datetime.timedelta`。 * 在請求與回應中會以總秒數的 `float` 表示。 - * Pydantic 也允許用「ISO 8601 time diff encoding」來表示，[詳情見文件](https://docs.pydantic.dev/latest/concepts/serialization/#custom-serializers)。 + * Pydantic 也允許用「ISO 8601 time diff encoding」來表示，[詳情見文件](https://pydantic.dev/docs/validation/latest/concepts/serialization/#custom-serializers)。 * `frozenset`： * 在請求與回應中與 `set` 相同處理： * 在請求中，會讀取一個 list，去除重複並轉為 `set`。 @@ -50,7 +50,7 @@ * `Decimal`： * 標準的 Python `Decimal`。 * 在請求與回應中，與 `float` 的處理方式相同。 -* 你可以在此查閱所有可用的 Pydantic 資料型別：[Pydantic 資料型別](https://docs.pydantic.dev/latest/usage/types/types/)。 +* 你可以在此查閱所有可用的 Pydantic 資料型別：[Pydantic 資料型別](https://pydantic.dev/docs/validation/latest/concepts/types/)。 ## 範例 { #example } diff --git a/docs/zh-hant/docs/tutorial/extra-models.md b/docs/zh-hant/docs/tutorial/extra-models.md index 162325e9d1..0a2b90fbd3 100644 --- a/docs/zh-hant/docs/tutorial/extra-models.md +++ b/docs/zh-hant/docs/tutorial/extra-models.md @@ -166,7 +166,7 @@ UserInDB( /// note -在定義 [`Union`](https://docs.pydantic.dev/latest/concepts/types/#unions) 時，請先放置「更具體」的型別，再放「較不具體」的型別。以下範例中，較具體的 `PlaneItem` 置於 `CarItem` 之前：`Union[PlaneItem, CarItem]`。 +在定義 [`Union`](https://pydantic.dev/docs/validation/latest/concepts/unions/) 時，請先放置「更具體」的型別，再放「較不具體」的型別。以下範例中，較具體的 `PlaneItem` 置於 `CarItem` 之前：`Union[PlaneItem, CarItem]`。 /// diff --git a/docs/zh-hant/docs/tutorial/first-steps.md b/docs/zh-hant/docs/tutorial/first-steps.md index bc023cc399..726e18161e 100644 --- a/docs/zh-hant/docs/tutorial/first-steps.md +++ b/docs/zh-hant/docs/tutorial/first-steps.md @@ -6,12 +6,18 @@ 將其複製到一個名為 `main.py` 的文件中。 +/// tip + +FastAPI 有一個[官方 VS Code 擴充套件](https://marketplace.visualstudio.com/items?itemName=FastAPILabs.fastapi-vscode)（也支援 Cursor），提供許多功能，包括路徑操作瀏覽器、路徑操作搜尋、測試中的 CodeLens 導航（從測試跳到定義），以及 FastAPI Cloud 部署與日誌，全部都能從你的編輯器中使用。 + +/// + 執行即時重新載入伺服器（live server）：
```console -$ fastapi dev +$ uv run fastapi dev FastAPI Starting development server 🚀 @@ -78,7 +84,7 @@ INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) 現在，前往 [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc)。 -你將看到另一種自動文件（由 [ReDoc](https://github.com/Rebilly/ReDoc) 提供）： +你將看到另一種自動文件（由 [ReDoc](https://github.com/Redocly/redoc) 提供）： ![ReDoc](https://fastapi.tiangolo.com/img/index/index-02-redoc-simple.png) @@ -185,13 +191,13 @@ from backend.main import app 你也可以把檔案路徑傳給 `fastapi dev` 指令，它會自動猜測要使用的 FastAPI app 物件： ```console -$ fastapi dev main.py +$ uv run fastapi dev main.py ``` 或者，你也可以把 `--entrypoint` 選項傳給 `fastapi dev` 指令： ```console -$ fastapi dev --entrypoint main:app +$ uv run fastapi dev --entrypoint main:app ``` 但這樣每次執行 `fastapi` 指令時都要記得傳入正確的路徑\entrypoint。 @@ -205,7 +211,7 @@ $ fastapi dev --entrypoint main:app
```console -$ fastapi deploy +$ uv run fastapi deploy Deploying to FastAPI Cloud... @@ -232,7 +238,7 @@ CLI 會自動偵測你的 FastAPI 應用並將它部署到雲端。若你尚未 `FastAPI` 是一個直接繼承自 `Starlette` 的類別。 -你同樣可以透過 `FastAPI` 來使用 [Starlette](https://www.starlette.dev/) 所有的功能。 +你同樣可以透過 `FastAPI` 來使用 [Starlette](https://starlette.dev/) 所有的功能。 /// diff --git a/docs/zh-hant/docs/tutorial/frontend.md b/docs/zh-hant/docs/tutorial/frontend.md index fbfd8b3c55..cc7709dec0 100644 --- a/docs/zh-hant/docs/tutorial/frontend.md +++ b/docs/zh-hant/docs/tutorial/frontend.md @@ -52,7 +52,7 @@ npm run build {* ../../docs_src/frontend/tutorial002_py310.py hl[5] *} -**FastAPI** 只會對看起來像瀏覽器導覽的 `GET` 和 `HEAD` 請求使用這個 fallback。遺失的檔案，例如 JavaScript、CSS 和圖片，仍會回傳 `404`。 +**FastAPI** 只會對明確使用 `Accept: text/html` 或 `Accept: application/xhtml+xml` 接受 HTML 的 `GET` 和 `HEAD` 請求使用這個 fallback，就像瀏覽器導覽請求通常會做的那樣。遺失的檔案，例如 JavaScript、CSS 和圖片，仍會回傳 `404`。 對於只符合前端 fallback 的路徑，使用其他方法的請求，例如 `POST` 或 `PUT`，也會回傳 `404`。一般的 **FastAPI** *路徑操作*仍然比前端路由有更高優先順序。 @@ -106,9 +106,13 @@ npm run build ## 檢查目錄 { #check-directory } -預設情況下，`app.frontend()` 會在建立應用程式時檢查目錄是否存在。 +預設情況下，`app.frontend()` 會使用 `check_dir="auto"`。 -這有助於及早發現設定錯誤。例如，如果缺少前端建置輸出目錄，**FastAPI** 會在啟動時引發錯誤。 +當 `FASTAPI_ENV` 環境變數設定為 `development` 時，如果前端建置輸出目錄遺失，**FastAPI** 只會顯示警告。如果尚未設定此環境變數，[`fastapi dev` 指令](https://github.com/fastapi/fastapi-cli#fastapi-dev)會為你設定。這讓你可以在開發期間，在建置或啟動前端之前先啟動後端。 + +在任何其他環境中，**FastAPI** 會在建立應用程式時引發錯誤。這有助於在部署沒有前端檔案的應用程式之前，及早發現設定錯誤。 + +你也可以設定 `check_dir=True`，以便在建立應用程式時一律檢查目錄。 如果你的前端檔案稍後才會建立，例如在建立 app 物件之後由另一個建置步驟產生，請設定 `check_dir=False`： @@ -132,6 +136,8 @@ npm run build 來自 app、`APIRouter` 和 `include_router()` 的 dependencies 也會套用到前端回應。這對使用 cookie authentication 或類似方式保護前端很有用。 +Dependencies 也可以像一般*路徑操作*一樣修改回應 headers 並加入 background tasks。 + ## 僅限靜態建置輸出 { #static-build-output-only } `app.frontend()` 會提供你的前端建置已經產生的檔案。 diff --git a/docs/zh-hant/docs/tutorial/handling-errors.md b/docs/zh-hant/docs/tutorial/handling-errors.md index dc6d7a7cc3..b20151ee39 100644 --- a/docs/zh-hant/docs/tutorial/handling-errors.md +++ b/docs/zh-hant/docs/tutorial/handling-errors.md @@ -81,7 +81,7 @@ ## 安裝自訂例外處理器 { #install-custom-exception-handlers } -你可以使用 [Starlette 的相同例外工具](https://www.starlette.dev/exceptions/) 來加入自訂例外處理器。 +你可以使用 [Starlette 的相同例外工具](https://starlette.dev/exceptions/) 來加入自訂例外處理器。 假設你有一個自訂例外 `UnicornException`，你（或你使用的函式庫）可能會 `raise` 它。 diff --git a/docs/zh-hant/docs/tutorial/index.md b/docs/zh-hant/docs/tutorial/index.md index e20c9ca24d..5612ded8f9 100644 --- a/docs/zh-hant/docs/tutorial/index.md +++ b/docs/zh-hant/docs/tutorial/index.md @@ -10,12 +10,12 @@ 所有程式碼區塊都可以直接複製和使用（它們實際上是經過測試的 Python 檔案）。 -要運行任何範例，請將程式碼複製到 `main.py` 檔案，並使用以下命令啟動 `fastapi dev`： +要運行任何範例，請將程式碼複製到 `main.py` 檔案，並使用 `uv run` 啟動 `fastapi dev`：
```console -$ fastapi dev +$ uv run fastapi dev FastAPI Starting development server 🚀 @@ -60,36 +60,76 @@ $ fastapi dev ## 安裝 FastAPI { #install-fastapi } -第一步是安裝 FastAPI。 +第一步是設定你的專案並加入 FastAPI。 -確保你建立一個[虛擬環境](../virtual-environments.md)，啟用它，然後**安裝 FastAPI**： +安裝 [`uv`](https://docs.astral.sh/uv/getting-started/installation/)，然後建立專案並加入 FastAPI：
```console -$ pip install "fastapi[standard]" +$ uv init awesome-project --bare +$ cd awesome-project +$ uv add "fastapi[standard]" ---> 100% ```
-/// note | 注意 +`uv add` 會在 `.venv` 中建立專案的虛擬環境，將 FastAPI 加入 `pyproject.toml`，並建立 `uv.lock`，讓之後可以安裝相同的套件版本。 -當你使用 `pip install "fastapi[standard]"` 安裝時，會包含一些預設的可選標準依賴項，其中包括 `fastapi-cloud-cli`，它可以讓你部署到 [FastAPI Cloud](https://fastapicloud.com)。 +/// details | 這些指令的作用 -如果你不想包含那些可選的依賴項，你可以改為安裝 `pip install fastapi`。 +* `uv init`：建立新的 Python 專案。 +* `awesome-project`：在具有此名稱的新目錄中建立專案。 +* `--bare`：只建立最小的 `pyproject.toml` 檔案，不產生範例 `main.py`、`README.md` 或其他檔案。你將在本教學的後續步驟中自行建立應用程式檔案。 -如果你想安裝標準依賴項，但不包含 `fastapi-cloud-cli`，可以使用 `pip install "fastapi[standard-no-fastapi-cloud-cli]"` 安裝。 +接著 `cd awesome-project` 會在加入 FastAPI 前進入新的專案目錄。 + +`uv` 會使用你系統上已安裝的相容 Python 版本，或在需要時下載一個。 + +當你運行 `uv add` 時，它會選擇 FastAPI 與 FastAPI 依賴的所有套件的相容版本。它會將確切版本記錄在 `uv.lock` 中，讓之後在另一台電腦或部署應用程式時，可以安裝相同的套件版本。 + +建立或更新這個檔案稱為[**鎖定**專案依賴項](https://docs.astral.sh/uv/concepts/projects/sync/)。`uv` 會在你加入套件時自動完成。 + +/// + +/// details | FastAPI 安裝選項 + +當你使用 `uv add "fastapi[standard]"` 安裝時，會包含一些預設的可選標準依賴項，其中包括 `fastapi-cloud-cli`，它可以讓你部署到 [FastAPI Cloud](https://fastapicloud.com)。 + +如果你不想包含那些可選的依賴項，你可以改為安裝 `uv add fastapi`。 + +如果你想安裝標準依賴項，但不包含 `fastapi-cloud-cli`，可以使用 `uv add "fastapi[standard-no-fastapi-cloud-cli]"` 安裝。 + +/// + +/// details | 改用 `pip` + +如果你偏好手動管理虛擬環境與套件，請建立並啟用虛擬環境，然後使用 `pip install "fastapi[standard]"` 安裝 FastAPI。 + +請閱讀[虛擬環境指南](https://tiangolo.com/guides/virtual-environments/)以取得詳細步驟。 /// -/// tip +## AI Agent 技能 { #ai-agent-skills } + +FastAPI 包含給 AI coding agent 使用的官方技能。它隨套件一起提供，因此其指引會與你專案中安裝的 FastAPI 版本保持一致，並在你更新 FastAPI 時一起更新。 -FastAPI 提供了 [VS Code 官方擴充功能](https://marketplace.visualstudio.com/items?itemName=FastAPILabs.fastapi-vscode)（以及 Cursor），包含許多功能，例如路徑操作探索器、路徑操作搜尋、測試中的 CodeLens 導航（從測試跳到定義）、以及 FastAPI Cloud 的部署與日誌，全部可直接在你的編輯器中完成。 +在你的專案中安裝 FastAPI 後，你可以使用 Library Skills 安裝這個技能： + +```bash +uvx library-skills +``` + +/// note + +`uvx` 是 `uv tool run` 的別名。它會在暫時且隔離的環境中運行 Library Skills，同時 Library Skills 會掃描你專案中已安裝的套件。 /// +這個技能相容於 Codex、Claude Code、Cursor、GitHub Copilot、Gemini CLI、Pi、OpenCode，以及大多數其他 coding agent。若使用 Claude Code，當系統詢問要將技能安裝到哪裡時，請選擇 `.claude/skills`。 + ## 進階使用者指南 { #advanced-user-guide } 還有一個**進階使用者指南**你可以在讀完這個**教學 - 使用者指南**後再閱讀。 diff --git a/docs/zh-hant/docs/tutorial/middleware.md b/docs/zh-hant/docs/tutorial/middleware.md index 42a922d354..fcf9a36e39 100644 --- a/docs/zh-hant/docs/tutorial/middleware.md +++ b/docs/zh-hant/docs/tutorial/middleware.md @@ -37,7 +37,7 @@ 請記得，自訂的非標準標頭可以[使用 `X-` 前綴](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers)。 -但如果你有自訂標頭並希望瀏覽器端的用戶端能看到它們，你需要在 CORS 設定（[CORS（跨來源資源共用）](cors.md)）中使用 [Starlette 的 CORS 文件](https://www.starlette.dev/middleware/#corsmiddleware)所記載的參數 `expose_headers` 將它們加入。 +但如果你有自訂標頭並希望瀏覽器端的用戶端能看到它們，你需要在 CORS 設定（[CORS（跨來源資源共用）](cors.md)）中使用 [Starlette 的 CORS 文件](https://starlette.dev/middleware/#corsmiddleware)所記載的參數 `expose_headers` 將它們加入。 /// diff --git a/docs/zh-hant/docs/tutorial/path-params.md b/docs/zh-hant/docs/tutorial/path-params.md index 4e8d3dd8f5..98525feae6 100644 --- a/docs/zh-hant/docs/tutorial/path-params.md +++ b/docs/zh-hant/docs/tutorial/path-params.md @@ -92,7 +92,7 @@ ## 基於標準的優勢與替代文件 { #standards-based-benefits-alternative-documentation } -而且因為產生的 schema 來自 [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.1.0.md) 標準，有很多相容的工具可用。 +而且因為產生的 schema 來自 [OpenAPI](https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md) 標準，有很多相容的工具可用。 因此，**FastAPI** 本身也提供另一種 API 文件（使用 ReDoc），你可以在 [http://127.0.0.1:8000/redoc](http://127.0.0.1:8000/redoc) 存取： @@ -102,7 +102,7 @@ ## Pydantic { #pydantic } -所有資料驗證都由 [Pydantic](https://docs.pydantic.dev/) 在底層處理，因此你能直接受惠。而且你可以放心使用。 +所有資料驗證都由 [Pydantic](https://pydantic.dev/docs/) 在底層處理，因此你能直接受惠。而且你可以放心使用。 你可以用相同的型別宣告搭配 `str`、`float`、`bool` 與許多更複雜的資料型別。 @@ -248,4 +248,4 @@ OpenAPI 並不支援直接宣告一個「路徑參數」內再包含一個「路 而且你只要宣告一次就好。 -這大概是 **FastAPI** 相較於其他框架最明顯的優勢之一（除了原始效能之外）。 +這大概是 **FastAPI** 相較於其他框架最明顯的優勢（除了原始效能之外）。 diff --git a/docs/zh-hant/docs/tutorial/query-params-str-validations.md b/docs/zh-hant/docs/tutorial/query-params-str-validations.md index 99690708ef..61e6ca1683 100644 --- a/docs/zh-hant/docs/tutorial/query-params-str-validations.md +++ b/docs/zh-hant/docs/tutorial/query-params-str-validations.md @@ -370,11 +370,11 @@ http://127.0.0.1:8000/items/?item-query=foobaritems 這種情況下，你可以使用**自訂驗證函式**，它會在一般驗證之後套用（例如先確認值是 `str` 之後）。 -你可以在 `Annotated` 中使用 [Pydantic 的 `AfterValidator`](https://docs.pydantic.dev/latest/concepts/validators/#field-after-validator) 來達成。 +你可以在 `Annotated` 中使用 [Pydantic 的 `AfterValidator`](https://pydantic.dev/docs/validation/latest/concepts/validators/#field-after-validator) 來達成。 /// tip | 提示 -Pydantic 也有 [`BeforeValidator`](https://docs.pydantic.dev/latest/concepts/validators/#field-before-validator) 等等。🤓 +Pydantic 也有 [`BeforeValidator`](https://pydantic.dev/docs/validation/latest/concepts/validators/#field-before-validator) 等等。🤓 /// diff --git a/docs/zh-hant/docs/tutorial/request-files.md b/docs/zh-hant/docs/tutorial/request-files.md index 979a579ebd..7d6bdede3c 100644 --- a/docs/zh-hant/docs/tutorial/request-files.md +++ b/docs/zh-hant/docs/tutorial/request-files.md @@ -7,10 +7,10 @@ 若要接收上傳的檔案，請先安裝 [`python-multipart`](https://github.com/Kludex/python-multipart)。 -請先建立並啟用一個[虛擬環境](../virtual-environments.md)，然後安裝，例如： +將它加入你的專案： ```console -$ pip install python-multipart +$ uv add python-multipart ``` 因為上傳的檔案是以「表單資料」送出的。 diff --git a/docs/zh-hant/docs/tutorial/request-form-models.md b/docs/zh-hant/docs/tutorial/request-form-models.md index 9bafb0ef7f..681a0e0c09 100644 --- a/docs/zh-hant/docs/tutorial/request-form-models.md +++ b/docs/zh-hant/docs/tutorial/request-form-models.md @@ -6,10 +6,10 @@ 要使用表單，首先安裝 [`python-multipart`](https://github.com/Kludex/python-multipart)。 -請先建立[虛擬環境](../virtual-environments.md)、啟用後再安裝，例如： +將它加入你的專案： ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// @@ -26,7 +26,7 @@ $ pip install python-multipart {* ../../docs_src/request_form_models/tutorial001_an_py310.py hl[9:11,15] *} -**FastAPI** 會從請求中的 **表單資料** 擷取 **各欄位** 的資料，並將這些資料組成你定義的 Pydantic 模型實例。 +**FastAPI** 會從請求中的 **表單資料** **擷取** **每個欄位** 的資料，並給你所定義的 Pydantic 模型。 ## 檢視文件 { #check-the-docs } @@ -38,7 +38,7 @@ $ pip install python-multipart ## 禁止額外的表單欄位 { #forbid-extra-form-fields } -在某些特殊情況（可能不常見）下，你可能希望僅允許 Pydantic 模型中宣告的表單欄位，並禁止任何額外欄位。 +在某些特殊情況（可能不常見）下，你可能希望將 **表單欄位** **限制** 為只有 Pydantic 模型中宣告的欄位。並**禁止**任何**額外**欄位。 /// note | 注意 @@ -50,7 +50,7 @@ $ pip install python-multipart {* ../../docs_src/request_form_models/tutorial002_an_py310.py hl[12] *} -如果用戶端嘗試傳送額外資料，將會收到錯誤回應。 +如果用戶端嘗試傳送額外資料，將會收到**錯誤**回應。 例如，用戶端若送出以下表單欄位： 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 2db9e283b4..91ea5cdf2c 100644 --- a/docs/zh-hant/docs/tutorial/request-forms-and-files.md +++ b/docs/zh-hant/docs/tutorial/request-forms-and-files.md @@ -6,10 +6,10 @@ 要接收上傳的檔案與/或表單資料，請先安裝 [`python-multipart`](https://github.com/Kludex/python-multipart)。 -請先建立並啟用一個 [虛擬環境](../virtual-environments.md)，然後再安裝，例如： +將它加入你的專案： ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// diff --git a/docs/zh-hant/docs/tutorial/request-forms.md b/docs/zh-hant/docs/tutorial/request-forms.md index 5907791682..d116d4a428 100644 --- a/docs/zh-hant/docs/tutorial/request-forms.md +++ b/docs/zh-hant/docs/tutorial/request-forms.md @@ -7,10 +7,10 @@ 要使用表單，請先安裝 [`python-multipart`](https://github.com/Kludex/python-multipart)。 -請先建立並啟用一個[虛擬環境](../virtual-environments.md)，然後再安裝，例如： +將它加入你的專案： ```console -$ pip install python-multipart +$ uv add python-multipart ``` /// diff --git a/docs/zh-hant/docs/tutorial/response-model.md b/docs/zh-hant/docs/tutorial/response-model.md index be276945b1..1a20dab2f0 100644 --- a/docs/zh-hant/docs/tutorial/response-model.md +++ b/docs/zh-hant/docs/tutorial/response-model.md @@ -76,16 +76,16 @@ FastAPI 會使用這個 `response_model` 來做所有的資料文件、驗證等 要使用 `EmailStr`，請先安裝 [`email-validator`](https://github.com/JoshData/python-email-validator)。 -請先建立一個[虛擬環境](../virtual-environments.md)、啟用它，然後安裝，例如： +將它加入你的專案： ```console -$ pip install email-validator +$ uv add email-validator ``` -或： +或使用： ```console -$ pip install "pydantic[email]" +$ uv add "pydantic[email]" ``` /// @@ -258,7 +258,7 @@ FastAPI 在內部會搭配 Pydantic 做一些事情，來確保不會把類別 * `response_model_exclude_defaults=True` * `response_model_exclude_none=True` -如 [Pydantic 文件](https://docs.pydantic.dev/1.10/usage/exporting_models/#modeldict)中對 `exclude_defaults` 與 `exclude_none` 的說明。 +如 [Pydantic 文件](https://pydantic.dev/docs/validation/latest/concepts/serialization/#excluding-and-including-fields-based-on-their-value)中對 `exclude_defaults` 與 `exclude_none` 的說明。 /// diff --git a/docs/zh-hant/docs/tutorial/schema-extra-example.md b/docs/zh-hant/docs/tutorial/schema-extra-example.md index 8cca5003a0..d2f196c1c1 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](https://docs.pydantic.dev/latest/api/config/)。 +你可以使用屬性 `model_config`（接收一個 `dict`），詳見 [Pydantic 文件：Configuration](https://pydantic.dev/docs/validation/latest/api/pydantic/config/)。 你可以將 `"json_schema_extra"` 設為一個 `dict`，其中包含你想在產生的 JSON Schema 中出現的任何額外資料，包括 `examples`。 @@ -197,6 +197,6 @@ JSON Schema 中新的 `examples` 欄位「就是一個 `list`」的範例集合 ### 總結 { #summary } -我以前常說我不太喜歡歷史……結果現在在這裡講「科技史」。😅 +我以前常說我不太喜歡歷史...結果現在在這裡講「科技史」。😅 簡而言之，**升級到 FastAPI 0.99.0 或以上**，事情會更**簡單、一致又直覺**，而且你不需要了解這些歷史細節。😎 diff --git a/docs/zh-hant/docs/tutorial/security/first-steps.md b/docs/zh-hant/docs/tutorial/security/first-steps.md index 7640a45564..dbf1542a5e 100644 --- a/docs/zh-hant/docs/tutorial/security/first-steps.md +++ b/docs/zh-hant/docs/tutorial/security/first-steps.md @@ -26,14 +26,14 @@ /// note -當你使用 `pip install "fastapi[standard]"` 指令安裝時，[`python-multipart`](https://github.com/Kludex/python-multipart) 套件會隨 **FastAPI** 自動安裝。 +當你執行 `uv add "fastapi[standard]"` 指令時，[`python-multipart`](https://github.com/Kludex/python-multipart) 套件會隨 **FastAPI** 自動安裝。 -不過若只執行 `pip install fastapi`，預設不會包含 `python-multipart`。 +不過若你使用 `uv add fastapi` 指令，預設不會包含 `python-multipart` 套件。 -若要手動安裝，請先建立並啟用一個[虛擬環境](../../virtual-environments.md)，接著執行： +若要手動安裝，請將它加入你的專案： ```console -$ pip install python-multipart +$ uv add python-multipart ``` 因為 **OAuth2** 會以「form data」傳送 `username` 與 `password`。 @@ -45,7 +45,7 @@ $ pip install python-multipart
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -72,7 +72,7 @@ $ fastapi dev -/// note | 注意 +/// note 不管你在表單輸入什麼，現在都還不會成功；等等我們會把它完成。 @@ -98,19 +98,19 @@ OAuth2 的設計讓後端或 API 可以獨立於執行使用者驗證的伺服 簡化來看流程如下： -- 使用者在前端輸入 `username` 與 `password`，按下 `Enter`。 -- 前端（在使用者的瀏覽器中執行）把 `username` 與 `password` 傳到我們 API 的特定 URL（在程式中宣告為 `tokenUrl="token"`）。 -- API 檢查 `username` 與 `password`，並回應一個「token（權杖）」（我們還沒實作這部分）。 - - 「token（權杖）」就是一段字串，之後可用來識別並驗證此使用者。 - - 通常 token 會設定一段時間後失效。 - - 因此使用者之後需要重新登入。 - - 若 token 被竊取，風險也較低；它不像永遠有效的萬用鑰匙（多數情況下）。 -- 前端會暫存這個 token。 -- 使用者在前端點擊，前往前端網頁應用程式的另一個區段。 -- 前端需要再向 API 取得資料。 - - 但該端點需要驗證。 - - 因此為了向 API 驗證，請求會帶上一個 `Authorization` 標頭，值為 `Bearer ` 加上 token。 - - 例如 token 是 `foobar`，則 `Authorization` 標頭內容為：`Bearer foobar`。 +* 使用者在前端輸入 `username` 與 `password`，按下 `Enter`。 +* 前端（在使用者的瀏覽器中執行）把 `username` 與 `password` 傳到我們 API 的特定 URL（在程式中宣告為 `tokenUrl="token"`）。 +* API 檢查 `username` 與 `password`，並回應一個「token（權杖）」（我們還沒實作這部分）。 + * 「token（權杖）」就是一段字串，之後可用來識別並驗證此使用者。 + * 通常 token 會設定一段時間後失效。 + * 因此使用者之後需要重新登入。 + * 若 token 被竊取，風險也較低；它不像永遠有效的萬用鑰匙（多數情況下）。 +* 前端會暫存這個 token。 +* 使用者在前端點擊，前往前端網頁應用程式的另一個區段。 +* 前端需要再向 API 取得資料。 + * 但該端點需要驗證。 + * 因此為了向 API 驗證，請求會帶上一個 `Authorization` 標頭，值為 `Bearer ` 加上 token。 + * 例如 token 是 `foobar`，則 `Authorization` 標頭內容為：`Bearer foobar`。 ## **FastAPI** 的 `OAuth2PasswordBearer` { #fastapis-oauth2passwordbearer } diff --git a/docs/zh-hant/docs/tutorial/security/oauth2-jwt.md b/docs/zh-hant/docs/tutorial/security/oauth2-jwt.md index dc75092b4e..499a3b2af0 100644 --- a/docs/zh-hant/docs/tutorial/security/oauth2-jwt.md +++ b/docs/zh-hant/docs/tutorial/security/oauth2-jwt.md @@ -30,12 +30,12 @@ eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4 我們需要安裝 `PyJWT` 才能在 Python 中產生與驗證 JWT 權杖。 -請先建立並啟用一個[虛擬環境](../../virtual-environments.md)，然後安裝 `pyjwt`： +將 `pyjwt` 加入你的專案：
```console -$ pip install pyjwt +$ uv add pyjwt ---> 100% ``` @@ -72,12 +72,12 @@ pwdlib 是一個很棒的 Python 套件，用來處理密碼雜湊。 建議使用的演算法是「Argon2」。 -請先建立並啟用一個[虛擬環境](../../virtual-environments.md)，然後以 Argon2 支援安裝 pwdlib： +將帶有 Argon2 的 `pwdlib` 加入你的專案：
```console -$ pip install "pwdlib[argon2]" +$ uv add "pwdlib[argon2]" ---> 100% ``` diff --git a/docs/zh-hant/docs/tutorial/sql-databases.md b/docs/zh-hant/docs/tutorial/sql-databases.md index 3a0e43d844..aa1e4504d1 100644 --- a/docs/zh-hant/docs/tutorial/sql-databases.md +++ b/docs/zh-hant/docs/tutorial/sql-databases.md @@ -34,12 +34,12 @@ ## 安裝 `SQLModel` { #install-sqlmodel } -首先，請先建立你的[虛擬環境](../virtual-environments.md)、啟用它，然後安裝 `sqlmodel`： +將 `sqlmodel` 加入你的專案：
```console -$ pip install sqlmodel +$ uv add sqlmodel ---> 100% ``` @@ -152,7 +152,7 @@ SQLModel 之後會提供包裝 Alembic 的遷移工具，但目前你可以直
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` @@ -337,7 +337,7 @@ $ fastapi dev
```console -$ fastapi dev +$ uv run fastapi dev INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit) ``` diff --git a/docs/zh-hant/docs/tutorial/static-files.md b/docs/zh-hant/docs/tutorial/static-files.md index 0d6369eef7..fba526b122 100644 --- a/docs/zh-hant/docs/tutorial/static-files.md +++ b/docs/zh-hant/docs/tutorial/static-files.md @@ -12,8 +12,8 @@ ## 使用 `StaticFiles` { #use-staticfiles } -- 匯入 `StaticFiles`。 -- 在特定路徑上「掛載」一個 `StaticFiles()` 實例。 +* 匯入 `StaticFiles`。 +* 在特定路徑上「掛載」一個 `StaticFiles()` 實例。 {* ../../docs_src/static_files/tutorial001_py310.py hl[2,6] *} @@ -45,4 +45,4 @@ ## 更多資訊 { #more-info } -如需更多細節與選項，請參考 [Starlette 關於靜態檔案的文件](https://www.starlette.dev/staticfiles/)。 +如需更多細節與選項，請參考 [Starlette 關於靜態檔案的文件](https://starlette.dev/staticfiles/)。 diff --git a/docs/zh-hant/docs/tutorial/testing.md b/docs/zh-hant/docs/tutorial/testing.md index 09f6c0ec7a..fbc5b107d2 100644 --- a/docs/zh-hant/docs/tutorial/testing.md +++ b/docs/zh-hant/docs/tutorial/testing.md @@ -1,6 +1,6 @@ # 測試 { #testing } -多虧了 [Starlette](https://www.starlette.dev/testclient/)，測試 **FastAPI** 應用既簡單又好用。 +多虧了 [Starlette](https://starlette.dev/testclient/)，測試 **FastAPI** 應用既簡單又好用。 它是基於 [HTTPX](https://www.python-httpx.org) 打造，而 HTTPX 的設計又參考了 Requests，所以用起來非常熟悉、直覺。 @@ -12,10 +12,10 @@ 要使用 `TestClient`，請先安裝 [`httpx`](https://www.python-httpx.org)。 -請先建立並啟用一個[虛擬環境](../virtual-environments.md)，然後安裝，例如： +把它加入你的專案： ```console -$ pip install httpx +$ uv add httpx ``` /// @@ -156,12 +156,12 @@ $ pip install httpx 接下來，你只需要安裝 `pytest`。 -請先建立並啟用一個[虛擬環境](../virtual-environments.md)，然後安裝，例如： +把它加入你的專案：
```console -$ pip install pytest +$ uv add pytest ---> 100% ``` @@ -175,7 +175,7 @@ $ pip install pytest
```console -$ pytest +$ uv run pytest ================ test session starts ================ platform linux -- Python 3.6.9, pytest-5.3.5, py-1.8.1, pluggy-0.13.1 diff --git a/docs/zh-hant/docs/virtual-environments.md b/docs/zh-hant/docs/virtual-environments.md index 5503634133..a9c306eaeb 100644 --- a/docs/zh-hant/docs/virtual-environments.md +++ b/docs/zh-hant/docs/virtual-environments.md @@ -1,864 +1,35 @@ # 虛擬環境 { #virtual-environments } -當你在 Python 專案中工作時，你可能會需要使用一個**虛擬環境**（或類似的機制）來隔離你為每個專案安裝的套件。 +當你在 Python 專案中工作時，你應該使用**虛擬環境**來隔離每個專案安裝的套件。 -/// note - -如果你已經了解虛擬環境，知道如何建立和使用它們，你可以考慮跳過這一部分。🤓 - -/// - -/// tip - -**虛擬環境**和**環境變數**是不同的。 - -**環境變數**是系統中的一個變數，可以被程式使用。 - -**虛擬環境**是一個包含一些檔案的目錄。 - -/// - -/// note - -這個頁面將教你如何使用**虛擬環境**以及了解它們的工作原理。 - -如果你計畫使用一個**可以為你管理一切的工具**（包括安裝 Python），試試 [uv](https://github.com/astral-sh/uv)。 - -/// +對於 FastAPI 專案，我建議使用 [uv](https://docs.astral.sh/uv/) 來管理專案、其依賴項和虛擬環境。 ## 建立一個專案 { #create-a-project } -首先，為你的專案建立一個目錄。 - -我通常會在我的主目錄下建立一個名為 `code` 的目錄。 - -在這個目錄下，我再為每個專案建立一個目錄。 +使用[官方安裝指南](https://docs.astral.sh/uv/getting-started/installation/)安裝 `uv`，然後建立一個專案：
```console -// 進入主目錄 -$ cd -// 建立一個用於存放所有程式碼專案的目錄 -$ mkdir code -// 進入 code 目錄 -$ cd code -// 建立一個用於存放這個專案的目錄 -$ mkdir awesome-project -// 進入這個專案的目錄 +$ uv init awesome-project --bare $ cd awesome-project +$ uv add "fastapi[standard]" ```
-## 建立一個虛擬環境 { #create-a-virtual-environment } - -在開始一個 Python 專案的**第一時間**，**在你的專案內部**建立一個虛擬環境。 - -/// tip - -你只需要**在每個專案中操作一次**，而不是每次工作時都操作。 - -/// - -//// tab | `venv` - -你可以使用 Python 自帶的 `venv` 模組來建立一個虛擬環境。 - -
- -```console -$ python -m venv .venv -``` - -
- -/// details | 上述指令的含義 - -* `python`: 使用名為 `python` 的程式 -* `-m`: 以腳本的方式呼叫一個模組，我們將告訴它接下來使用哪個模組 -* `venv`: 使用名為 `venv` 的模組，這個模組通常隨 Python 一起安裝 -* `.venv`: 在新目錄 `.venv` 中建立虛擬環境 - -/// - -//// - -//// tab | `uv` - -如果你安裝了 [`uv`](https://github.com/astral-sh/uv)，你也可以使用它來建立一個虛擬環境。 - -
- -```console -$ uv venv -``` - -
- -/// tip - -預設情況下，`uv` 會在一個名為 `.venv` 的目錄中建立一個虛擬環境。 - -但你可以透過傳遞一個額外的引數來自訂它，指定目錄的名稱。 - -/// - -//// - -這個指令會在一個名為 `.venv` 的目錄中建立一個新的虛擬環境。 - -/// details | `.venv`，或是其他名稱 - -你可以在不同的目錄下建立虛擬環境，但通常我們會把它命名為 `.venv`。 - -/// - -## 啟動虛擬環境 { #activate-the-virtual-environment } - -啟動新的虛擬環境來確保你運行的任何 Python 指令或安裝的套件都能使用到它。 - -/// tip - -**每次**開始一個**新的終端會話**來在這個專案工作時，你都需要執行這個操作。 - -/// - -//// tab | Linux, macOS - -
- -```console -$ source .venv/bin/activate -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ .venv\Scripts\Activate.ps1 -``` - -
- -//// - -//// tab | Windows Bash - -或者，如果你在 Windows 上使用 Bash（例如 [Git Bash](https://gitforwindows.org/)）： - -
- -```console -$ source .venv/Scripts/activate -``` - -
- -//// - -/// tip - -每次你在這個環境中安裝一個**新的套件**時，都需要**再次啟用**這個環境。 - -這麼做確保了當你使用一個由這個套件安裝的**終端（CLI）程式**時，你使用的是你的虛擬環境中的程式，而不是全域安裝、可能版本不同的程式。 - -/// - -## 檢查虛擬環境是否啟動 { #check-the-virtual-environment-is-active } - -檢查虛擬環境是否啟動（前面的指令是否生效）。 - -/// tip - -這是**非必需的**，但這是一個很好的方法，可以**檢查**一切是否按預期工作，以及你是否使用了你打算使用的虛擬環境。 - -/// - -//// tab | Linux, macOS, Windows Bash - -
- -```console -$ which python - -/home/user/code/awesome-project/.venv/bin/python -``` - -
- -如果它顯示了在你專案（在這個例子中是 `awesome-project`）的 `.venv/bin/python` 中的 `python` 二進位檔案，那麼它就生效了。🎉 - -//// +`uv` 會自動為專案建立虛擬環境。你不需要自己建立或啟動虛擬環境。 -//// tab | Windows PowerShell +使用 `uv run` 在專案環境中執行指令，例如：
```console -$ Get-Command python - -C:\Users\user\code\awesome-project\.venv\Scripts\python +$ uv run fastapi dev ```
-如果它顯示了在你專案（在這個例子中是 `awesome-project`）的 `.venv\Scripts\python` 中的 `python` 二進位檔案，那麼它就生效了。🎉 - -//// - -## 升級 `pip` { #upgrade-pip } - -/// tip - -如果你使用 [`uv`](https://github.com/astral-sh/uv) 來安裝內容，而不是 `pip`，那麼你就不需要升級 `pip`。😎 - -/// - -如果你使用 `pip` 來安裝套件（它是 Python 的預設元件），你應該將它**升級**到最新版本。 - -在安裝套件時出現的許多奇怪的錯誤都可以透過先升級 `pip` 來解決。 - -/// tip - -通常你只需要在建立虛擬環境後**執行一次**這個操作。 - -/// - -確保虛擬環境是啟動的（使用上面的指令），然後運行： - -
- -```console -$ python -m pip install --upgrade pip - ----> 100% -``` - -
- -/// tip - -有時你在嘗試升級 pip 時，可能會遇到 **`No module named pip`** 的錯誤。 - -如果發生這種情況，請用下面的指令安裝並升級 pip： - -
- -```console -$ python -m ensurepip --upgrade - ----> 100% -``` - -
- -此指令會在未安裝 pip 時為你安裝它，並確保安裝的 pip 版本至少與 `ensurepip` 所提供的版本一樣新。 - -/// - -## 加入 `.gitignore` { #add-gitignore } - -如果你使用 **Git**（這是你應該使用的），加入一個 `.gitignore` 檔案來排除你的 `.venv` 中的所有內容。 - -/// tip - -如果你使用 [`uv`](https://github.com/astral-sh/uv) 來建立虛擬環境，它會自動為你完成這個操作，你可以跳過這一步。😎 - -/// - -/// tip - -通常你只需要在建立虛擬環境後**執行一次**這個操作。 - -/// - -
- -```console -$ echo "*" > .venv/.gitignore -``` - -
- -/// details | 上述指令的含義 - -- `echo "*"`: 將在終端中「顯示」文本 `*`（接下來的部分會對這個操作進行一些修改） -- `>`: 使左邊的指令顯示到終端的任何內容實際上都不會被顯示，而是會被寫入到右邊的檔案中 -- `.gitignore`: 被寫入文本的檔案的名稱 - -而 `*` 對於 Git 來說意味著「所有內容」。所以，它會忽略 `.venv` 目錄中的所有內容。 - -該指令會建立一個名為 `.gitignore` 的檔案，內容如下： - -```gitignore -* -``` - -/// - -## 安裝套件 { #install-packages } - -在啟用虛擬環境後，你可以在其中安裝套件。 - -/// tip - -當你需要安裝或升級套件時，執行本操作**一次**； - -如果你需要再升級版本或新增套件，你可以**再次執行此操作**。 - -/// - -### 直接安裝套件 { #install-packages-directly } - -如果你急於安裝，不想使用檔案來聲明專案的套件依賴，你可以直接安裝它們。 - -/// tip - -將程式所需的套件及其版本放在檔案中（例如 `requirements.txt` 或 `pyproject.toml`）是個好（而且非常好）的主意。 - -/// - -//// tab | `pip` - -
- -```console -$ pip install "fastapi[standard]" - ----> 100% -``` - -
- -//// - -//// tab | `uv` - -如果你有 [`uv`](https://github.com/astral-sh/uv): - -
- -```console -$ uv pip install "fastapi[standard]" ----> 100% -``` - -
- -//// - -### 從 `requirements.txt` 安裝 { #install-from-requirements-txt } - -如果你有一個 `requirements.txt` 檔案，你可以使用它來安裝其中的套件。 - -//// tab | `pip` - -
- -```console -$ pip install -r requirements.txt ----> 100% -``` - -
- -//// - -//// tab | `uv` - -如果你有 [`uv`](https://github.com/astral-sh/uv): - -
- -```console -$ uv pip install -r requirements.txt ----> 100% -``` - -
- -//// - -/// details | `requirements.txt` - -一個包含一些套件的 `requirements.txt` 檔案看起來應該是這樣的： - -```requirements.txt -fastapi[standard]==0.113.0 -pydantic==2.8.0 -``` - -/// - -## 執行程式 { #run-your-program } - -在啟用虛擬環境後，你可以執行你的程式，它將使用虛擬環境中的 Python 和你在其中安裝的套件。 - -
- -```console -$ python main.py - -Hello World -``` - -
- -## 設定編輯器 { #configure-your-editor } - -你可能會用到編輯器，請確保設定它使用你建立的相同虛擬環境（它可能會自動偵測到），以便你可以獲得自動完成和內嵌錯誤提示。 - -例如： - -* [VS Code](https://code.visualstudio.com/docs/python/environments#_select-and-activate-an-environment) -* [PyCharm](https://www.jetbrains.com/help/pycharm/creating-virtual-environment.html) - -/// tip - -通常你只需要在建立虛擬環境時執行此操作**一次**。 - -/// - -## 退出虛擬環境 { #deactivate-the-virtual-environment } - -當你完成工作後，你可以**退出**虛擬環境。 - -
- -```console -$ deactivate -``` - -
- -這樣，當你執行 `python` 時它不會嘗試從已安裝套件的虛擬環境中執行。 - -## 開始工作 { #ready-to-work } - -現在你已經準備好開始你的工作了。 - - - -/// tip - -你想要理解上面的所有內容嗎？ - -繼續閱讀。👇🤓 - -/// - -## 為什麼要使用虛擬環境 { #why-virtual-environments } - -你需要安裝 [Python](https://www.python.org/) 才能使用 FastAPI。 - -接下來，你需要**安裝** FastAPI 以及你想使用的其他**套件**。 - -要安裝套件，你通常會使用隨 Python 一起提供的 `pip` 指令（或類似的替代工具）。 - -然而，如果你直接使用 `pip`，套件將會安裝在你的**全域 Python 環境**中（即 Python 的全域安裝）。 - -### 存在的問題 { #the-problem } - -那麼，在全域 Python 環境中安裝套件有什麼問題呢？ - -有時候，你可能會開發許多不同的程式，而這些程式各自依賴於**不同的套件**；有些專案甚至需要依賴於**相同套件的不同版本**。😱 - -例如，你可能會建立一個名為 `philosophers-stone` 的專案，這個程式依賴於另一個名為 **`harry` 的套件，並使用版本 `1`**。因此，你需要安裝 `harry`。 - -```mermaid -flowchart LR - stone(philosophers-stone) -->|需要| harry-1[harry v1] -``` - -然而，在此之後，你又建立了另一個名為 `prisoner-of-azkaban` 的專案，而這個專案也依賴於 `harry`，但需要的是 **`harry` 版本 `3`**。 - -```mermaid -flowchart LR - azkaban(prisoner-of-azkaban) --> |需要| harry-3[harry v3] -``` - -現在的問題是，如果你在全域環境中安裝套件而不是在本地**虛擬環境**中，你將面臨選擇安裝哪個版本的 `harry` 的困境。 - -如果你想運行 `philosophers-stone`，你需要先安裝 `harry` 版本 `1`，例如： - -
- -```console -$ pip install "harry==1" -``` - -
- -然後你會在全域 Python 環境中安裝 `harry` 版本 `1`。 - -```mermaid -flowchart LR - subgraph global[全域環境] - harry-1[harry v1] - end - subgraph stone-project[專案 philosophers-stone] - stone(philosophers-stone) -->|需要| harry-1 - end -``` - -但如果你想運行 `prisoner-of-azkaban`，你需要解除安裝 `harry` 版本 `1` 並安裝 `harry` 版本 `3`（或者只要你安裝版本 `3`，版本 `1` 就會自動移除）。 - -
- -```console -$ pip install "harry==3" -``` - -
- -於是，你在全域 Python 環境中安裝了 `harry` 版本 `3`。 - -如果你再次嘗試運行 `philosophers-stone`，很可能會**無法正常運作**，因為它需要的是 `harry` 版本 `1`。 - -```mermaid -flowchart LR - subgraph global[全域環境] - harry-1[harry v1] - style harry-1 fill:#ccc,stroke-dasharray: 5 5 - harry-3[harry v3] - end - subgraph stone-project[專案 philosophers-stone] - stone(philosophers-stone) -.-x|⛔️| harry-1 - end - subgraph azkaban-project[專案 prisoner-of-azkaban] - azkaban(prisoner-of-azkaban) --> |需要| harry-3 - end -``` - -/// tip - -Python 套件在推出**新版本**時通常會儘量**避免破壞性更改**，但最好還是要謹慎，在安裝新版本前進行測試，以確保一切能正常運行。 - -/// - -現在，想像一下如果有**許多**其他**套件**，它們都是你的**專案所依賴的**。這樣是非常難以管理的。你可能會發現有些專案使用了一些**不相容的套件版本**，而無法得知為什麼某些程式無法正常運作。 - -此外，取決於你的作業系統（例如 Linux、Windows、macOS），它可能已經預先安裝了 Python。在這種情況下，它可能已經有一些系統所需的套件和特定版本。如果你在全域 Python 環境中安裝套件，可能會**破壞**某些隨作業系統一起安裝的程式。 - -## 套件安裝在哪裡 { #where-are-packages-installed } - -當你安裝 Python 時，它會在你的電腦中建立一些目錄並放置一些檔案。 - -其中一些目錄專門用來存放你所安裝的所有套件。 - -當你運行： - -
- -```console -// 先別去運行這個指令，這只是個示例 🤓 -$ pip install "fastapi[standard]" ----> 100% -``` - -
- -這會從 [PyPI](https://pypi.org/project/fastapi/) 下載一個壓縮檔案，其中包含 FastAPI 的程式碼。 - -它還會**下載** FastAPI 所依賴的其他套件的檔案。 - -接著，它會**解壓**所有這些檔案，並將它們放在你的電腦中的某個目錄中。 - -預設情況下，這些下載和解壓的檔案會放置於隨 Python 安裝的目錄中，即**全域環境**。 - -## 什麼是虛擬環境 { #what-are-virtual-environments } - -解決套件都安裝在全域環境中的問題方法是為你所做的每個專案使用一個**虛擬環境**。 - -虛擬環境是一個**目錄**，與全域環境非常相似，你可以在其中針對某個專案安裝套件。 - -這樣，每個專案都會有自己的虛擬環境（`.venv` 目錄），其中包含自己的套件。 - -```mermaid -flowchart TB - subgraph stone-project[專案 philosophers-stone] - stone(philosophers-stone) --->|需要| harry-1 - subgraph venv1[.venv] - harry-1[harry v1] - end - end - subgraph azkaban-project[專案 prisoner-of-azkaban] - azkaban(prisoner-of-azkaban) --->|需要| harry-3 - subgraph venv2[.venv] - harry-3[harry v3] - end - end - stone-project ~~~ azkaban-project -``` - -## 啟用虛擬環境意味著什麼 { #what-does-activating-a-virtual-environment-mean } - -當你啟用了虛擬環境，例如： - -//// tab | Linux, macOS - -
- -```console -$ source .venv/bin/activate -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ .venv\Scripts\Activate.ps1 -``` - -
- -//// - -//// tab | Windows Bash - -或者如果你在 Windows 上使用 Bash（例如 [Git Bash](https://gitforwindows.org/)）： - -
- -```console -$ source .venv/Scripts/activate -``` - -
- -//// - -這個命令會建立或修改一些[環境變數](environment-variables.md)，這些環境變數將在接下來的指令中可用。 - -其中之一是 `PATH` 變數。 - -/// tip - -你可以在 [環境變數](environment-variables.md#path-environment-variable) 部分了解更多關於 `PATH` 環境變數的內容。 - -/// - -啟用虛擬環境會將其路徑 `.venv/bin`（在 Linux 和 macOS 上）或 `.venv\Scripts`（在 Windows 上）加入到 `PATH` 環境變數中。 - -假設在啟用環境之前，`PATH` 變數看起來像這樣： - -//// tab | Linux, macOS - -```plaintext -/usr/bin:/bin:/usr/sbin:/sbin -``` - -這意味著系統會在以下目錄中查找程式： - -* `/usr/bin` -* `/bin` -* `/usr/sbin` -* `/sbin` - -//// - -//// tab | Windows - -```plaintext -C:\Windows\System32 -``` - -這意味著系統會在以下目錄中查找程式： - -* `C:\Windows\System32` - -//// - -啟用虛擬環境後，`PATH` 變數會變成這樣： - -//// tab | Linux, macOS - -```plaintext -/home/user/code/awesome-project/.venv/bin:/usr/bin:/bin:/usr/sbin:/sbin -``` - -這意味著系統現在會首先在以下目錄中查找程式： - -```plaintext -/home/user/code/awesome-project/.venv/bin -``` - -然後再在其他目錄中查找。 - -因此，當你在終端機中輸入 `python` 時，系統會在以下目錄中找到 Python 程式： - -```plaintext -/home/user/code/awesome-project/.venv/bin/python -``` - -並使用這個。 - -//// - -//// tab | Windows - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts;C:\Windows\System32 -``` - -這意味著系統現在會首先在以下目錄中查找程式： - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts -``` - -然後再在其他目錄中查找。 - -因此，當你在終端機中輸入 `python` 時，系統會在以下目錄中找到 Python 程式： - -```plaintext -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -並使用這個。 - -//// - -一個重要的細節是，虛擬環境路徑會被放在 `PATH` 變數的**開頭**。系統會在找到任何其他可用的 Python **之前**找到它。這樣，當你運行 `python` 時，它會使用**虛擬環境中的** Python，而不是任何其他 `python`（例如，全域環境中的 `python`）。 - -啟用虛擬環境還會改變其他一些內容，但這是它所做的最重要的事情之一。 - -## 檢查虛擬環境 { #checking-a-virtual-environment } - -當你檢查虛擬環境是否啟動時，例如： - -//// tab | Linux, macOS, Windows Bash - -
- -```console -$ which python - -/home/user/code/awesome-project/.venv/bin/python -``` - -
- -//// - -//// tab | Windows PowerShell - -
- -```console -$ Get-Command python - -C:\Users\user\code\awesome-project\.venv\Scripts\python -``` - -
- -//// - -這表示將使用的 `python` 程式是**在虛擬環境中**的那一個。 - -在 Linux 和 macOS 中使用 `which`，在 Windows PowerShell 中使用 `Get-Command`。 - -這個指令的運作方式是，它會在 `PATH` 環境變數中搜尋，依序**逐個路徑**查找名為 `python` 的程式。一旦找到，它會**顯示該程式的路徑**。 - -最重要的是，當你呼叫 `python` 時，將執行的就是這個確切的 "`python`"。 - -因此，你可以確認是否在正確的虛擬環境中。 - -/// tip - -啟動一個虛擬環境，取得一個 Python，然後**切換到另一個專案**是件很容易的事； - -但如果第二個專案**無法正常運作**，那可能是因為你使用了來自其他專案的虛擬環境的、**不正確的 Python**。 - -因此，檢查正在使用的 `python` 是非常實用的。🤓 - -/// - -## 為什麼要停用虛擬環境 { #why-deactivate-a-virtual-environment } - -例如，你可能正在一個專案 `philosophers-stone` 上工作，**啟動了該虛擬環境**，安裝了套件並使用了該環境， - -然後你想要在**另一個專案** `prisoner-of-azkaban` 上工作， - -你進入那個專案： - -
- -```console -$ cd ~/code/prisoner-of-azkaban -``` - -
- -如果你不去停用 `philosophers-stone` 的虛擬環境，當你在終端中執行 `python` 時，它會嘗試使用 `philosophers-stone` 中的 Python。 - -
- -```console -$ cd ~/code/prisoner-of-azkaban - -$ python main.py - -// 匯入 sirius 錯誤，未安裝 😱 -Traceback (most recent call last): - File "main.py", line 1, in - import sirius -``` - -
- -但如果你停用虛擬環境並啟用 `prisoner-of-azkaban` 的新虛擬環境，那麼當你執行 `python` 時，它會使用 `prisoner-of-azkaban` 中虛擬環境的 Python。 - -
- -```console -$ cd ~/code/prisoner-of-azkaban - -// 你不需要在舊目錄中操作停用，你可以在任何地方操作停用，甚至在切換到另一個專案之後 😎 -$ deactivate - -// 啟用 prisoner-of-azkaban/.venv 中的虛擬環境 🚀 -$ source .venv/bin/activate - -// 現在當你執行 python 時，它會在這個虛擬環境中找到已安裝的 sirius 套件 ✨ -$ python main.py - -I solemnly swear 🐺 -``` - -
- -## 替代方案 { #alternatives } - -這是一個簡單的指南，幫助你入門並教會你如何理解一切**底層**的原理。 - -有許多**替代方案**來管理虛擬環境、套件依賴（requirements）、專案。 - -當你準備好並想要使用一個工具來**管理整個專案**、套件依賴、虛擬環境等，建議你嘗試 [uv](https://github.com/astral-sh/uv)。 - -`uv` 可以執行許多操作，它可以： - -* 為你**安裝 Python**，包括不同的版本 -* 為你的專案管理**虛擬環境** -* 安裝**套件** -* 為你的專案管理套件的**依賴和版本** -* 確保你有一個**精確**的套件和版本集合來安裝，包括它們的依賴項，這樣你可以確保專案在生產環境中運行的狀態與開發時在你的電腦上運行的狀態完全相同，這被稱為**鎖定** -* 還有很多其他功能 - -## 結論 { #conclusion } - -如果你讀過並理解了所有這些，現在**你對虛擬環境的了解已超過許多開發者**。🤓 +## 了解更多 { #learn-more } -未來當你為看起來複雜的問題除錯時，了解這些細節很可能會有所幫助，你會知道**它是如何在底層運作的**。😎 +閱讀[虛擬環境指南](https://tiangolo.com/guides/virtual-environments/)來了解虛擬環境在底層如何運作，包括啟動，以及替代的 `python -m venv` 和 `pip` 工作流程。