JSON Schema 驗證實戰：API 契約測試

JSON Schema 驗證實戰：打造穩定且強大的 API 契約測試流程

在現代微服務架構（Microservices）與前後端分離的開發模式中，API（Application Programming Interface）扮演著溝通的橋樑角色。然而，當開發團隊規模擴大、服務數量增加時，最常遇到的噩夢莫過於：「後端改了一個欄位名稱，前端直接掛掉」或是「API 回傳的資料格式變了，導致行動端 App 崩潰」。

這種問題的本質，在於 API 契約（API Contract）的失效。為了避免這種「破壞性變遷」（Breaking Changes），我們需要一套嚴謹的驗證機制。這正是 JSON Schema 驗證實戰 的核心價值所在。本文將深入探討如何利用 JSON Schema 建立一套自動化的 API 契約測試流程，確保你的系統在快速迭代的同時，依然保有極高的穩定性。

為什麼 API 契約測試是現代微服務的核心？

API 變更帶來的災難：Breaking Changes

在單體架構時代，所有的邏輯都在同一個專案內，型別檢查（Type Checking）可以透過編譯器（如 TypeScript）在開發階段就捕捉到錯誤。但在微服務架構下，服務之間透過 HTTP/REST 進行通訊，資料格式的變動是隱蔽且致命的。

例如，後端將 user_id 從 integer 改成了 string（UUID），如果沒有任何驗證機制，前端的邏輯在處理數值運算時會立刻出錯，而這類錯誤往往要到生產環境（Production）發生 Crash 時才會被發現。這種「破壞性變更」會大幅增加維運成本與修復時間。

什麼是「契約測試」(Contract Testing)？

契約測試的核心思想是：「定義一組雙方都必須遵守的規則」。 * 消費者（Consumer）：例如前端、行動端或另一個微服務，他們期望 API 提供特定結構的資料。 * 提供者（Provider）：API 的伺服器端，負責依照約定格式回傳資料。

當我們說進行「契約測試」時，我們不只是在測試 API 的功能是否正確（例如：登入是否成功），更是在測試 API 的「形狀」是否符合預期。如果 API 回傳了不該出現的欄位，或者缺少了必要的欄位，測試就應該失敗。

JSON Schema 在契約測試中的角色

JSON Schema 是一種基於 JSON 格式的標準化語言，用來描述 JSON 資料的結構、型別與約束條件。它在契約測試中扮演了「法律條文」的角色。透過定義一套 JSON Schema，開發者可以： 1. 自動化驗證：利用現成的函式庫（如 Ajv）自動檢查 Request Body 與 Response Body。 2. 作為溝通文檔：Schema 本身就是一份結構化的技術文件，減少溝通誤解。 3. 降低測試成本：不需要寫大量的 if-else 來檢查欄位是否存在，只需一套 Schema 即可應對所有資料結構。

如果你正在尋找快速建立 Schema 的方法，可以使用 Super Tools JSON Schema 工具 來快速生成基礎結構，節省手寫 JSON 的時間。

深入解構 JSON Schema：從基礎語法到核心約束

要玩轉 JSON Schema 驗證實戰，首先必須精通其核心關鍵字。JSON Schema 並不只是檢查「欄位是否存在」，它能深入到資料的細節。

JSON Schema 的基本結構

一個典型的 JSON Schema 檔案通常包含 $schema（指定版本）、type（資料型態）以及 properties（屬性定義）。

必備的關鍵關鍵字

以下是開發 API 契約時最常用的關鍵字：

• type: 定義資料的基本型別，如 string, number, integer, boolean, object, array, null。
• properties: 當 type 為 object 時，用來定義物件內各個欄位的規則。
• required: 一個陣列，列出哪些欄位是「絕對不能缺席」的。
• additionalProperties: 控制是否允許出現 Schema 中未定義的額外欄位。在嚴格的契約測試中，我們通常會將其設為 false，以防止隱藏的資料變動。

進階約束條件

為了更精準地定義 API 契約，我們需要更細緻的約束：

JSON Schema 驗證實戰：從需求到程式碼實現

現在，讓我們進入實戰環節。假設我們正在開發一個「使用者管理系統」的 API，我們需要為 POST /users 這個端點建立一套嚴謹的驗證機制。

場景模擬：建立一個使用者管理系統 API

我們預期的 API Request Body 應該包含以下資訊： * id: 唯一的 UUID 字串。 * username: 3 到 20 字元的英數字。 * email: 合法的 Email 格式。 * role: 必須是 admin, editor, 或 viewer 其中之一。 * tags: 一組字串陣列。

撰寫 Schema 定義

