【Day 05】第一支 FastAPI 的小程式

2025 iThome 鐵人賽

DAY 5

生成式 AI

Multi-Agent 實戰：開發多代理智慧小幫手系列第 5 篇

17th鐵人賽

meow0924

團隊nutc imac

2025-09-19 17:06:45

59 瀏覽

分享至

用 FastAPI 建立第一支 API

準備環境：安裝 FastAPI 與 Uvicorn

接下來我們要來利用 FastAPI 開發一支小 API。
在開始之前，請確保你已經安裝了 Python (建議 3.7+)。然後，打開你的終端機或命令提示字元，輸入以下指令來安裝 FastAPI 和它的伺服器 Uvicorn：

pip install fastapi uvicorn pydantic

fastapi：框架本身。
uvicorn：一個超快的 ASGI 伺服器，用於運行 FastAPI 應用程式。
pydantic：檢查資料格式的工具。

如果不想安裝在電腦上的話，也可以用一個虛擬機並在虛擬機上執行安裝

首先建立一個虛擬機
```
python -m venv venv
```
啟動虛擬機
```
./venv/Scripts/Activate
```
- 如果啟動失敗，並出現這個錯誤
  
  這個錯誤是 Windows 預設的安全機制，防止未經授權的腳本執行，我們可以讓它暫時允許執行本地腳本(就是下面那行)，然後在執行一次上面的指令就好了
```
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
```
  成功的樣子
這樣就啟動成功了，接著在執行上面的指令安裝就好了

建立第一支 API：Hello World

現在，讓我們來建立第一支 FastAPI 程式。首先在你的專案資料夾中，建立一個名為 FastApi.py 的檔案(檔名可更改)，並輸入以下程式：

from fastapi import FastAPI
# 為了展示更複雜的資料傳輸，我們引入 Pydantic
# Pydantic 用於資料驗證和序列化
from pydantic import BaseModel

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

# 定義一個 GET 請求
# 當使用者訪問根路徑 "/" 時，會執行下面的函式
@app.get("/")
async def read_root():
    """
    這是一個簡單的根路徑 API，回傳 "Hello World" 訊息。
    """
    return {"message": "Hello World"}

# 定義另一個 GET 請求，帶有路徑參數
# 例如：訪問 /John 會回傳 "Hello John"
@app.get("/{name}")
async def greet_name(name: str):
    """
    這個 API 接收一個名字作為路徑參數，並回傳問候語。
    """
    return {"message": f"Hello {name}"}

# 定義一個 POST 請求
# 定義一個資料模型，用於接收 POST 請求的資料
class Item(BaseModel):
    name: str
    price: float
    is_offer: bool

# 接收一個 Item 物件作為請求主體 (Request Body)
@app.post("/items")
async def create_item(request: Item):
    """
    這個 API 接收一個 Item 物件 (包含 name, price, is_offer)，
    並回傳接收到的 Item 資料。
    """
    return request

運行 FastAPI 程式

接著要運行這支 API 需要先打開終端機
在終端機中，切換到那個專案的資料夾，然後執行以下指令：

uvicorn FastApi:app --host 0.0.0.0 --port 5678 --reload

(FastApi 的部分要替換成自己的檔案名)

uvicorn：啟動 Uvicorn 伺服器。
FastApi:app：告訴 Uvicorn 去運行 FastApi.py 檔案中的 app 實例。
--host 0.0.0.0：設定伺服器要綁定的主機位址，在開發時常用 0.0.0.0，方便測試不同裝置（手機、同網路電腦等）。
- 0.0.0.0 代表允許所有網路來源的連線（內網、外網皆可）。
- 127.0.0.1 就只能在本機存取，外部連不到。
--port 5678：指定伺服器的埠號(Port)，預設是 8000，這裡改成 5678，之後瀏覽器訪問時就可以用 http://localhost:5678。
--reload：每當有修改程式碼並儲存時，伺服器便會自動重啟，無需手動關閉再啟動，是一個非常方便的開發模式，但在正式上線（production）時最好不要用這個選項，因為可能會影響到效能。

當你看到下圖時就代表你的 API 伺服器已經成功啟動了

測試你的 API

打開測試 API 的工具，這裡我會使用 Postman 來做示範

/ (會回傳 Hello World 的 API)
/{name} (會反傳 Hello {name} 的 API)
/items (會回傳接收到的 Item 資料的 API)

FastAPI：自動 API 文件

首先，打開你的網頁瀏覽器，嘗試訪問以下網址：
http://localhost:5678/docs
我們會看到一個由 Swagger UI 自動生成的互動式 API 文件頁面，如下圖

我們可以這裡看到所有我們剛剛在程式中所定義的 API (/, /{name}, /items)

接著點開每一支要測試的 API 並測試

/ (會回傳 Hello World 的 API)
1. 點開 API
  - 像這樣
2. 點擊旁邊的 Try it out
  - 會變成這樣
3. 點擊 Execute
  - 就可以測試 API 了，成功後長這樣
/{name} (會反傳 Hello {name} 的 API)
1. 點開 API
2. 點擊旁邊的 Try it out
3. 填入相關的參數
4. 點擊 Execute
  - 成功的樣子
/items (會回傳接收到的 Item 資料的 API)
1. 點開 API
2. 點擊旁邊的 Try it out
3. 填入相關的參數
4. 點擊 Execute
  - 成功的樣子