這篇文章將會教你如何在電腦上建置 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/
結語
你已經成功建置了開發環境，並執行了第一個 FastAPI 專案，這證明你已經知道虛擬環境的重要性、學會 uvicorn 啟動指令，以及路由（Routing）的基本定義。
