JAVA小咖秀 - 當同事引入這款開發神器以後。。－鑽石舞台

Nov 09 Wed 2022 17:00
JAVA小咖秀 - 當同事引入這款開發神器以後。。

簡介

在開發前後台分離項目並且通過不同團隊來實現的時候，如何將後台設計的 API 準確的傳達到前台，是一個非常重要的工作。為了簡化這個過程，開源社區做了很多努力，比如 protobuf技術，swagger 的誕生，以及後面 openapi 的演化，都在試圖解決 API 描述和文檔的問題。這些標準某些程度上大大簡化了 API 文檔的撰寫和維護，但是API設計往往比較複雜，所以另外還有一些痛點沒有解決：

1.若干 API 的調用順序是有要求的2.若干 API 的輸入和輸出是相互關聯的3.若干 API 需要重複調用達到不同的效果

舉了具體的例子, 某後端小夥伴X和前端小夥伴Y合作開發一款遊戲, X 設計好 API 然後 Y 來調用實現:

Y: API1 根本調用不成功, 得不到我想要的數據?

X: balabala 介紹了一遍. (X 默默地完善了文檔)

Y: 如何觸發這個遊戲邏輯啊? X: 可以參考我的文檔 (自信的說)

Y: 這個文檔根本看不懂啊, 還是給我舉個例子吧?

X: ... balabala 溝通半天

過了幾天來了一個新的前端開發 Z:

Z: 如何觸發這個遊戲邏輯啊 X: ...

有時候我們會發現很多時候 API 文檔不足以完成前後端 API 設計的交流, 更多的時間用在相互溝通中. API 管理平台的誕生，可以說解決了這些痛點. 說起 API 管理平台首先最成功的的要數 Postman 了，筆者是 Postman 早期用戶，基本使用了大部分的高級功能，近幾年開始推廣 Team 概念. ApiFox 作為中國的一體化 API 協作平台，從一開始就定位於團隊協作，可以說目標十分明確. 目前在嘗試從 Postman 遷移至 ApiFox，發現過程非常流暢，涵蓋了所有目前我們使用功能.

本文主要介紹兩方面內容:

1.如何從 Postman 遷移至 ApiFox2.如何使用 ApiFox 實現展示後台 API 的調用場景

在介紹第二個方面內容時，儘可能介紹 Postman 對應的功能名稱，從而給那些熟悉 Postman 的開發者以參考.

Postman 遷移至 ApiFox結構對比

首先我們先了解一下 Postman 和 ApiFox 的管理控制結構，

Postman: Team → Workspace → Collections → Any Level Folders → Request

ApiFox: Team → Project → Any Level Folders → Request

變量控制

兩者類似:

1.支持全局變量2.支持環境變量及切換

ApiFox 導入 Postman

通過上面的管理控制結構，我們可以明確知道，我們只需要將對應的 Postman 的 Collection 導入 ApiFox 的 Project 中即可.

其中 ApiFox 提供了詳細的文檔介紹 Postman 的導出以及 ApiFox 導入. 通過測試，目前的 Postman 可以支持所有的數據映射，包含了 Postman 中的 Pre-req 和 test 腳本.

導入完成後兩者對比，可以發現 Postman 的 Collection 映射到 Project 的 Root Folder 之後的結構完全是相同的:

這裡唯一美中不足的是, 目前無法導入環境變量, 應該還在開發中.

關於 Script 的導入

這裡需要注意的一點是，在 Postman 中我們可以直接在 Request 上進行編輯 pre-req 和 test 來控制 Request 的 Response. 在導入後，ApiFox 把默認的數據創建出一個 API Case，這個 Case 包含了 Postman 的 script 數據.

舉個例子:

這是 Postman 中的一個 API，其中包含 Test script

在 ApiFox 中，Request 本身並沒有包含這個 Script

ApiFox 創建了一個默認的 Passed API Case，然後在這個 API Case 中加入了這個 Script

ApiFox 展示 API 調用場景

介紹完導入工作，下面就開始重點介紹使用 ApiFox 來模擬 API 使用場景. 實現這個目標是基於如下功能:

1.無限級別目錄2.動態更新環境變量3.每個請求支持 pre-processer 和 post-processer 來處理返回數據，理論上支持任何操作4.測試用例支持添加某個目錄來執行

總的來說，通過 ApiFox 的腳本引擎，來模擬客戶端的一些操作，從而達到展示 API 使用場景的目的. 本文針對筆者目前使用經驗介紹若干腳本的使用方法，如果需要深入了解腳本系統，請參考官方文檔:使用腳本[1]. ApiFox 提供了比 Postman 更加強大的腳本系統，除了 Javascript，還支持其他語言的調用.

