feat(data): 添加动态Specification构建器及配套工具类

- 新增DynamicSpecificationBuilder工具类,支持根据DTO动态生成JPA Specification查询条件
- 添加FieldMatch注解,用于配置字段匹配方式和查询条件
- 添加MatchType枚举,定义多种字段匹配类型如EQUALS、CONTAINS、BETWEEN等
- 添加LogicalOperator枚举,支持AND和OR逻辑操作符
- 实现缓存机制提升反射操作性能,包括实体字段缓存、DTO字段信息缓存等
- 支持嵌套属性访问,如user.address.city格式的字段路径
- 提供默认匹配机制,根据字段类型自动选择合适的匹配方式
- 添加PageableFactory接口,简化分页参数处理
- 更新zkh-data模块依赖,引入Jakarta Persistence API和Spring Data JPA
- 升级项目版本至1.2,统一管理各模块版本号
- 添加详细的使用文档README.md,包含使用示例和最佳实践
This commit is contained in:
zkh
2025-11-21 18:27:58 +08:00
parent eb66fe7810
commit 5029ae6664
11 changed files with 1278 additions and 4 deletions

119
CLAUDE.md Normal file
View File

@ -0,0 +1,119 @@
# CLAUDE.md
这个文件为Claude Code (claude.ai/code)提供在此代码库中工作的指导。
## 项目概述
ZKH Framework是一个基于Spring Boot 3.5.7和Java 21的企业级Java开发框架采用多模块Maven架构。框架提供了Web开发、数据访问、安全认证等核心功能。
## 模块架构
项目采用多模块架构,包含以下核心模块:
### zkh-common
- **作用**: 通用工具类和基础实体类
- **关键组件**:
- `R<T>`: 统一响应结果封装类
- `BaseEntity`: 基础实体类包含审计字段id, createTime, updateTime, createBy, updateBy
- `BizException`: 业务异常类
- **依赖**: Spring Data JPA, Jakarta Persistence API, Jackson Annotations
### zkh-web
- **作用**: Web层组件和安全配置
- **关键组件**:
- `WebSecurityConfig`: Spring Security配置支持Token认证
- `TokenFilter`: Token认证过滤器
- `JsonUsernamePasswordAuthenticationFilter`: JSON格式的用户名密码认证
- `TokenRedisStorage`: Redis Token存储管理
- `GlobalExceptionHandler`: 全局异常处理
- **特性**:
- 基于Redis的Token认证机制
- 支持CORS和JSON格式登录
- 自动清理过期Token每30分钟
- JPA审计支持
### zkh-data
- **作用**: 数据访问层组件
- **关键组件**:
- `DynamicSpecificationBuilder`: 动态Specification构建器支持复杂查询条件
- `FieldMatch`: 字段匹配注解,用于查询条件映射
- `MatchType`: 匹配类型枚举EQUALS, CONTAINS, GREATER_THAN等
- `LogicalOperator`: 逻辑操作符AND, OR
- **特性**:
- 基于注解的动态查询构建
- 支持嵌套属性查询(如: user.address.city
- 查询条件缓存机制
- 支持AND/OR逻辑组合
## 构建和开发
### 构建命令
```bash
# 编译整个项目
mvn clean compile
# 运行测试
mvn test
# 打包项目
mvn clean package
# 跳过测试打包
mvn clean package -DskipTests
# 安装到本地仓库
mvn clean install
# 发布到Maven Central需要GPG签名
mvn clean deploy -P release
```
### 开发环境要求
- JDK 21
- Maven 3.6+
- Redis用于Token存储
- 数据库支持JPA的任何数据库
## 核心技术栈
- **Spring Boot**: 3.5.7
- **Spring Security**: 认证和授权
- **Spring Data JPA**: 数据访问层
- **Redis**: Token存储和缓存
- **Jackson**: JSON序列化/反序列化
- **Lombok**: 减少样板代码
- **BCrypt**: 密码加密
## 使用指南
### Token认证
- 登录成功后返回UUID格式的Token
- 请求时在Header中添加 `Authorization: Bearer <token>`
- 支持单点登出和全部登出
### 动态查询
使用`@FieldMatch`注解在DTO字段上配置查询条件
```java
@FieldMatch(matchType = MatchType.CONTAINS, ignoreCase = true)
private String name;
@FieldMatch(matchType = MatchType.BETWEEN)
private Date[] createTimeRange;
```
### 审计功能
继承`BaseEntity`类自动获得:
- 主键自增
- 创建/更新时间自动记录
- 创建/更新人自动记录
## 项目配置
### 安全配置
通过`SecurityProps`配置忽略认证的URL路径。
### Redis配置
确保Redis服务可用用于Token存储和管理。
### 数据库配置
配置Spring Boot数据源以使用JPA功能。