SSD Nodes Learn Hosting plans →
指南 Matt Connor作者: Matt Connor · 已更新 2026-10-30

VPS 自架 API Mock 與測試:WireMock、Hurl 部署

了解 API mock server 與 test runner 的差異,使用 WireMock 將 stub 存入 git,搭配 Hurl 在 CI 執行測試,並在 VPS 重建後保留報告。

共用同一個儲存庫的兩項工作

自行託管 API 模擬與測試是兩項不同的工作,把它們當成同一件事會浪費一週時間。模擬伺服器可代替 CI 無法呼叫的相依服務,例如付款提供者、合作夥伴 API、受速率限制的上游服務,或其他團隊尚未發布的服務。API 測試執行器則會依固定順序呼叫自有端點,驗證回應內容,並將某個回應中的值帶入下一個請求。

有些工具可以同時執行這兩項工作。模擬伺服器的主要工作是回應請求。測試執行器不會預設付款提供者在卡片遭拒時應回傳什麼。對已經租用伺服器的大多數團隊而言,最後通常會各執行一個工具,由同一個 Docker Compose 檔案啟動,並在同一個 pull request 中審查。

為何要自行託管 API 模擬與測試?

你的 fixture 是依照正式環境資料結構建立的資料。API 測試中的 request body 可能是真實客戶紀錄,只是改了姓名;也可能連姓名都沒改,因為沒有人檢查。錄製的 stub 更危險:proxy 錄製會儲存上游實際回傳的內容,因此透過錄製建立的 stub 目錄,可能在有人逐一讀取每個檔案前,一直保留有效 token 與客戶電子郵件地址。在託管服務上,這些資料會成為他人的資安事件,也會造成你的資料外洩。

第二個原因是可連線性。繫結至私有位址的服務,必須先建立私有網路連線,託管 runner 才能連線。每種替代方案都有成本。為了測試 API 而將其公開至網際網路,就失去了原本設為私有的理由。tunnel 或公開的 staging 副本都需要額外維護,而 staging 副本會在每次 release 之間逐漸偏離 production。GitHub-hosted runner 也支援透過 WireGuard overlay 或 Azure Virtual Network 進行私有存取。位於相同私有網路上的 runner 可直接呼叫該服務,不需要這些額外設定;這就是 自行託管的 GitHub Actions runner 的實際理由。

應執行哪一種自架 mock server?

這些 mock server 都會在你擁有的主機上以容器執行。關鍵在於各自將什麼視為真實來源,因為這會決定重新建立容器時是零成本,還是需要花上一個下午。

  • WireMock 將每個 stub 保存為 mappings/ 目錄中的 JSON 檔案,較大的回應本文則放在 __files/。其映像檔是 wiremock/wiremock,容器內的根目錄是 /home/wiremock,也能作為錄製代理執行。檔案儲存在磁碟上,表示 mock 可以像其他程式碼一樣納入 git。
  • Mockoon CLI 將完整的 mock API 保存於單一 JSON 資料檔案中。使用 npm install -g @mockoon/cli 安裝,並以 mockoon-cli start --data ./data-file.json 啟動;或者執行 mockoon/cli 映像檔,並將該檔案繫結掛載進去。桌面應用程式也會編輯同一個檔案,因此可以在 UI 中設計,再提交結果,兩者相容。
  • MockServer 使用 mockserver/mockserver 映像檔執行,並監聽連接埠 1080。Expectations 會透過其專用 REST API 傳入,從測試程式碼操作很方便,但作為部署方式有風險:預設情況下,透過 HTTP 呼叫建立的 expectation 會在容器重新啟動時消失。對於需要永久保留的 stub,請使用 JSON 初始化檔案。若要保留執行期間的變更,請啟用 persistExpectations,將輸出檔案保存於容器外部,並在啟動時透過 initializationJsonPath 載入。
  • Prism 會直接從 OpenAPI 文件建立 mock,而不是使用個別的 stub 檔案。使用 npm install -g @stoplight/prism-cli 安裝,接著執行 prism mock openapi.yaml。在容器中執行時,請加入 -h 0.0.0.0,因為 Prism 預設會繫結至 localhost,否則容器外部無法連線。
  • Microcks 是功能較完整的選項:它提供 Web UI,可匯入 OpenAPI 文件與 Postman collection,接著以 mock 的形式提供服務,並執行契約測試。完整安裝需要 MongoDB 與 Keycloak,非同步功能還需要 Kafka。整合式 microcks-uber 映像檔內含記憶體內 MongoDB;專案文件指出此配置適合暫時性使用。因此,請將在該 UI 中建立的內容視為可丟棄資料,並將來源檔案保存在 git 中。

