SuperAPI AI 工具集

clean-architecture

通用与其它

查看项目

更新于 10-15 20:31

技能介绍

用途:把业务规则与框架、数据库、传输层解耦。核心原则是依赖指向内层:domain 不认识 HTTP、SQL 和框架;clean、hexagonal、onion 是同一设计的不同叫法,不要在仓库里并行实现三套,选择一套命名。

分层:Domain 放实体、值对象、不变式,禁止 import web/ORM;Application 放用例(一个命令一个事务),编排 ports;Adapters 放 REST、GraphQL、CLI、UI、sqlx/EF/Prisma、队列;Framework(Gin、Axum、ASP.NET、Nest)只在最外层。依赖方向为 adapter → application → domain,绝不能 domain → Prisma/Gin。

Ports:输出端口如 OrderRepository、Clock、EventPublisher 的 trait/interface;输入端口即用例(PlaceOrder),由 controller 调用。每个 port 与每种技术对应一个 adapter,不要“就这一次”把 SQL 写进用例。

用例:用意图命名(PlaceOrder、CancelShipment),不用 OrderService.do。应用层输入输出不要直接等于数据库行或 JSON DTO,映射放在边界;事务放在 application 或 repository 实现,不放 controller;授权由用例要求身份,所有权规则可放 domain。

测试:用 fake ports 测试用例,这是该架构的价值所在;adapter 用独立的集成测试(DB、HTTP)。若不用 Docker 就测不了用例,说明依赖方向反了。

不适用场景:脚本、50 行 lambda、生成的 CRUD;不要为两个页面建 8 个 .NET 项目。模块内的垂直切片可把某功能的 adapter 与 use case 放一起,但 domain 仍不 import 框架。

反模式:domain 里出现 Entity Framework/Prisma;用例返回 HttpResponse/gin.Context;无第二实现却为每个类建接口(IOrder + Order);一个 DTO 穿过所有层;只在文件夹名上“Clean”。

相关主题:架构决策见 software-architecture,富模型见 ddd,模块见 modular-monolith,读写分离见 cqrs,HTTP 见 api-design 及各栈,持久化属于 adapter。完成标准:domain/application 无需 web/ORM 包即可编译;用例可用 fake 测试;边界处做映射;仓库内命名统一;不引入无测试或演进收益的多余分层。