API 調試與自動化測試平台實戰：Postman、Hoppscotch、Swagger 全流程指南

2025-05-16

一、為什麼要使用 API 調試工具？

在對接京東開放平台 API（或第三方如 LuckData 的京東 API 封裝）時，經常會遇到以下問題：

手動拼接請求參數和簽名計算繁瑣；
錯誤排查效率低，難以快速定位問題；
測試參數無法重用，不易在不同環境間切換；
缺乏測試用例與接口文檔的統一管理與團隊共享能力。

此時，選擇合適的 API 調試與測試平台 能大幅提升開發效率、提升穩定性與可維護性。

二、主流工具介紹與對比

工具	特點	適用場景
Postman	支援 Collection 管理、環境變數、Pre-request 腳本、自動化測試	適合企業團隊日常開發與測試需求
Hoppscotch	開源、輕量、免登入即可使用，支援 WebSocket 等高級協議	適用於快速測試、Postman 替代工具
Swagger UI	自動生成 API 文檔、支援線上交互調試	適合配合 OpenAPI 文檔進行展示與維護
Swagger + Newman（Postman CLI 工具）	結合 CI/CD 做 API 回歸測試，自動化執行接口測試	適合構建自動化測試流程

三、Postman 調試京東官方 API（或 LuckData 京東 API）

1. 構造基本請求

以京東聯盟 API 的商品搜尋接口 jingdong.union.search.goods.query 為例：

請求地址：

POST https://api.jd.com/routerjson

Headers（可選）：

Content-Type: application/x-www-form-urlencoded

請求參數（x-www-form-urlencoded 格式）：

{ "app_key": "你的app_key", "method": "jingdong.union.search.goods.query", "access_token": "你的access_token", "timestamp": "2025-05-15 10:30:00", "format": "json", "v": "1.0", "sign": "根據簽名規則計算結果", "360buy_param_json": "{\"goodsReqDTO\":{\"keyword\":\"iPhone\"}}" }

✅ 如果使用 LuckData 提供的京東 API，已內建簽名機制，僅需傳入標準參數，無需自行處理簽名，大幅簡化操作。

2. 使用 Pre-request Script 自動計算簽名（適用於原始京東 API）

在 Postman 的 Pre-request Script 中加入以下 JavaScript 腳本，自動處理簽名計算：

const appSecret = "你的app_secret";
const params = {
method: "jingdong.union.search.goods.query",
app_key: "你的app_key",
access_token: "你的access_token",
timestamp: pm.variables.replaceIn("{{timestamp}}"),
v: "1.0",
format: "json",
"360buy_param_json": JSON.stringify({
goodsReqDTO: {
keyword: "iPhone"
}
})
};
// 簽名計算
let signStr = appSecret;
Object.keys(params).sort().forEach(k => {
signStr += k + params[k];
});
signStr += appSecret;
const md5 = CryptoJS.MD5(signStr).toString().toUpperCase();
params["sign"] = md5;
pm.environment.set("signed_params", JSON.stringify(params));

在請求的 Body 區塊中使用 {{signed_params}} 引用自動計算後的參數。

四、Hoppscotch：開源輕量選擇

當只需快速驗證 API 是否可用，不需配置過多測試邏輯時，Hoppscotch 是極佳的輕量級替代方案：

開啟即用，無需註冊安裝；
支援多種認證方式與協議；
可直接生成程式碼範本（支援 Python、JavaScript 等）；

使用步驟：

打開 hoppscotch.io；
輸入京東 API 的請求地址；
選擇 POST 方法與 x-www-form-urlencoded 格式；
填寫所有必要參數；
發送請求並檢視返回結果。

✅ 使用 LuckData 封裝版本時，可直接填寫標準 JSON 參數，體驗更加流暢簡單。

五、Swagger UI：構建可交互文檔與快速測試入口

適用場景：

團隊自行封裝 API 並提供外部使用（如搭配 Kong、Tyk API Gateway）；
將第三方 API（如 LuckData）封裝給內部或合作開發者測試；
需對外公開提供 API 文檔查閱與互動。

OpenAPI 3.0 文檔結構範例：

paths: /jingdong/goods-search: post: summary: 京東商品搜尋接口（LuckData 托管） requestBody: content: application/json: schema: type: object properties: keyword: type: string example: "iPhone" responses: 200: description: 正常返回商品列表

該文檔可部署至以下平台：

Swagger UI（官方互動式界面）；
ReDoc（支援美觀文檔展示）；
Stoplight.io（完整 API 設計與共享平台）；

可快速生成 API 測試點與協作平台，提升溝通效率。

六、自動化測試：Postman Collection + Newman

在 Postman 中配置測試腳本

pm.test("響應成功", function () {
pm.response.to.have.status(200);
});
pm.test("返回包含商品資料", function () {
const json = pm.response.json();
pm.expect(json.data).to.be.an("array");
});

將測試流程保存為 Collection，並透過 Newman CLI 工具進行自動化測試執行：

newman run jd_goods_collection.json

可整合 GitHub Actions、GitLab CI、Jenkins 等工具，完成接口測試流程自動化與部署檢查。

七、LuckData 封裝 API 的優勢：免簽名、快測試、全平台支持

京東原生 API 較為繁瑣，涉及簽名計算、token 管理、參數格式非標準等問題，而 LuckData 提供的統一封裝 API 則解決了這些痛點，具有如下優勢：

標準化 JSON 請求格式，無需 x-www-form-urlencoded；
無需自行簽名，只需提供 Token 即可完成請求；
支援京東、拼多多、淘寶、Amazon 等主流電商平台，統一接口調用方式；
提供 SDK（Python、Node.js、Java、Shell）與內建調試工具，適合快速集成。

調用示例（LuckData 封裝 API）：

curl -X POST https://luckdata.cn/api/jingdong-api/goods-search \ -H "Authorization: Bearer your_token" \ -d '{"keyword": "iPhone"}'

相比原生 API 的複雜度，簡單易用，大幅提升開發效率與接入速度。

八、總結

工具	使用重點	特別適合對象
Postman	自動簽名、測試腳本撰寫、變數管理	後端開發者、測試工程師
Hoppscotch	輕量即用、快速驗證 API 呼叫結果	運維、技術支持人員、小型團隊
Swagger UI	自動生成文檔、提供交互式測試入口	有文檔需求的技術團隊與前端協作者
LuckData SDK	零簽名、零配置、統一 API 接口支持多平台電商數據對接	數據平台開發者、整合多電商平台者

Articles related to APIs :

如您需要方便快速使用 Jingdong API 可聯係我們：support@luckdata.com