面向對象的WebAPI框架XXL-HEX

一、簡介

1.1 概述

XXL-HEX 是一個簡單易用的WebAPI框架, 擁有 "面向對象、數據加密、跨語言" 的特點。目標是: 提高Web API (如 Android、IOS 等APP接口, 或者 unity3d 等遊戲服務端接口) 的開發體驗以及開發效率。現已開放源代碼，開箱即用。

1.2 特性

1、面向對象: 一個API接口對應 "一個Handler" 和 "Requset對象/Response對象"; 針對Web API開發 (如 Android、IOS 等APP接口開發, 或者 unity3d 等遊戲接口開發), 採用面向對象的思維去開發 Web API接口。提高API接口的開發效率以及開發體驗;
2、數據加密: 通訊數據以16進制數據的形式存在, 數據天然加密; 同時, 底層爲API接口預留了API校驗接口, 可方便的擴展數據加密邏輯, 進一步校驗數據安全性;
3、跨語言: 一個API接口, 開發一次, 支持任何語言調用(系統開放底層通信協議, 任何語言可靈活定製自己語言的Client端實現), 無論Client端是Android、IOS、C#開發的U3D遊戲等等;

1.3 背景

面向對象

當我們爲APP(安卓、IOS等)開發API接口時, 我們可能採用類似 RESTFUL 等方案, 但是此時API接口請求參數和響應數據比較零散, 需要針對多個參數進行繁瑣的參數獲取賦值等操作, 維護和使用比較繁瑣。

因此, 我們考慮上述Web API接口是否可以換一種面向對象的開發方式。在新系統中, 開發每一個API接口需要定義一個Handler類, 同時綁定Request對象和Response對象, 系統底層會自動把請求對象賦值給Request對象, 我們只需要調用Request對象中屬性值即可。同樣的, 我們只需要把響應數據賦值給Response對象即可; 自此, API接口的開發效率和開發體驗將會大幅度提升;

數據加密

常規API接口服務數據以明文格式存在, 數據易暴露業務信息, 如遭遇惡意爬蟲或者DDOS攻擊, 輕則加重服務器負擔, 服務器處理了外部非法的接口請求; 重則篡改線上業務數據, 造成嚴重後果。

XXL-HEX 的API接口通訊數據以HEX的格式存在, 天然加密, 安全性相對較高。初次之外, 支持自由擴展API接口的校驗邏輯, 進一步校驗數據安全性, 提高體統的整體安全性;

跨語言

當我們提供API接口, 調用方千差萬別, 如下:

