Files

zkh 5029ae6664 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，包含使用示例和最佳实践

2025-11-21 18:27:58 +08:00

3.2 KiB

Raw Permalink Blame History

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逻辑组合

构建和开发

构建命令

# 编译整个项目
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字段上配置查询条件：

@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功能。

3.2 KiB Raw Permalink Blame History Unescape Escape