以下是我們為此 API 撰寫的 JSON Schema：

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "UserRegistrationSchema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "username": {
      "type": "string",
      "minLength": 3,
      "maxLength": 20,
      "pattern": "^[a-zA-Z0-9_]+$"
    },
    "email": {
      驗證: "string",
      "format": "email"
    },
    "role": {
      "type": "string",
      "enum": ["admin", "editor", "viewer"]
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "uniqueItems": true
    }
  },
  "required": ["id", "username", "email", "role"],
  "additionalProperties": false
}

實作驗證邏輯 (Node.js 範例)

在 Node.js 環境中，最推薦使用的驗證套件是 Ajv (Another JSON Validator)。它速度極快且完全符合 JSON Schema 標準。

const Ajv = require("ajv");
const addFormats = require("ajv-formats");

const ajv = new Ajv({ allErrors: true }); // allErrors: true 會列出所有錯誤，而不僅僅是第一個
addFormats(ajv); // 必須載入 formats 才能支援 email, uuid 等格式

// 引入我們上面定義的 Schema
const schema = {
  type: "object",
  properties: {
    id: { type: "string", format: "uuid" },
    username: { type: "string", minLength: 3, maxLength: 20 },
    email: { type: "string", format: "email" },
    role: { type: "string", enum: ["admin", "editor", "viewer"] }
  },
  required: ["id", "username", "email", "role"],
  additionalProperties: false
};

const validate = ajv.compile(schema);

// 測試資料 1：完全正確的資料
const validData = {
  id: "550e8400-e29b-41d4-a716-446655440000",
  username: "dev_master",
  email: "test@example.com",
  role: "admin"
};

// 測試資料 2：錯誤的資料 (缺少 email 且 role 不合法)
const invalidData = {
  id: "not-a-uuid",
  username: "a", // 太短
  role: "super_user" // 不在 enum 內
};

console.log("--- 驗證正確資料 ---");
const isData1Valid = validate(validData);
console.log(isData1Valid ? "✅ 通過驗證" : "❌ 驗證失敗");

console.log("\n--- 驗證錯誤資料 ---");
const isData2Valid = validate(invalidData);
if (!isData2Valid) {
  console.log("❌ 驗證失敗，錯誤訊息如下：");
  validate.errors.forEach(err => {
    console.log(`- 欄位 [${err.instancePath}]: ${err.message}`);
  });
}

透過這段程式碼，你可以看到當資料不符合契約時，Ajv 會精準地告訴你哪一個欄位出錯、錯誤的原因是什麼（例如：should be string 或 must match pattern）。這對於 API 串接過程中的除錯（Debug）非常有幫助。

進階技巧：處理複雜的資料結構與邏輯

在真實的企業級開發中，API 的資料結構往往不只是簡單的物件，還包含複雜的邏輯判斷與多樣化的回應格式。

邏輯組合運算子 (allOf, anyOf, oneOf)

當你的 API 回傳結果具有「多型」（Polymorphism）特性時，這三個運算子非常強大：

• oneOf: 資料必須符合給定的 Schema 之中恰好一個。這常用於處理「根據類型回傳不同結構」的情境。例如，搜尋結果可能是一個 User 物件，也可能是一個 Product 物件。
• anyOf: 資料必須符合給定的 Schema 之中至少一個。
• allOf: 資料必須同時符合所有給定的 Schema。這常用於「組合多個小的 Schema」來構成一個大的 Schema。
• not: 排除掉符合該 Schema 的資料。

處理動態欄位與依賴關係 (dependencies)

有時候，某個欄位的出現會導致另一個欄位變成「必填」。例如：如果 payment_method 是 credit_card，那麼 card_number 就必須存在。在 JSON Schema 中，你可以使用 dependencies 或 if-then-else 語法來實現這種邏輯。

使用 Regular Expression (Regex) 進行精準格式驗證

不要只滿足於 type: "string"。對於身分證字號、特定格式的訂單編號、或是符合特定規則的 URL，使用 pattern 搭配正規表示式是確保契約嚴謹性的關鍵。這能防止髒資料（Dirty Data）進入資料庫，從源頭降低系統風險。

建立自動化測試流水線：將驗證納入 CI/CD

JSON Schema 驗證不應該只發生在開發者的電腦上，它必須被整合進自動化流程中。

在單元測試中整合 Schema 驗證 (Jest 範例)

如果你使用 Jest 作為測試框架，你可以撰寫 Integration Test，直接對 API 的 Response 進行 Schema 驗證。

const request = require('supertest');
const app = require('../app'); // 你的 Express App
const schema = require('../schemas/user.schema.json');
const Ajv = require("ajv");
const ajv = new Ajv();