1、Android (java)
2、IOS (object-c)
3、J2EE
4、PHP Web
5、.NET
6、unity3d (C#)
7、PC客戶端 (C++)

存在如此多的異構系統的情形下, 一種跨語言的 API 通訊方案顯得尤爲重要。

如果簡單實現跨語言則 RESTFUL 等方案可簡單實現, 但是如若要兼容上述 "面向對象" 和 "數據加密" 的特點, 同時保證系統簡易且穩定則存在一定難度。XXL-HEX得益於其基於HEX的特性以及底層特殊數據結構, 在保證兼容上述特性的技術上, 天然支持跨語言。

1.4 下載

源碼地址 (將會在兩個git倉庫同步發佈最新代碼)

博客地址

技術交流羣 (僅作技術交流)

社區交流

1.5 環境

Maven3+
Jdk1.7+
Tomcat7+

二、總體設計

2.1 架構圖

XXL-HEX作爲一個API接口實現方案, 是個典型的CS模型。

Server端只要由以下三個組件組成:

1、HexServlet: 服務端API接口的統一入口, 承擔API接口請求的路由功能;
2、HexHandlerFactory: 服務端核心組件, 負責API接口請求的 "dispatch", 以及消息的編解碼以及序列化; 同時作爲Handler倉庫, 彙總並維護服務端可用業務Handler;
3、HexHandler: API接口以HexHandler的形式存在。開發人員開發具體業務Handler時, 需要實現 "validate" 和 "handle" 接口, 前者負責業務校驗, 後者執行具體的業務邏輯;

Client端主要由兩個模塊組成:

1、serialize/desecrialize: 負責對消息對象序列化以及編解碼操作, 生成服務端可識別的hex消息;
2、remote: 負責和Server端之間的消息通信, 消息體爲hex格式數據;

2.2 "一次API接口請求時序圖" 分析

從上圖可知, 一次API請求過程所經歷的流程爲:

1、Client端創建Request消息對象;
2、Request消息對象, 轉換爲 "HEX格式Request消息" (Server端只會識別HEX格式消息), POST發送到Server端;
3、HexServlet路由組件, 接收API請求, 將請求發送給HexHandlerFactory組件;
4、HexHandlerFactory負責解碼 "HEX格式Request消息", 並反序列化爲Request對象, 然後將API請求dispatch到指定的業務Handler上;
5、業務Handler首先會根據Request對象進行validate校驗, 校驗成功則執行業務handle方法, 執行具體的業務邏輯;
6、業務handle執行結束, 封裝執行結果爲Response對象;
7、HexHandlerFactory組件負責將Response對象序列化, 然後編碼爲 "HEX格式Response消息", 返回給HexServlet路由;
8、HexServlet路由組件, 響應 "HEX格式Response消息" 消息給Client端。Finish。

2.3 "消息體結構(HEX數據結構)" 設計

網絡傳輸時, 請求響應數據以HEX(16進制字符串)的格式存在。HEX格式消息的數據來源如下 (以將請求參數轉換爲HEX爲例) :

第一步: 封裝 "Request對象" (不同開發語言, 對象可能不同, 這一步僅僅針對Java語言, 如其餘開發語言實現Client, 可直接跳到 "第二步" )
第二步: 將 "Request對象" 序列化爲 "JSON字符串" ; (JSON屬性, 應該可服務端Request對象屬性保持一致)
第三步: 將 "JSON字符串" 轉換爲 "特殊格式" 的字節數據 "byte[]", "byte[]" 的組成: "JSON字符串"長度(4字節) + "JSON字符串"字節內容;
第四步: 將 "byte[]" 轉換爲 HEX 數據。 Finish。

至此, 已經生成了服務端可以識別的HEX數據。至於服務端返回的HEX格式數據的解析, 安裝上述步驟逆序操作即可。

三、快速入門

3.1 服務端配置和開發

1、配置maven依賴

2、配置HexHandler路由入口

3、配置HexHandler工廠, 並配置HexHandler掃描路徑

4、開發第一個API接口 (可參考下面Demo示例, 進行理解和學習)

每個API接口, 由三部分組成: HexHandler + Request + HexResponse

開發HexHandler流程:

1、需要繼承HexHandler<T>父類, 並且定義T(Request對象), 該對象爲該API接口的入參;
2、實現父類的validate方法, 可進行安全性校驗, 以及業務參數校驗等。返回null表示校驗成功;
3、實現父類的handle方法, 開發業務邏輯即可, 並且定義HexResponse, 其含義爲API接口返回值。
4、新增Spring註解	 "@Service", 用於方便的注入Spring容器中其餘服務; 新增 "@HexHandlerMapping" 註解, 註解value值爲該API接口的唯一標示, Client端調用時將會使用到;

開發Request流程: 創建普通Java類即可

開發HexResponse流程:

1、需要繼承HexResponse父類
2、需要實現Serializable接口

訪問地址 http://localhost:8080/hex 可查看在提供服務的的API接口

3.1 客戶端開發 (可參考提供的三種Client調用Demo, 進行理解和學習，並定製其他版本Client端實現)

三種Client調用Demo說明:

1、對象方式調用: 本方式適用於Client同爲Java語言, 且Client端可以獲取Server端API接口對應的的Request和Response的Java文件的情況;
- 調用方法: 使用官方提供 "HexClient.handleObj" 方法發起API請求
- 特點: 使用方便, 但是需要依賴Server端API接口的Request和Response的Java類文件;
2、JSON方式調用: 適用於Client同爲Java語言情況;
- 調用方法: 使用官網提供 "HexClient.handleJson" 方法發起API請求
- 特點: 使用靈活, 不需要依賴Server端
3、原始方式調用: 本方式採用原始方式對XXL-HEX服務端發起請求, 非Java開發語言的開發者, 可以參考本方式, 從而定製各自開發語言Client端實現;
- 調用方法: 採用原始方式對XXL-HEX服務端發起請求, 對數據編解碼和序列化/反序列化步驟有詳細的說明
- 特點: 非常靈活, 跨語言。可以根據本方式示例方便的實現一個"面向對象、數據加密、跨語言"的API接口Client端;

3.2 JS版本客戶端開發

系統已經提供了JavaScript版本的Client端實現，調用DemoHandler的JS代碼如上圖，簡單易用。接入之後，底層數據通訊將會以HEX加密串的形式進行數據傳輸。

首先，提供系統的安全性；其次，API接口一次開發，可以多次複用，無論開發語言是Java、OC、C#、JS等等；而且，API服務端可採用面向對象的方式進行API接口開發，提供開發效率和體驗；

讓API接口擁有 "面向對象、數據加密、跨語言" 的特點。

四、歷史版本

4.1 版本1.1.0新特性

1、面向對象: 一個API接口對應 "一個Handler" 和 "Requset對象/Response對象"; 針對Web API開發 (如 Android、IOS 等APP接口開發, 或者 unity3d 等遊戲接口開發), 採用面向對象的思維去開發 Web API接口。提高API接口的開發效率以及開發體驗;
2、數據加密: 通訊數據以16進制數據的形式存在, 數據天然加密; 同時, 底層爲API接口預留了API校驗接口, 可方便的擴展數據加密邏輯, 進一步校驗數據安全性;
3、跨語言: 一個API接口, 開發一次, 支持任何語言調用(系統開放底層通信協議, 任何語言可靈活定製自己語言的Client端實現), 無論Client端是Android、IOS、C#開發的U3D遊戲等等;

4.2 版本1.2.0新特性

1、Client端，新增Javascript版本實現：示例文件見 "xxl-hex/xxl-hex-example/src/main/webapp/jsclient.html"，啓動 "xxl-hex-example" 項目訪問即可；
2、Server端，新增明文模式：如果系統不需要Hex加密特性，可選擇明文數據傳輸方案；

規劃中

WebAPI之家：可通過界面查看登記的API列表，支持API管理，支持Mock調用等；
服務端在線MOCK功能實現(支持通過瀏覽器訪問 http://項目地址/hex 查看可提供服務的所有業務API接口, 同時可在線MOCK接口調用);
"xxl-hex-core" 推送maven中央倉庫

五、其他

5.1 報告問題

項目託管在Github上，如有問題可在 ISSUES 上提問，也可以加入上文技術交流羣；

5.2 接入登記

更多接入公司，歡迎在github 登記