From 3692657b6477bc1923a856748167ed9f5ab7f711 Mon Sep 17 00:00:00 2001 From: lanyuanxiaoyao Date: Wed, 21 Jan 2026 22:05:46 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E8=A1=A5=E5=85=85README?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 529 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 438 insertions(+), 91 deletions(-) diff --git a/README.md b/README.md index 8e55c62..2c20c7b 100644 --- a/README.md +++ b/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 com.lanyuanxiaoyao - spring-boot-service-template - 1.0.0-SNAPSHOT + spring-boot-service-template-common + 1.1.0-SNAPSHOT ``` -#### 7.2.2 配置依赖管理 +#### 7.3.2 添加数据库实现依赖 + +根据您选择的数据库实现方式，添加对应的依赖： + +**JPA 实现** +```xml + + com.lanyuanxiaoyao + spring-boot-service-template-database-jpa + 1.1.0-SNAPSHOT + +``` + +**Easy Query 实现** +```xml + + com.lanyuanxiaoyao + spring-boot-service-template-database-eq + 1.1.0-SNAPSHOT + +``` + +**Xbatis 实现** +```xml + + com.lanyuanxiaoyao + spring-boot-service-template-database-xbatis + 1.1.0-SNAPSHOT + +``` + +#### 7.3.3 配置依赖管理 确保您的项目中包含以下依赖管理配置： @@ -277,14 +469,14 @@ RESTful API 设计规范，统一的响应格式。 org.springframework.boot spring-boot-dependencies - ${spring-boot.version} + 4.0.0 pom import org.springframework.cloud spring-cloud-dependencies - ${spring-cloud.version} + 2025.1.0 pom import @@ -292,33 +484,90 @@ RESTful API 设计规范，统一的响应格式。 ``` -#### 7.2.3 配置编译插件 +#### 7.3.4 配置编译插件 确保您的项目中包含以下编译插件配置： +**JPA 模块编译插件** ```xml org.apache.maven.plugins maven-compiler-plugin - 3.14.0 + 3.14.1 org.projectlombok lombok - 1.18.36 org.hibernate hibernate-jpamodelgen - 6.6.3.Final + 7.1.8.Final io.github.openfeign.querydsl - querydsl-jpa - 7.0 + querydsl-apt + 7.1 + jpa + + + jakarta.persistence + jakarta.persistence-api + 3.2.0 + + + + -Aquerydsl.entityAccessors=true + -Aquerydsl.createDefaultVariable=true + + + + + +``` + +**Easy Query 模块编译插件** +```xml + + + + org.apache.maven.plugins + maven-compiler-plugin + 3.14.1 + + + + org.projectlombok + lombok + + + com.easy-query + sql-processor + 3.1.68 + + + + + + +``` + +**Xbatis 模块编译插件** +```xml + + + + org.apache.maven.plugins + maven-compiler-plugin + 3.14.1 + + + + org.projectlombok + lombok @@ -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 { // 自定义查询方法 @@ -358,9 +620,12 @@ public interface EmployeeRepository extends SimpleRepository { #### 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 { public EmployeeService(EmployeeRepository repository) { @@ -372,9 +637,13 @@ public class EmployeeService extends SimpleServiceSupport { #### 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 { @@ -385,16 +654,39 @@ public class EmployeeController extends SimpleControllerSupport saveItemMapper() { // 实现保存项转换逻辑 + return item -> { + Employee employee = new Employee(); + employee.setId(item.getId()); + employee.setName(item.getName()); + employee.setAge(item.getAge()); + return employee; + }; } @Override protected Function listItemMapper() { // 实现列表项转换逻辑 + return employee -> { + EmployeeListItem item = new EmployeeListItem(); + item.setId(employee.getId()); + item.setName(employee.getName()); + item.setAge(employee.getAge()); + return item; + }; } @Override protected Function 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