url: /posts/02b0c96842d1481c72dab63a149ce0dd/
title: FastAPI如何用契約測試確保API的「菜單」與「菜品」一致？
date: 2025-09-13T02:46:54+08:00
lastmod: 2025-09-13T02:46:54+08:00
author: cmdragon

summary:
契約測試是驗證API提供者與消費者交互一致性的方法，核心在於定義API請求格式、響應結構等規則的「契約」。FastAPI通過類型註解、Pydantic模型和路徑操作自動生成OpenAPI規範，作為契約源，確保代碼與文檔一致。Schemathesis工具加載OpenAPI規範，生成測試用例驗證API行為。實踐步驟包括編寫API代碼、契約測試代碼，運行測試並集成CI流程，確保每次提交自動驗證契約一致性，減少協作成本，提前發現問題，明確責任邊界。

categories:

• fastapi

tags:

• 契約測試

• FastAPI
• OpenAPI規範
• Schemathesis
• API一致性
• Pydantic模型
• 持續集成

<img src="https://api2.cmdragon.cn/upload/cmder/20250304_012821924.jpg" title="cmdragon_cn.png" alt="cmdragon_cn.png"/>

掃描二維碼關注或者微信搜一搜：編程智域 前端至全棧交流與成長

發現1000+提升效率與開發的AI工具和實用程序：https://tools.cmdragon.cn/

一、契約測試：API交互的「合同」保障

1.1 什麼是契約測試？

契約測試（Contract Testing）是一種驗證API提供者（如FastAPI服務）與消費者（如前端、其他微服務）之間交互一致性的測試方法。它的核心是一份「契約」——定義了API的請求格式、響應結構、參數約束等規則，雙方必須嚴格遵守。
打個比方：你去餐廳吃飯，菜單（契約）上寫着「番茄雞蛋麪」包含番茄、雞蛋、麪條（規則）。如果廚師端上來的面沒有雞蛋（違反契約），你可以拒絕付款——契約測試就是這個「檢查菜單與實際菜品是否一致」的過程。

1.2 契約測試的核心價值

• 減少協作成本：前端無需等待後端開發完成，可直接根據契約Mock數據開發；
• 提前發現問題：避免因API修改（如新增/刪除字段）導致消費者崩潰；
• 明確責任邊界：若測試失敗，可快速定位是提供者（API不符合契約）還是消費者（調用不符合契約）的問題。

1.3 FastAPI中的契約定位

在FastAPI中，契約不是手動寫的——框架會通過「類型註解+Pydantic模型+路徑操作」自動生成OpenAPI規範（即/openapi.json），這份規範就是天然的「契約」。這意味着：
你寫的API代碼=契約定義，無需額外維護兩份文檔，從根源避免「文檔與代碼不一致」的問題。

二、OpenAPI規範：FastAPI的「契約DNA」

2.1 FastAPI如何自動生成OpenAPI？

FastAPI的「魔法」在於通過代碼自動推導規範。舉個簡單例子：

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str  # 必填字符串
    price: float  # 必填浮點數
    is_offer: bool = None  # 可選布爾值

@app.post("/items/")
def create_item(item: Item):  # 請求體為Item模型
    return {"item_name": item.name, "item_price": item.price}

FastAPI會自動生成以下OpenAPI信息：

• 路徑：/items/，方法POST；
• 請求體：需符合Item模型（name必填、price必填、is_offer可選）；
• 響應：返回包含item_name和item_price的JSON。

你可以通過http://localhost:8000/openapi.json查看完整規範，或通過http://localhost:8000/docs查看可視化文檔（Swagger UI）。

2.2 OpenAPI規範的核心要素

一份完整的OpenAPI規範包含以下關鍵部分（對應FastAPI代碼）：

三、契約測試與OpenAPI的協同實踐

3.1 協同邏輯：用OpenAPI做「契約源」

