{
  "id": "hexagonal-architecture",
  "title": "六边形架构",
  "lang": "zh-Hans",
  "source_lang": "en",
  "summary": "六边形架构通过端口和适配器将应用核心的业务行为与外部技术隔离，使其能够独立开发和测试。",
  "category": "computer-science",
  "subcategory": "software",
  "type": "concept",
  "aliases": [
    "端口与适配器架构",
    "端口适配器架构"
  ],
  "generated_at": "2026-11-04",
  "model": "pro/gpt-6.1-sol",
  "url": "https://aiwiki.page/zh/hexagonal-architecture/",
  "translations": {
    "en": {
      "url": "https://aiwiki.page/en/hexagonal-architecture/",
      "json": "https://aiwiki.page/en/hexagonal-architecture.json"
    }
  },
  "sections": [
    {
      "heading": "",
      "text": "六边形架构是一种软件架构模式，将应用的核心行为与用户、外部系统及基础设施同应用交互时所采用的技术分离。应用通过端口和适配器跨越自身边界进行通信：端口描述具有明确目的的交互，适配器则将这些交互转换为特定技术或外部接口所需的形式。其核心目标是让应用行为的开发和测试不依赖于特定的用户界面、数据库或部署环境。"
    },
    {
      "heading": "起源与术语",
      "text": "阿利斯泰尔·科伯恩（Alistair Cockburn）于 2005 年提出六边形架构，也称为端口与适配器架构。这一方案旨在解决一个反复出现的问题：业务逻辑与用户界面代码或持久化机制相互纠缠，导致应用难以脱离这些机制独立测试。\n\n六边形只是一种图示惯例，并不要求系统必须有六个组件、六个层次或六个接口。这种形状为绘制多种外部交互留出了空间，也不会让人误以为应用只有上、中、下三部分。真正重要的区别在于内部与外部：内部承载应用行为，外部负责与特定技术相关的交互。\n\n这种架构不绑定任何特定的编程语言、框架或部署模型。它既可用于组织单个可执行程序，也可用于模块化应用或单个服务。"
    },
    {
      "heading": "核心结构",
      "text": "应用核心\n\n应用核心包含那些在外部技术变化后仍应保持意义的行为。根据系统的不同，这些行为可能包括业务规则、领域对象、业务不变量的校验，以及应用用例的编排。\n\n例如，订单处理核心可以判断订单是否允许提交、计算订单总额，并协调库存预留。它不应需要了解 HTTP 路由、数据库连接配置或支付服务商的专有消息格式。\n\n这一模式并不规定唯一的内部组织方式。核心可以划分为独立的领域层和应用层，但这种划分是额外的设计选择，而不是六边形图示所要求的结构。\n\n端口\n\n端口定义跨越应用边界的一组内聚交互。它描述应用向外部参与者提供什么，或应用需要外部提供什么能力。\n\n端口通常分为两类：\n\n- 驱动端口、主端口或入站端口：暴露供外部参与者发起应用行为的操作，例如提交订单或查询账户余额。\n- 被驱动端口、次端口或出站端口：描述应用所使用的能力，例如检索已存储的订单、发送通知或获取当前时间。\n\n不同实现使用的术语有所不同。“入站”和“出站”描述的是由哪一方负责发起交互，而不是每条消息或每个返回值的传递方向。\n\n端口是一种架构契约，而不是网络端口。它可以表示为编程语言接口、函数签名、一组操作或消息传递契约，不必与某个类、端点或外部系统一一对应。\n\n适配器\n\n适配器将端口连接到具体的外部机制。它负责转换数据表示和交互方式，同时将特定技术的细节留在核心之外。\n\n驱动适配器可以是：\n\n- 将 超文本传输协议请求转换为应用操作的 Web 控制器。\n- 调用同一操作的命令行界面。\n- 将传入消息转换为应用命令的消息消费者。\n- 直接执行用例的测试工具。\n\n被驱动适配器可以使用关系数据库实现持久化、调用外部支付服务，或提供用于测试的内存替代实现。\n\n多个适配器可以服务于同一个端口。例如，通知端口可以同时具有电子邮件和短信实现，前提是两者都满足该端口要求的行为。"
    },
    {
      "heading": "依赖方向与执行流程",
      "text": "一个核心实现原则是：核心不应依赖具体的外部适配器。外部机制应依赖由应用需求定义或与这些需求相匹配的契约。\n\n这通常通过依赖倒置原则实现。应用服务不直接导入特定的数据库客户端，而是依赖订单仓储之类的抽象，再由数据库适配器实现这一抽象。\n\n因此，执行流程与源代码依赖是两回事：\n\n- Web 适配器调用应用操作。\n- 应用调用出站仓储端口。\n- 具体的仓储适配器执行数据库操作。\n- 结果沿相同的边界返回。\n\n尽管执行流程从核心进入数据库适配器，核心的源代码却不必引用适配器的实现。\n\n依赖注入是在启动时提供具体适配器的常见方式，但并不要求使用依赖注入框架。普通的构造函数参数、函数参数或显式组装代码都可以建立相同的关系。完成组装的位置通常称为组合根。"
    },
    {
      "heading": "示例：下单",
      "text": "订单应用可以定义如下边界：\n\n元素 | 职责\n入站端口：PlaceOrder | 接受下单请求并返回应用层面的结果\n应用服务 | 协调校验、库存预留和订单持久化\n领域对象 | 强制执行业务中的订单规则，并限制允许的状态变更\n出站端口：OrderRepository | 检索和存储订单\n出站端口：Inventory | 请求预留库存\nHTTP 适配器 | 将请求和响应与应用的输入和输出相互转换\n数据库适配器 | 实现订单持久化\n库存服务适配器 | 将库存预留请求转换为外部服务使用的协议格式\n\nHTTP 适配器处理请求解析、状态码等传输细节。核心判断订单是否有效。数据库适配器负责查询、存储映射以及数据库特有的故障处理。\n\n测试可以配合内存适配器调用 PlaceOrder。其他驱动适配器（例如批量导入流程）也可以调用同一操作，而不必重复实现下单规则。\n\n这种分离并不意味着外部系统可以自动互换。替代实现必须满足端口的行为契约，包括相关的一致性、故障处理和性能预期。"
    },
    {
      "heading": "测试",
      "text": "独立测试是采用六边形架构的核心动机之一。无需启动 Web 服务器、连接生产数据库或联系外部服务，就可以测试业务行为。\n\n不同测试验证不同的性质：\n\n- **单元测试**检查领域行为或应用行为中的小块逻辑。\n- 应用级测试通过入站端口驱动应用，并用行为可控的实现替代出站端口的实际实现。\n- **集成测试**在真实基础设施或具有代表性的外部环境中检查具体适配器。\n- 契约测试检查适配器是否满足约定的交互与行为预期。\n- 端到端测试检查组装完成的应用中选定的完整执行路径。\n\n测试替身很有用，但如果其行为与真实基础设施不同，就可能让人产生错误的信心。例如，内存仓储可能无法再现唯一性约束、并发更新或数据库事务的行为。六边形架构使隔离更容易，但并不能免除对外部集成的测试。"
    },
    {
      "heading": "与其他架构方法的关系",
      "text": "分层架构\n\n传统分层设计通常将表现层、业务逻辑层和持久化层绘制为垂直堆栈。六边形架构则强调内外边界：表现机制和持久化机制都位于应用行为之外。\n\n这两种方法并不互斥。只要业务代码不依赖具体基础设施，分层实现也可以遵循六边形架构的原则。\n\n领域驱动设计\n\n领域驱动设计关注围绕业务领域建立软件模型，并定义恰当的模型边界。六边形架构关注应用如何与其环境交互。两者相辅相成，但任何一方都不以另一方为前提。应用不需要拥有丰富的领域对象模型，也可以使用端口与适配器。\n\n洋葱架构与整洁架构\n\n洋葱架构和整洁架构同样致力于使核心策略独立于外部机制。它们提供了更明确的同心层次结构和依赖规则。这些方法与六边形架构密切相关，但并非完全同义。\n\n微服务\n\n六边形架构不是微服务的同义词。服务可以在内部使用端口与适配器，单体应用也同样可以。这一模式不决定部署边界、服务发现或服务间通信。"
    },
    {
      "heading": "应用与局限",
      "text": "当业务行为需要通过多种接口访问、外部集成会随时间变化，或大量应用测试需要脱离基础设施独立运行时，这一模式尤其适用。\n\n它的主要成本是额外的契约、转换代码，以及持续遵守架构约束的要求。对于业务行为较少的小型应用，为每个操作都引入接口和适配器，可能只会增加间接层，而没有相应收益。有效的端口应体现有意义的应用交互，而不是机械地包装每一次库调用。\n\n边界设计也涉及一些权衡：\n\n- **外部表示泄漏：**通过端口暴露数据库特有的对象或传输机制特有的响应类型，即使目录结构看似分离，仍会使核心与基础设施耦合。\n- **过度泛化的契约：**试图支持所有可能的数据库或服务提供方，可能产生表达能力不足或不必要地复杂的抽象。\n- **事务边界：**将持久化隔离在端口之后，并不能决定如何协调需要原子完成的变更。事务由谁管理以及提供何种一致性保证，仍需明确设计。\n- **分布式故障：**适配器无法隐藏延迟、部分失败、重试和重复投递的所有影响。在相关场景中，应用行为必须考虑幂等性和恢复机制。\n- **适配器之间的语义差异：**两个方法签名完全相同的实现，在顺序、持久性或一致性方面可能有所不同。这些差异可能影响正确性。\n- **框架耦合：**即使代码被组织在不同的包中，持久化注解、框架基类和基础设施异常类型仍可能将依赖引入核心。\n\n因此，六边形架构首先是一种管理依赖和变化的方法。它本身并不能确保安全性、可扩展性、容错性或正确性；这些性质都需要额外的设计与验证。"
    }
  ],
  "links": [
    "software-architecture",
    "programming-language",
    "hypertext-transfer-protocol",
    "relational-database",
    "source-code",
    "database-transaction",
    "idempotence"
  ],
  "sources": [],
  "license": "https://creativecommons.org/licenses/by/4.0/"
}