應該使用哪個自架 API 測試執行器?

這項工作是一連串操作:驗證身分、建立訂單、讀回訂單,並確認狀態已變更。這需要擷取一個回應中的值,並在下一個請求中使用。如果工具無法在呼叫之間保留狀態,它就是健康檢查工具,而不是 API 測試工具。

  • Hurl 會以單一二進位檔執行純文字格式的 HTTP 請求檔案。[Captures] 區段會從回應中擷取值,[Asserts] 區段會檢查這些值,而 --test 會將其轉換成具備摘要與結束碼的測試執行器。截至 2026 年 8 月,目前版本為 8.0.1。
  • Bruno CLI 會執行資料夾中的 .bru 檔案。使用 npm install -g @usebruno/cli 安裝,然後執行 bru run folder --env Local --reporter-junit results.xml。其 collection 格式刻意採用目錄中的文字檔,因此在程式碼審查中容易閱讀差異。
  • Newman 可在 Postman 外部執行 Postman collections:npm install -g newman,接著執行 newman run collection.json -r cli,junit --reporter-junit-export results.xml。問題在於格式。Newman 會執行匯出的 v2.1 JSON 格式 collection。Postman 現在也支援 v3 collection 格式,以及透過 Postman CLI 使用 Native Git 工作流程。Postman 文件表示,Newman 不會再收到更新或修正,並建議將指令碼與 CI pipeline 遷移至 Postman CLI。
  • Schemathesis 是另一種類型的檢查工具。它會讀取 OpenAPI schema,並產生測試案例,嘗試取得 schema 宣告為不可能的回應:uvx schemathesis run https://your.api/openapi.json。它能找出當機與契約違規,但不了解你的業務規則,因此應與指令碼化測試套件並用,而不是取代測試套件。
  • Hoppscotch self hosted 是網頁 UI 選項,且需要 Postgres 執行個體。安裝前請先了解這項取捨:collections 儲存在資料庫,而不是 repository 中。

有一個工具應避免使用。Step CI 仍會出現在工具整理文章中,其 YAML 工作流程格式也相當易讀,但該 repository 上次收到 commit 是 2024 年 8 月。位於 CI 與 API 之間的程式,不應採用未維護的程式碼。

將 mock server 放在防火牆後方

以下設定會將 WireMock 作為付款服務供應商的替代服務執行。若你不熟悉 compose 檔案格式,VPS 上的 Docker Compose 涵蓋本節所需的生命週期指令。

services:
  mock-payments:
    image: wiremock/wiremock:3.13.2
    command: ["--verbose"]
    volumes:
      - ./mocks/payments:/home/wiremock
    ports:
      - "127.0.0.1:8080:8080"
    restart: unless-stopped

連接埠前的 127.0.0.1: 前綴是關鍵。單獨使用 8080:8080 會在所有介面上發布 mock,包括公開 IP;即使 ufw 拒絕該連接埠,仍然可以連線,因為 Docker 會在流量套用 ufw 的 INPUT 規則前,先透過 nat 表格轉送已發布的流量。在 Engine 28.0.0 或更新版本的預設 bridge 網路中,繫結至 loopback 位址,可讓已發布的連接埠只能從主機存取。較舊版本允許同一個 layer 2 網路上的主機連線至發布到 localhost 的連接埠。繫結至 private interface 位址時,仍可從能路由至該位址的網路存取。

接著,讓待測服務指向 mock。若服務執行於同一個 compose 專案中,mock 的 base URL 是 http://mock-payments:8080,因為 compose 會在自己的網路上解析服務名稱。若服務執行於主機上,則是 http://127.0.0.1:8080。請透過環境變數設定,絕不要寫在程式碼中,否則測試 URL 會隨應用程式發布到 production。

Stub 放在 ./mocks/payments/mappings/,每個 JSON 檔案放置一個 stub。

{
  "request": {
    "method": "POST",
    "urlPath": "/v1/charges",
    "bodyPatterns": [{ "matchesJsonPath": "$.amount" }]
  },
  "response": {
    "status": 201,
    "headers": { "Content-Type": "application/json" },
    "jsonBody": { "id": "ch_test_001", "status": "succeeded", "amount": 4200 }
  }
}

啟動服務,然後確認實際載入的內容。

docker compose up -d --wait mock-payments
curl -fsS http://127.0.0.1:8080/__admin/mappings

