Python使用FastAPI從零開始構建你的第一個Web?API

更新時間：2026年03月24日 08:27:24 作者：小莊-Python辦公

在現(xiàn)代Web開發(fā)中,構建高效、可靠且易于維護的API是核心技能之一,本文專為零基礎的初學者設計,我們將以系統(tǒng)且專業(yè)的步驟,帶你從零開始編寫并運行你的第一個FastAPI應用,有需要的小伙伴可以了解下

引言

在現(xiàn)代Web開發(fā)中，構建高效、可靠且易于維護的API是核心技能之一。如果你正在尋找一個現(xiàn)代化的Python Web框架，FastAPI 絕對是不容錯過的選擇。

顧名思義，F(xiàn)astAPI以**“快”**著稱。它不僅運行速度極快（性能可與NodeJS和Go媲美），而且開發(fā)速度極快。得益于Python的類型提示（Type Hints），F(xiàn)astAPI能夠自動校驗數(shù)據(jù)并生成交互式API文檔，極大地提升了開發(fā)體驗。

本文專為零基礎的初學者設計，我們將以系統(tǒng)且專業(yè)的步驟，帶你從零開始編寫并運行你的第一個FastAPI應用。

前置準備

在開始編寫代碼之前，請確保你的開發(fā)環(huán)境滿足以下要求：

Python環(huán)境：FastAPI需要 Python 3.7 或更高版本?？梢酝ㄟ^在終端輸入 python --version 來檢查你的版本。

基礎知識：了解Python的基本語法（如函數(shù)、字典、類的基本概念）。

安裝依賴庫：我們需要安裝兩個核心庫：fastapi（框架本身）和 uvicorn（用于運行FastAPI的輕量級Web服務器）。

打開你的終端（Terminal或CMD），運行以下命令：

pip install fastapi
pip install "uvicorn[standard]"

逐步指南：構建你的第一個API

第一步：編寫最基礎的代碼

創(chuàng)建一個新的Python文件，命名為 main.py。使用你喜歡的代碼編輯器（如VS Code、PyCharm），輸入以下基礎代碼：

from fastapi import FastAPI

# 創(chuàng)建FastAPI實例
app = FastAPI()

# 定義一個路由和處理函數(shù)
@app.get("/")
def read_root():
    return {"message": "歡迎來到FastAPI的世界！"}

原理解析：

app = FastAPI()：這是你的API應用的核心對象。
@app.get("/")：這是一個裝飾器。它告訴FastAPI，當用戶通過 GET 方法訪問根路徑 "/`" 時，應該執(zhí)行下面的函數(shù)。
return {"message": ...}：FastAPI會自動將Python字典轉(zhuǎn)換為JSON格式返回給客戶端。

第二步：啟動你的應用

FastAPI本身不包含Web服務器，我們需要使用前面安裝的Uvicorn來運行它。

在包含 main.py 的目錄下，打開終端并運行：

uvicorn main:app --reload

命令解析：

main：你的Python文件名（不包含 .py）。
app：你在代碼中創(chuàng)建的FastAPI實例變量名。
--reload：熱更新模式。只要你修改了代碼并保存，服務器就會自動重啟，非常適合開發(fā)階段使用。

終端會輸出類似 Uvicorn running on http://127.0.0.1:8000 的信息。打開瀏覽器訪問該地址，你將看到：
{"message": "歡迎來到FastAPI的世界！"}

第三步：體驗自動生成的交互式文檔

這是FastAPI最強大的功能之一！你不需要手寫任何API文檔。在瀏覽器中訪問：http://127.0.0.1:8000/docs

你將看到一個由Swagger UI自動生成的、美觀且可交互的API文檔頁面。你甚至可以直接在這個頁面上點擊 “Try it out” 來測試你的API。

(提示：訪問 http://127.0.0.1:8000/redoc 可以看到另一種風格的文檔)

第四步：接收路徑參數(shù)與查詢參數(shù)

讓我們?yōu)锳PI添加更多的功能。修改 main.py，添加以下代碼：

# 路徑參數(shù)示例
@app.get("/items/{item_id}")
def read_item(item_id: int, q: str = None):
    return {"item_id": item_id, "query_string": q}

原理解析：

路徑參數(shù)：{item_id} 會捕捉URL中的對應部分。因為我們聲明了 item_id: int，F(xiàn)astAPI會自動將URL中的字符串轉(zhuǎn)換為整數(shù)。如果用戶輸入 /items/abc，F(xiàn)astAPI會自動返回一個友好的錯誤提示，而不是讓程序崩潰。
查詢參數(shù)：函數(shù)參數(shù) q 沒有在路徑中定義，它自動成為查詢參數(shù)。例如訪問 /items/5?q=apple，item_id 為 5，q 為 “apple”。

第五步：處理POST請求與數(shù)據(jù)校驗

當客戶端需要向服務器發(fā)送數(shù)據(jù)（如注冊用戶）時，通常使用 POST 請求。FastAPI與 Pydantic 庫深度集成，讓數(shù)據(jù)驗證變得極為簡單。

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

# 定義數(shù)據(jù)模型
class Item(BaseModel):
    name: str
    price: float
    is_offer: bool = None # 可選參數(shù)，默認為None

@app.post("/items/")
def create_item(item: Item):
    # 此時 item 已經(jīng)是被校驗過的 Item 對象
    return {"item_name": item.name, "item_price": item.price, "status": "創(chuàng)建成功"}

在這個例子中，如果客戶端發(fā)送的JSON中 price 不是數(shù)字，F(xiàn)astAPI會自動拒絕該請求并返回具體的錯誤信息。你無需編寫復雜的 if/else 驗證邏輯。

常見避坑指南

對于初學者，在使用FastAPI時容易遇到以下幾個常見問題：

忘記啟動Uvicorn：初學者常習慣直接用 python main.py 運行，這在FastAPI中不會啟動服務（除非你在代碼末尾寫了 uvicorn.run(...)）。請始終習慣使用 uvicorn main:app --reload 啟動。
忽略類型提示（Type Hints）：FastAPI的強大在于類型提示。如果你寫了 def read_item(item_id): 而不是 def read_item(item_id: int):，你將失去自動數(shù)據(jù)轉(zhuǎn)換和文檔生成的優(yōu)勢。
路由順序沖突：FastAPI是按順序匹配路由的。如果你先定義了 @app.get("/users/{user_id}")，再定義 @app.get("/users/me")，當訪問 /users/me 時，F(xiàn)astAPI會認為 “me” 是一個 user_id。解決辦法：將固定路徑定義在動態(tài)路徑之前。