Spring Boot Service Template

这是一个基于 Spring Boot 的服务模板项目，旨在为开发者提供一个标准化的微服务基础结构，简化新项目的搭建过程，提高开发效率。

目录

• 1. 项目概述
• 2. 技术架构
• 3. 项目结构
• 4. 核心功能
• 5. 使用指南
• 6. 开发规范
• 7. 项目集成指南

1. 项目概述

1.1 项目简介

Spring Boot Service Template 是一个标准化的微服务基础结构模板，专为 Java 开发者和微服务架构设计者打造。该项目提供了一套完整的 CRUD 操作框架，通过泛型支持不同类型的数据转换，大大减少了重复代码的编写。

该模板内置了完善的实体审计机制，自动维护实体的创建时间和修改时间。同时，提供了强大的查询功能，支持多种条件查询、分页和排序功能。

1.2 项目目标

提供统一的服务模板，简化新项目的搭建过程，提高开发效率。通过封装通用的业务逻辑，让开发者能够专注于核心业务功能的实现。

1.3 核心特性

• 标准化的项目结构：遵循业界最佳实践的目录结构和代码组织方式
• 简化依赖管理和构建流程：基于 Maven 的依赖管理，清晰的构建配置
• 支持快速构建和部署微服务：提供完整的微服务基础组件
• 泛型支持：通过泛型实现不同类型间的数据转换
• 完善的审计机制：自动维护实体的创建时间和修改时间
• 强大的查询功能：支持多种条件查询、分页和排序
• 灵活的扩展机制：易于定制和扩展的架构设计

1.4 适用场景

适用于需要快速搭建 Spring Boot 微服务的项目，特别是那些需要大量 CRUD 操作的业务系统。

2. 技术架构

2.1 技术选型

2.1.1 后端技术栈

• Java 17
• Spring Boot 3.4.3
• Spring Data JPA
• QueryDSL 7.0
• Lombok
• Fenix Spring Boot Starter 3.1.0

2.1.2 核心框架

• Spring Boot 作为核心框架，提供自动配置和快速开发能力
• Spring Data JPA 用于数据访问，简化数据库操作
• QueryDSL 用于类型安全的查询构建，避免运行时错误
• Fenix 用于复杂动态查询，提供更灵活的查询能力
• Lombok 减少样板代码，提高开发效率

2.1.3 数据库技术

• H2 Database (测试环境)

2.2 架构设计

2.2.1 整体架构图

┌─────────────────────────────────────┐
│            Controller Layer         │
│  (处理HTTP请求，数据转换与响应)      │
├─────────────────────────────────────┤
│             Service Layer           │
│  (业务逻辑处理，事务管理)            │
├─────────────────────────────────────┤
│          Repository Layer           │
│  (数据访问，数据库交互)              │
├─────────────────────────────────────┤
│            Entity Layer             │
│  (数据模型定义，实体映射)            │
└─────────────────────────────────────┘

2.2.2 模块划分

• controller: 控制层，处理 HTTP 请求，包括接口定义和支持类
• entity: 实体层，定义数据模型和数据库映射
• service: 服务层，处理业务逻辑和事务管理
• repository: 仓储层，处理数据访问和数据库交互
• helper: 辅助类模块，提供工具类和通用方法

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/

3.2 核心模块介绍

3.2.1 controller模块

提供基础的 CRUD 操作控制器接口和支持类。主要包含：

• SimpleController：定义基础 CRUD 接口
• SimpleControllerSupport：实现基础 CRUD 功能
• Query：查询条件封装类
• 其他辅助接口如 SaveController、ListController、DetailController、RemoveController

3.2.2 entity模块

定义基础实体类，包含审计字段。主要包含：

• IdOnlyEntity：仅包含 ID 的基础实体
• SimpleEntity：包含基础字段的实体类，继承自 IdOnlyEntity

3.2.3 service模块

提供基础服务接口和支持类。主要包含：

• SimpleService：定义基础服务接口
• SimpleServiceSupport：实现基础服务功能

3.2.4 repository模块

定义数据访问仓储接口。主要包含：

• SimpleRepository：基础仓储接口

3.2.5 helper模块

提供辅助工具类。主要包含：

• ObjectHelper：对象帮助类

3.3 测试模块结构

