409 lines
9.2 KiB
Markdown
409 lines
9.2 KiB
Markdown
# Database 模块使用指南
|
||
|
||
单表 CRUD → REST 接口快速实现框架。
|
||
|
||
## 使用模式
|
||
|
||
### Web 应用
|
||
|
||
引入 database 模块，创建 Entity → Repository → Service → Controller，实现 REST 接口。
|
||
|
||
### 非 Web 应用
|
||
|
||
**无需引入 web 依赖**（database 模块的 `spring-boot-starter-web` scope 为 `provided`）。
|
||
|
||
仅使用 Entity → Repository → Service，直接注入 Service 使用：
|
||
|
||
```java
|
||
@SpringBootApplication
|
||
public class Application implements CommandLineRunner {
|
||
@Autowired
|
||
private EmployeeService service;
|
||
|
||
@Override
|
||
public void run(String... args) {
|
||
Employee emp = new Employee();
|
||
emp.setName("张三");
|
||
Long id = service.save(emp);
|
||
Employee found = service.detail(id);
|
||
List<Employee> list = service.list();
|
||
}
|
||
}
|
||
```
|
||
|
||
适用：批处理、定时任务、数据迁移、命令行应用、后台服务。
|
||
|
||
## 快速开始
|
||
|
||
### 1. 添加依赖
|
||
|
||
```xml
|
||
<dependency>
|
||
<groupId>com.lanyuanxiaoyao</groupId>
|
||
<artifactId>spring-boot-service-template-database</artifactId>
|
||
</dependency>
|
||
```
|
||
|
||
### 2. 创建实体
|
||
|
||
```java
|
||
@Getter @Setter
|
||
@ToString(callSuper = true)
|
||
@FieldNameConstants
|
||
@Entity
|
||
@Table(name = "employee")
|
||
public class Employee extends SimpleEntity {
|
||
@Column(comment = "员工姓名", nullable = false)
|
||
private String name;
|
||
|
||
@Column(comment = "部门ID")
|
||
private Long departmentId;
|
||
|
||
@Column(comment = "邮箱")
|
||
private String email;
|
||
}
|
||
```
|
||
|
||
继承 `SimpleEntity` 自动获得 `id`（雪花算法）、`createdTime`、`modifiedTime`（自动填充）。
|
||
|
||
### 3. 创建 Repository
|
||
|
||
```java
|
||
@Repository
|
||
public interface EmployeeRepository extends SimpleRepository<Employee> {}
|
||
```
|
||
|
||
继承能力：CRUD、分页、Specification、QueryDSL、Example。
|
||
|
||
### 4. 创建 Service
|
||
|
||
```java
|
||
@Slf4j
|
||
@Service
|
||
public class EmployeeService extends SimpleServiceSupport<Employee> {
|
||
public EmployeeService(EmployeeRepository repository) {
|
||
super(repository);
|
||
}
|
||
}
|
||
```
|
||
|
||
自动获得完整 CRUD 能力。
|
||
|
||
### 5. 创建 Controller（Web 应用）
|
||
|
||
```java
|
||
@Slf4j
|
||
@RestController
|
||
@RequestMapping("employee")
|
||
public class EmployeeController
|
||
extends SimpleControllerSupport<Employee, EmployeeController.SaveItem, EmployeeController.ListItem, EmployeeController.DetailItem> {
|
||
|
||
private final EmployeeService service;
|
||
|
||
public EmployeeController(EmployeeService service) {
|
||
super(service);
|
||
this.service = service;
|
||
}
|
||
|
||
@Override
|
||
protected Function<SaveItem, Employee> saveItemMapper() {
|
||
return item -> {
|
||
Employee entity = new Employee();
|
||
entity.setId(item.id());
|
||
entity.setName(item.name());
|
||
entity.setDepartmentId(item.departmentId());
|
||
entity.setEmail(item.email());
|
||
return entity;
|
||
};
|
||
}
|
||
|
||
@Override
|
||
protected Function<Employee, ListItem> listItemMapper() {
|
||
return entity -> new ListItem(
|
||
entity.getId(), entity.getName(), entity.getDepartmentId(),
|
||
entity.getEmail(), entity.getCreatedTime()
|
||
);
|
||
}
|
||
|
||
@Override
|
||
protected Function<Employee, DetailItem> detailItemMapper() {
|
||
return entity -> new DetailItem(
|
||
entity.getId(), entity.getName(), entity.getDepartmentId(),
|
||
entity.getEmail(), entity.getCreatedTime(), entity.getModifiedTime()
|
||
);
|
||
}
|
||
|
||
public record SaveItem(Long id, String name, Long departmentId, String email) {}
|
||
public record ListItem(Long id, String name, Long departmentId, String email, LocalDateTime createdTime) {}
|
||
public record DetailItem(Long id, String name, Long departmentId, String email, LocalDateTime createdTime, LocalDateTime modifiedTime) {}
|
||
}
|
||
```
|
||
|
||
实现三个 Mapper：`saveItemMapper()`, `listItemMapper()`, `detailItemMapper()`
|
||
|
||
## 代码生成
|
||
|
||
```java
|
||
DatabaseHelper.generateBasicFiles(
|
||
"com.example.entity", // 实体包
|
||
"com.example", // 项目根包
|
||
"./src/main/java/com/example", // 源码路径
|
||
false // 是否覆盖
|
||
);
|
||
```
|
||
|
||
生成 Repository、Service、Controller。
|
||
|
||
## API 接口（Web 应用）
|
||
|
||
### POST /{entity}/save
|
||
|
||
保存/更新实体。
|
||
|
||
请求（新增）：
|
||
```json
|
||
{"name": "张三", "departmentId": 1, "email": "zhangsan@example.com"}
|
||
```
|
||
|
||
请求（更新）：
|
||
```json
|
||
{"id": 123456789, "name": "李四"}
|
||
```
|
||
|
||
响应：
|
||
```json
|
||
{"status": 0, "message": "OK", "data": 123456789}
|
||
```
|
||
|
||
特性：不传 id 为新增，传 id 为更新（仅更新非 null 字段）。
|
||
|
||
### GET/POST /{entity}/list
|
||
|
||
GET：获取全部列表
|
||
|
||
POST：条件查询
|
||
```json
|
||
{
|
||
"query": {
|
||
"equal": {"departmentId": 1},
|
||
"like": {"name": "%张%"},
|
||
"greatEqual": {"createdTime": "2026-01-01 00:00:00"}
|
||
},
|
||
"sort": [{"column": "createdTime", "direction": "DESC"}],
|
||
"page": {"index": 1, "size": 20}
|
||
}
|
||
```
|
||
|
||
响应：
|
||
```json
|
||
{"status": 0, "message": "OK", "data": {"items": [...], "total": 100}}
|
||
```
|
||
|
||
### GET /{entity}/detail/{id}
|
||
|
||
响应：
|
||
```json
|
||
{"status": 0, "message": "OK", "data": {"id": 123, "name": "张三", ...}}
|
||
```
|
||
|
||
ID 不存在返回 500。
|
||
|
||
### GET /{entity}/remove/{id}
|
||
|
||
响应：
|
||
```json
|
||
{"status": 0, "message": "OK", "data": null}
|
||
```
|
||
|
||
## 查询条件
|
||
|
||
### Query 结构
|
||
|
||
```java
|
||
Query(
|
||
query: Queryable, // 查询条件
|
||
sort: List<Sortable>, // 排序
|
||
page: Pageable // 分页
|
||
)
|
||
```
|
||
|
||
### 查询操作
|
||
|
||
| 操作 | 类型 | 示例 |
|
||
|---|---|---|
|
||
| equal | Map | `{"name": "张三"}` |
|
||
| notEqual | Map | `{"status": "DELETED"}` |
|
||
| like | Map | `{"name": "%张%"}` |
|
||
| contain | Map | `{"name": "张"}` → `%张%` |
|
||
| startWith | Map | `{"name": "张"}` → `张%` |
|
||
| endWith | Map | `{"name": "三"}` → `%三` |
|
||
| great/greatEqual | Map | `{"age": 18}` |
|
||
| less/lessEqual | Map | `{"age": 60}` |
|
||
| between | Map | `{"age": {"start": 18, "end": 60}}` |
|
||
| inside | Map | `{"id": [1, 2, 3]}` |
|
||
| notInside | Map | `{"status": ["DELETED"]}` |
|
||
| nullEqual | List | `["deletedAt"]` |
|
||
| notNullEqual | List | `["email"]` |
|
||
|
||
### 排序
|
||
|
||
```json
|
||
{"sort": [{"column": "createdTime", "direction": "DESC"}]}
|
||
```
|
||
|
||
direction: `ASC` 升序，`DESC` 降序
|
||
|
||
### 分页
|
||
|
||
```json
|
||
{"page": {"index": 1, "size": 20}}
|
||
```
|
||
|
||
index 从 1 开始，默认 `(1, 10)`，无排序默认 `createdTime DESC`
|
||
|
||
## 高级用法
|
||
|
||
### 扩展 Service
|
||
|
||
```java
|
||
@Service
|
||
public class EmployeeService extends SimpleServiceSupport<Employee> {
|
||
private final EmployeeRepository repository;
|
||
|
||
public EmployeeService(EmployeeRepository repository) {
|
||
super(repository);
|
||
this.repository = repository;
|
||
}
|
||
|
||
// 自定义方法
|
||
public List<Employee> findByDepartmentId(Long departmentId) {
|
||
return repository.findAll(
|
||
(root, query, builder) -> builder.equal(root.get("departmentId"), departmentId)
|
||
);
|
||
}
|
||
|
||
// 全局过滤条件
|
||
@Override
|
||
protected Predicate commonPredicates(Root<Employee> root, CriteriaQuery<?> query, CriteriaBuilder builder) {
|
||
return builder.equal(root.get("deleted"), false); // 软删除过滤
|
||
}
|
||
}
|
||
```
|
||
|
||
### QueryDSL 查询
|
||
|
||
```java
|
||
public List<Employee> findActiveEmployees() {
|
||
QEmployee q = QEmployee.employee;
|
||
return repository.findAll(q.status.eq("ACTIVE").and(q.deleted.isFalse()));
|
||
}
|
||
```
|
||
|
||
### MapStruct Mapper
|
||
|
||
```java
|
||
@Mapper
|
||
public interface EmployeeMapper {
|
||
Employee toEntity(SaveItem item);
|
||
ListItem toListItem(Employee entity);
|
||
DetailItem toDetailItem(Employee entity);
|
||
}
|
||
|
||
// Controller 中使用
|
||
@Override
|
||
protected Function<SaveItem, Employee> saveItemMapper() {
|
||
return mapper::toEntity;
|
||
}
|
||
```
|
||
|
||
## 实体设计
|
||
|
||
### 字段类型
|
||
|
||
- ID: `Long`（雪花算法）
|
||
- 时间: `LocalDateTime`
|
||
- 金额: `BigDecimal`
|
||
- 枚举: Java enum（存储为字符串）
|
||
- 布尔: `Boolean`
|
||
|
||
### 关联关系
|
||
|
||
```java
|
||
@Entity
|
||
public class Order extends SimpleEntity {
|
||
@ManyToOne
|
||
@JoinColumn(name = "customer_id")
|
||
private Customer customer;
|
||
|
||
@OneToMany(mappedBy = "order", fetch = FetchType.LAZY)
|
||
private List<OrderItem> items;
|
||
}
|
||
```
|
||
|
||
注意：谨慎使用 `@OneToMany`，可能导致 N+1 问题。
|
||
|
||
### 索引
|
||
|
||
```java
|
||
@Entity
|
||
@Table(name = "employee", indexes = {
|
||
@Index(name = "idx_department", columnList = "department_id")
|
||
})
|
||
public class Employee extends SimpleEntity { ... }
|
||
```
|
||
|
||
## 工具类
|
||
|
||
### DatabaseHelper
|
||
|
||
```java
|
||
// 生成 DDL
|
||
DatabaseHelper.generateDDL(
|
||
"com.example.entity", "./sql", MySQL8Dialect.class,
|
||
"jdbc:mysql://localhost:3306/test", "root", "password",
|
||
com.mysql.cj.jdbc.Driver.class
|
||
);
|
||
```
|
||
|
||
### SnowflakeHelper
|
||
|
||
```java
|
||
Long id = SnowflakeHelper.next();
|
||
```
|
||
|
||
## 常见问题
|
||
|
||
**Q: 非 Web 应用如何使用？**
|
||
|
||
A: 不引入 web 依赖，创建 Entity → Repository → Service，直接注入 Service 使用。
|
||
|
||
**Q: 如何实现软删除？**
|
||
|
||
A: 添加 `deleted` 字段，重写 `commonPredicates()` 过滤，覆盖 `remove()` 改为更新。
|
||
|
||
**Q: 如何处理复杂查询？**
|
||
|
||
A: 使用 QueryDSL 或 Repository `@Query` 方法：
|
||
```java
|
||
@Query("SELECT e FROM Employee e WHERE e.departmentId = :deptId")
|
||
List<Employee> findByDepartment(@Param("deptId") Long deptId);
|
||
```
|
||
|
||
**Q: 如何批量插入？**
|
||
|
||
A: `service.save(entities)` 或 `repository.saveAll(entities)`
|
||
|
||
**Q: 查询条件支持关联对象吗？**
|
||
|
||
A: 支持，使用多级路径如 `"department.name"`
|
||
|
||
## 最佳实践
|
||
|
||
1. DTO 设计：SaveItem 可修改字段，ListItem 列表字段，DetailItem 完整字段
|
||
2. 事务：Service 方法已加事务，无需重复
|
||
3. 性能：列表查询避免关联对象，使用投影或 DTO
|
||
4. 代码生成：初期脚手架生成，后期手动调整
|
||
|
||
## 测试用例
|
||
|
||
`src/test/java/.../integration/` |