--wait 會等待容器回報 healthy。這是可行的,因為 WireMock image 提供針對 /__admin/health endpoint 的 HEALTHCHECK。mappings 呼叫會列出伺服器讀取的所有 stub。你撰寫的 stub 若未出現在清單中,表示它從未載入:請確認檔案位於 mappings/ 下方,而不是掛載的根目錄中,並確認 JSON 可以正確解析。

收到請求但沒有任何 stub 符合時,WireMock 會回應 404。若找到近似符合項目,回應本文會以 Request was not matched 開頭,後面接著與最接近 stub 的差異比較。沒有 stub mappings 時,本文是 No response could be served as there are no stub mappings in this WireMock instance. 閱讀差異內容後再進行修改,因為其中會指出不一致的確切欄位。該欄位通常是包含 /v1/charge 的路徑,而 stub 中則是 /v1/charges。

將測試撰寫為跨呼叫保留狀態的連續流程

Hurl 檔案是純文字。請從專案的 releases 安裝 deb 套件。

VERSION=8.0.1
curl --location --remote-name https://github.com/Orange-OpenSource/hurl/releases/download/$VERSION/hurl_${VERSION}_amd64.deb
sudo apt update && sudo apt install ./hurl_${VERSION}_amd64.deb

在 tests/checkout.hurl 中,有一組測試會對 mock 執行自有 API 的測試。

POST {{base_url}}/orders
Content-Type: application/json
{
  "sku": "ssd-1tb",
  "amount": 4200
}
HTTP 201
[Captures]
order_id: jsonpath "$['id']"

GET {{base_url}}/orders/{{order_id}}
HTTP 200
[Asserts]
jsonpath "$.status" == "paid"
jsonpath "$.charge_id" == "ch_test_001"

[Captures] 區塊讓這成為 API 測試,而不是兩個互不相關的請求。order_id 會從第一個回應讀取,並插入第二個請求的 URL。對 charge_id 的斷言是整個測試的重點:它證明服務呼叫了 payment provider,並儲存了回傳內容;比較的值就是你寫入 WireMock stub 的值。現在,一個檔案即可涵蓋流程的兩個部分。

hurl --test --variable base_url=http://127.0.0.1:3000 \
  --report-junit reports/junit.xml \
  --report-json reports/json \
  tests/

測試通過時,每個檔案會輸出一行,最後輸出摘要。

tests/checkout.hurl: Success (2 request(s) in 61 ms)
Executed files:    1
Executed requests: 2 (30.1/s)
Succeeded files:   1 (100.0%)
Failed files:      0 (0.0%)
Duration:          64 ms

測試失敗時,會輸出 error: Assert failure、檔案名稱與行號,接著列出實際取得的值和預期值;hurl 會以非零狀態結束,讓 CI 停止。如果 status 讀到的是 pending,但你預期的是 paid,表示服務未處理 mock 的回應。接下來應查看 /__admin/requests 的 WireMock request journal,確認請求是否真的到達 mock。

從您自己的 CI runner 觸發測試套件

如果 runner 註冊在同一台主機上,工作流程很簡短。runner 是主機上的一般程序,因此該主機必須安裝 docker 和 hurl。系統不會繼承代管映像檔中的任何內容。

name: api-tests
on: [push]
jobs:
  hurl:
    runs-on: self-hosted
    steps:
      - uses: actions/checkout@v4
      - name: Start the mock
        run: docker compose up -d --wait mock-payments
      - name: Run the suite
        run: hurl --test --variable base_url=http://127.0.0.1:3000 --report-junit reports/junit.xml tests/
      - name: Archive the reports
        if: always()
        run: install -d /srv/api-tests/reports/$GITHUB_SHA && cp -r reports/. /srv/api-tests/reports/$GITHUB_SHA/
      - name: Stop the mock
        if: always()
        run: docker compose down

封存步驟中的 if: always() 很重要。如果沒有它,測試執行失敗時就會略過複製作業,導致您遺失原本要查看的報告。複製目標也必須位於工作區之外,因為 actions/checkout@v4 預設會在擷取前執行 git clean -ffdx,下一次 checkout 時會從 repository 目錄移除未追蹤的報告。

保留結果,而不只是最後一次執行結果

