┌─────────────────────────────────────────────────────────────────────┐
│                    Spring Boot Service Template                      │
├─────────────────────────────────────────────────────────────────────┤
│                                                                      │
│   ┌──────────────────────────────────────────────────────────────┐  │
│   │                      能力模块 (Capability)                    │  │
│   │                                                              │  │
│   │   ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │  │
│   │   │  database   │  │    user     │  │   payment   │  ...    │  │
│   │   │   ✅ 已实现  │  │   🔜 规划中  │  │   🔜 规划中  │         │  │
│   │   └──────┬──────┘  └─────────────┘  └─────────────┘         │  │
│   │          │                                                   │  │
│   │          ▼                                                   │  │
│   │   ┌─────────────────────────────────────────────┐           │  │
│   │   │   jpa   │    eq    │   xbatis   (实现)      │           │  │
│   │   └─────────────────────────────────────────────┘           │  │
│   └──────────────────────────────────────────────────────────────┘  │
│                                                                      │
│   ┌──────────────────────────────────────────────────────────────┐  │
│   │                      通用基础 (Common)                        │  │
│   │                                                              │  │
│   │   ObjectHelper (对象工具)  │  SnowflakeHelper (ID生成)        │  │
│   └──────────────────────────────────────────────────────────────┘  │
│                                                                      │
└─────────────────────────────────────────────────────────────────────┘

模块依赖关系：

┌─────────────┐
│    应用     │
└──────┬──────┘
       │
       ▼
┌─────────────────┐     ┌───────────────────┐
│ capability-common│────▶│ capability-impl   │
│   (接口定义)     │     │ (jpa/eq/xbatis)   │
└───────┬─────────┘     └───────────────────┘
        │
        ▼
┌─────────────┐
│   common    │
│ (通用工具)  │
└─────────────┘

3. 通用规范

3.1 模块命名

模块类型	命名格式	示例
能力模块	`spring-boot-service-template-{capability}`	database
通用定义	`spring-boot-service-template-{capability}-common`	database-common
具体实现	`spring-boot-service-template-{capability}-{impl}`	database-jpa
通用基础	`spring-boot-service-template-common`	common

3.2 依赖原则

common 模块：与业务无关的工具类，不依赖任何能力模块
capability-common：定义接口和通用实体，不依赖具体实现技术
最小化第三方依赖：优先使用 JDK 和 Spring 内置能力

3.3 响应格式

所有 API 使用统一的 GlobalResponse<T> 格式：

{
  "status": 0,
  "message": "OK",
  "data": { ... }
}

字段	说明
status	状态码：0=成功，500=错误
message	描述信息
data	业务数据

列表数据封装：

{
  "status": 0,
  "message": "OK",
  "data": {
    "items": [...],
    "total": 100
  }
}

3.4 代码风格

接口与实现分离：接口定义在 *-common，实现在具体模块
空值检查：使用 ObjectHelper.isNull/isNotNull/isEmpty/isNotEmpty
异常定义：继承 RuntimeException，构造器接收业务参数
注解使用：@Getter / @Setter / @FieldNameConstants / @NoArgsConstructor

4. 能力模块

4.1 database 模块

单表 CRUD → REST 接口的快速实现，支持三种数据库访问方式。

模块概述

功能	说明
保存	单条/批量保存，自动判断新增/更新
查询	详情查询、列表查询、分页查询、条件查询
删除	单条/批量删除

实现方式对比

特性	JPA	Easy Query	Xbatis
类型安全查询	✅ QueryDSL	✅ Proxy API	❌
自动审计	✅	❌	❌
逻辑删除	❌	✅	✅
复杂 SQL	中等	中等	强
适用场景	标准 JPA 项目	类型安全 + 逻辑删除	复杂查询场景

快速开始

1. 添加依赖

<!-- JPA 实现 -->
<dependency>
    <groupId>com.lanyuanxiaoyao</groupId>
    <artifactId>spring-boot-service-template-database-jpa</artifactId>
    <version>1.1.0-SNAPSHOT</version>
</dependency>

2. 实现 CRUD 的 5 个步骤

参考测试代码：spring-boot-service-template-database-jpa/src/test/java/.../

步骤	说明	参考文件
1. 创建实体	继承 `SimpleEntity`	`entity/Employee.java`
2. 创建 Repository	继承 `SimpleRepository<ENTITY>`	`repository/EmployeeRepository.java`
3. 创建 Service	继承 `SimpleServiceSupport<ENTITY>`	`service/EmployeeService.java`
4. 创建 DTO	定义 SaveItem, ListItem, DetailItem	`controller/EmployeeController.java`
5. 创建 Controller	继承 `SimpleControllerSupport`，实现 3 个 Mapper	`controller/EmployeeController.java`

3. 查询条件语法

{
  "query": {
    "equal": { "name": "张三" },
    "like": { "name": "%张%" },
    "contain": { "name": "张" },
    "startWith": { "name": "张" },
    "endWith": { "name": "三" },
    "great": { "age": 18 },
    "less": { "age": 60 },
    "greatEqual": { "age": 18 },
    "lessEqual": { "age": 60 },
    "between": { "age": { "start": 18, "end": 60 } },
    "inside": { "id": [1, 2, 3] },
    "notInside": { "id": [1, 2, 3] },
    "nullEqual": ["deletedTime"],
    "notNullEqual": ["name"]
  },
  "sort": [{ "column": "createdTime", "direction": "DESC" }],
  "page": { "index": 1, "size": 10 }
}

模块特定规范

分层结构：

Controller (HTTP处理、DTO转换)
    │
    ▼
Service (业务逻辑、事务管理)
    │
    ▼
Repository/Mapper (数据访问)
    │
    ▼
Entity (数据模型)

泛型参数：

ENTITY - 实体类型
SAVE_ITEM - 保存请求 DTO
LIST_ITEM - 列表响应 DTO
DETAIL_ITEM - 详情响应 DTO

实体继承：

JPA: IdOnlyEntity → SimpleEntity → 业务实体
EQ/Xbatis: IdOnlyEntity → SimpleEntity 或 LogicDeleteEntity

4.2 user 模块

🚧 规划中...

4.3 payment 模块

🚧 规划中...

5. 技术栈

组件	版本
Java	17
Spring Boot	4.0.0
Spring Cloud	2025.1.0
Hibernate	7.1.8.Final
QueryDSL	7.1
Easy Query	3.1.68
Xbatis	1.9.7-spring-boot4
Lombok	-
MapStruct	1.6.3

6. 开发与测试

构建项目：

mvn clean package

运行测试：

mvn test

测试使用 H2 内存数据库，无需额外配置。

7. 文档索引

详细文档：docs/ 目录
测试示例：各模块的 src/test/java/ 目录

README.md Unescape Escape

Spring Boot Service Template

1. 项目概述

2. 架构