契約測試的核心是「驗證API行為符合契約」，而FastAPI的OpenAPI規範就是最準確的契約源。整個流程可總結為：
API代碼 → 自動生成OpenAPI契約 → 契約測試工具（如Schemathesis） → 驗證API是否符合契約

3.2 工具選擇：Schemathesis

Schemathesis是FastAPI生態中最常用的契約測試工具，它能：

• 自動加載OpenAPI規範；
• 生成覆蓋所有路徑、參數、響應的測試用例；
• 驗證請求/響應是否符合契約；
• 集成到Pytest和CI流程。

3.3 實踐步驟：從0到1做契約測試

我們以「用户管理API」為例，完整演示契約測試的流程。

3.3.1 步驟1：編寫API代碼（生成契約）

首先創建main.py，實現用户的「創建」和「查詢」功能：

from fastapi import FastAPI, HTTPException
from pydantic import BaseModel, EmailStr, Field
from typing import Optional

# 1. 初始化FastAPI應用（自動生成OpenAPI）
app = FastAPI(title="用户管理API", version="1.0.0")

# 模擬數據庫（替換為真實數據庫即可）
fake_db = []

# 2. 定義請求/響應模型（Pydantic）
class UserCreate(BaseModel):
    """創建用户的請求模型（消費者需遵守的請求格式）"""
    name: str = Field(..., min_length=2, max_length=50, description="用户名，2-50字符")
    email: EmailStr = Field(..., description="合法郵箱")
    age: Optional[int] = Field(None, ge=0, le=120, description="年齡，0-120歲")

class User(UserCreate):
    """查詢用户的響應模型（提供者需遵守的響應格式）"""
    id: int = Field(..., description="用户唯一ID")

# 3. 定義路徑操作（自動生成OpenAPI的路徑、參數、響應）
@app.post("/users/", response_model=User, status_code=201, summary="創建用户")
def create_user(user_in: UserCreate):
    """創建新用户，返回包含ID的用户信息"""
    # 生成自增ID（模擬數據庫操作）
    user_id = len(fake_db) + 1
    # 構造響應數據（嚴格遵循User模型）
    user = User(id=user_id, **user_in.model_dump())
    fake_db.append(user)
    return user

@app.get("/users/{user_id}", response_model=User, summary="查詢用户")
def get_user(user_id: int):
    """根據ID查詢用户，未找到返回404"""
    for user in fake_db:
        if user.id == user_id:
            return user
    raise HTTPException(status_code=404, detail="用户未找到")

關鍵説明：

• response_model=User：強制要求響應數據嚴格符合User模型（過濾額外字段、保證必填字段存在）；
• model_dump()：Pydantic 2.x的方法（替代舊版dict()），確保返回數據與模型一致；
• 路徑參數user_id: int：FastAPI會自動驗證類型（若傳入字符串，返回422錯誤）。

3.3.2 步驟2：編寫契約測試代碼

創建test_contract.py，用Schemathesis和Pytest實現契約測試：

import pytest
from schemathesis import from_asgi
from main import app

# 1. 加載FastAPI的OpenAPI規範（契約源）
# 注意：`/openapi.json`是FastAPI默認的規範路徑
schema = from_asgi("/openapi.json", app)

# 2. 編寫契約測試用例
@pytest.mark.asyncio  # Schemathesis的call_asgi是異步方法，需加此裝飾器
@schema.parametrize()  # 自動生成所有測試用例（覆蓋所有路徑、參數、響應）
async def test_contract_compliance(case):
    """驗證API是否符合OpenAPI契約"""
    # 發送請求到API（用FastAPI的ASGI接口，無需啓動服務）
    response = await case.call_asgi(app=app)
    # 驗證響應是否符合契約（如字段類型、必填項、響應碼）
    case.validate_response(response)

3.3.3 步驟3：運行測試並查看結果

安裝依賴（確保版本最新）：

pip install fastapi==0.104.1 pydantic==2.5.2 schemathesis==3.17.0 pytest==7.4.3 uvicorn==0.24.0.post1

運行測試：

