面向对象的WebAPI框架XXL-HEX

小咪咪 2022-05-31 03:40 365阅读 0赞

## 一、简介 ##

#### 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仓库同步发布最新代码)

*  [github地址][github]
 *  [gitee地址][gitee]

博客地址

*  [oschina地址][oschina]
 *  [cnblogs地址][cnblogs]

##### 技术交流群 (仅作技术交流) #####

*  [社区交流][Link 1]

#### 1.5 环境 ####

*  Maven3+
 *  Jdk1.7+
 *  Tomcat7+

## 二、总体设计 ##

#### 2.1 架构图 ####

[![输入图片说明][68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313630392f31363230303134385f4c6f4d522e6a7067]][68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313630392f31363230303134385f4c6f4d522e6a7067]

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接口请求时序图" 分析 ####

[![输入图片说明][68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313630392f31363139313531375f4870634b2e6a7067]][68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313630392f31363139313531375f4870634b2e6a7067]

从上图可知, 一次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数据结构)" 设计 ####

[![输入图片说明][68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313630392f31363139333835395f4a4979752e6a7067]][68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313630392f31363139333835395f4a4979752e6a7067]

网络传输时, 请求响应数据以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依赖

[![输入图片说明][68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313630392f31363231313033325f384a584e2e706e67]][68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313630392f31363231313033325f384a584e2e706e67]

*  2、配置HexHandler路由入口

[![输入图片说明][68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313630392f31363231313433355f357457702e706e67]][68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313630392f31363231313433355f357457702e706e67]

*  3、配置HexHandler工厂, 并配置HexHandler扫描路径

[![输入图片说明][68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313630392f31363231313234375f4e3442562e706e67]][68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313630392f31363231313234375f4e3442562e706e67]

*  4、开发第一个API接口 (可参考下面Demo示例, 进行理解和学习)

[![输入图片说明][68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313630392f31363231323534385f416147742e6a7067]][68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313630392f31363231323534385f416147742e6a7067]

每个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][http_localhost_8080_hex] 可查看在提供服务的的API接口

[![输入图片说明][68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313630392f31363231333531305f794c41672e706e67]][68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313630392f31363231333531305f794c41672e706e67]

#### 3.1 客户端开发 (可参考提供的三种Client调用Demo, 进行理解和学习，并定制其他版本Client端实现) ####

[![输入图片说明][68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313630392f31363232303432355f76314c4b2e6a7067]][68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313630392f31363232303432355f76314c4b2e6a7067]

[![输入图片说明][68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313630392f31363232303433375f434851342e6a7067]][68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313630392f31363232303433375f434851342e6a7067]

[![输入图片说明][68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313630392f31363232303435355f636d79502e6a7067]][68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313630392f31363232303435355f636d79502e6a7067]

三种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版本客户端开发 ####

[![输入图片说明][68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313631302f30363231343730305f643770482e706e67]][68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313631302f30363231343730305f643770482e706e67]

[![输入图片说明][68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313631302f30363231343633375f57694f682e706e67]][68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313631302f30363231343633375f57694f682e706e67]

系统已经提供了JavaScript版本的Client端实现，调用DemoHandler的JS代码如上图，简单易用。接入之后，底层数据通讯将会以HEX加密串的形式进行数据传输。

首先，提供系统的安全性；其次，API接口一次开发，可以多次复用，无论开发语言是Java、OC、C\#、JS等等；而且，API服务端可采用面向对象的方式进行API接口开发，提供开发效率和体验；

让API接口拥有 "面向对象、数据加密、跨语言" 的特点。

## 四、历史版本 ##

#### 4.1 版本1.1.0新特性 ####

#### 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][http_hex] 查看可提供服务的所有业务API接口, 同时可在线MOCK接口调用);
 *  "xxl-hex-core" 推送maven中央仓库

## 五、其他 ##

#### 5.1 报告问题 ####

项目托管在Github上，如有问题可在 [ ISSUES][ISSUES] 上提问，也可以加入上文技术交流群；

#### 5.2 接入登记 ####

更多接入公司，欢迎在github [ 登记][Link 2]

[github]: https://github.com/xuxueli/xxl-hex
[gitee]: https://gitee.com/xuxueli0323/xxl-hex
[oschina]: https://my.oschina.net/xuxueli/blog/747391
[cnblogs]: http://www.cnblogs.com/xuxueli/p/5003305.html
[Link 1]: http://www.xuxueli.com/page/community.html
[68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313630392f31363230303134385f4c6f4d522e6a7067]: /images/20220531/898c21051de145bdbbe2ce8b0a108add.png
[68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313630392f31363139313531375f4870634b2e6a7067]: /images/20220531/944af3d9e38d444899a0628c4a77709e.png
[68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313630392f31363139333835395f4a4979752e6a7067]: /images/20220531/5f3d39f6c5604059ab477d85757964c5.png
[68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313630392f31363231313033325f384a584e2e706e67]: /images/20220531/f95816a635ad4f44b11dea1b4a2bbdce.png
[68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313630392f31363231313433355f357457702e706e67]: /images/20220531/1b6fac7b88924d679f296b2172f66900.png
[68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313630392f31363231313234375f4e3442562e706e67]: /images/20220531/689f5231d1374a71819a0c72c6a6a17f.png
[68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313630392f31363231323534385f416147742e6a7067]: /images/20220531/2a2ce0972a8a4b8e886c9d813d9c8c6e.png
[http_localhost_8080_hex]: http://localhost:8080/hex
[68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313630392f31363231333531305f794c41672e706e67]: /images/20220531/056a05cf8f314e9b95faa5f8279f61bf.png
[68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313630392f31363232303432355f76314c4b2e6a7067]: /images/20220531/b49f0840b5164bb9a929ed85c5b287eb.png
[68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313630392f31363232303433375f434851342e6a7067]: /images/20220531/5e84b1fe24c34d1a892f70be14531c58.png
[68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313630392f31363232303435355f636d79502e6a7067]: /images/20220531/0423af1cebd0420fa9611796184e3bdd.png
[68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313631302f30363231343730305f643770482e706e67]: /images/20220531/0baf46275fa5489b977cacb56bf85986.png
[68747470733a2f2f7374617469632e6f736368696e612e6e65742f75706c6f6164732f696d672f3230313631302f30363231343633375f57694f682e706e67]: /images/20220531/53c0c443938e4e2cbf84b7ea2e87dea0.png
[http_hex]: http://%E9%A1%B9%E7%9B%AE%E5%9C%B0%E5%9D%80/hex
[ISSUES]: https://github.com/xuxueli/xxl-hex/issues
[Link 2]: https://github.com/xuxueli/xxl-hex/issues/1