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:
119
CLAUDE.md
Normal file
119
CLAUDE.md
Normal 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功能。
|
||||
Reference in New Issue
Block a user