# zadmin

**Repository Path**: lionheart666/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**: 1
- **Forks**: 0
- **Created**: 2025-12-06
- **Last Updated**: 2026-03-04

## 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.0-green.svg)](https://spring.io/projects/spring-boot)
[![Easy-Query](https://img.shields.io/badge/Easy--Query-3.1.73-purple.svg)](https://www.easy-query.com/)

ZAdmin 是一个基于 **Java 25** 和 **Spring Boot 4.0** 构建的现代化、模块化后台管理系统。项目采用 Maven 多模块架构设计，集成了高性能 ORM 框架 Easy-Query，致力于提供高效、灵活且易于维护的开发体验。

## 🚀 项目特性

### 核心能力
- **前沿技术栈**: 基于最新的 **Java SDK 25** 开发，充分利用虚拟线程、模式匹配等新特性
- **模块化架构**: 采用清晰的 Maven 多模块设计，实现关注点分离，支持按需加载
- **高性能 ORM**: 集成 **[Easy-Query](https://www.easy-query.com/)**，支持强类型 Lambda 查询、编译期代理生成、零反射调用
- **多数据源支持**: 内置动态数据源管理，支持运行时动态注册数据源，轻松应对多租户场景

### 开发体验
- **简洁的实体操作**: 基于 `ParentClientEntity` 基类，实体类可直接调用 CRUD 方法，无需注入 Service
- **通用分页查询**: `PageQueryUtil` 工具类封装动态条件查询，支持精确/模糊/范围查询
- **自动审计填充**: 拦截器自动填充 `updateId`、`updateTime` 等审计字段
- **多租户隔离**: 透明的租户数据隔离，自动注入租户条件

### 工具集成
- **API 文档**: Knife4j + OpenAPI 3，自动生成接口文档
- **工具类库**: 集成 Hutool，提供丰富的工具方法
- **对象存储**: 内置 AWS S3 兼容的对象存储客户端
- **Excel 处理**: 支持 Excel 导入导出

## 📂 模块结构

```text
zadmin/
├── a_start/          # [启动模块] 应用程序入口，聚合各业务模块
├── core/             # [核心模块] 公共配置、工具类、基础实体、拦截器
│   ├── configuration/    # 配置类
│   │   ├── easyquery/        # Easy-Query 相关配置
│   │   │   ├── MultiDataSourceConfiguration  # 多数据源配置
│   │   │   ├── SnowflakePrimaryKeyGenerator  # 雪花算法主键生成器
│   │   │   ├── AuditInterceptor              # 审计字段拦截器
│   │   │   └── TenantInterceptor             # 多租户拦截器
│   │   ├── exception/        # 全局异常处理
│   │   └── spring/           # Spring 动态 Bean 工厂
│   ├── entity/           # 基础实体类
│   │   ├── parent/           # 父类实体 (ParentClientEntity, PageDTO 等)
│   │   └── user_center/      # 用户中心实体 (User, Role, Menu 等)
│   └── util/             # 工具类
│       ├── PageQueryUtil     # 分页查询工具
│       ├── CopyUtil          # 对象拷贝工具
│       ├── TreeUtil          # 树形结构工具
│       └── ExcelExportUtil   # Excel 导出工具
├── generator/        # [代码生成] 代码生成器模块 (可选)
├── user_center/      # [业务模块] 用户中心
│   ├── login/            # 登录认证
│   ├── user/             # 用户管理
│   ├── role/             # 角色管理
│   ├── menu/             # 菜单管理
│   ├── dept/             # 部门管理
│   └── tenant/           # 租户管理
└── z_doc/            # 项目文档
```

## 🛠️ 技术选型

| 技术 | 说明 | 版本 |
| :--- | :--- | :--- |
| **Java** | 编程语言 | **25** |
| **Spring Boot** | 核心框架 | **4.0.0** |
| **Easy-Query** | ORM 框架 | 3.1.73 |
| **PostgreSQL** | 主数据库 | 18+ |
| **Redis** | 缓存数据库 | 8+ |
| **Knife4j** | API 文档 | 4.5.0 |
| **Hutool** | 工具类库 | 5.8.41 |
| **AWS SDK** | 对象存储 | 2.40.13 |

## 💡 核心亮点

### 1. 简洁的实体操作

实体类继承 `ParentClientEntity` 后，可直接进行 CRUD 操作：

```java
// 插入
new User().setUsername("admin").insertable().executeRows();

// 查询
User user = new User().queryable().whereById(id).singleOrNull();

// 更新
new User().setId(id).setNickname("新昵称").updatable().executeRows();

// 删除
new User().deletable().whereById(id).executeRows();
```

### 2. 通用分页查询

前端传递统一的查询参数，后端自动解析：

```java
// Controller
@PostMapping("/page")
public ApiResult<PageResult<User>> page(@RequestBody PageDTO dto) {
    return ok(PageQueryUtil.pageDesc(dto, new User().queryable()));
}
```

支持的查询类型：
- `queryType=1`: 精确匹配
- `queryType=2`: 模糊查询
- `queryType=3`: 日期范围

### 3. 可读雪花算法主键

主键格式：`yyyyMMddHHmmssSSS + 机器ID(5位) + 序列号(6位)`

```
示例：2025052914302512300001000001
├── 时间戳：2025-05-29 14:30:25.123
├── 机器ID：00001
└── 序列号：000001
```

特点：
- 趋势递增，索引友好
- 可直接读取时间信息
- 支持 99999 个节点，每毫秒 999999 个 ID

### 4. 自动审计与多租户

```java
// 自动填充 updateId、updateTime
@Component
public class AuditInterceptor implements EntityInterceptor {
    // 插入/更新时自动填充审计字段
}

// 自动添加租户条件
@Component  
public class TenantInterceptor implements PredicateFilterInterceptor {
    // 查询/更新/删除时自动添加 tenantId 条件
}
```

## ⚡ 快速开始

### 1. 环境准备

- JDK 25+
- Maven 4+
- PostgreSQL 18+
- Redis 8+

### 2. 克隆项目

```bash
git clone https://github.com/lionheartlattice/zadmin.git
cd zadmin
```

### 3. 配置修改

在 `a_start/src/main/resources/application.yml` 中配置数据库连接：

```yaml
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/zadmin
    username: postgres
    password: your_password
```

### 4. 编译与运行

```bash
# 编译（跳过测试）
mvn clean install -DskipTests

# 运行
cd a_start
mvn spring-boot:run
```

### 5. 访问文档

启动成功后，访问 Knife4j 接口文档：

```
http://localhost:8080/doc.html
```

## 📁 相关项目

| 项目 | 说明 |
| :--- | :--- |
| [zadmin_ui](../zadmin_ui) | 前端项目 (Vue 3 + Element Plus) |
| [easy-query-doc](../easy-query-doc) | Easy-Query 框架文档 |

## 🤝 贡献指南

欢迎提交 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-2025 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) - 应用框架
- [Hutool](https://hutool.cn/) - Java 工具类库
- [Knife4j](https://doc.xiaominfo.com/) - API 文档工具