pytest test_contract.py -v

預期結果：

• 對於/users/的POST請求：驗證請求體符合UserCreate、響應符合User；
• 對於/users/{user_id}的GET請求：驗證路徑參數user_id是整數、響應符合User或404；
• 若測試通過，輸出PASSED；若失敗，輸出具體錯誤（如「響應缺少id字段」）。

3.3.4 步驟4：集成CI（持續保障契約一致）

將契約測試集成到GitHub Actions（或GitLab CI），確保每次代碼提交都自動運行測試：

# .github/workflows/contract-test.yml
name: 契約測試
on: [push, pull_request]  # 推送或PR時觸發
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: 安裝Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - name: 安裝依賴
        run: pip install -r requirements.txt
      - name: 運行契約測試
        run: pytest test_contract.py -v

四、課後Quiz：鞏固核心知識點

問題1：在FastAPI中，契約測試的「契約源」是什麼？為什麼它比手動寫契約更可靠？

答案解析：
契約源是FastAPI自動生成的OpenAPI規範。
可靠性原因：OpenAPI由API代碼推導而來（類型註解、Pydantic模型、路徑操作），完全同步代碼邏輯——手動寫契約容易出現「文檔與代碼不一致」，而自動生成則避免了這個問題。

問題2：當Schemathesis測試失敗，提示「Response schema mismatch: missing required field 'id'」，可能的原因是什麼？如何解決？

答案解析：

• 原因：API的響應缺少id字段，違反了User模型的契約（id是必填字段）；

• 解決步驟：

  1. 檢查路徑操作的response_model是否設置為User（如@app.post("/users/", response_model=User)）；
  2. 檢查返回值是否用User模型構造（如return User(id=user_id, **user_in.model_dump())）；
  3. 避免直接返回字典（如return {"name": "張三"}），需用Pydantic模型保證字段完整。

五、常見報錯與解決方案

報錯1：「422 Validation Error」（請求參數不符合契約）

• 原因：消費者發送的請求不符合Pydantic模型的約束（如name長度不足2字符、email格式錯誤）；

• 解決：

  1. 檢查請求參數是否符合UserCreate模型的定義；
  2. 用FastAPI的/docs調試（輸入參數後，文檔會提示錯誤）；
  3. 確保消費者使用application/json格式發送請求。

報錯2：「Response schema mismatch」（響應不符合契約）

• 原因：API返回的響應不符合response_model的定義（如缺少id字段、age類型是字符串）；

• 解決：

  1. 檢查路徑操作的response_model是否正確（如User而非UserCreate）；
  2. 用User(**data)構造返回值（而非直接返回字典）；
  3. 禁止返回額外字段（如return User(..., extra_field="xxx")會被Pydantic過濾）。

報錯3：「OpenAPI schema not found at /openapi.json」

• 原因：Schemathesis無法加載OpenAPI規範（如FastAPI應用未正確初始化）；

• 解決：

  1. 確保app = FastAPI()正確初始化；
  2. 檢查from_asgi的路徑是否為"/openapi.json"（FastAPI默認路徑）；
  3. 若用測試客户端，需確保應用處於運行狀態（如with TestClient(app) as client:）。

六、流程圖：契約測試的完整流程

graph TD
    A[編寫API代碼<br>（Pydantic模型+路徑操作）] --> B[自動生成OpenAPI契約<br>（/openapi.json）]
    B --> C[Schemathesis加載契約<br>生成測試用例]
    C --> D[發送請求到API<br>（驗證請求/響應）]
    D --> E{測試結果？}
    E -->|通過| F[API符合契約<br>可交付]
    E -->|失敗| G[修正API代碼<br>（如調整模型/參數）]
    G --> B[重新生成契約]
    F --> H[集成CI<br>持續保障契約一致]

餘下文章內容請點擊跳轉至 個人博客頁面 或者 掃碼關注或者微信搜一搜：編程智域 前端至全棧交流與成長，閲讀完整的文章：FastAPI如何用契約測試確保API的「菜單」與「菜品」一致？