测试模块包含完整的测试用例，覆盖 controller、entity、repository 和 service 各层。通过实际的业务实体（如 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: 字段值不模糊匹配的条件
• great: 字段值大于的条件
• less: 字段值小于的条件
• greatEqual: 字段值大于等于的条件
• lessEqual: 字段值小于等于的条件
• in: 字段值在指定范围内的条件
• notIn: 字段值不在指定范围内的条件
• 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 的审计功能自动维护。

4.3.3 实体关系

支持常见的实体关系映射，如一对一、一对多、多对多等。

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.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 Maven 依赖引入方式

7.2.1 添加依赖

在您的项目 pom.xml 文件中添加以下依赖：

<dependency>
    <groupId>com.lanyuanxiaoyao</groupId>
    <artifactId>spring-boot-service-template</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

7.2.2 配置依赖管理

确保您的项目中包含以下依赖管理配置：

<dependencyManagement>
    <dependencies>
        <!-- spring boot 相关依赖 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-dependencies</artifactId>
            <version>${spring-boot.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
        <dependency>
            <groupId>org.springframework.cloud</groupId>
            <artifactId>spring-cloud-dependencies</artifactId>
            <version>${spring-cloud.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

7.2.3 配置编译插件

确保您的项目中包含以下编译插件配置：

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.14.0</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>
                    </path>
                    <path>
                        <groupId>io.github.openfeign.querydsl</groupId>
                        <artifactId>querydsl-jpa</artifactId>
                        <version>7.0</version>
                    </path>
                </annotationProcessorPaths>
            </configuration>
        </plugin>
    </plugins>
</build>

7.4 创建业务模块

创建业务模块的步骤如下：

7.4.1 创建实体类

创建实体类并继承 SimpleEntity：

@Entity
@Table(name = "employee")
public class Employee extends SimpleEntity {
    private String name;
    private Integer age;
    // 其他字段和方法
}

7.4.2 创建仓储接口

创建仓储接口并继承 SimpleRepository：

@Repository
public interface EmployeeRepository extends SimpleRepository<Employee> {
    // 自定义查询方法
}

7.4.3 创建服务类

创建服务类并继承 SimpleServiceSupport：

@Service
public class EmployeeService extends SimpleServiceSupport<Employee> {
    public EmployeeService(EmployeeRepository repository) {
        super(repository);
    }
    // 自定义业务方法
}

7.4.4 创建控制器类

创建控制器类并继承 SimpleControllerSupport：

@RestController
@RequestMapping("employee")
public class EmployeeController extends SimpleControllerSupport<Employee, EmployeeSaveItem, EmployeeListItem, EmployeeDetailItem> {
    public EmployeeController(EmployeeService service) {
        super(service);
    }
    
    @Override
    protected Function<EmployeeSaveItem, Employee> saveItemMapper() {
        // 实现保存项转换逻辑
    }
    
    @Override
    protected Function<Employee, EmployeeListItem> listItemMapper() {
        // 实现列表项转换逻辑
    }
    
    @Override
    protected Function<Employee, EmployeeDetailItem> detailItemMapper() {
        // 实现详情项转换逻辑
    }
}

7.4.5 创建数据传输对象

创建用于数据传输的对象：

// 保存项
public class EmployeeSaveItem {
    private Long id;
    private String name;
    private Integer age;
    // getter和setter方法
}

// 列表项
public class EmployeeListItem {
    private Long id;
    private String name;
    private Integer age;
    // getter和setter方法
}

// 详情项
public class EmployeeDetailItem {
    private Long id;
    private String name;
    private Integer age;
    private LocalDateTime createdTime;
    private LocalDateTime modifiedTime;
    // getter和setter方法
}

7.5 配置启用 JPA 审计

在您的主应用类上添加 @EnableJpaAuditing 注解以启用 JPA 审计功能：

@SpringBootApplication
@EnableJpaAuditing
public class YourApplication {
    public static void main(String[] args) {
        SpringApplication.run(YourApplication.class, args);
    }
}

7.6 配置 Fenix

在您的 application.yml 或 application.properties 文件中添加 Fenix 配置：

fenix:
  # 是否开启 Fenix
  enabled: true
  # SQL 执行后的输出格式，console: 控制台彩色输出; html: 彩色 HTML 输出; text: 纯文本输出
  output-format: console

7.7 测试集成效果

完成以上步骤后，您可以运行您的应用程序并测试以下功能：

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