方格子 vocus

【FastAPI 學習筆記 EP.1】簡介與環境建置

2025/12/19 更新2025/12/01 發佈閱讀 6 分鐘

這篇文章將教你如何在電腦上建置 Python 的 Web 框架：FastAPI，你將學會建立隔離的開發環境、安裝必要套件，並寫出你的第一支 API 程式。

什麼是 FastAPI？

FastAPI 是一個用於建構 Web API 的 Python 框架 (Framework)，以執行速度快和開發效率高為特點。想像它是一個餐廳服務生，當你點餐（Request）時，他會立刻幫你核對餐點，一旦確認單子沒填錯（自動檢查資料），他就會用最快的速度把餐點端上桌（Response）。

FastAPI 基礎環境建置

1. 虛擬環境 (Virtual Environment)

虛擬環境是專屬於這個專案的獨立空間，能避免不同專案間的套件版本發生衝突。

# Windows
python -m venv venv
# 啟動虛擬環境
.\venv\Scripts\activate

# macOS / Linux
python3 -m venv venv
# 啟動虛擬環境
source venv/bin/activate

執行後，你的終端機 (Terminal) 前面會出現 (venv) 字樣，代表目前正處於隔離環境中。

2. 套件安裝 (Installation)

FastAPI 需要兩個核心元件：框架本身以及執行它的伺服器 Uvicorn。我們使用官方推薦的 standard 選項一次安裝到位。

pip install "fastapi[standard]"

這行指令會同時安裝 FastAPI 框架和 Uvicorn 網頁伺服器，確保你的環境具備執行 Web 服務所需的所有依賴。

3. 應用程式實例 (App Instance)

這是 FastAPI 的核心物件，所有的路由 (Route) 和設定都必須掛載在這個物件上。

from fastapi import FastAPI

# 建立一個 FastAPI 應用程式實例
app = FastAPI()

app 變數就是你的網站主體，後續所有的功能（如網頁路徑）都是透過這個變數來定義。

FastAPI 實作範例

接下來，我們將撰寫一個簡單的 API，當使用者訪問首頁時，回傳一段 JSON 資料。

請在專案資料夾中建立一個名為 main.py 的檔案，並貼上以下程式碼：

from fastapi import FastAPI

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

# 2. 定義路由 (Route)
# @app.get("/") 當使用者用 GET 方法訪問根目錄 "/" 時，執行下方的函式
@app.get("/")
def read_root():
    # 3. 回傳資料
    # FastAPI 會自動將這個字典 (Dictionary) 轉換成 JSON 格式回傳
    return {"message": "Hello World", "status": "success"}

在終端機輸入以下指令啟動開發伺服器：

fastapi dev main.py

這個範例會啟動了一個 Web 服務，當你在瀏覽器輸入 http://127.0.0.1:8000/ 時，程式會觸發 read_root 函式，並在網頁上顯示 {"message": "Hello World", "status": "success"}。fastapi dev 指令會啟動開發模式，當你修改程式碼並存檔時，伺服器會自動重新啟動，提升開發效率。

常見錯誤與解決方法

1. 檔名或實例名稱錯誤

執行指令時，系統找不到指定的應用程式入口。

# 錯誤：如果你的檔案叫 main.py，但在程式碼內變數叫 app
# 錯誤指令
uvicorn main:server --reload

# 正確：指令格式為 [檔名]:[實例變數名]
uvicorn main:app --reload
# 或者使用新版簡化指令
fastapi dev main.py

2. 忘了啟動虛擬環境

直接安裝套件到全域環境，導致不同專案互相干擾或找不到套件。

# 錯誤：終端機開頭沒有 (venv) 就直接執行 pip install
pip install fastapi

# 正確：先確認有啟動虛擬環境
# Windows: .\venv\Scripts\activate
# Mac/Linux: source venv/bin/activate
pip install "fastapi[standard]"

3. 404 Not Found 錯誤

訪問了未定義的網址路徑 (Path)。

# 你的程式碼只有定義根目錄 "/"
@app.get("/")
def root():
    return {"msg": "hi"}

# 錯誤：瀏覽器訪問 http://127.0.0.1:8000/users
# 結果：{"detail": "Not Found"}

# 正確：確保瀏覽器網址與 @app.get("...") 內的字串完全一致
# 訪問 http://127.0.0.1:8000/