<details>
<summary>往期文章歸檔</summary>

• 為什麼TDD能讓你的FastAPI開發飛起來？ - cmdragon's Blog

• 如何用FastAPI玩轉多模塊測試與異步任務，讓代碼不再“鬧脾氣”？ - cmdragon's Blog
• 如何在FastAPI中玩轉“時光倒流”的數據庫事務回滾測試？
• 如何在FastAPI中優雅地模擬多模塊集成測試？ - cmdragon's Blog
• 多環境配置切換機制能否讓開發與生產無縫銜接？ - cmdragon's Blog
• 如何在 FastAPI 中巧妙覆蓋依賴注入並攔截第三方服務調用？ - cmdragon's Blog
• 為什麼你的單元測試需要Mock數據庫才能飛起來？ - cmdragon's Blog
• 如何在FastAPI中巧妙隔離依賴項，讓單元測試不再頭疼？ - cmdragon's Blog
• 如何在FastAPI中巧妙隔離依賴項，讓單元測試不再頭疼？ - cmdragon's Blog
• 測試覆蓋率不夠高？這些技巧讓你的FastAPI測試無懈可擊！ - cmdragon's Blog
• 為什麼你的FastAPI測試覆蓋率總是低得讓人想哭？ - cmdragon's Blog
• 如何讓FastAPI測試不再成為你的噩夢？ - cmdragon's Blog
• FastAPI測試環境配置的秘訣，你真的掌握了嗎？ - cmdragon's Blog
• 全鏈路追蹤如何讓FastAPI微服務架構的每個請求都無所遁形？ - cmdragon's Blog
• 如何在API高併發中玩轉資源隔離與限流策略？ - cmdragon's Blog
• 任務分片執行模式如何讓你的FastAPI性能飆升？ - cmdragon's Blog
• 冷熱任務分離：是提升Web性能的終極秘籍還是技術噱頭？ - cmdragon's Blog
• 如何讓FastAPI在百萬級任務處理中依然遊刃有餘？ - cmdragon's Blog
• 如何讓FastAPI與消息隊列的聯姻既甜蜜又可靠？ - cmdragon's Blog
• 如何在FastAPI中巧妙實現延遲隊列，讓任務乖乖等待？ - cmdragon's Blog
• FastAPI的死信隊列處理機制：為何你的消息系統需要它？ - cmdragon's Blog
• 如何讓FastAPI任務系統在失敗時自動告警並自我修復？ - cmdragon's Blog
• 如何用Prometheus和FastAPI打造任務監控的“火眼金睛”？ - cmdragon's Blog
• 如何用APScheduler和FastAPI打造永不宕機的分佈式定時任務系統？ - cmdragon's Blog
• 如何在 FastAPI 中玩轉 APScheduler，讓任務定時自動執行？ - cmdragon's Blog
• 定時任務系統如何讓你的Web應用自動完成那些煩人的重複工作？ - cmdragon's Blog
• Celery任務監控的魔法背後藏着什麼秘密？ - cmdragon's Blog
• 如何讓Celery任務像VIP客户一樣享受優先待遇？ - cmdragon's Blog
• 如何讓你的FastAPI Celery Worker在壓力下優雅起舞？ - cmdragon's Blog
• FastAPI與Celery的完美邂逅，如何讓異步任務飛起來？ - cmdragon's Blog
• FastAPI消息持久化與ACK機制：如何確保你的任務永不迷路？ - cmdragon's Blog
• FastAPI的BackgroundTasks如何玩轉生產者-消費者模式？ - cmdragon's Blog
• BackgroundTasks 還是 RabbitMQ？你的異步任務到底該選誰？ - cmdragon's Blog
• BackgroundTasks與Celery：誰才是異步任務的終極贏家？ - cmdragon's Blog
• 如何在 FastAPI 中優雅處理後台任務異常並實現智能重試？ - cmdragon's Blog
• BackgroundTasks 如何巧妙駕馭多任務併發？ - cmdragon's Blog
• 如何讓FastAPI後台任務像多米諾骨牌一樣井然有序地執行？ - cmdragon's Blog

