# zadmin **Repository Path**: minivip/zadmin ## Basic Information - **Project Name**: zadmin - **Description**: 使用springboot4 easy-query最新技术栈的多租户后台管理框架 - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 1 - **Created**: 2026-03-22 - **Last Updated**: 2026-03-22 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # ZAdmin 后台管理系统 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0) [![Java](https://img.shields.io/badge/Java-25-orange.svg)](https://openjdk.org/) [![Spring Boot](https://img.shields.io/badge/Spring%20Boot-4.0.3-green.svg)](https://spring.io/projects/spring-boot) [![Maven](https://img.shields.io/badge/Maven-4-C71A36.svg)](https://maven.apache.org/) [![Easy-Query](https://img.shields.io/badge/Easy--Query-3.1.82-purple.svg)](https://www.easy-query.com/) ZAdmin 是一个基于 **Java 25** 和 **Spring Boot 4.0** 构建的现代化、模块化后台管理系统。项目采用 **Maven 4** 多模块架构设计，集成高性能 ORM 框架 Easy-Query，致力于提供高效、灵活且易于维护的开发体验。 ## 🚀 项目特性 ### 核心能力 - **前沿技术栈**: 基于最新的 **Java 25** 开发，充分利用虚拟线程、模式匹配等新特性 - **Maven 4 构建**: 使用 POM 4.1.0 模型，支持 `root` 属性、`` 自动推断、子项目自动发现、CI-friendly 版本等新特性 - **模块化架构**: 清晰的 Maven 多模块设计，实现关注点分离，支持按需加载 - **高性能 ORM**: 集成 **[Easy-Query](https://www.easy-query.com/)**，支持强类型 Lambda 查询、编译期代理生成、零反射调用 - **多数据源支持**: 内置动态数据源管理，支持运行时动态注册，涵盖 12+ 种数据库（PostgreSQL、MySQL、Oracle、达梦、人大金仓等） - **Spring Security**: 基于 Redis Token 的无状态认证，路径级权限控制，完整的 RBAC 模型 ### 开发体验 - **极简实体操作**: 基于 `ParentClientEntity` 基类，实体可直接调用 `insert()` / `update()` / `delete()` / `save()` 等链式方法 - **批量链式操作**: `EntityList` 支持 `new Entity().copyFrom(dtos).insert()` 批量链式操作 - **通用查询方案**: `IPageDTO` + `whereObject` + `orderByObject` 封装动态条件查询与排序，默认排序通过 `dto.defaultIdAsc()` 链式调用 - **自动审计填充**: `AuditInterceptor` 自动填充 `updateId`、`updateTime` 等审计字段 - **多租户隔离**: `TenantInterceptor` 透明的租户数据隔离，自动注入租户条件 - **部门数据隔离**: `DeptInterceptor` 自动按部门过滤数据 - **灵活跳过过滤**: `@SkipDataFilter` 注解可按权限跳过租户/部门过滤 - **历史数据追溯**: `HistoryUtil` 基于 JSONB 字段的历史记录查询 ### 安全与防护 - **Token 认证**: Redis 存储 Token，支持自动续期与最大存活时间限制 - **路径权限校验**: `PathAuthorityInterceptor` 自动根据请求路径校验用户权限 - **接口防抖**: `DebounceInterceptor` 基于 Redis 的请求防抖，防止重复提交 - **验证码**: 滑块验证码，支持容错值配置与水印 - **AES 加密**: 内置 AES 对称加密工具 - **自定义校验**: `@INotNull` 注解，支持多类型非空校验（String/Number/Collection/File 等） ### 工具集成 - **API 文档**: Knife4j + OpenAPI 3，自动生成接口文档 - **异步访问日志**: `AccessLogAspect` 使用虚拟线程异步记录 Controller 访问日志 - **虚拟线程**: 全面启用 Java 25 虚拟线程，自动传递 ThreadLocal 上下文 - **对象存储**: 内置 AWS S3 兼容的对象存储服务（`OssService` + `ZFileService`） - **Excel 处理**: 支持 Excel 导入/导出（`ExcelExportUtil` / `ExcelImportUtil`） - **工具类库**: 集成 Hutool、StreamEx，提供丰富的工具方法 - **拼音转换**: 集成 TinyPinyin，支持中文转拼音 ## 📂 模块结构 ```text zadmin/ # root="true"，Maven 4 自动发现子项目 ├── .mvn/ # Maven 4 项目根标识 & 构建配置 │ ├── maven.config # Maven CLI 参数 │ └── mvnd.properties # Maven Daemon 参数 ├── a_start/ # [启动模块] 应用程序入口，聚合各业务模块 │ └── resources/ │ ├── dev/ # 开发环境配置 (db/redis/oss/app) │ ├── test/ # 测试环境配置 │ └── prod/ # 生产环境配置 ├── core/ # [核心模块] 公共配置、工具类、基础实体、拦截器 │ ├── aspect/ # AOP 切面 │ │ ├── accesslog/ # 访问日志切面 (虚拟线程异步记录) │ │ ├── notnull/ # @INotNull 自定义非空校验 │ │ └── skip_filter/ # @SkipDataFilter 跳过数据过滤 │ ├── configuration/ # 配置类 │ │ ├── easyquery/ # Easy-Query 相关配置 │ │ │ ├── MultiDataSourceConfiguration # 多数据源配置 (12+ 数据库) │ │ │ ├── EasyMultiEntityQuery # 多数据源查询接口 │ │ │ ├── DynamicTransactionManager # 动态事务管理器 │ │ │ ├── SnowflakePrimaryKeyGenerator # 可读雪花算法主键 │ │ │ ├── conveter/ # 类型转换器 (PgSQL数组等) │ │ │ └── interceptor/ # Easy-Query 拦截器 │ │ │ ├── AuditInterceptor # 审计字段自动填充 │ │ │ ├── TenantInterceptor # 多租户数据隔离 │ │ │ └── DeptInterceptor # 部门数据隔离 │ │ ├── exception/ # 全局异常处理 (ErrorEnum + CustomAssert) │ │ ├── interceptor/ # Web 拦截器 │ │ │ ├── PathAuthorityInterceptor # 路径权限校验 │ │ │ ├── DebounceInterceptor # 接口防抖 │ │ │ └── BodyCachingFilter # 请求体缓存 │ │ ├── redis/ # Redisson 配置 (Jackson 3.x 编解码) │ │ ├── s3bult/ # S3 对象存储 + 文件管理 │ │ ├── spring/ # Spring 动态 Bean 工厂 │ │ ├── thread/ # 虚拟线程配置与上下文传递 │ │ ├── JacksonConfiguration # Jackson 序列化配置 │ │ └── Knife4jConfiguration # API 文档配置 │ ├── entity/ # 基础实体类 │ │ ├── parent/ # 父类实体 │ │ │ ├── ParentClientEntity # 实体基类 (CRUD/查询/关联加载) │ │ │ ├── ParentCrud # CRUD 便捷操作层 │ │ │ ├── ParentCloneable # 对象拷贝层 │ │ │ ├── EntityList # 批量操作链式包装 │ │ │ ├── ApiResult # 统一响应结果 │ │ │ ├── IPageDTO / IListDTO # 泛型分页/列表请求参数 │ │ │ ├── PageDTO / ListDTO # 分页/列表基类 (含 defaultIdAsc 等) │ │ │ └── PageResult # 分页响应结果 │ │ ├── sys/ # 系统实体 (User/Role/Menu/Dept/Tenant 等) │ │ └── z_file/ # 文件管理实体 │ └── util/ # 工具类 │ ├── CopyUtil # 对象拷贝工具 │ ├── TreeUtil # 树形结构工具 │ ├── CurrentUserHelper # 当前用户上下文 │ ├── HistoryUtil # 历史数据追溯 │ ├── JsonUtil # JSON 工具 (SnakeCase 支持) │ ├── AESUtil # AES 加密工具 │ ├── ExcelExportUtil # Excel 导出 │ ├── ExcelImportUtil # Excel 导入 │ ├── CaptchaImageUtil # 验证码图片生成 │ └── interface_util/ # 接口化工具 (ZUtil 等) ├── sys/ # [系统模块] 用户中心 & 权限管理 │ ├── configuration/ # 安全配置 │ │ ├── SecurityConfig # Spring Security 配置 │ │ └── TokenAuthenticationFilter # Token 认证过滤器 │ ├── login/ # 登录认证 & 验证码 │ ├── user/ # 用户管理 │ ├── role/ # 角色管理 │ ├── menu/ # 菜单管理 │ ├── dept/ # 部门管理 │ ├── tenant/ # 租户管理 │ ├── token/ # Token 管理 (Redis 存储/续期) │ └── test/ # 测试接口 ├── sales/ # [业务模块] 销售/客户管理 │ └── customer/ # 客户管理 (Controller + Service) └── z_doc/ # 项目文档 ``` ## 🛠️ 技术选型 | 技术 | 说明 | 版本 | | :--- | :--- | :--- | | **Java** | 编程语言 | **25** | | **Maven** | 构建工具 | **4** (POM 4.1.0) | | **Spring Boot** | 核心框架 | **4.0.3** | | **Spring Security** | 安全框架 | 7.x | | **Easy-Query** | ORM 框架 | 3.1.82 | | **PostgreSQL** | 主数据库 | 18+ | | **Redis / Redisson** | 缓存 & 分布式锁 | 8+ / 4.1.0 | | **Knife4j** | API 文档 | 4.5.0 | | **Hutool** | 工具类库 | 5.8.43 | | **StreamEx** | Stream 增强 | 0.8.4 | | **AWS SDK** | 对象存储 | 2.41.4 | | **Apache POI** | Excel 处理 | 5.5.1 | | **Lombok** | 代码简化 | 1.18.42 | | **HikariCP** | 连接池 | 内置 | ### 前端技术栈 | 技术 | 说明 | 版本 | | :--- | :--- | :--- | | **Vue** | 前端框架 | 3.5 | | **Naive UI** | UI 组件库 | 2.43 | | **Pinia** | 状态管理 | 3.0 | | **Vue Router** | 路由管理 | 5.0 | | **TypeScript** | 类型系统 | 5.9 | | **Vite (Rolldown)** | 构建工具 | 7.3 | | **Axios** | HTTP 客户端 | 1.13 | ## 💡 核心亮点 ### 1. Maven 4 构建 (POM 4.1.0) 项目使用 Maven 4 的 `modelVersion 4.1.0`，充分利用新特性简化项目配置： ```xml 4.1.0 ${revision} pom 4.1.0 core ``` Maven 4 特性一览： - **`root="true"`**: 声明项目根目录 - **子项目自动发现**: 无需 `` / `` 列表 - **`` 推断**: 子模块自动推断父 POM 的 GAV 坐标 - **版本推断**: 内部模块依赖无需声明版本 - **CI-friendly 版本**: `${revision}` 原生支持，无需 flatten-maven-plugin ### 2. 极简实体操作 实体类继承 `ParentClientEntity` 后，可直接进行链式 CRUD 操作： ```java // 插入（自动断言影响行数） new User().setUsername("admin").setNickname("管理员").insert(); // 查询 User user = new User().queryable().whereById(id).singleOrNull(); // 更新（自动断言影响行数） new User().setId(id).setNickname("新昵称").update(); // 删除 new User().setId(id).delete(); // 保存（存在则更新，不存在则插入） new User().setId(id).setNickname("昵称").save(); ``` ### 3. 批量链式操作 ```java // 从 DTO 列表批量复制并插入 List tenants = new Tenant().copyFrom(dtos).insert(); // 批量更新 new Tenant().update(tenantList); ``` ### 4. 通用分页查询 使用 Easy Query 官方的 `IPageDTO` + `whereObject` + `orderByObject` 方案： ```java // 1. 在实体接口中定义 WhereObject，使用 @EasyWhereCondition 注解 @Data class CustomerWhereObject { @EasyWhereCondition private String name; // 默认 like 模糊查询 @EasyWhereCondition(type = Condition.EQUAL) private Integer status; // 精确匹配 } // 2. Controller 直接使用泛型 IPageDTO，无需为每个实体创建子类 @PostMapping("/page") public ApiResult> page(@RequestBody IPageDTO dto) { return ok(customerService.page(dto)); } // 3. Service 中调用 public EasyPageResult page(IPageDTO dto) { return new Customer().queryable() .whereObject(dto.getWhereObject()) // DTO 筛选 .orderByObject(dto.defaultIdAsc()) // 默认排序（前端未传时生效） .toPageResult(dto.getPageIndex(), dto.getPageSize()); } ``` 支持的查询类型（@EasyWhereCondition）： - `LIKE`: 模糊查询（默认） - `EQUAL`: 精确匹配 - `IN`/`NOT_IN`: 范围查询 - `RANGE_LEFT_CLOSED`/`RANGE_RIGHT_CLOSED`: 日期/数值范围 - 更多类型见 EasyQuery 官方文档 ### 5. 可读雪花算法主键 主键格式：`yyyyMMddHHmmssSSS + 机器ID(5位) + 序列号(6位)` ``` 示例：2025052914302512300001000001 ├── 时间戳：2025-05-29 14:30:25.123 ├── 机器ID：00001 └── 序列号：000001 ``` 特点： - 趋势递增，索引友好 - 可直接读取时间信息，方便调试 - 支持 99999 个节点，每毫秒 999999 个 ID ### 6. 多层数据隔离 ```java // 审计拦截器 - 自动填充 updateId、updateTime @Component public class AuditInterceptor implements EntityInterceptor, UpdateSetInterceptor { ... } // 租户拦截器 - 查询/更新/删除自动添加 tenantId 条件 @Component public class TenantInterceptor implements EntityInterceptor, PredicateFilterInterceptor { ... } // 部门拦截器 - 查询/更新/删除自动添加 primaryDeptId 条件 @Component public class DeptInterceptor implements EntityInterceptor, PredicateFilterInterceptor { ... } // 灵活跳过过滤 @SkipDataFilter(value = "sys_admin", skipTenant = true, skipDept = true) public void adminOperation() { ... } ``` ### 7. 多数据源 & 动态事务 ```yaml # 配置文件中有多少数据源就注册多少 spring: datasource: dynamic: primary: url: jdbc:postgresql://... ds2: url: jdbc:mysql://... ``` ```java // 指定数据源执行 easyMultiEntityQuery.executeScope("ds2", eq -> { return eq.queryable(User.class).toList(); }); ``` 支持 12+ 种数据库：PostgreSQL、MySQL、Oracle、SQL Server、H2、SQLite、ClickHouse、达梦、人大金仓、高斯DB、DuckDB、DB2 ### 8. 异步访问日志 ```java // 自动记录所有 Controller 访问日志（虚拟线程异步，零性能损耗） @Around("execution(* io.github.lionheartlattice..*Controller.*(..))") public Object logAccess(ProceedingJoinPoint joinPoint) throws Throwable { ... } // 跳过日志记录 @SkipAccessLog @GetMapping("/health") public String health() { return "ok"; } ``` ## ⚡ 快速开始 ### 1. 环境准备 - JDK 25+ - Maven 4+ (推荐使用 [mvnd](https://github.com/apache/maven-mvnd) 加速编译) - PostgreSQL 18+ - Redis 8+ ### 2. 克隆项目 ```bash git clone https://gitee.com/lionheart666/zadmin.git cd zadmin ``` ### 3. 配置修改 在 `a_start/src/main/resources/dev/db.yml` 中配置数据库连接： ```yaml spring: datasource: dynamic: primary: url: jdbc:postgresql://localhost:5432/postgres?currentSchema=public username: postgres password: your_password ``` 在 `a_start/src/main/resources/dev/redis.yml` 中配置 Redis 连接。 ### 4. 编译与运行 ```bash # 使用 mvnd 并行编译（推荐，注意由于是父子项目首次需要 install） mvnd clean install -DskipTests # 或使用 Maven 4 mvn clean install -DskipTests # 运行 cd a_start mvn spring-boot:run ``` ### 5. Docker 部署 ```bash # 构建镜像（基于 Liberica JDK 25 + ZGC） docker build -t zadmin . # 运行容器 docker run -d -p 19991:19991 \ -e SPRING_PROFILES_ACTIVE=prod \ zadmin ``` ### 6. 访问文档 启动成功后，访问 Knife4j 接口文档： ``` http://localhost:19991/api/admin/doc.html ``` ## 📁 相关项目 | 项目 | 说明 | 地址 | | :--- | :--- | :--- | | **zadmin** | 后端项目 | [gitee.com/lionheart666/zadmin](https://gitee.com/lionheart666/zadmin) | | **zui** | 前端项目 (Vue 3 + Naive UI + TypeScript + Pinia) | [gitee.com/lionheart666/zui](https://gitee.com/lionheart666/zui) | ## 🤝 贡献指南 欢迎提交 Issue 和 Pull Request！ 1. Fork 本仓库 2. 创建特性分支 (`git checkout -b feature/AmazingFeature`) 3. 提交更改 (`git commit -m 'Add some AmazingFeature'`) 4. 推送到分支 (`git push origin feature/AmazingFeature`) 5. 提交 Pull Request ## 📄 开源协议 本项目采用 [Apache License 2.0](LICENSE) 开源协议。 ``` Copyright 2024-2026 LionHeart Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. ``` ## 🙏 致谢 - [Easy-Query](https://www.easy-query.com/) - 高性能 ORM 框架 - [Spring Boot](https://spring.io/projects/spring-boot) - 应用框架 - [Naive UI](https://www.naiveui.com/) - Vue 3 组件库 - [Hutool](https://hutool.cn/) - Java 工具类库 - [Knife4j](https://doc.xiaominfo.com/) - API 文档工具 - [Redisson](https://redisson.org/) - Redis 客户端