請求的後置腳本

下面我們通過一個簡單的遊戲 API 案例來介紹以上功能的使用.

API 接口定義很簡單，只包含兩個 API

1.Game_init: 初始化用戶數據2.Game_round: 遊戲的玩法很簡單，玩家只需要點擊一個按鈕來進行抽獎，抽獎的結果是隨機的，並且可能觸發特殊遊戲: 比如更換更高級的獎品. API 本身支持調試，就是通過輸入參數來返回特定的抽獎結果.

現在我們的目標就是模擬一次用戶開始抽獎並且觸發了特殊遊戲獲取高級獎勵，並繼續抽獎最後獲取獎勵的遊戲場景. 通過 API 的接口定義，我們可以看到 API 的調用邏輯應該是:

1.調用 Game_init 一次2.調用 Game_round 多次，直到遊戲結束

所以遊戲場景的 API 結構如下圖:

我們使用 Scene1 來表示上述演示的調用場景. 下面我們開始對每個 API 的 Request 進行處理，從而達到模擬 API 連續調用.

Game_initAPI的輸入和輸出很簡單:

輸入:

{ "gameId": "{{fe}}"， "player": { "isDummy": true }}

輸出

{ "player": { "playerId": "Demo"， "name": "Demo"， "balance": "1000000"， "balanceRate": "100"， "currency": "FUN"， "isDummy": true }}

Game_initAPI 調用完成後，我們需要持續追蹤玩家數據的變化，所以這裡我們需要將返回的用戶信息儲存在環境變量中，我們可以通過 Post-processors，添加一個 Custom Script 來實現:

pm.test("Get Response"，function () { var jsonData = pm.response.json(); console.log(jsonData) // we update playerData in the environment pm.environment.set('playerData'，JSON.stringify(jsonData.player))});

這段代碼有兩個關鍵點:

1.將 API 的返回結果解析為 JSON 數據:pm.response.json()2.將 JSON 數據中的player信息出處到環境變量中，並且命名為playerData:pm.environment.set('playerData'，JSON.stringify(jsonData.player))

完成這腳本後，我們可以執行這個 Request，然後查看我們的環境變量信息，playerData動態添加進來:

Game_roundAPI的輸入輸出

輸入:

{ "gameId": "{{fe}}"， "cheat": { "cheatId": 1 }， "player": {{playerData}}， "betContext": {{betContextData}}}

輸出

{ "player": { "playerId": "Demo"， "name": "Demo"， "balance": "1015000"， "balanceRate": "100"， "currency": "FUN"， "isDummy": true }， "betContext": { "roundsAwarded": 1， "currentBetMode": "A"， "nextBetMode": "B" }， "gameRoundResult": {}}

我們在處理 Game_round API 的時候和 Game_init 類似，每次得到 Game Round 的返回的 JSON 後，更新playerData和betContextData. 同時我們還發現，該請求的輸入數據同樣使用了環境變量playerData和betContextData，從而多次調用 Game_round API 後，玩家數據和遊戲數據是不斷進行更新的.

pm.test("Get Response"，function () { var jsonData = pm.response.json(); console.log(jsonData) // we update playerData and game context in the environment pm.environment.set('playerData'，JSON.stringify(jsonData.player)) pm.environment.set('betContextData'，JSON.stringify(jsonData.betContext))});

通過這種方法在執行這 3 個 API的過程中，就可以查看用戶數據的變化以及每次遊戲結果，從而幫助前端開發者理解和使用 API.

1.GameInit遊戲初始化2.Round1進入特殊遊戲3.Round2特殊遊戲獎勵

增加斷言驗證 API

我們在設計 API 使用場景的時候，可以同時對 API 進行測試. 在不同場景下 API 的返回可能是不同的，所以這裡進行測試斷言可以更精確的定位問題.

比如我們上述的案例，第二個請求需要觸發用戶進入特殊的遊戲模式，這裡需要後台 API 支持特殊的測試參數，通過這個參數可以跳過隨機結果直接獲取需要的結果.

"cheat": { "cheatId": 1}

也就是說如果 Game_round 請求的輸入數據中包含如下數據，那麼這個請求的數據一定是進入了特殊模式. 在這個案例中就是說，輸出的nextBetMode一定是模式SpeicalMode

"betContext": { "roundsAwarded": 1， "currentBetMode": "A"， "nextBetMode": "SpeicalMode"}

這時候我們就可以斷言:$.betContext.nextBetMode equl SpeicalMode

如果我們在執行 request 的時候斷言出錯，就會得到一個 Error，如下圖 (這裡是故意配置錯誤的斷言結果)