</details>

<details>
<summary>免費好用的熱門在線工具</summary>

• 歌詞生成工具 - 應用商店 | By cmdragon
• 網盤資源聚合搜索 - 應用商店 | By cmdragon
• ASCII字符畫生成器 - 應用商店 | By cmdragon
• JSON Web Tokens 工具 - 應用商店 | By cmdragon
• Bcrypt 密碼工具 - 應用商店 | By cmdragon
• GIF 合成器 - 應用商店 | By cmdragon
• GIF 分解器 - 應用商店 | By cmdragon
• 文本隱寫術 - 應用商店 | By cmdragon
• CMDragon 在線工具 - 高級AI工具箱與開發者套件 | 免費好用的在線工具
• 應用商店 - 發現1000+提升效率與開發的AI工具和實用程序 | 免費好用的在線工具
• CMDragon 更新日誌 - 最新更新、功能與改進 | 免費好用的在線工具
• 支持我們 - 成為贊助者 | 免費好用的在線工具
• AI文本生成圖像 - 應用商店 | 免費好用的在線工具
• 臨時郵箱 - 應用商店 | 免費好用的在線工具
• 二維碼解析器 - 應用商店 | 免費好用的在線工具
• 文本轉思維導圖 - 應用商店 | 免費好用的在線工具
• 正則表達式可視化工具 - 應用商店 | 免費好用的在線工具
• 文件隱寫工具 - 應用商店 | 免費好用的在線工具
• IPTV 頻道探索器 - 應用商店 | 免費好用的在線工具
• 快傳 - 應用商店 | 免費好用的在線工具
• 隨機抽獎工具 - 應用商店 | 免費好用的在線工具
• 動漫場景查找器 - 應用商店 | 免費好用的在線工具
• 時間工具箱 - 應用商店 | 免費好用的在線工具
• 網速測試 - 應用商店 | 免費好用的在線工具
• AI 智能摳圖工具 - 應用商店 | 免費好用的在線工具
• 背景替換工具 - 應用商店 | 免費好用的在線工具
• 藝術二維碼生成器 - 應用商店 | 免費好用的在線工具
• Open Graph 元標籤生成器 - 應用商店 | 免費好用的在線工具
• 圖像對比工具 - 應用商店 | 免費好用的在線工具
• 圖片壓縮專業版 - 應用商店 | 免費好用的在線工具
• 密碼生成器 - 應用商店 | 免費好用的在線工具
• SVG優化器 - 應用商店 | 免費好用的在線工具
• 調色板生成器 - 應用商店 | 免費好用的在線工具
• 在線節拍器 - 應用商店 | 免費好用的在線工具
• IP歸屬地查詢 - 應用商店 | 免費好用的在線工具
• CSS網格佈局生成器 - 應用商店 | 免費好用的在線工具
• 郵箱驗證工具 - 應用商店 | 免費好用的在線工具
• 書法練習字帖 - 應用商店 | 免費好用的在線工具
• 金融計算器套件 - 應用商店 | 免費好用的在線工具
• 中國親戚關係計算器 - 應用商店 | 免費好用的在線工具
• Protocol Buffer 工具箱 - 應用商店 | 免費好用的在線工具
• IP歸屬地查詢 - 應用商店 | 免費好用的在線工具
• 圖片無損放大 - 應用商店 | 免費好用的在線工具
• 文本比較工具 - 應用商店 | 免費好用的在線工具
• IP批量查詢工具 - 應用商店 | 免費好用的在線工具
• 域名查詢工具 - 應用商店 | 免費好用的在線工具
• DNS工具箱 - 應用商店 | 免費好用的在線工具
• 網站圖標生成器 - 應用商店 | 免費好用的在線工具
• XML Sitemap

</details>