zkh
5029ae6664
- 新增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，包含使用示例和最佳实践
119 lines
3.2 KiB
Markdown
119 lines
3.2 KiB
Markdown
# 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功能。 |