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:
@@ -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 接口即可(接口和实现放在同一层)。
|
||||
|
||||
Reference in New Issue
Block a user