设计或重构后端服务时用整洁架构、六边形架构与 DDD…

在从零设计微服务、重构单体、划分限界上下文或排查分层依赖环时，落地 Clean/Hexagonal/DDD 架构模式。

适用场景

解决思路

1. 按 Clean Architecture 划分四层，依赖只能向内：Entities（核心业务模型，不引入任何框架）、Use Cases（应用业务规则，编排实体）、Interface Adapters（控制器、presenter、gateway，在用例与外部格式间转换）、Frameworks & Drivers（UI、数据库、外部服务，位于最外层）。
2. 遵守 Clean Architecture 关键原则：依赖只向内、内层对外层一无所知；业务逻辑独立于框架、数据库与交付机制；跨层边界一律通过抽象接口；无需 UI、数据库或外部服务即可测试。
3. 按 Hexagonal Architecture 组织组件：Domain Core 放无框架的业务逻辑；Ports 定义核心与外界交互的抽象接口（driving 与 driven）；Adapters 提供端口的具体实现（如 PostgreSQL adapter、Stripe adapter、REST adapter）。
4. 利用六边形架构的好处：不改核心即可替换实现（如把 PostgreSQL 换成 DynamoDB）；测试中使用 in-memory adapter，无需 Docker；把技术选型推迟到边缘。
5. 应用 DDD 战略模式：用 Bounded Contexts 为单个子域隔离一致模型，避免全系统共用一个模型；用 Context Mapping 定义上下文关系（Anti-Corruption Layer、Shared Kernel、Open Host Service）；用 Ubiquitous Language 让代码术语与领域专家术语一致。
6. 应用 DDD 战术模式：Entities（有稳定标识、随时间变化）、Value Objects（由属性标识的不可变对象，如 Email、Money、Address）、Aggregates（一致性边界，仅根可从外部访问）、Repositories（持久化与重建聚合，抽象存储机制）、Domain Events（记录领域内已发生的事，用于跨聚合协调）。
7. 需要更细的模式文档与完整示例时，阅读 references/details.md；需要 DDD 限界上下文映射、完整多服务项目树、Anti-Corruption Layer 实现与 Onion Architecture 对比时，阅读 references/advanced-patterns.md。
8. 用 in-memory adapter 做单元测试：为仓储接口实现 InMemoryUserRepository（用字典存储，实现 find_by_id、find_by_email、save、delete），在测试中注入该实现，验证用例成功与重复邮箱被拒等场景，全程不依赖真实数据库、Docker 或网络。
9. 若用例测试需要运行中的数据库，说明业务逻辑泄漏到了基础设施层：把所有数据库调用移到 IRepository 接口之后，测试中注入 in-memory 实现；用例构造函数必须接收抽象端口而非具体类。
10. 若层间出现循环导入（如 use_cases 与 adapters 之间 ImportError），通常是用例导入了具体 adapter 类而非抽象端口；强制规则：use_cases/ 只能从 domain/（实体与接口）导入，绝不能从 adapters/ 或 infrastructure/ 导入。
11. 若领域实体上出现框架装饰器（如 SQLAlchemy Column() 或 Pydantic Field()），实体已不纯；在 adapters/repositories/ 中建立独立 ORM 模型，并在仓储的 _to_entity() 方法中与领域实体互相映射。
12. 若所有逻辑都堆在控制器里，把超出 HTTP 解析与响应格式化的逻辑抽取为用例类；控制器方法只做三件事：解析请求、调用用例、映射响应。
13. 若值对象报错太晚，在 __post_init__（Python）或构造函数中校验不变量，使非法的 Email 或 Money 根本无法被构造，从而在边界而非业务逻辑深处暴露坏数据。
14. 若限界上下文之间发生上下文渗透（如 Order 上下文导入 Identity 上下文的 User 实体），引入 Anti-Corruption Layer：Order 上下文持有自己的轻量 CustomerId 值对象，只通过显式接口调用 Identity 上下文。

适用边界 · 注意事项

• 需要快速原型或一次性脚本、无需长期可维护性与测试隔离时，不必引入完整分层与端口适配器。
• 团队规模很小、领域模型简单且没有多实现替换或跨上下文协调需求时，过度分层会带来不必要的复杂度。
• 尚未确定服务边界或领域语言时，先做领域探索与限界上下文划分，再套用这些结构模式。