Skip to content

约 4 分钟阅读

六边形架构(Hexagonal Architecture) ​

六边形架构又称端口与适配器架构。它把用例和业务规则放在应用内部,把 HTTP、数据库、支付 SDK 等技术接入放在外部。端口描述应用提供或需要的能力,适配器完成协议、数据和错误的转换。六条边没有数量含义,端口也不必恰好有六个。

调用方向与代码依赖分开的端口适配器图

用订单导出理解两种端口 ​

运营人员从网页导出订单,夜间定时任务也要生成相同报表。两者应调用同一个 RequestOrderExport 用例,而不是各写一遍租户校验、时间范围和任务创建规则。网页控制器和定时任务是驱动适配器:将外部输入转成命令并调用输入端口;用例服务实现这个端口。控制器通常不实现用例接口。

用例要读取订单、保存任务、写出文件,但不应认识某个云存储 SDK。它定义 OrderReader、ExportJobRepository、ExportFileStore 等输出端口,数据库和对象存储适配器实现这些接口。端口中的语言是“保存导出文件并返回标识”,而不是某厂商的 Bucket 请求对象。

这里有两种方向:运行时,用例会调用存储适配器;源码依赖上,存储适配器依赖核心定义的接口。通过装配把实现传入核心,既保留运行能力,也避免核心导入外部 SDK。端口不一定都是 Java 接口,但业务交互契约必须清楚。

把职责放到可定位的位置 ​

text
order-export/
├── application/
│   ├── ExportService.java          # 实现输入端口,编排用例
│   └── port/
│       ├── in/RequestOrderExport.java
│       └── out/ExportFileStore.java
├── domain/ExportJob.java           # 状态、范围和业务规则
├── adapter/
│   ├── in/ExportController.java
│   ├── out/S3ExportFileStore.java
│   └── out/JdbcExportJobRepository.java
└── bootstrap/ExportConfiguration.java  # 创建实现并装配

下面是输出端口的结构片段,省略实现。它明确了幂等标识和返回值,但流的关闭、覆盖、超时及部分上传清理仍需写入契约,不能只凭一个接口名判断替换安全:

java
public interface ExportFileStore {
    StoredFile store(ExportId id, InputStream csv) throws ExportStorageException;
}

public record StoredFile(String key, long sizeBytes, String checksum) {}

存储适配器把 SDK 错误转换为应用能够处理的错误,例如不可重试的权限拒绝、可重试的临时不可用和结果未知。重试次数不能在控制器、用例、SDK 三层无限叠加。若上传成功但响应丢失,要用稳定的导出标识查明或覆盖到同一受控对象,不能每次生成一个永久孤儿文件。

架构边界不替代业务合同 ​

HTTP 适配器负责协议解析和身份提取,用例负责租户授权、业务前提和提交边界,领域模型保护状态规则,存储适配器负责技术协议与资源释放。后台任务也必须经过相同业务检查,不能因为没有 HTTP 请求就绕过权限和状态控制。

数据库事务不会自动覆盖对象存储。可先可靠提交导出任务,再由 Worker 写文件、校验内容、条件更新任务状态;失败时记录重试或清理入口。文件存在而任务更新失败、任务已取消而上传仍在进行,都要单独处理。目录分层不能消除这些中间状态。完整案例见 AI 开发项目实践。

分别验证核心和适配器 ​

验证层次导出案例它不能证明什么
领域与用例测试内存仓储、存储替身,验证权限、状态、范围及失败决策真实 SQL、网络和厂商 SDK 可用
适配器集成测试实际数据库事务、对象存储测试环境,验证编码、异常转换和清理所有业务场景正确
契约验证同一套用例检查内存与生产实现的覆盖、幂等、分页和错误语义环境权限和部署配置正确
关键路径验收请求、Worker、文件下载与撤销,包含超时、重复和取消所有故障自动恢复

内存适配器若不模拟唯一约束和事务回滚,核心测试可能通过而生产失败。替换数据库还涉及隔离级别、查询语义、分页、迁移和性能,并不是新增一个类就能无成本切换。

选型与常见误用 ​

外部依赖多、业务规则需要独立验证或同一用例有多种入口时,端口隔离容易产生收益。简单录入系统可以只对支付、存储等重要边界抽象,不必为每个类建立对应接口。团队尚未厘清业务与技术职责时,先从一个用例建立示范,再扩大范围。

分层与六边形可以组合:前者描述职责组织,后者强调内外边界和依赖方向;DDD 用于业务建模,微服务用于部署与所有权边界,都不是六边形的必选条件。核心中少量框架注解是否可接受,需要按耦合程度判断;真正应检查的是业务行为能否在没有 Web 容器和真实数据库时验证,是否隐式依赖会话、懒加载或 SDK 类型。

落地时沿一次导出请求检查:调用者是否经过同一输入端口,外部类型是否止于适配器,事务是否可定位,错误是否有恢复规则,替身与真实实现是否遵守同一契约。接口数量和包名不作为效果指标。

别急,先让缓存热一下。