docs: 补充README
This commit is contained in:
527
README.md
527
README.md
@@ -1,6 +1,6 @@
|
||||
# Spring Boot Service Template
|
||||
|
||||
这是一个基于 Spring Boot 的服务模板项目，旨在为开发者提供一个标准化的微服务基础结构，简化新项目的搭建过程，提高开发效率。
|
||||
这是一个基于 Spring Boot 的服务模板项目，采用模块化架构设计，旨在为开发者提供标准化的微服务基础结构，简化新项目的搭建过程，提高开发效率。
|
||||
|
||||
## 目录
|
||||
|
||||
@@ -16,7 +16,7 @@
|
||||
|
||||
### 1.1 项目简介
|
||||
|
||||
Spring Boot Service Template 是一个标准化的微服务基础结构模板，专为 Java 开发者和微服务架构设计者打造。该项目提供了一套完整的 CRUD 操作框架，通过泛型支持不同类型的数据转换，大大减少了重复代码的编写。
|
||||
Spring Boot Service Template 是一个标准化的微服务基础结构模板，专为 Java 开发者和微服务架构设计者打造。该项目采用模块化架构设计，提供了一套完整的 CRUD 操作框架，支持多种数据库访问方式（JPA、Easy Query、Xbatis），通过泛型支持不同类型的数据转换，大大减少了重复代码的编写。
|
||||
|
||||
该模板内置了完善的实体审计机制，自动维护实体的创建时间和修改时间。同时，提供了强大的查询功能，支持多种条件查询、分页和排序功能。
|
||||
|
||||
@@ -26,17 +26,24 @@ Spring Boot Service Template 是一个标准化的微服务基础结构模板，
|
||||
|
||||
### 1.3 核心特性
|
||||
|
||||
- 模块化架构：采用多模块设计，通用功能与数据库操作分离，便于按需引入
|
||||
- 标准化的项目结构：遵循业界最佳实践的目录结构和代码组织方式
|
||||
- 多数据库支持：支持 JPA、Easy Query、Xbatis 三种数据库访问方式
|
||||
- 简化依赖管理和构建流程：基于 Maven 的依赖管理，清晰的构建配置
|
||||
- 支持快速构建和部署微服务：提供完整的微服务基础组件
|
||||
- 泛型支持：通过泛型实现不同类型间的数据转换
|
||||
- 完善的审计机制：自动维护实体的创建时间和修改时间
|
||||
- 强大的查询功能：支持多种条件查询、分页和排序
|
||||
- 灵活的扩展机制：易于定制和扩展的架构设计
|
||||
- 统一的响应格式：标准化的 API 响应结构
|
||||
- 雪花 ID 生成器：支持分布式环境下的唯一 ID 生成
|
||||
|
||||
### 1.4 适用场景
|
||||
|
||||
适用于需要快速搭建 Spring Boot 微服务的项目，特别是那些需要大量 CRUD 操作的业务系统。
|
||||
适用于需要快速搭建 Spring Boot 微服务的项目，特别是那些需要大量 CRUD 操作的业务系统。支持三种数据库访问方式，可根据项目需求灵活选择：
|
||||
- **JPA 模块**：适合传统的 Spring Data JPA 项目，提供完整的 JPA 功能
|
||||
- **Easy Query 模块**：适合需要类型安全查询的项目，提供强大的查询构建能力
|
||||
- **Xbatis 模块**：适合需要 MyBatis 灵活性的项目，提供增强的 MyBatis 功能
|
||||
|
||||
## 2. 技术架构
|
||||
|
||||
@@ -44,20 +51,37 @@ Spring Boot Service Template 是一个标准化的微服务基础结构模板，
|
||||
|
||||
#### 2.1.1 后端技术栈
|
||||
- Java 17
|
||||
- Spring Boot 3.4.3
|
||||
- Spring Data JPA
|
||||
- QueryDSL 7.0
|
||||
- Spring Boot 4.0.0
|
||||
- Spring Cloud 2025.1.0
|
||||
- Lombok
|
||||
- Fenix Spring Boot Starter 3.1.0
|
||||
- MapStruct 1.6.3
|
||||
- Hutool 5.8.43
|
||||
|
||||
#### 2.1.2 核心框架
|
||||
#### 2.1.2 数据库技术栈
|
||||
|
||||
**JPA 模块**
|
||||
- Spring Data JPA
|
||||
- Hibernate 7.1.8.Final
|
||||
- QueryDSL 7.1
|
||||
- Fenix 4.0.0
|
||||
|
||||
**Easy Query 模块**
|
||||
- Easy Query 3.1.68
|
||||
|
||||
**Xbatis 模块**
|
||||
- Xbatis 1.9.7-spring-boot4
|
||||
|
||||
#### 2.1.3 核心框架
|
||||
- Spring Boot 作为核心框架，提供自动配置和快速开发能力
|
||||
- Spring Data JPA 用于数据访问，简化数据库操作
|
||||
- QueryDSL 用于类型安全的查询构建，避免运行时错误
|
||||
- Fenix 用于复杂动态查询，提供更灵活的查询能力
|
||||
- Spring Data JPA 用于数据访问，简化数据库操作（JPA 模块）
|
||||
- QueryDSL 用于类型安全的查询构建，避免运行时错误（JPA 模块）
|
||||
- Fenix 用于复杂动态查询，提供更灵活的查询能力（JPA 模块）
|
||||
- Easy Query 用于类型安全的查询构建和灵活的数据访问（EQ 模块）
|
||||
- Xbatis 用于增强的 MyBatis 数据访问（Xbatis 模块）
|
||||
- Lombok 减少样板代码，提高开发效率
|
||||
- MapStruct 用于对象映射，简化数据转换
|
||||
|
||||
#### 2.1.3 数据库技术
|
||||
#### 2.1.4 数据库技术
|
||||
- H2 Database (测试环境)
|
||||
|
||||
### 2.2 架构设计
|
||||
@@ -71,7 +95,7 @@ Spring Boot Service Template 是一个标准化的微服务基础结构模板，
|
||||
│ Service Layer │
|
||||
│ (业务逻辑处理，事务管理) │
|
||||
├─────────────────────────────────────┤
|
||||
│ Repository Layer │
|
||||
│ Repository/Mapper Layer │
|
||||
│ (数据访问，数据库交互) │
|
||||
├─────────────────────────────────────┤
|
||||
│ Entity Layer │
|
||||
@@ -80,86 +104,189 @@ Spring Boot Service Template 是一个标准化的微服务基础结构模板，
|
||||
```
|
||||
|
||||
#### 2.2.2 模块划分
|
||||
- controller: 控制层，处理 HTTP 请求，包括接口定义和支持类
|
||||
- entity: 实体层，定义数据模型和数据库映射
|
||||
- service: 服务层，处理业务逻辑和事务管理
|
||||
- repository: 仓储层，处理数据访问和数据库交互
|
||||
- helper: 辅助类模块，提供工具类和通用方法
|
||||
|
||||
项目采用模块化架构，主要包含以下模块：
|
||||
|
||||
**通用模块**
|
||||
- spring-boot-service-template-common：通用工具类模块，提供对象操作等基础功能
|
||||
|
||||
**数据库通用模块**
|
||||
- spring-boot-service-template-database-common：数据库通用功能模块，定义统一的 Controller、Service 接口和实体类
|
||||
- spring-boot-service-template-database-common-test：数据库通用测试模块，提供测试基类和配置
|
||||
|
||||
**数据库实现模块**
|
||||
- spring-boot-service-template-database-jpa：JPA 实现模块，基于 Spring Data JPA
|
||||
- spring-boot-service-template-database-eq：Easy Query 实现模块，基于 Easy Query
|
||||
- spring-boot-service-template-database-xbatis：Xbatis 实现模块，基于增强的 MyBatis
|
||||
|
||||
#### 2.2.3 设计模式
|
||||
- 模板方法模式：通过抽象类定义通用操作流程
|
||||
- 策略模式：通过函数式接口实现数据转换策略
|
||||
- 仓储模式：封装数据访问逻辑，提供统一的数据操作接口
|
||||
- 工厂模式：支持多种数据库实现方式的切换
|
||||
|
||||
## 3. 项目结构
|
||||
|
||||
### 3.1 目录结构说明
|
||||
```
|
||||
src/
|
||||
├── main/
|
||||
│ └── java/
|
||||
│ └── com/lanyuanxiaoyao/service/template/
|
||||
│ ├── controller/
|
||||
│ ├── entity/
|
||||
│ ├── helper/
|
||||
│ ├── repository/
|
||||
│ └── service/
|
||||
└── test/
|
||||
└── java/
|
||||
└── com/lanyuanxiaoyao/service/template/
|
||||
├── controller/
|
||||
├── entity/
|
||||
├── repository/
|
||||
└── service/
|
||||
spring-boot-service-template/
|
||||
├── spring-boot-service-template-common/ # 通用工具类模块
|
||||
│ └── src/main/java/com/lanyuanxiaoyao/service/template/common/
|
||||
│ └── helper/
|
||||
│ └── ObjectHelper.java # 对象工具类
|
||||
│
|
||||
├── spring-boot-service-template-database/ # 数据库模块目录
|
||||
│ ├── spring-boot-service-template-database-common/ # 数据库通用模块
|
||||
│ │ └── src/main/java/com/lanyuanxiaoyao/service/template/database/common/
|
||||
│ │ ├── controller/ # 控制器接口定义
|
||||
│ │ │ ├── SimpleController.java
|
||||
│ │ │ ├── SaveController.java
|
||||
│ │ │ ├── QueryController.java
|
||||
│ │ │ └── RemoveController.java
|
||||
│ │ ├── service/ # 服务接口定义
|
||||
│ │ │ ├── SimpleService.java
|
||||
│ │ │ ├── SaveService.java
|
||||
│ │ │ ├── QueryService.java
|
||||
│ │ │ ├── RemoveService.java
|
||||
│ │ │ └── QueryParser.java # 查询解析器
|
||||
│ │ ├── entity/ # 通用实体类
|
||||
│ │ │ ├── GlobalResponse.java # 统一响应格式
|
||||
│ │ │ ├── Query.java # 查询条件封装
|
||||
│ │ │ └── Page.java # 分页结果封装
|
||||
│ │ ├── exception/ # 异常定义
|
||||
│ │ │ ├── IdNotFoundException.java
|
||||
│ │ │ ├── NotCollectionException.java
|
||||
│ │ │ ├── NotComparableException.java
|
||||
│ │ │ └── NotStringException.java
|
||||
│ │ └── helper/ # 辅助类
|
||||
│ │ └── SnowflakeHelper.java # 雪花ID生成器
|
||||
│ │
|
||||
│ ├── spring-boot-service-template-database-common-test/ # 数据库通用测试模块
|
||||
│ │ └── src/main/java/com/lanyuanxiaoyao/service/template/database/common/test/
|
||||
│ │ └── AbstractTestApplication.java # 测试应用基类
|
||||
│ │
|
||||
│ ├── spring-boot-service-template-database-jpa/ # JPA 实现模块
|
||||
│ │ ├── src/main/java/com/lanyuanxiaoyao/service/template/database/jpa/
|
||||
│ │ │ ├── controller/
|
||||
│ │ │ │ └── SimpleControllerSupport.java # JPA 控制器实现
|
||||
│ │ │ ├── service/
|
||||
│ │ │ │ └── SimpleServiceSupport.java # JPA 服务实现
|
||||
│ │ │ ├── repository/
|
||||
│ │ │ │ └── SimpleRepository.java # JPA 仓储接口
|
||||
│ │ │ ├── entity/
|
||||
│ │ │ │ ├── IdOnlyEntity.java # 仅包含 ID 的实体
|
||||
│ │ │ │ ├── SimpleEntity.java # 包含基础字段的实体
|
||||
│ │ │ │ ├── SnowflakeId.java # 雪花 ID 注解
|
||||
│ │ │ │ └── SnowflakeIdGenerator.java # 雪花 ID 生成器
|
||||
│ │ │ └── helper/
|
||||
│ │ │ └── DatabaseHelper.java # 数据库辅助类
|
||||
│ │ └── src/test/java/... # 测试用例
|
||||
│ │
|
||||
│ ├── spring-boot-service-template-database-eq/ # Easy Query 实现模块
|
||||
│ │ ├── src/main/java/com/lanyuanxiaoyao/service/template/database/eq/
|
||||
│ │ │ ├── controller/
|
||||
│ │ │ │ └── SimpleControllerSupport.java # EQ 控制器实现
|
||||
│ │ │ ├── service/
|
||||
│ │ │ │ └── SimpleServiceSupport.java # EQ 服务实现
|
||||
│ │ │ └── entity/
|
||||
│ │ │ ├── IdOnlyEntity.java # 仅包含 ID 的实体
|
||||
│ │ │ ├── LogicDeleteEntity.java # 逻辑删除实体
|
||||
│ │ │ ├── SimpleEntity.java # 包含基础字段的实体
|
||||
│ │ │ └── SnowflakeIdGenerator.java # 雪花 ID 生成器
|
||||
│ │ └── src/test/java/... # 测试用例
|
||||
│ │
|
||||
│ └── spring-boot-service-template-database-xbatis/ # Xbatis 实现模块
|
||||
│ ├── src/main/java/com/lanyuanxiaoyao/service/template/database/xbatis/
|
||||
│ │ ├── controller/
|
||||
│ │ │ └── SimpleControllerSupport.java # Xbatis 控制器实现
|
||||
│ │ ├── service/
|
||||
│ │ │ └── SimpleServiceSupport.java # Xbatis 服务实现
|
||||
│ │ ├── mapper/
|
||||
│ │ │ └── MybatisBasicMapper.java # MyBatis 基础 Mapper
|
||||
│ │ ├── entity/
|
||||
│ │ │ ├── IdOnlyEntity.java # 仅包含 ID 的实体
|
||||
│ │ │ ├── LogicDeleteEntity.java # 逻辑删除实体
|
||||
│ │ │ ├── SimpleEntity.java # 包含基础字段的实体
|
||||
│ │ │ └── SnowflakeIdGenerator.java # 雪花 ID 生成器
|
||||
│ │ └── configuration/
|
||||
│ │ └── MybatisConfiguration.java # MyBatis 配置
|
||||
│ └── src/test/java/... # 测试用例
|
||||
│
|
||||
├── pom.xml # 父 POM 文件
|
||||
└── README.md # 项目文档
|
||||
```
|
||||
|
||||
### 3.2 核心模块介绍
|
||||
|
||||
#### 3.2.1 controller模块
|
||||
提供基础的 CRUD 操作控制器接口和支持类。主要包含：
|
||||
- [SimpleController](src/main/java/com/lanyuanxiaoyao/service/template/controller/SimpleController.java)：定义基础 CRUD 接口
|
||||
- [SimpleControllerSupport](src/main/java/com/lanyuanxiaoyao/service/template/controller/SimpleControllerSupport.java)：实现基础 CRUD 功能
|
||||
- [Query](src/main/java/com/lanyuanxiaoyao/service/template/controller/Query.java)：查询条件封装类
|
||||
- 其他辅助接口如 SaveController、ListController、DetailController、RemoveController
|
||||
#### 3.2.1 common 模块
|
||||
提供通用的工具类，主要包含：
|
||||
- [ObjectHelper](spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/helper/ObjectHelper.java)：对象工具类，提供对象空值判断、类型判断等常用功能
|
||||
|
||||
#### 3.2.2 entity模块
|
||||
定义基础实体类，包含审计字段。主要包含：
|
||||
- [IdOnlyEntity](src/main/java/com/lanyuanxiaoyao/service/template/entity/IdOnlyEntity.java)：仅包含 ID 的基础实体
|
||||
- [SimpleEntity](src/main/java/com/lanyuanxiaoyao/service/template/entity/SimpleEntity.java)：包含基础字段的实体类，继承自 IdOnlyEntity
|
||||
#### 3.2.2 database-common 模块
|
||||
定义数据库操作的通用接口和实体类，主要包含：
|
||||
- **controller 包**：
|
||||
- [SimpleController](spring-boot-service-template-database/spring-boot-service-template-database-common/src/main/java/com/lanyuanxiaoyao/service/template/database/common/controller/SimpleController.java)：定义基础 CRUD 控制器接口
|
||||
- [SaveController](spring-boot-service-template-database/spring-boot-service-template-database-common/src/main/java/com/lanyuanxiaoyao/service/template/database/common/controller/SaveController.java)：保存操作接口
|
||||
- [QueryController](spring-boot-service-template-database/spring-boot-service-template-database-common/src/main/java/com/lanyuanxiaoyao/service/template/database/common/controller/QueryController.java)：查询操作接口
|
||||
- [RemoveController](spring-boot-service-template-database/spring-boot-service-template-database-common/src/main/java/com/lanyuanxiaoyao/service/template/database/common/controller/RemoveController.java)：删除操作接口
|
||||
|
||||
#### 3.2.3 service模块
|
||||
提供基础服务接口和支持类。主要包含：
|
||||
- [SimpleService](src/main/java/com/lanyuanxiaoyao/service/template/service/SimpleService.java)：定义基础服务接口
|
||||
- [SimpleServiceSupport](src/main/java/com/lanyuanxiaoyao/service/template/service/SimpleServiceSupport.java)：实现基础服务功能
|
||||
- **service 包**：
|
||||
- [SimpleService](spring-boot-service-template-database/spring-boot-service-template-database-common/src/main/java/com/lanyuanxiaoyao/service/template/database/common/service/SimpleService.java)：定义基础服务接口
|
||||
- [QueryParser](spring-boot-service-template-database/spring-boot-service-template-database-common/src/main/java/com/lanyuanxiaoyao/service/template/database/common/service/QueryParser.java)：查询条件解析器
|
||||
|
||||
#### 3.2.4 repository模块
|
||||
定义数据访问仓储接口。主要包含：
|
||||
- [SimpleRepository](src/main/java/com/lanyuanxiaoyao/service/template/repository/SimpleRepository.java)：基础仓储接口
|
||||
- **entity 包**：
|
||||
- [GlobalResponse](spring-boot-service-template-database/spring-boot-service-template-database-common/src/main/java/com/lanyuanxiaoyao/service/template/database/common/entity/GlobalResponse.java)：统一 API 响应封装类
|
||||
- [Query](spring-boot-service-template-database/spring-boot-service-template-database-common/src/main/java/com/lanyuanxiaoyao/service/template/database/common/entity/Query.java)：查询条件封装类
|
||||
- [Page](spring-boot-service-template-database/spring-boot-service-template-database-common/src/main/java/com/lanyuanxiaoyao/service/template/database/common/entity/Page.java)：分页结果封装类
|
||||
|
||||
#### 3.2.5 helper模块
|
||||
提供辅助工具类。主要包含：
|
||||
- [ObjectHelper](src/main/java/com/lanyuanxiaoyao/service/template/helper/ObjectHelper.java)：对象帮助类
|
||||
- **exception 包**：定义各种业务异常类
|
||||
|
||||
- **helper 包**：
|
||||
- [SnowflakeHelper](spring-boot-service-template-database/spring-boot-service-template-database-common/src/main/java/com/lanyuanxiaoyao/service/template/database/common/helper/SnowflakeHelper.java)：雪花 ID 生成器
|
||||
|
||||
#### 3.2.3 database-jpa 模块
|
||||
基于 Spring Data JPA 的实现，主要包含：
|
||||
- [SimpleControllerSupport](spring-boot-service-template-database/spring-boot-service-template-database-jpa/src/main/java/com/lanyuanxiaoyao/service/template/database/jpa/controller/SimpleControllerSupport.java)：JPA 控制器实现
|
||||
- [SimpleServiceSupport](spring-boot-service-template-database/spring-boot-service-template-database-jpa/src/main/java/com/lanyuanxiaoyao/service/template/database/jpa/service/SimpleServiceSupport.java)：JPA 服务实现
|
||||
- [SimpleRepository](spring-boot-service-template-database/spring-boot-service-template-database-jpa/src/main/java/com/lanyuanxiaoyao/service/template/database/jpa/repository/SimpleRepository.java)：JPA 仓储接口，整合多种数据访问功能
|
||||
- [SimpleEntity](spring-boot-service-template-database/spring-boot-service-template-database-jpa/src/main/java/com/lanyuanxiaoyao/service/template/database/jpa/entity/SimpleEntity.java)：包含基础字段的实体类
|
||||
- [IdOnlyEntity](spring-boot-service-template-database/spring-boot-service-template-database-jpa/src/main/java/com/lanyuanxiaoyao/service/template/database/jpa/entity/IdOnlyEntity.java)：仅包含 ID 的基础实体
|
||||
|
||||
#### 3.2.4 database-eq 模块
|
||||
基于 Easy Query 的实现，主要包含：
|
||||
- [SimpleControllerSupport](spring-boot-service-template-database/spring-boot-service-template-database-eq/src/main/java/com/lanyuanxiaoyao/service/template/database/eq/controller/SimpleControllerSupport.java)：Easy Query 控制器实现
|
||||
- [SimpleServiceSupport](spring-boot-service-template-database/spring-boot-service-template-database-eq/src/main/java/com/lanyuanxiaoyao/service/template/database/eq/service/SimpleServiceSupport.java)：Easy Query 服务实现
|
||||
- [SimpleEntity](spring-boot-service-template-database/spring-boot-service-template-database-eq/src/main/java/com/lanyuanxiaoyao/service/template/database/eq/entity/SimpleEntity.java)：包含基础字段的实体类
|
||||
- [LogicDeleteEntity](spring-boot-service-template-database/spring-boot-service-template-database-eq/src/main/java/com/lanyuanxiaoyao/service/template/database/eq/entity/LogicDeleteEntity.java)：逻辑删除实体
|
||||
|
||||
#### 3.2.5 database-xbatis 模块
|
||||
基于 Xbatis 的实现，主要包含：
|
||||
- [SimpleControllerSupport](spring-boot-service-template-database/spring-boot-service-template-database-xbatis/src/main/java/com/lanyuanxiaoyao/service/template/database/xbatis/controller/SimpleControllerSupport.java)：Xbatis 控制器实现
|
||||
- [SimpleServiceSupport](spring-boot-service-template-database/spring-boot-service-template-database-xbatis/src/main/java/com/lanyuanxiaoyao/service/template/database/xbatis/service/SimpleServiceSupport.java)：Xbatis 服务实现
|
||||
- [MybatisBasicMapper](spring-boot-service-template-database/spring-boot-service-template-database-xbatis/src/main/java/com/lanyuanxiaoyao/service/template/database/xbatis/mapper/MybatisBasicMapper.java)：MyBatis 基础 Mapper
|
||||
- [SimpleEntity](spring-boot-service-template-database/spring-boot-service-template-database-xbatis/src/main/java/com/lanyuanxiaoyao/service/template/database/xbatis/entity/SimpleEntity.java)：包含基础字段的实体类
|
||||
- [LogicDeleteEntity](spring-boot-service-template-database/spring-boot-service-template-database-xbatis/src/main/java/com/lanyuanxiaoyao/service/template/database/xbatis/entity/LogicDeleteEntity.java)：逻辑删除实体
|
||||
|
||||
### 3.3 测试模块结构
|
||||
测试模块包含完整的测试用例，覆盖 controller、entity、repository 和 service 各层。通过实际的业务实体（如 Employee、Company、Report）演示如何使用模板。
|
||||
每个数据库实现模块都包含完整的测试用例，通过实际的业务实体（如 Employee、Company、Report）演示如何使用模板。
|
||||
|
||||
## 4. 核心功能
|
||||
|
||||
### 4.1 基础CRUD操作
|
||||
### 4.1 基础 CRUD 操作
|
||||
|
||||
#### 4.1.1 创建(Create)
|
||||
#### 4.1.1 创建 (Create)
|
||||
支持通过 POST 请求创建实体对象。通过 save 接口实现，接收 SAVE_ITEM 类型的参数，通过 Mapper 转换为实体对象后保存。
|
||||
|
||||
#### 4.1.2 查询(Retrieve)
|
||||
#### 4.1.2 查询 (Retrieve)
|
||||
支持多种查询方式：
|
||||
- 列表查询：获取所有实体对象
|
||||
- 条件查询：根据指定条件查询实体对象
|
||||
- 详情查询：根据 ID 获取单个实体对象
|
||||
|
||||
#### 4.1.3 更新(Update)
|
||||
#### 4.1.3 更新 (Update)
|
||||
支持通过 POST 请求更新实体对象。通过 save 接口实现，当传入包含 ID 的对象时执行更新操作。
|
||||
|
||||
#### 4.1.4 删除(Delete)
|
||||
#### 4.1.4 删除 (Delete)
|
||||
支持通过 GET 请求删除实体对象。通过 remove 接口实现，根据 ID 删除指定实体。
|
||||
|
||||
### 4.2 查询功能详解
|
||||
@@ -169,20 +296,26 @@ src/
|
||||
|
||||
#### 4.2.2 条件查询
|
||||
支持基于多种条件的复杂查询，通过 list 接口实现，支持以下查询条件：
|
||||
- nullEqual: 字段值为null的条件
|
||||
- notNullEqual: 字段值不为null的条件
|
||||
- nullEqual: 字段值为 null 的条件
|
||||
- notNullEqual: 字段值不为 null 的条件
|
||||
- empty: 字段值为空的条件
|
||||
- notEmpty: 字段值不为空的条件
|
||||
- equal: 字段值相等的条件
|
||||
- notEqual: 字段值不相等的条件
|
||||
- like: 字段值模糊匹配的条件
|
||||
- notLike: 字段值不模糊匹配的条件
|
||||
- contain: 字段包含指定字符串的条件
|
||||
- notContain: 字段不包含指定字符串的条件
|
||||
- startWith: 字段以指定字符串开头的条件
|
||||
- notStartWith: 字段不以指定字符串开头的条件
|
||||
- endWith: 字段以指定字符串结尾的条件
|
||||
- notEndWith: 字段不以指定字符串结尾的条件
|
||||
- great: 字段值大于的条件
|
||||
- less: 字段值小于的条件
|
||||
- greatEqual: 字段值大于等于的条件
|
||||
- lessEqual: 字段值小于等于的条件
|
||||
- in: 字段值在指定范围内的条件
|
||||
- notIn: 字段值不在指定范围内的条件
|
||||
- inside: 字段值在指定范围内的条件
|
||||
- notInside: 字段值不在指定范围内的条件
|
||||
- between: 字段值在指定区间内的条件
|
||||
- notBetween: 字段值不在指定区间内的条件
|
||||
|
||||
@@ -198,19 +331,39 @@ src/
|
||||
定义通用的实体基类，包括 IdOnlyEntity 和 SimpleEntity。
|
||||
|
||||
#### 4.3.2 审计字段
|
||||
包含创建时间(createdTime)和修改时间(modifiedTime)等审计字段，通过 Spring Data JPA 的审计功能自动维护。
|
||||
包含创建时间 (createdTime) 和修改时间 (modifiedTime) 等审计字段，通过 Spring Data JPA 的审计功能自动维护（JPA 模块）。
|
||||
|
||||
#### 4.3.3 实体关系
|
||||
支持常见的实体关系映射，如一对一、一对多、多对多等。
|
||||
|
||||
#### 4.3.4 雪花 ID 生成器
|
||||
支持分布式环境下的唯一 ID 生成，通过 SnowflakeIdGenerator 实现。
|
||||
|
||||
#### 4.3.5 逻辑删除
|
||||
支持逻辑删除功能，通过 LogicDeleteEntity 实现（EQ 和 Xbatis 模块）。
|
||||
|
||||
### 4.4 统一响应格式
|
||||
|
||||
提供统一的 API 响应格式，包含以下字段：
|
||||
- status: 响应状态码（0 表示成功，500 表示错误）
|
||||
- message: 响应消息
|
||||
- data: 响应数据
|
||||
|
||||
支持多种响应类型：
|
||||
- 成功响应（无数据）
|
||||
- 成功响应（带数据）
|
||||
- 分页列表响应（包含 items 和 total）
|
||||
- 详情响应
|
||||
- 错误响应
|
||||
|
||||
## 5. 使用指南
|
||||
|
||||
### 5.1 环境准备
|
||||
|
||||
#### 5.1.1 JDK安装
|
||||
#### 5.1.1 JDK 安装
|
||||
需要安装 JDK 17 或更高版本。
|
||||
|
||||
#### 5.1.2 Maven配置
|
||||
#### 5.1.2 Maven 配置
|
||||
需要配置 Maven 3.x 环境。
|
||||
|
||||
### 5.2 项目构建
|
||||
@@ -228,7 +381,7 @@ src/
|
||||
|
||||
#### 5.3.2 生产部署
|
||||
可通过生成的 JAR 文件直接运行或部署到服务器，使用命令：
|
||||
`java -jar target/spring-boot-service-template-1.0-SNAPSHOT.jar`
|
||||
`java -jar target/spring-boot-service-template-1.1.0-SNAPSHOT.jar`
|
||||
|
||||
## 6. 开发规范
|
||||
|
||||
@@ -252,21 +405,60 @@ RESTful API 设计规范，统一的响应格式。
|
||||
|
||||
通过 Maven 依赖引入（推荐）
|
||||
|
||||
### 7.2 Maven 依赖引入方式
|
||||
### 7.2 选择数据库实现方式
|
||||
|
||||
#### 7.2.1 添加依赖
|
||||
项目提供三种数据库实现方式，根据您的需求选择：
|
||||
|
||||
- **JPA 模块**：适合传统的 Spring Data JPA 项目
|
||||
- **Easy Query 模块**：适合需要类型安全查询的项目
|
||||
- **Xbatis 模块**：适合需要 MyBatis 灵活性的项目
|
||||
|
||||
### 7.3 Maven 依赖引入方式
|
||||
|
||||
#### 7.3.1 添加基础依赖
|
||||
|
||||
在您的项目 pom.xml 文件中添加以下依赖：
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>com.lanyuanxiaoyao</groupId>
|
||||
<artifactId>spring-boot-service-template</artifactId>
|
||||
<version>1.0.0-SNAPSHOT</version>
|
||||
<artifactId>spring-boot-service-template-common</artifactId>
|
||||
<version>1.1.0-SNAPSHOT</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
#### 7.2.2 配置依赖管理
|
||||
#### 7.3.2 添加数据库实现依赖
|
||||
|
||||
根据您选择的数据库实现方式，添加对应的依赖：
|
||||
|
||||
**JPA 实现**
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>com.lanyuanxiaoyao</groupId>
|
||||
<artifactId>spring-boot-service-template-database-jpa</artifactId>
|
||||
<version>1.1.0-SNAPSHOT</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
**Easy Query 实现**
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>com.lanyuanxiaoyao</groupId>
|
||||
<artifactId>spring-boot-service-template-database-eq</artifactId>
|
||||
<version>1.1.0-SNAPSHOT</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
**Xbatis 实现**
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>com.lanyuanxiaoyao</groupId>
|
||||
<artifactId>spring-boot-service-template-database-xbatis</artifactId>
|
||||
<version>1.1.0-SNAPSHOT</version>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
#### 7.3.3 配置依赖管理
|
||||
|
||||
确保您的项目中包含以下依赖管理配置：
|
||||
|
||||
@@ -277,14 +469,14 @@ RESTful API 设计规范，统一的响应格式。
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-dependencies</artifactId>
|
||||
<version>${spring-boot.version}</version>
|
||||
<version>4.0.0</version>
|
||||
<type>pom</type>
|
||||
<scope>import</scope>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>org.springframework.cloud</groupId>
|
||||
<artifactId>spring-cloud-dependencies</artifactId>
|
||||
<version>${spring-cloud.version}</version>
|
||||
<version>2025.1.0</version>
|
||||
<type>pom</type>
|
||||
<scope>import</scope>
|
||||
</dependency>
|
||||
@@ -292,33 +484,90 @@ RESTful API 设计规范，统一的响应格式。
|
||||
</dependencyManagement>
|
||||
```
|
||||
|
||||
#### 7.2.3 配置编译插件
|
||||
#### 7.3.4 配置编译插件
|
||||
|
||||
确保您的项目中包含以下编译插件配置：
|
||||
|
||||
**JPA 模块编译插件**
|
||||
```xml
|
||||
<build>
|
||||
<plugins>
|
||||
<plugin>
|
||||
<groupId>org.apache.maven.plugins</groupId>
|
||||
<artifactId>maven-compiler-plugin</artifactId>
|
||||
<version>3.14.0</version>
|
||||
<version>3.14.1</version>
|
||||
<configuration>
|
||||
<annotationProcessorPaths>
|
||||
<path>
|
||||
<groupId>org.projectlombok</groupId>
|
||||
<artifactId>lombok</artifactId>
|
||||
<version>1.18.36</version>
|
||||
</path>
|
||||
<path>
|
||||
<groupId>org.hibernate</groupId>
|
||||
<artifactId>hibernate-jpamodelgen</artifactId>
|
||||
<version>6.6.3.Final</version>
|
||||
<version>7.1.8.Final</version>
|
||||
</path>
|
||||
<path>
|
||||
<groupId>io.github.openfeign.querydsl</groupId>
|
||||
<artifactId>querydsl-jpa</artifactId>
|
||||
<version>7.0</version>
|
||||
<artifactId>querydsl-apt</artifactId>
|
||||
<version>7.1</version>
|
||||
<classifier>jpa</classifier>
|
||||
</path>
|
||||
<path>
|
||||
<groupId>jakarta.persistence</groupId>
|
||||
<artifactId>jakarta.persistence-api</artifactId>
|
||||
<version>3.2.0</version>
|
||||
</path>
|
||||
</annotationProcessorPaths>
|
||||
<compilerArgs>
|
||||
<arg>-Aquerydsl.entityAccessors=true</arg>
|
||||
<arg>-Aquerydsl.createDefaultVariable=true</arg>
|
||||
</compilerArgs>
|
||||
</configuration>
|
||||
</plugin>
|
||||
</plugins>
|
||||
</build>
|
||||
```
|
||||
|
||||
**Easy Query 模块编译插件**
|
||||
```xml
|
||||
<build>
|
||||
<plugins>
|
||||
<plugin>
|
||||
<groupId>org.apache.maven.plugins</groupId>
|
||||
<artifactId>maven-compiler-plugin</artifactId>
|
||||
<version>3.14.1</version>
|
||||
<configuration>
|
||||
<annotationProcessorPaths>
|
||||
<path>
|
||||
<groupId>org.projectlombok</groupId>
|
||||
<artifactId>lombok</artifactId>
|
||||
</path>
|
||||
<path>
|
||||
<groupId>com.easy-query</groupId>
|
||||
<artifactId>sql-processor</artifactId>
|
||||
<version>3.1.68</version>
|
||||
</path>
|
||||
</annotationProcessorPaths>
|
||||
</configuration>
|
||||
</plugin>
|
||||
</plugins>
|
||||
</build>
|
||||
```
|
||||
|
||||
**Xbatis 模块编译插件**
|
||||
```xml
|
||||
<build>
|
||||
<plugins>
|
||||
<plugin>
|
||||
<groupId>org.apache.maven.plugins</groupId>
|
||||
<artifactId>maven-compiler-plugin</artifactId>
|
||||
<version>3.14.1</version>
|
||||
<configuration>
|
||||
<annotationProcessorPaths>
|
||||
<path>
|
||||
<groupId>org.projectlombok</groupId>
|
||||
<artifactId>lombok</artifactId>
|
||||
</path>
|
||||
</annotationProcessorPaths>
|
||||
</configuration>
|
||||
@@ -329,13 +578,23 @@ RESTful API 设计规范，统一的响应格式。
|
||||
|
||||
### 7.4 创建业务模块
|
||||
|
||||
创建业务模块的步骤如下：
|
||||
创建业务模块的步骤如下（以 JPA 模块为例）：
|
||||
|
||||
#### 7.4.1 创建实体类
|
||||
|
||||
创建实体类并继承 [SimpleEntity](src/main/java/com/lanyuanxiaoyao/service/template/entity/SimpleEntity.java)：
|
||||
创建实体类并继承 SimpleEntity：
|
||||
|
||||
```java
|
||||
import com.lanyuanxiaoyao.service.template.database.jpa.entity.SimpleEntity;
|
||||
import jakarta.persistence.Entity;
|
||||
import jakarta.persistence.Table;
|
||||
import lombok.Getter;
|
||||
import lombok.Setter;
|
||||
import lombok.experimental.FieldNameConstants;
|
||||
|
||||
@Getter
|
||||
@Setter
|
||||
@FieldNameConstants
|
||||
@Entity
|
||||
@Table(name = "employee")
|
||||
public class Employee extends SimpleEntity {
|
||||
@@ -347,9 +606,12 @@ public class Employee extends SimpleEntity {
|
||||
|
||||
#### 7.4.2 创建仓储接口
|
||||
|
||||
创建仓储接口并继承 [SimpleRepository](src/main/java/com/lanyuanxiaoyao/service/template/repository/SimpleRepository.java)：
|
||||
创建仓储接口并继承 SimpleRepository：
|
||||
|
||||
```java
|
||||
import com.lanyuanxiaoyao.service.template.database.jpa.repository.SimpleRepository;
|
||||
import org.springframework.stereotype.Repository;
|
||||
|
||||
@Repository
|
||||
public interface EmployeeRepository extends SimpleRepository<Employee> {
|
||||
// 自定义查询方法
|
||||
@@ -358,9 +620,12 @@ public interface EmployeeRepository extends SimpleRepository<Employee> {
|
||||
|
||||
#### 7.4.3 创建服务类
|
||||
|
||||
创建服务类并继承 [SimpleServiceSupport](src/main/java/com/lanyuanxiaoyao/service/template/service/SimpleServiceSupport.java)：
|
||||
创建服务类并继承 SimpleServiceSupport：
|
||||
|
||||
```java
|
||||
import com.lanyuanxiaoyao.service.template.database.jpa.service.SimpleServiceSupport;
|
||||
import org.springframework.stereotype.Service;
|
||||
|
||||
@Service
|
||||
public class EmployeeService extends SimpleServiceSupport<Employee> {
|
||||
public EmployeeService(EmployeeRepository repository) {
|
||||
@@ -372,9 +637,13 @@ public class EmployeeService extends SimpleServiceSupport<Employee> {
|
||||
|
||||
#### 7.4.4 创建控制器类
|
||||
|
||||
创建控制器类并继承 [SimpleControllerSupport](src/main/java/com/lanyuanxiaoyao/service/template/controller/SimpleControllerSupport.java)：
|
||||
创建控制器类并继承 SimpleControllerSupport：
|
||||
|
||||
```java
|
||||
import com.lanyuanxiaoyao.service.template.database.jpa.controller.SimpleControllerSupport;
|
||||
import org.springframework.web.bind.annotation.RequestMapping;
|
||||
import org.springframework.web.bind.annotation.RestController;
|
||||
|
||||
@RestController
|
||||
@RequestMapping("employee")
|
||||
public class EmployeeController extends SimpleControllerSupport<Employee, EmployeeSaveItem, EmployeeListItem, EmployeeDetailItem> {
|
||||
@@ -385,16 +654,39 @@ public class EmployeeController extends SimpleControllerSupport<Employee, Employ
|
||||
@Override
|
||||
protected Function<EmployeeSaveItem, Employee> saveItemMapper() {
|
||||
// 实现保存项转换逻辑
|
||||
return item -> {
|
||||
Employee employee = new Employee();
|
||||
employee.setId(item.getId());
|
||||
employee.setName(item.getName());
|
||||
employee.setAge(item.getAge());
|
||||
return employee;
|
||||
};
|
||||
}
|
||||
|
||||
@Override
|
||||
protected Function<Employee, EmployeeListItem> listItemMapper() {
|
||||
// 实现列表项转换逻辑
|
||||
return employee -> {
|
||||
EmployeeListItem item = new EmployeeListItem();
|
||||
item.setId(employee.getId());
|
||||
item.setName(employee.getName());
|
||||
item.setAge(employee.getAge());
|
||||
return item;
|
||||
};
|
||||
}
|
||||
|
||||
@Override
|
||||
protected Function<Employee, EmployeeDetailItem> detailItemMapper() {
|
||||
// 实现详情项转换逻辑
|
||||
return employee -> {
|
||||
EmployeeDetailItem item = new EmployeeDetailItem();
|
||||
item.setId(employee.getId());
|
||||
item.setName(employee.getName());
|
||||
item.setAge(employee.getAge());
|
||||
item.setCreatedTime(employee.getCreatedTime());
|
||||
item.setModifiedTime(employee.getModifiedTime());
|
||||
return item;
|
||||
};
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -405,6 +697,13 @@ public class EmployeeController extends SimpleControllerSupport<Employee, Employ
|
||||
|
||||
```java
|
||||
// 保存项
|
||||
import lombok.Getter;
|
||||
import lombok.Setter;
|
||||
import lombok.experimental.FieldNameConstants;
|
||||
|
||||
@Getter
|
||||
@Setter
|
||||
@FieldNameConstants
|
||||
public class EmployeeSaveItem {
|
||||
private Long id;
|
||||
private String name;
|
||||
@@ -413,6 +712,9 @@ public class EmployeeSaveItem {
|
||||
}
|
||||
|
||||
// 列表项
|
||||
@Getter
|
||||
@Setter
|
||||
@FieldNameConstants
|
||||
public class EmployeeListItem {
|
||||
private Long id;
|
||||
private String name;
|
||||
@@ -421,6 +723,9 @@ public class EmployeeListItem {
|
||||
}
|
||||
|
||||
// 详情项
|
||||
@Getter
|
||||
@Setter
|
||||
@FieldNameConstants
|
||||
public class EmployeeDetailItem {
|
||||
private Long id;
|
||||
private String name;
|
||||
@@ -431,11 +736,15 @@ public class EmployeeDetailItem {
|
||||
}
|
||||
```
|
||||
|
||||
### 7.5 配置启用 JPA 审计
|
||||
### 7.5 配置启用 JPA 审计（JPA 模块）
|
||||
|
||||
在您的主应用类上添加 [@EnableJpaAuditing](https://docs.spring.io/spring-data/jpa/docs/current/api/org/springframework/data/jpa/repository/config/EnableJpaAuditing.html) 注解以启用 JPA 审计功能：
|
||||
在您的主应用类上添加 @EnableJpaAuditing 注解以启用 JPA 审计功能：
|
||||
|
||||
```java
|
||||
import org.springframework.boot.SpringApplication;
|
||||
import org.springframework.boot.autoconfigure.SpringBootApplication;
|
||||
import org.springframework.data.jpa.repository.config.EnableJpaAuditing;
|
||||
|
||||
@SpringBootApplication
|
||||
@EnableJpaAuditing
|
||||
public class YourApplication {
|
||||
@@ -445,7 +754,7 @@ public class YourApplication {
|
||||
}
|
||||
```
|
||||
|
||||
### 7.6 配置 Fenix
|
||||
### 7.6 配置 Fenix（JPA 模块）
|
||||
|
||||
在您的 application.yml 或 application.properties 文件中添加 Fenix 配置：
|
||||
|
||||
@@ -457,7 +766,20 @@ fenix:
|
||||
output-format: console
|
||||
```
|
||||
|
||||
### 7.7 测试集成效果
|
||||
### 7.7 配置数据源
|
||||
|
||||
在您的 application.yml 或 application.properties 文件中配置数据源：
|
||||
|
||||
```yaml
|
||||
spring:
|
||||
datasource:
|
||||
url: jdbc:mysql://localhost:3306/your_database
|
||||
username: your_username
|
||||
password: your_password
|
||||
driver-class-name: com.mysql.cj.jdbc.Driver
|
||||
```
|
||||
|
||||
### 7.8 测试集成效果
|
||||
|
||||
完成以上步骤后，您可以运行您的应用程序并测试以下功能：
|
||||
|
||||
@@ -467,3 +789,28 @@ fenix:
|
||||
4. 删除实体：GET /employee/remove/{id}
|
||||
|
||||
通过以上步骤，您就可以成功在现有项目中集成 Spring Boot Service Template 的能力，快速实现 CRUD 功能。
|
||||
|
||||
### 7.9 不同数据库实现方式的差异
|
||||
|
||||
#### 7.9.1 JPA 模块特点
|
||||
- 基于 Spring Data JPA，提供完整的 JPA 功能
|
||||
- 支持 QueryDSL 类型安全查询
|
||||
- 支持 Fenix 动态查询
|
||||
- 自动审计功能（创建时间、修改时间）
|
||||
- 需要配置 @EnableJpaAuditing
|
||||
|
||||
#### 7.9.2 Easy Query 模块特点
|
||||
- 基于 Easy Query，提供类型安全的查询构建
|
||||
- 支持逻辑删除
|
||||
- 支持雪花 ID 生成
|
||||
- 查询性能优异
|
||||
- 不需要复杂的注解配置
|
||||
|
||||
#### 7.9.3 Xbatis 模块特点
|
||||
- 基于 MyBatis，提供灵活的 SQL 控制
|
||||
- 支持逻辑删除
|
||||
- 支持雪花 ID 生成
|
||||
- 适合复杂查询场景
|
||||
- 需要编写 Mapper XML
|
||||
|
||||
根据您的项目需求和技术栈，选择最适合的数据库实现方式。
|
||||
|
||||
Reference in New Issue
Block a user