Skip to content

建立 2026-09-14 更新 2026-09-14

安裝與第一支 API

這一頁走完，你會有一支能回 JSON、能在瀏覽器試打的 API。請真的在本機執行：FastAPI 的好處（補齊、驗證、文件）要跑起來才感覺得到。

安裝

建議用 uv 管理專案與虛擬環境：

uv init awesome-project --bare
cd awesome-project
uv add "fastapi[standard]"

fastapi[standard] 會一併帶上開發常用套件，包括 ASGI 伺服器 Uvicorn 與 fastapi 命令列。若不想安裝 FastAPI Cloud CLI，可改用 uv add "fastapi[standard-no-fastapi-cloud-cli]"。

偏好手動管理時，先啟用虛擬環境，再執行 pip install "fastapi[standard]"。

最小應用

建立 main.py：

from fastapi import FastAPI

app = FastAPI()


@app.get("/")
def read_root():
    return {"message": "Hello World"}


@app.get("/items/{item_id}")
def read_item(item_id: int, q: str | None = None):
    return {"item_id": item_id, "q": q}

四件事同時發生：

  1. app = FastAPI() 建立應用實例，之後所有路由都掛在它上面。
  2. @app.get("/") 是路徑操作裝飾器：告訴框架「GET / 由下面這個函式處理」。
  3. item_id: int 讓路徑裡的字串自動轉成整數；不是數字就回驗證錯誤。
  4. q: str | None = None 是可選的查詢參數，對應 ?q=...。

啟動開發伺服器

uv run fastapi dev

fastapi dev 會尋找 main.py 裡的 app，用 Uvicorn 啟動，並開啟檔案監看（改程式會自動重載）。瀏覽器打開：

正式環境請改用 fastapi run（關閉自動重載）。應用不在預設位置時，可在 pyproject.toml 指定：

[tool.fastapi]
entrypoint = "main:app"

官方編輯器擴充套件

FastAPI Official 支援 VS Code 與 Cursor，方便瀏覽路徑操作。建議把 entrypoint 寫進 pyproject.toml，擴充套件才找得到應用。

路徑操作在做什麼

URL https://example.com/items/foo 的路徑是 /items/foo。HTTP 操作則是 GET、POST、PUT、DELETE 等方法。FastAPI 把「某個路徑 + 某個方法」稱為路徑操作。

對應裝飾器：

@app.post("/items/")
@app.put("/items/{item_id}")
@app.delete("/items/{item_id}")

框架不強制 REST 語意，但實務上仍習慣：POST 建立、GET 讀取、PUT 更新、DELETE 刪除。

函式可以是 def 或 async def。現在用 def 即可；差別見 非同步。

進一步學習