lanyuanxiaoyao/spring-boot-service-template
1
0
Fork 0
Code Activity
Files
3692657b6477bc1923a856748167ed9f5ab7f711
spring-boot-service-template/README.md
lanyuanxiaoyao 3692657b64 docs: 补充README
2026-01-22 22:18:37 +08:00

817 lines
33 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Spring Boot Service Template
这是一个基于 Spring Boot 的服务模板项目，采用模块化架构设计，旨在为开发者提供标准化的微服务基础结构，简化新项目的搭建过程，提高开发效率。
## 目录
- [1. 项目概述](#1-项目概述)
- [2. 技术架构](#2-技术架构)
- [3. 项目结构](#3-项目结构)
- [4. 核心功能](#4-核心功能)
- [5. 使用指南](#5-使用指南)
- [6. 开发规范](#6-开发规范)
- [7. 项目集成指南](#7-项目集成指南)
## 1. 项目概述
### 1.1 项目简介
Spring Boot Service Template 是一个标准化的微服务基础结构模板，专为 Java 开发者和微服务架构设计者打造。该项目采用模块化架构设计，提供了一套完整的 CRUD 操作框架，支持多种数据库访问方式（JPA、Easy Query、Xbatis），通过泛型支持不同类型的数据转换，大大减少了重复代码的编写。
该模板内置了完善的实体审计机制，自动维护实体的创建时间和修改时间。同时，提供了强大的查询功能，支持多种条件查询、分页和排序功能。
### 1.2 项目目标
提供统一的服务模板，简化新项目的搭建过程，提高开发效率。通过封装通用的业务逻辑，让开发者能够专注于核心业务功能的实现。
### 1.3 核心特性
- 模块化架构：采用多模块设计，通用功能与数据库操作分离，便于按需引入
- 标准化的项目结构：遵循业界最佳实践的目录结构和代码组织方式
- 多数据库支持：支持 JPA、Easy Query、Xbatis 三种数据库访问方式
- 简化依赖管理和构建流程：基于 Maven 的依赖管理，清晰的构建配置
- 支持快速构建和部署微服务：提供完整的微服务基础组件
- 泛型支持：通过泛型实现不同类型间的数据转换
- 完善的审计机制：自动维护实体的创建时间和修改时间
- 强大的查询功能：支持多种条件查询、分页和排序
- 灵活的扩展机制：易于定制和扩展的架构设计
- 统一的响应格式：标准化的 API 响应结构
- 雪花 ID 生成器：支持分布式环境下的唯一 ID 生成
### 1.4 适用场景
适用于需要快速搭建 Spring Boot 微服务的项目，特别是那些需要大量 CRUD 操作的业务系统。支持三种数据库访问方式，可根据项目需求灵活选择：
- **JPA 模块**：适合传统的 Spring Data JPA 项目，提供完整的 JPA 功能
- **Easy Query 模块**：适合需要类型安全查询的项目，提供强大的查询构建能力
- **Xbatis 模块**：适合需要 MyBatis 灵活性的项目，提供增强的 MyBatis 功能
## 2. 技术架构
### 2.1 技术选型
#### 2.1.1 后端技术栈
- Java 17
- Spring Boot 4.0.0
- Spring Cloud 2025.1.0
- Lombok
- MapStruct 1.6.3
- Hutool 5.8.43
#### 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 用于数据访问，简化数据库操作（JPA 模块）
- QueryDSL 用于类型安全的查询构建，避免运行时错误（JPA 模块）
- Fenix 用于复杂动态查询，提供更灵活的查询能力（JPA 模块）
- Easy Query 用于类型安全的查询构建和灵活的数据访问（EQ 模块）
- Xbatis 用于增强的 MyBatis 数据访问（Xbatis 模块）
- Lombok 减少样板代码，提高开发效率
- MapStruct 用于对象映射，简化数据转换
#### 2.1.4 数据库技术
- H2 Database (测试环境)
### 2.2 架构设计
#### 2.2.1 整体架构图
```
┌─────────────────────────────────────┐
│ Controller Layer │
│ (处理HTTP请求，数据转换与响应) │
├─────────────────────────────────────┤
│ Service Layer │
│ (业务逻辑处理，事务管理) │
├─────────────────────────────────────┤
│ Repository/Mapper Layer │
│ (数据访问，数据库交互) │
├─────────────────────────────────────┤
│ Entity Layer │
│ (数据模型定义，实体映射) │
└─────────────────────────────────────┘
```
#### 2.2.2 模块划分
项目采用模块化架构，主要包含以下模块：
**通用模块**
- 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 目录结构说明
```
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 common 模块
提供通用的工具类，主要包含：
- [ObjectHelper](spring-boot-service-template-common/src/main/java/com/lanyuanxiaoyao/service/template/common/helper/ObjectHelper.java)：对象工具类，提供对象空值判断、类型判断等常用功能
#### 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)：删除操作接口
- **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)：查询条件解析器
- **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)：分页结果封装类
- **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 测试模块结构
每个数据库实现模块都包含完整的测试用例，通过实际的业务实体（如 Employee、Company、Report）演示如何使用模板。
## 4. 核心功能
### 4.1 基础 CRUD 操作
#### 4.1.1 创建 (Create)
支持通过 POST 请求创建实体对象。通过 save 接口实现，接收 SAVE_ITEM 类型的参数，通过 Mapper 转换为实体对象后保存。
#### 4.1.2 查询 (Retrieve)
支持多种查询方式：
- 列表查询：获取所有实体对象
- 条件查询：根据指定条件查询实体对象
- 详情查询：根据 ID 获取单个实体对象
#### 4.1.3 更新 (Update)
支持通过 POST 请求更新实体对象。通过 save 接口实现，当传入包含 ID 的对象时执行更新操作。
#### 4.1.4 删除 (Delete)
支持通过 GET 请求删除实体对象。通过 remove 接口实现，根据 ID 删除指定实体。
### 4.2 查询功能详解
#### 4.2.1 简单查询
支持基于 ID 的简单查询，通过 detail 接口实现。
#### 4.2.2 条件查询
支持基于多种条件的复杂查询，通过 list 接口实现，支持以下查询条件：
- nullEqual: 字段值为 null 的条件
- notNullEqual: 字段值不为 null 的条件
- empty: 字段值为空的条件
- notEmpty: 字段值不为空的条件
- equal: 字段值相等的条件
- notEqual: 字段值不相等的条件
- like: 字段值模糊匹配的条件
- notLike: 字段值不模糊匹配的条件
- contain: 字段包含指定字符串的条件
- notContain: 字段不包含指定字符串的条件
- startWith: 字段以指定字符串开头的条件
- notStartWith: 字段不以指定字符串开头的条件
- endWith: 字段以指定字符串结尾的条件
- notEndWith: 字段不以指定字符串结尾的条件
- great: 字段值大于的条件
- less: 字段值小于的条件
- greatEqual: 字段值大于等于的条件
- lessEqual: 字段值小于等于的条件
- inside: 字段值在指定范围内的条件
- notInside: 字段值不在指定范围内的条件
- between: 字段值在指定区间内的条件
- notBetween: 字段值不在指定区间内的条件
#### 4.2.3 分页查询
支持分页查询功能，通过 page 配置实现分页参数设置。
#### 4.2.4 排序查询
支持排序查询功能，通过 sort 配置实现排序参数设置。
### 4.3 数据实体设计
#### 4.3.1 基础实体类
定义通用的实体基类，包括 IdOnlyEntity 和 SimpleEntity。
#### 4.3.2 审计字段
包含创建时间 (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 安装
需要安装 JDK 17 或更高版本。
#### 5.1.2 Maven 配置
需要配置 Maven 3.x 环境。
### 5.2 项目构建
#### 5.2.1 依赖管理
通过 Maven 管理项目依赖。
#### 5.2.2 编译打包
使用 `mvn clean package` 命令编译打包项目。
### 5.3 运行部署
#### 5.3.1 本地运行
可以使用 `mvn spring-boot:run` 命令运行项目。
#### 5.3.2 生产部署
可通过生成的 JAR 文件直接运行或部署到服务器，使用命令：
`java -jar target/spring-boot-service-template-1.1.0-SNAPSHOT.jar`
## 6. 开发规范
### 6.1 代码规范
遵循 Java 标准编码规范和 Spring Boot 最佳实践。
### 6.2 接口规范
RESTful API 设计规范，统一的响应格式。
### 6.3 注释规范
遵循标准的 JavaDoc 格式编写注释，详细说明类、方法、参数和返回值的含义。
### 6.4 异常处理
统一异常处理机制，提供友好的错误信息。
## 7. 项目集成指南
本章节详细介绍如何在现有项目中集成 Spring Boot Service Template 的能力。
### 7.1 集成方式
通过 Maven 依赖引入（推荐）
### 7.2 选择数据库实现方式
项目提供三种数据库实现方式，根据您的需求选择：
- **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-common</artifactId>
<version>1.1.0-SNAPSHOT</version>
</dependency>
```
#### 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 配置依赖管理
确保您的项目中包含以下依赖管理配置：
```xml
<dependencyManagement>
<dependencies>
<!-- spring boot 相关依赖 -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-dependencies</artifactId>
<version>4.0.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
<dependency>
<groupId>org.springframework.cloud</groupId>
<artifactId>spring-cloud-dependencies</artifactId>
<version>2025.1.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
```
#### 7.3.4 配置编译插件
确保您的项目中包含以下编译插件配置：
**JPA 模块编译插件**
```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>org.hibernate</groupId>
<artifactId>hibernate-jpamodelgen</artifactId>
<version>7.1.8.Final</version>
</path>
<path>
<groupId>io.github.openfeign.querydsl</groupId>
<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>
</plugin>
</plugins>
</build>
```
### 7.4 创建业务模块
创建业务模块的步骤如下（以 JPA 模块为例）：
#### 7.4.1 创建实体类
创建实体类并继承 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 {
private String name;
private Integer age;
// 其他字段和方法
}
```
#### 7.4.2 创建仓储接口
创建仓储接口并继承 SimpleRepository：
```java
import com.lanyuanxiaoyao.service.template.database.jpa.repository.SimpleRepository;
import org.springframework.stereotype.Repository;
@Repository
public interface EmployeeRepository extends SimpleRepository<Employee> {
// 自定义查询方法
}
```
#### 7.4.3 创建服务类
创建服务类并继承 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) {
super(repository);
}
// 自定义业务方法
}
```
#### 7.4.4 创建控制器类
创建控制器类并继承 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> {
public EmployeeController(EmployeeService service) {
super(service);
}
@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;
};
}
}
```
#### 7.4.5 创建数据传输对象
创建用于数据传输的对象：
```java
// 保存项
import lombok.Getter;
import lombok.Setter;
import lombok.experimental.FieldNameConstants;
@Getter
@Setter
@FieldNameConstants
public class EmployeeSaveItem {
private Long id;
private String name;
private Integer age;
// getter和setter方法
}
// 列表项
@Getter
@Setter
@FieldNameConstants
public class EmployeeListItem {
private Long id;
private String name;
private Integer age;
// getter和setter方法
}
// 详情项
@Getter
@Setter
@FieldNameConstants
public class EmployeeDetailItem {
private Long id;
private String name;
private Integer age;
private LocalDateTime createdTime;
private LocalDateTime modifiedTime;
// getter和setter方法
}
```
### 7.5 配置启用 JPA 审计（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 {
public static void main(String[] args) {
SpringApplication.run(YourApplication.class, args);
}
}
```
### 7.6 配置 Fenix（JPA 模块）
在您的 application.yml 或 application.properties 文件中添加 Fenix 配置：
```yaml
fenix:
# 是否开启 Fenix
enabled: true
# SQL 执行后的输出格式，console: 控制台彩色输出; html: 彩色 HTML 输出; text: 纯文本输出
output-format: console
```
### 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 测试集成效果
完成以上步骤后，您可以运行您的应用程序并测试以下功能：
1. 创建实体：POST /employee/save
2. 查询列表：GET /employee/list 或 POST /employee/list（带条件）
3. 查询详情：GET /employee/detail/{id}
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
根据您的项目需求和技术栈，选择最适合的数据库实现方式。
View Git Blame Copy Permalink