FastAPI 安裝與環境建立

本篇將協助你快速建立開發環境，安裝 FastAPI，並執行你的第一個 API 伺服器。

安裝 FastAPI

首先，你需要安裝 fastapi 套件。為了執行伺服器，你還需要一個 ASGI (Asynchronous Server Gateway Interface) 伺服器，例如 uvicorn。

你可以一次安裝這兩者：

pip install "fastapi[standard]"

這是一條簡便的指令，它會安裝 FastAPI 以及開發時常用的標準套件，包括 uvicorn（ASGI 伺服器）和 email-validator 等。

"uvicorn[standard]" 會安裝 uvicorn 以及一些建議的標準依賴套件（如 uvloop，這能讓 Python 非同步效能大幅提升）。如果你使用的是 zsh (Mac/Linux 常見)，記得加上雙引號，否則括號 [] 可能會被 Shell 解析錯誤。

建立第一個 API

建立一個名為 main.py 的檔案，並輸入以下程式碼：

from fastapi import FastAPI

# 1. 建立一個 FastAPI "實例"
app = FastAPI()

# 2. 定義一個 "路徑操作裝飾器" (Path Operation Decorator)
# 告訴 FastAPI：
# - 當收到路徑為 "/" 的請求
# - 且使用的是 "get" 操作 (HTTP 方法)
@app.get("/")
# 3. 定義 "路徑操作函數" (Path Operation Function)
# 這是真正處理請求的 Python 函數
async def root():
    # 4. 回傳內容
    # 可以回傳 dict, list, str, int 等，
    # FastAPI 會自動將其轉換為 JSON 格式
    return {"message": "Hello World"}

程式碼解析

  1. 導入 FastAPI：from fastapi import FastAPI。
  2. 建立實例：app = FastAPI()。這個 app 變數將是我們操作的主要物件。
  3. 路徑操作裝飾器：@app.get("/")。
    • @app 對應到我們剛剛建立的 app 變數。
    • .get 代表 HTTP GET 方法。如果你的 API 是要接收資料，可能會用 .post。
    • ("/") 是 API 的路徑 (Path)。
  4. 定義函數：async def root():。
    • 使用 async def 是因為 FastAPI 支援非同步。如果不熟悉 async/await，也可以使用普通的 def root():，FastAPI 一樣能正常運作。
  5. 回傳內容：return {"message": "Hello World"}。
    • 我們回傳一個 Python 字典 (dict)。FastAPI 會自動把它轉換成 JSON 格式回應給客戶端 (瀏覽器或 API 使用者)。

啟動伺服器

開啟終端機 (Terminal)，切換到 main.py 所在的目錄，然後執行以下指令：

uvicorn main:app --reload

指令說明：

  • main：你的 Python 檔案名稱 (main.py)。
  • app：在 main.py 裡面建立的 FastAPI 實例變數名稱 (app = FastAPI())。
  • --reload：讓伺服器在程式碼變更時自動重新啟動。這在開發階段非常方便，但在正式環境 (Production) 請不要使用此參數。

使用 fastapi 指令 (現代做法)

在最新的 FastAPI 版本中，推薦使用內建的 fastapi 命令行工具：

fastapi dev main.py

這條指令會自動開啟 reload 模式，並預設監聽 8000 埠號，非常適合本地開發環境。

執行後，你應該會看到類似以下的輸出：

INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
INFO:     Started reloader process [28720] using WatchFiles
INFO:     Started server process [28722]
INFO:     Waiting for application startup.
INFO:     Application startup complete.

測試 API

打開瀏覽器，前往 http://127.0.0.1:8000/。

你應該會看到以下 JSON 回應：

{
  "message": "Hello World"
}

恭喜！你已經成功建立了第一個 FastAPI 應用程式。

自動化互動式文件

FastAPI 最強大的功能之一就是自動生成文件。

在瀏覽器中前往 http://127.0.0.1:8000/docs。

你會看到基於 Swagger UI 的互動式 API 文件：

FastAPI Swagger UI (示意圖：Swagger UI 介面)

你可以在這個頁面上直接測試 API：

  1. 點擊條目（例如 GET /）。
  2. 點擊 "Try it out"。
  3. 點擊 "Execute"。
  4. 查看伺服器的回應。

另外，還有一個替代文件介面 ReDoc，位於 http://127.0.0.1:8000/redoc。

總結

在本章中，我們學會了：

  1. 安裝 FastAPI 和 Uvicorn。
  2. 撰寫最簡單的 FastAPI 程式 (app = FastAPI(), @app.get("/"))。
  3. 使用 uvicorn 啟動伺服器。
  4. 使用瀏覽器和自動生成的文件 (/docs) 來測試 API。