261 lines
9.3 KiB
Markdown
261 lines
9.3 KiB
Markdown
# 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/` 目录
|