Night Market 技能 — 来源于 claude-night-market/archetypes。如需获得包含智能体（agents）、钩子（hooks）和命令（commands）的完整体验，请安装 Claude Code 插件。

六边形架构（端口与适配器）范式

适用场景

• 将业务逻辑与外部依赖隔离
• 系统需要可替换的适配器以支持测试

不适用场景

• 无外部依赖的小型脚本或工具
• 原型开发阶段，此时引入端口/适配器抽象会带来额外开销

应采用该范式的时机

• 当预判数据库、框架或用户界面将频繁变更，而需确保核心领域逻辑保持稳定时。
• 当对核心应用进行测试需模拟复杂或响应缓慢的基础设施组件时。
• 当开发团队需为第三方集成提供清晰的入站（inbound）与出站（outbound）接口时。

落地实施步骤

1. 定义领域端口（Domain Ports）：识别所有与核心领域模块的交互点。定义入站“驱动端口”（driver ports），用于承载发起操作的参与者（例如 UI、CLI、自动化任务）；并定义出站“被驱动端口”（driven ports），用于承载应用所依赖的服务（例如数据库、消息总线、外部 API）。将这些端口明确定义为形式化接口。
2. 在系统边界实现适配器（Adapters）：针对每种外部技术，创建一个实现对应端口接口的“适配器”。确保核心领域模块完全不感知适配器中所使用的具体框架或库。
3. 聚合用例（Aggregate Use Cases）：将应用功能组织为围绕业务能力构建的服务。这些服务通过已定义的端口协调调用领域逻辑。
4. 实施契约测试（Contract Testing）：验证每个适配器是否严格遵守其所实现端口的约定。使用契约测试（contract tests）或消费者驱动的契约测试（consumer-driven contract tests）来确认该行为。
5. 强制执行依赖规则：最关键的规则是——仅适配器模块可依赖外部框架。可通过自动化架构测试或静态分析规则强制落实该约束。

关键交付物

• 一份架构决策记录（ADR），正式命名各端口、其对应适配器及依赖策略。
• 一组端口接口定义，随核心领域模块一同存储。
• 为每个适配器配备的契约测试套件，并辅以领域模块与应用服务的单元测试。
• 展示入站与出站数据流向的架构图，供运维团队与架构评审人员使用。

风险与应对措施

• 端口/接口膨胀（Port/Interface Bloat）：
  • 应对措施：端口数量过多会增加维护成本。应将相关操作聚合成更内聚、更高层级的端口，通常按领域聚合（domain aggregates）进行组织。
• 抽象泄漏（Leaky Abstractions）：
  • 应对措施：若某端口接口暴露了传输层细节（例如 HTTP 头部），即构成“抽象泄漏”。应重构该接口，改用以领域为中心的数据传输对象（DTO）。
• 适配器漂移（Adapter Drift）：
  • 应对措施：适配器可能与其所封装的外部技术（例如数据库 Schema 变更）逐渐脱节。应定期、自动地校验适配器一致性，例如验证 SQL 迁移脚本是否仍满足持久化端口（persistence port）的预期。

具体组件

以下术语指代该范式落地时出现的具体工具与抽象概念。它们并非强制依赖项，也不属于该技能的 tools: 前置元数据字段（该字段专用于限定 Claude Code 工具调用范围）。请在架构讨论中参考此列表以明确术语含义。

• boundary-validator —— 校验每个适配器是否符合其所实现端口的契约
• adapter-generator —— 根据端口规范生成主/次适配器脚手架
• contract-tester —— 通过共享契约测试，验证每个适配器是否满足其对应端口的要求