每個 commit 一份 JUnit XML 檔案只能回答一個問題:測試是否通過。當你不再開啟這些檔案後,沒有人會讀取它們,因此無法知道某個 endpoint 是從何時開始變慢。若要追蹤趨勢,請將每次執行結果新增一列,寫入同一台主機上的小型資料庫。單一資料表只要保存 commit SHA、檔案名稱、通過數、失敗數及執行時間即可。將 SQLite 用於 VPS 正式環境 作為儲存位置是合理的選擇:只需一個檔案,不需要伺服器程序,而且完整歷史記錄會一併包含在你原本就會執行的備份中。解析 Hurl 的 --report-json 輸出以取得詳細執行資料;JSON 與 JUnit XML 都是機器可讀格式。

容器重建後必須保留的內容

Mock 定義與測試套件都是原始碼。它們應放在描述該服務的儲存庫中,並與端點變更一起提交同一個 pull request。若在 Web UI 中編輯 stub,或在執行期間透過 MockServer 的 REST API 推送 expectation,必須設定匯出或持久化機制,才能在重建後保留。執行 docker compose down 後,容器記憶體與可寫入層會遺失;儲存在 bind mount 或 named volume 中的資料則會保留。如果你的儲存庫也在自有硬體上執行,自架的 git 伺服器 能讓 fixtures 與服務位於同一個信任邊界內。

接著是實務規則。固定 image tag,因為 latest 可能在儲存庫未變更的情況下改變 mock 比對請求的方式,而這類失敗很難追查其原因。工具不需要寫入 stub 目錄時,請以唯讀方式掛載。絕不要將 mock 的 stub 放在 named Docker volume 中,因為該 volume 會成為真實來源,而 git 中的副本會在不知不覺間變成錯誤版本。

還有一點很容易被忽略。如果你透過 proxy 錄製實際網路流量來建立 stub,提交前請逐一讀過所有產生的檔案。錄製內容會完整保留 upstream 傳回的資料,包括 bearer token 與客戶的電子郵件地址。提交後,這些內容會永久留在儲存庫中,因為 git 會在歷史記錄中保留已刪除的內容。

FAQ

API mock server 與 API test runner 有何不同?

mock server 會回應請求。它可代替 CI 無法呼叫的相依服務;部分工具也能執行契約測試並回報結果。API test runner 會向自己的服務發送請求、驗證回應、將一次呼叫的值帶入下一次呼叫,並在驗證失敗時以非零狀態結束。兩者解決的是不同問題。典型設定會同時執行兩者:runner 呼叫自己的服務,而自己的服務呼叫 mock。

我可以從代管的 CI runner 測試內部 API 嗎?

可以,但需要私有網路。GitHub-hosted runner 支援 WireGuard overlay 或 Azure Virtual Network,可在不公開 API 的情況下連線至私有資源。其他選項包括公開 API、執行 tunnel,或維護公開的 staging 副本;每個選項都會增加可能故障或洩漏的系統。位於同一個私有網路的 runner 可直接呼叫服務,這也是團隊自行代管這項工作的主要實務原因。

mock stub 和 API test suite 應該放在哪裡?

放在 git 中,與其描述的服務放在一起。將定義儲存為檔案的工具,例如 WireMock 的 mappings/ 目錄、Mockoon 的 data file、Hurl 檔案和 Bruno 的 .bru 資料夾,可提供 code review,且重新建置容器不會增加成本。將定義儲存在資料庫或 web UI 的工具需要備份方案和匯出步驟;人們通常要等到容器已經消失,才會想起匯出是容易遺漏的部分。

為什麼 mock 在 stub 看似正確時仍回傳 404?

WireMock 只有在請求符合其設定的 matcher 時,才會提供 stub。未符合的請求會取得 404;存在近似符合項目時,回應本文會以 Request was not matched 開頭,接著列出與最接近 stub 的差異,而該差異會指出不一致的欄位。沒有 stub mappings 時,本文則會說明該 instance 沒有任何 mapping。常見原因包括 path 結尾多了斜線、stub 要求但 client 未傳送的 Content-Type header、在 stub 需要以 urlPathPattern 表示變動區段時卻使用了 urlPath,以及不符合 payload 的 body matcher。先檢查 /__admin/requests,確認請求是否確實到達 mock。

如果有 staging environment,仍需要 mock 嗎?

需要,原因有兩個。你無法控制的上游 staging 副本仍可能停止服務,也仍可能限制速率,因此 test suite 會因為與程式碼無關的原因失敗。它也無法產生最需要測試的回應,例如拒絕刷卡或 gateway timeout。mock 可依需求回傳這些回應,且使用本機網路速度,讓原本對 sandbox 需要數分鐘的 test suite 縮短為數秒。保留 staging 作為 release 前的最終檢查,並在 CI 中使用 mock。

這篇文章對您有幫助嗎?