1 / 4概念
Layered Architecture
分层架构不是把代码切成四个文件夹,而是让源码依赖只朝一个方向:外层知道内层,内层不知道外层。判断一次分层是否成立,只看一条:把 UI、数据库或框架换掉时,领域代码是否需要修改。
1 概念
1.1 一句话定义
分层架构把系统按职责分成若干层,并规定源码依赖从外层指向内层;内层定义业务规则和抽象接口,外层提供框架、协议、存储等具体实现。Clean Architecture、Hexagonal Architecture 和 Onion Architecture 是这条规则的不同画法。
1.2 它解决什么问题
- 业务规则散落在 Controller、SQL 和前端校验里,改一个规则要改三处。
- 单元测试必须启动数据库或 Web 容器,反馈从毫秒变成秒级。
- 换 ORM、换消息队列、换 Web 框架时,领域代码被一起拖下水。
- 同一个用例被 HTTP、定时任务和消息消费者复用,却没有稳定的调用入口。
分层把“做什么”和“怎么做”分开:用例和领域模型回答做什么,适配器回答怎么做。
1.3 不属于本页的内容
| 主题 | 去哪 |
|---|---|
| 服务拆分、独立部署与数据所有权 | Microservices |
| 限界上下文、聚合与通用语言 | Domain-Driven Design |
| 事件、CQRS 与最终一致性 | Event-Driven Architecture |
| 面向客户端的聚合层 | BFF |
| 依赖注入容器与框架生命周期 | 各语言生态的 Runtime / Toolchain 页 |
1.4 关键术语
| 术语 | 含义 | 容易混淆的点 |
|---|---|---|
| 依赖规则 | 源码依赖只能由外向内 | 不是运行时调用方向 |
| 端口 | 内层定义的抽象接口 | 不是网络端口 |
| 适配器 | 实现端口的外层代码 | 不是设计模式里的 Adapter |
| 用例 | 一次业务动作的编排入口 | 不是 Controller 方法 |
| 领域模型 | 业务概念、规则与不变量 | 不是数据库表结构 |
| DTO | 跨边界传输的数据形状 | 不是领域实体 |
| 组合根 | 在进程入口完成依赖装配的地方 | 不是业务层 |
| 贫血模型 | 只有字段和 getter/setter 的对象 | 不是“简单的领域模型” |
2 机制
2.1 心智模型
把系统想成同心圆:领域模型在最内层,用例包住它,适配器再包一层,框架和进程入口在最外层。箭头只向内。数据库是外层的细节,不是架构的中心;Web 框架也是。
一条可复述的不变量:领域层不 import 框架、数据库、HTTP 或序列化库。如果做不到,说明边界只是目录,不是依赖。
2.2 机制拆解
一次请求的路径:
- 适配器接收 HTTP 请求,完成认证、参数解析和 DTO 转换。
- 适配器调用用例;用例只依赖端口(仓储、消息、时钟、ID 生成器)。
- 用例加载聚合、执行领域行为、保存聚合;事务边界通常由用例或工作单元控制。
- 用例返回结果;适配器把结果映射成响应 DTO。
- 组合根在进程启动时把真实适配器注入用例。
关键在依赖倒置:用例定义 OrderRepository 端口,数据库适配器实现它;用例不 import 数据库驱动。测试时注入内存实现,生产时注入 SQL 实现。
2.3 完整枚举
| 风格 | 分层 | 依赖方向 | 适用 |
|---|---|---|---|
| MVC | Model / View / Controller | Controller 依赖 Model | 表单型 Web、CRUD |
| 三层架构 | 表现层 / 业务层 / 数据层 | 上层依赖下层 | 传统企业应用 |
| Clean Architecture | Entities / Use Cases / Interface Adapters / Frameworks | 由外向内 | 领域复杂、需要隔离框架 |
| Hexagonal | 领域 + 端口 / 适配器 | 适配器依赖端口 | 多入口、多存储 |
| Onion | 领域模型 / 领域服务 / 应用服务 / 基础设施 | 由外向内 | 与 Clean 接近 |
| 垂直切片 | 按用例切分,每片自带层 | 片内自洽 | 功能独立、团队并行 |
2.4 关键数字与量级
| 指标 | 量级 | 说明 |
|---|---|---|
| 单元测试启动 | 毫秒级 | 不启动容器和数据库 |
| 进程内调用开销 | 纳秒到微秒 | 分层本身几乎不增加延迟 |
| 跨层 DTO 映射 | 每次请求 1–3 次 | 过多映射会拖慢并增加维护量 |
| 依赖环 | 0 | 出现即架构退化 |
| 领域层框架 import | 0 | 可用静态检查强制 |
| 单测覆盖率 | 70%–90% | 覆盖业务分支,不追求数字 |
3 实践
3.1 最小示例
// 内层:领域模型 + 端口。不依赖任何框架。
export class Order {
private constructor(
readonly id: string,
private status: 'open' | 'paid' | 'cancelled',
readonly totalCents: number,
) {}
static open(id: string, totalCents: number): Order {
if (totalCents <= 0) throw new Error('total must be positive');
return new Order(id, 'open', totalCents);
}
pay(): void {
if (this.status !== 'open') throw new Error('only open orders can be paid');
this.status = 'paid';
}
}
export interface OrderRepository {
findById(id: string): Promise<Order | null>;
save(order: Order): Promise<void>;
}
// 用例:只依赖端口。
export class PayOrder {
constructor(private readonly orders: OrderRepository) {}
async execute(orderId: string): Promise<void> {
const order = await this.orders.findById(orderId);
if (!order) throw new Error('order not found');
order.pay();
await this.orders.save(order);
}
}
// 外层:内存适配器,测试与本地开发使用。
export class InMemoryOrderRepository implements OrderRepository {
private readonly rows = new Map<string, Order>();
async findById(id: string): Promise<Order | null> {
return this.rows.get(id) ?? null;
}
async save(order: Order): Promise<void> {
this.rows.set(order.id, order);
}
}
// 组合根:在进程入口装配。
const payOrder = new PayOrder(new InMemoryOrderRepository());
await payOrder.execute('order-1');
3.2 常用操作与参数
| 操作 | 命令 / API | 说明 |
|---|---|---|
| 新建用例 | class XxxUseCase { execute(input): Promise<Output> } | 一个业务动作一个入口 |
| 定义端口 | interface XxxRepository | 放在内层,按用例需要设计 |
| 映射 DTO | toDto(domain) / fromDto(dto) | 在适配器层完成,领域层不感知 |
| 注入依赖 | 构造函数注入 | 避免服务定位器和全局单例 |
| 静态检查 | dependency-cruiser / import-linter | 禁止内层 import 外层 |
| 测试 | 注入内存适配器 | 不启动数据库和 Web 容器 |
3.3 标准流程
- 先写用例清单,不先画层。
- 为每个用例定义输入、输出和失败语义。
- 识别用例需要的端口;端口按内层需要设计,不照搬数据库表。
- 写领域模型和不变量,把业务规则放在模型或用例里。
- 实现适配器,在组合根装配。
- 用静态规则守住依赖方向,用单测覆盖不变量和失败分支。
3.4 与相邻技术的组合
- DDD:分层提供依赖方向,DDD 提供限界上下文、聚合和通用语言;两者一起用才不会把领域模型做成贫血 DTO。
- 微服务:每个服务内部仍然需要分层;服务边界由限界上下文决定,不由层决定。
- 事件驱动:用例通过端口发布领域事件,适配器负责把事件送到消息中间件。
- BFF:BFF 属于外层适配器,负责面向客户端的聚合,不应承载领域规则。
3.5 选型维度
| 维度 | 取值 | 影响 |
|---|---|---|
| 领域复杂度 | 低 / 中 / 高 | 低复杂度不值得全套分层 |
| 入口数量 | 1 个 / 多个 | 多入口需要用例层 |
| 存储可替换性 | 会换 / 不会换 | 需要端口隔离 |
| 团队规模 | 小 / 大 | 大团队需要清晰边界 |
| 交付节奏 | 快速原型 / 长期演进 | 原型可先薄,长期要守规则 |
| 测试要求 | 单测为主 / 端到端为主 | 单测为主更需要端口 |
3.6 决策规则
- 领域逻辑超过“读改写”且有多条不变量:上用例层和领域模型。
- 只有 CRUD、没有业务规则:MVC 或三层足够,不要为了架构而架构。
- 有多个入口(HTTP、定时任务、消息):必须把用例抽出来。
- 需要换存储或做契约测试:在用例层定义端口。
- 团队小、交付急:先分层,但只守依赖方向,不追求完整的四层。
3.7 替代方案对比
| 方案 | 优势 | 代价 | 适用 |
|---|---|---|---|
| MVC | 简单、框架原生 | 业务容易堆在 Controller | 表单、管理后台 |
| 三层架构 | 熟悉、上手快 | 业务层容易贫血 | 传统企业应用 |
| Clean / Hexagonal | 领域隔离、可测试 | 映射和端口多 | 复杂领域、长期系统 |
| 垂直切片 | 功能内聚、并行快 | 跨切片复用需要治理 | 功能边界清晰的产品 |
| 事务脚本 | 直接、调试简单 | 规则重复、难演进 | 一次性脚本、小工具 |
3.8 何时不该用
- 页面只是读写一张表:分层会制造空用例和空端口。
- 团队没有静态检查:依赖方向会在三个月内退化。
- 领域模型没有不变量:强行上聚合只会得到带方法的 DTO。
- 交付周期只有几天:先保证可运行,再在真实复杂度出现时补边界。
4 边界
4.1 典型故障
| 症状 | 根因 | 处理 |
|---|---|---|
| 改一个规则要改三层 | 业务规则散落在 Controller、SQL 和前端 | 把规则收回领域模型或用例 |
| 单测必须起数据库 | 用例直接依赖 ORM/驱动 | 在用例层定义仓储端口 |
| 领域层 import 了框架注解 | 依赖方向被破坏 | 用静态规则禁止,迁出注解 |
| 用例之间互相调用 | 缺少应用服务编排 | 抽出共享用例或领域服务 |
| DTO 和领域对象一模一样 | 没有真正的边界 | 按用例定义输入输出,按需映射 |
| 事务跨多个聚合 | 聚合边界划错 | 缩小聚合,改用领域事件/最终一致 |
| 更换数据库牵连业务代码 | 端口没有抽象查询语义 | 端口按用例设计,不照搬表 |
| 循环依赖 | 层内职责不清 | 拆模块,依赖倒置 |
4.2 反模式
| 做法 | 后果 | 替代 |
|---|---|---|
| 为每一层建一个空接口 | 抽象泄漏、维护成本高 | 只为真实替换点建端口 |
| Controller 里写事务和业务 | 规则无法复用 | 用例层承担编排 |
| 领域实体直接序列化给前端 | 内部结构被外部契约锁死 | 出口 DTO |
| 用基类继承复用层代码 | 继承爆炸、隐式耦合 | 组合与领域服务 |
| 把框架当架构 | 框架升级即重构 | 框架放最外层适配器 |
4.3 可观测信号
依赖图里的环、领域层的框架 import 数、单测启动时间、用例覆盖率、变更失败率、跨层修改的提交比例。静态检查(dependency-cruiser、import-linter)应作为 CI 门禁。
4.4 安全 / 性能 / 一致性边界
- 依赖方向是编译期约束:运行时可以跨层调用,但源码依赖不能反向。
- 事务边界:一个用例一个事务;跨聚合的强一致要么缩小聚合,要么改用最终一致。
- 性能:分层本身开销可忽略;真正的成本在 DTO 映射、网络调用和重复查询。
- 安全:认证和授权属于外层适配器;领域层只接收已认证的主体标识,不解析 token。