框架概览
HiAPI 是一套面向多租户 SaaS 系统的 Java 应用框架,基于 Spring Boot 3 与 Spring Cloud 构建。它解决的是这样一类重复劳动:每做一个新的 SaaS 业务系统,都要重新实现一遍租户隔离、 分页查询、鉴权、文件上传、短信、事件通知、分库分表——而这些东西的正确实现成本远高于看上去的样子。
框架把它们做成可继承、可配置的基座,业务代码只写真正属于业务的那一部分。
运行环境
| 项 | 版本 |
|---|---|
| JDK | 21 |
| Spring Boot | 3.4.4 |
| Spring Cloud | 2024.0.0 |
| 数据库 | MySQL(通过 ShardingSphere 接入) |
| 缓存 | Redis |
能力地图
框架由一组独立模块组成,按需引入。
内核
| 模块 | 提供 |
|---|---|
hiapi-core-basic | 基础实体、统一响应封装、账户类型、字段更新描述 |
hiapi-core-exception | 统一异常与错误码 |
hiapi-core-language | 多语言文案来源 |
hiapi-core-utils | 通用工具 |
数据访问
| 模块 | 提供 |
|---|---|
hiapi-core-service | BasicService / AbsBasicService,领域服务基类 |
hiapi-core-query | QueryWrapper 条件构造、分页请求、租户查询基类 |
hiapi-core-sharding | 分片配置:按时间或指定字段分表 |
hiapi-core-sharding-service | 分片表的服务层支持与建表任务 |
hiapi-core-redis | 缓存封装 |
Web 层
| 模块 | 提供 |
|---|---|
hiapi-core-controller | BasicQueryController / BasicCurdController |
hiapi-core-application | 启动期自动装配 |
安全
| 模块 | 提供 |
|---|---|
hiapi-core-security | Token 过滤器、URL→角色授权判定、开放接口清单 |
hiapi-core-security-token | Token 签发与解析 |
hiapi-core-login | 登录、注册、改密、找回,登录前后拦截与事件 |
hiapi-core-captcha-basic | 滑块验证码,含行为轨迹校验 |
基础设施
| 模块 | 提供 |
|---|---|
hiapi-core-upload | 文件上传:本地 / OSS / COS / S3,预签名直传与回调 |
hiapi-core-sender | 短信与邮件发送及发送记录 |
hiapi-core-dispatch | 跨服务 SPI 分发、Redis 分布式锁 |
hiapi-core-event-sdk | 事件发布订阅与 MQ 路由 |
hiapi-core-iot-mqtt | MQTT 设备接入(含 AWS IoT) |
hiapi-core-operation-log | 注解式操作日志 |
hiapi-core-thirdparty-api | 第三方平台对接 |
hiapi-core-app-install | 子应用安装、菜单与跳转链接注册 |
核心概念
一、Controller 继承即得 CRUD
业务 Controller 继承基类并声明泛型,分页查询、按 id 取详情、新增、修改、删除即刻可用:
java
@RestController
@RequestMapping("/merchant/product")
public class ProductController
extends BasicCurdController<Product, Long, ProductVo, ProductQuery> {
}需要定制的地方覆写钩子即可,不必推翻基类:
| 钩子 | 时机 |
|---|---|
getMid() | 取当前租户标识 |
parseData(...) | 保存前把请求字段转成实体 |
buildFields(...) | 更新前构造待更新字段 |
toListVo(...) / toDataVo(...) | 实体转出参 |
saveCallback(...) | 保存后置逻辑(在同一事务内) |
deleteBeforeIntercept(...) | 删除前校验 |
二、多租户是地基
框架区分四类账户,路径前缀就是权限边界:
| 前缀 | 账户类型 |
|---|---|
/merchant/** | 商户 |
/user/** | 终端用户 |
/channel/** | 渠道 |
/platform/** | 平台 |
所有业务数据都带租户标识。当前请求的租户与登录身份从 Token 中取:
java
Long mid = TokenGet.getMid(); // 租户标识
Long fid = TokenGet.getFid(); // 当前登录账户三、更新走字段描述,不整对象覆盖
避免读-改-写导致的并发覆盖:
java
service.update(
UpdateFields.newBuilder().put("status", 1).build(),
QueryWrapper.create().eq("mid", mid).eq("id", id)
);四、两层授权
- 账户类型:按路径前缀与注解做粗粒度拦截,全服务生效
- 角色 / 菜单:URL→角色规则在请求期判定,规则变更最长 60 秒生效,无需重启
五、跨服务调用只认 SPI
服务之间不直接依赖对方的客户端类,而是通过框架的 SPI 取得实现:
java
ICloudMerchantService merchant = dispatchContext.getCloudService(ICloudMerchantService.class);本地实现优先于远程调用实现,单体部署与微服务部署使用同一份业务代码。
关于授权
框架为专有商业软件。构件发布在 Maven Central 是为了让已授权客户(尤其是无法访问 中国大陆私有仓库的海外客户)能够直接拉取依赖,这不构成对公众的授权。
随构件发布的 -sources 与 -javadoc 附件是有意留空的占位包,不包含源代码。
详见授权说明。