feat: Enhance documentation on layering, object naming conventions, and API design

- Added object naming conventions (PO/DAO/BO/DTO/VO) in 02-layering.md to clarify terminology and usage within the team.
- Updated 06-api-design.md to include MapStruct for DTO and entity conversion, providing examples and configuration details.
- Expanded 07-config-governance.md with local development instructions and strategies for running without K8s, including two recommended approaches.
- Included K8s probe configuration details in 08-observability.md for liveness and readiness checks.
- Clarified CI/CD processes in 09-build-deploy.md, detailing environment distinctions and deployment strategies for local, Dev, UAT, and Prod.
- Introduced ArchUnit for architectural testing in 10-testing.md, ensuring adherence to defined layering rules and coverage verification with Jacoco.
This commit is contained in:
Guangfei.Zhao
2026-08-13 15:19:05 +08:00
parent 1e0cbb86a2
commit 8c0fcd84e8
6 changed files with 518 additions and 30 deletions
+18
View File
@@ -20,6 +20,24 @@ domains/xxx/
- **domain**(可选):领域模型(可以是纯 Kotlin data class,不一定是 JPA entity)、repository/client 接口、封装多步骤业务规则或状态机的领域服务。不依赖 Spring Web/JPA 相关类型,可以脱离容器单独做单元测试。
- **infrastructure**`domain`(或 `application`,跳过 domain 层时)里接口的具体实现——JPA repository 实现、`WebClient`/Feign 外部调用实现。
## 对象命名约定(PO / DAO / BO / DTO / VO
Java 生态里这几个缩写来源不一、经常被混用,这里把我们实际用的名字和这些通用叫法对应清楚,避免团队内部各叫各的:
| 通用叫法 | 全称 | 所在层 | 我们的命名 |
| --- | --- | --- | --- |
| PO | Persistent Object | infrastructure | `XxxEntity`JPA entity,见 [03-persistence.md](./03-persistence.md) |
| DAO | Data Access Object | infrastructure | `XxxJpaRepository`Spring Data JPA repository 接口) |
| BO | Business Object | domain(可选) | `domain` 层的领域模型,如本文 `WebviewTicket` |
| DTO | Data Transfer Object | api | **统称**,不是单独的类;`Request`/`Response` 都是 DTO 的具体形态 |
| VO | View Object | api | `Xxx*Response`,即返回给前端的对象 |
落地规则:
- **类名统一用 `Request`/`Response` 后缀**,不额外起 `XxxDTO`/`XxxVO` 这样的名字——`Request`/`Response` 已经把方向(输入/输出)表达清楚了,`DTO`/`VO` 只是这两者的统称,没必要在类名上重复。
- **`domain` 层模型(BO)不是必须的**,规则见下一节;没有 `domain` 层时,`Entity`PO)直接由 `application`/`api` 层转换成 `Response`,不会凭空多出一个 BO。
- **`Entity`PO)永远不跨出 `infrastructure` 层**`api`/`application` 看到的最多是 `domain` 层模型或 `Response`,见 [06-api-design.md](./06-api-design.md) 里 `Entity → Response` 的 MapStruct 转换约定。
## 何时可以跳过 domain 层
- **可以跳过**:简单 CRUD、没有跨 repository 协调、没有状态机——`application` 直接依赖 `infrastructure` 里定义的 repository/client 接口即可(接口和实现放在同一层)。