Guangfei.Zhao
1e0cbb86a2
- Introduced integration layer design with Resilience4j for external vendor calls. - Established API design standards with unified response structures and global exception handling. - Defined configuration and service governance using Kubernetes native solutions. - Implemented observability practices including trace ID propagation and structured logging. - Outlined build and multi-environment deployment strategies using Gradle and GitLab CI/CD. - Specified testing strategies across different layers, utilizing JUnit, MockK, Testcontainers, and WireMock.
155 lines
6.3 KiB
Markdown
155 lines
6.3 KiB
Markdown
# 03. 持久层方案
|
||
|
||
## 决策
|
||
|
||
Spring Data JPA + Hibernate 作为默认 ORM，Flyway 做 schema 迁移。
|
||
|
||
选 JPA 而不是 MyBatis-Plus / jOOQ，主要考虑：
|
||
|
||
- Kotlin + Spring Boot 生态里 JPA 是最主流、文档和踩坑资料最多的组合，团队上手成本低。
|
||
- 大部分 domain 模块（`identity-store`、`webview-ticket` 等）都是常规 CRUD + 少量关联查询，JPA 默认能力够用；真的遇到复杂查询，用 `Specification` 或原生 SQL（`@Query(nativeQuery = true)`）兜底，不需要为了少数复杂查询把整个技术栈换成 jOOQ。
|
||
- 如果某个 domain 后续查询复杂度明显上升（比如报表类需求），可以在那个模块单独引入 jOOQ 只处理复杂查询，两者不互斥。
|
||
|
||
## 结构约定
|
||
|
||
```
|
||
platform-persistence/
|
||
BaseEntity # 审计字段：createdAt/updatedAt/createdBy/updatedBy，各 domain entity 继承
|
||
PageResult<T> # 统一分页返回封装
|
||
JpaAuditingConfig # 开启 Spring Data JPA Auditing
|
||
|
||
domains/xxx/
|
||
src/main/kotlin/.../xxx/infrastructure/persistence/
|
||
XxxEntity # JPA entity
|
||
XxxJpaRepository # : JpaRepository<XxxEntity, Long>
|
||
src/main/resources/db/migration/xxx/
|
||
V1__init.sql # Flyway migration，按 domain 分子目录
|
||
```
|
||
|
||
## `BaseEntity` 示例
|
||
|
||
```kotlin
|
||
// platform-persistence/src/main/kotlin/.../BaseEntity.kt
|
||
@MappedSuperclass
|
||
@EntityListeners(AuditingEntityListener::class)
|
||
abstract class BaseEntity {
|
||
@CreatedDate
|
||
@Column(nullable = false, updatable = false)
|
||
var createdAt: Instant = Instant.EPOCH
|
||
|
||
@LastModifiedDate
|
||
@Column(nullable = false)
|
||
var updatedAt: Instant = Instant.EPOCH
|
||
|
||
@CreatedBy
|
||
@Column(updatable = false, length = 64)
|
||
var createdBy: String? = null
|
||
|
||
@LastModifiedBy
|
||
@Column(length = 64)
|
||
var updatedBy: String? = null
|
||
}
|
||
|
||
// platform-persistence/src/main/kotlin/.../JpaAuditingConfig.kt
|
||
@Configuration
|
||
@EnableJpaAuditing(auditorAwareRef = "auditorAware")
|
||
class JpaAuditingConfig {
|
||
@Bean
|
||
fun auditorAware(): AuditorAware<String> = AuditorAware {
|
||
Optional.ofNullable(StoreContextHolder.currentUserIdOrNull()?.toString())
|
||
}
|
||
}
|
||
```
|
||
|
||
`auditorAware` 直接读 [04-security-auth.md](./04-security-auth.md) 里的 `StoreContextHolder`，避免每个 domain 各写一份"当前操作人是谁"的逻辑。
|
||
|
||
## Entity + Repository + Migration 示例（`identity-store` 里的门店表）
|
||
|
||
```kotlin
|
||
// infrastructure/persistence/StoreEntity.kt
|
||
@Entity
|
||
@Table(name = "store", schema = "identity_store")
|
||
class StoreEntity(
|
||
@Id @GeneratedValue(strategy = GenerationType.IDENTITY)
|
||
val id: Long = 0,
|
||
|
||
@Column(nullable = false, length = 128)
|
||
var name: String,
|
||
|
||
@Column(name = "code", nullable = false, unique = true, length = 32)
|
||
var code: String,
|
||
|
||
@Enumerated(EnumType.STRING)
|
||
@Column(nullable = false, length = 16)
|
||
var status: StoreStatus,
|
||
) : BaseEntity()
|
||
|
||
@Repository
|
||
interface StoreJpaRepository : JpaRepository<StoreEntity, Long> {
|
||
fun findByCode(code: String): StoreEntity?
|
||
fun findByStatus(status: StoreStatus): List<StoreEntity>
|
||
}
|
||
```
|
||
|
||
```sql
|
||
-- src/main/resources/db/migration/identity_store/V1__init.sql
|
||
create schema if not exists identity_store;
|
||
|
||
create table identity_store.store (
|
||
id bigint generated always as identity primary key,
|
||
name varchar(128) not null,
|
||
code varchar(32) not null unique,
|
||
status varchar(16) not null,
|
||
created_at timestamp not null,
|
||
updated_at timestamp not null,
|
||
created_by varchar(64),
|
||
updated_by varchar(64)
|
||
);
|
||
```
|
||
|
||
Flyway 版本号（`V1`、`V2`…）在同一个 schema 目录下按提交顺序递增，不同 domain 目录之间的版本号互相独立，互不干扰。
|
||
|
||
## 跨 domain 数据访问规则
|
||
|
||
**每个 domain 独立 schema**：即使同一个数据库实例，各 `domains/*` 的表也归属各自 schema，不允许跨 domain 直接 `join` 表——需要数据时通过对方模块暴露的 `application` 层接口调用，保持模块边界（即使将来要拆分微服务，DB 层面也不用重新拆分）。
|
||
|
||
```kotlin
|
||
// 错误示范：workbench 直接 join identity_store 的表
|
||
@Query("""
|
||
select w from WorkbenchTileEntity w
|
||
join StoreEntity s on s.id = w.storeId -- 跨 schema 直接 join，禁止
|
||
""")
|
||
fun findTilesWithStoreInfo(): List<WorkbenchTileEntity>
|
||
|
||
// 正确做法：workbench 通过 identity-store 暴露的接口获取门店信息
|
||
@Service
|
||
class WorkbenchAppService(
|
||
private val storeQueryService: StoreQueryService, // identity-store 模块对外暴露的接口
|
||
private val tileRepository: WorkbenchTileRepository,
|
||
) {
|
||
fun listTiles(userId: Long): List<TileResponse> {
|
||
val stores = storeQueryService.listStoresByUserId(userId) // 走 application 层调用，不查表
|
||
val tiles = tileRepository.findByUserId(userId)
|
||
return buildTiles(tiles, stores)
|
||
}
|
||
}
|
||
```
|
||
|
||
## 附录：为什么坚持"每个 domain 独立 schema"
|
||
|
||
模块化单体最容易被破坏的地方就是数据库——代码层面 Gradle 依赖规则挡住了跨 domain import 类，但如果两个 domain 的表都在同一个 schema 下，写 SQL 的时候很容易"顺手 join 一下"，这条规则完全不受编译器约束，只能靠约定。所以我们把 schema 拆开：`workbench` 的 `DataSource` 配置的默认 schema 是 `workbench`，即使有人手滑写了一条跨 schema 的 join，大概率会因为找不到表或者权限问题直接报错，把"容易被绕开的软约束"变成"大概率会失败的硬约束"。
|
||
|
||
代价是：如果确实需要跨 domain 做一次性数据修复或报表查询，不能简单写 SQL join，要么走各自暴露的接口拼装，要么走专门的数据同步/报表管道——这是有意为之的摩擦，用来保护长期的模块边界。
|
||
|
||
## 待补充
|
||
|
||
- 具体数据库选型（PostgreSQL/MySQL）和实例划分方式（同实例多 schema，还是多实例）。
|
||
- 复杂查询是否引入 QueryDSL/jOOQ（`Specification` 不够用时再决定）。
|
||
- 各 domain 的实际表结构，等开发到对应模块时再补。
|
||
|
||
## 参考链接
|
||
|
||
- [Spring Data JPA 官方文档](https://docs.spring.io/spring-data/jpa/reference/)
|
||
- [Flyway 官方文档](https://documentation.red-gate.com/fd)
|
||
- [Spring Data JPA Auditing](https://docs.spring.io/spring-data/jpa/reference/auditing.html)
|