describe('GET /users/:id', () => {
  it('應該回傳符合 User Schema 的資料', async () => {
    const response = await request(app).get('/users/123');

    expect(response.status).toBe(200);

    const validate = ajv.compile(schema);
    const isValid = validate(response.body);

    if (!isValid) {
      console.error(validate.errors);
    }
    expect(isValid).toBe(true);
  });
});

使用 Postman 進行 API 整合測試

Postman 的 Tests 標籤頁也支援 JavaScript。你可以將 JSON Schema 貼進 Postman 的測試腳本中，當你執行 Collection Runner 時，Postman 會自動檢查每一次 API 呼叫的回傳值是否符合預期。這對於 QA 工程師進行回歸測試（Regression Testing）非常有效。

監控生產環境的 API 異常

除了測試環境，你甚至可以在 API Gateway（如 Kong, Nginx）或 Middleware 層級導入 JSON Schema 驗證。雖然這會稍微增加一點點延遲（Latency），但它能作為最後一道防線，攔截所有不符合契約的惡意請求或異常流量，保護後端服務不被髒資料衝垮。

最佳實踐與避坑指南

在進行 JSON Schema 驗證實戰時，請務碼遵循以下原則：

Schema 版本化管理策略

API 的變更是不可避免的。當你必須進行破壞性變更時，絕對不要直接修改舊有的 Schema。你應該建立新的版本（例如 v2/user.schema.json），並讓舊的 API 繼續使用舊的 Schema 運行一段時間，直到所有消費者（Consumers）都完成遷移。這就是所謂的「向後相容性」（Backward Compatibility）。

效能考量：避免過度複雜的驗證邏輯

雖然 JSON Schema 功能強大，但過於複雜的 oneOf 嵌套或極其複雜的 pattern 會消耗大量的 CPU 資源。在處理高併發（High Concurrency）的 API 時，應盡量保持 Schema 的簡潔，並在必要時針對關鍵路徑進行優化。

保持文檔與 Schema 的同步

最痛苦的事莫過於「文件寫的是 A，Schema 驗證的是 B」。建議將 JSON Schema 作為「單一事實來源」（Single Source of Truth）。你可以利用工具從 Schema 自動生成 Swagger/OpenAPI 文件，確保開發者看到的文檔永遠是最新的。

FAQ：關於 JSON Schema 驗證的常見問題

Q1: JSON Schema 驗證可以取代單元測試嗎？ 不可以。JSON Schema 驗證的是「資料結構與型別」，而單元測試驗證的是「業務邏輯」。例如，Schema 可以檢查 price 是數字，但無法檢查 price 是否符合折扣計算後的結果。兩者應該相輔相成。

Q2: 使用 additionalProperties: false 會不會太嚴苛？ 在 API 契約測試中，這是一個好習慣。它能強迫開發者在變更 API 時必須更新 Schema，避免因為多出了未定義的欄位而導致消費者產生誤解。但在某些需要擴充性的場景下，可以適度放寬。

Q3: 如何處理大型 JSON 檔案的驗證效能問題？ 對於超大型 JSON，建議不要在每次 Request 都進行全量驗證。可以考慮只驗證關鍵欄位，或者在非同步的處理流程（如 Message Queue 處理時）再進行深層驗證。

Q4: JSON Schema 有支援 TypeScript 的型別定義嗎？ 有。你可以使用 json-schema-to-typescript 等工具，根據現有的 JSON Schema 自動生成 TypeScript 的 interface 或 type，實現從 Schema 到前端型別的自動同步。

Q5: 如果 API 回傳的是 null，Schema 該如何定義？ 你可以使用 type: ["string", "null"]（在某些 Draft 版本中）或者在屬性定義中明確允許 null 型別。這對於處理可選欄位非常重要。

Q6: 我應該在哪個層級進行驗證？ 建議在「邊界層」（Boundary Layer）進行驗證，例如 API Controller 的入口處、Middleware 或 API Gateway。這樣可以確保進入核心業務邏輯（Domain Logic）的資料已經是乾淨且符合契約的。

結論

JSON Schema 驗證實戰 不僅僅是一種技術手段，更是一種工程文化的體現。它代表著開發團隊對「穩定性」與「契約精神」的堅持。透過建立嚴謹的 API 契約測試流程，我們能大幅降低微服務架構中的溝通成本，減少破壞性變更帶來的風險，並讓前後端開發能夠更放心地進行並行開發。

在開發過程中，善用如 Super Tools 提供的開發工具，並將驗證邏輯納入 CI/CD 流水線，是每一位資深開發者通往「高可用性架構」的必經之路。