# Spring Boot Service Template

微服务快速开发能力模板，提供标准化的能力模块，帮助开发者快速构建 Spring Boot 微服务应用。

**当前版本**: 1.1.0-SNAPSHOT

## 1. 项目概述

Spring Boot Service Template 是一个能力模块化的微服务开发模板。每个能力模块封装特定领域的通用功能，开发者只需引入依赖、实现少量代码即可获得完整的业务能力。

**核心价值**：
- 能力模块化：每个模块独立可用，按需引入
- 零样板代码：通用逻辑已封装，专注业务实现
- 多实现支持：同一能力支持多种技术实现，灵活选择

## 2. 架构

```
┌─────────────────────────────────────────────────────────────────────┐
│                    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>` 格式：

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

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

列表数据封装：

```json
{
  "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. 添加依赖**

```xml
<!-- 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. 查询条件语法**

```json
{
  "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. 开发与测试

**构建项目**：
```bash
mvn clean package
```

**运行测试**：
```bash
mvn test
```

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

## 7. 文档索引

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