nestjs-hexagonal：基于Claude Code的NestJS六边形架构开发插件

专为Claude Code设计的NestJS插件，支持领域驱动设计（DDD）、命令查询职责分离（CQRS）、端口与适配器模式，通过10个技能和8个智能体实现清洁架构工作流。

背景：企业级Node.js应用的架构挑战\n\nNestJS作为Node.js生态中最受欢迎的企业级框架，提供了模块化、依赖注入、装饰器等现代开发特性。然而，随着应用规模增长，许多团队面临一个共同问题：业务逻辑与技术实现紧密耦合，导致代码难以测试、修改和演进。\n\n六边形架构（Hexagonal Architecture）、领域驱动设计（DDD）和CQRS等模式为解决这些问题提供了理论指导，但在实际项目中落地往往需要大量样板代码和严格的规范约束。nestjs-hexagonal项目正是为解决这一痛点而生——它是一个Claude Code插件，通过AI智能体辅助开发者以正确的方式构建清洁架构的NestJS应用。\n\n## 核心理念：六边形架构与清洁架构\n\nnestjs-hexagonal的设计深受六边形架构（又称端口与适配器架构）和清洁架构（Clean Architecture）影响，其核心理念是将业务逻辑置于应用中心，外部依赖（Web框架、数据库、外部服务）通过明确的接口（端口）与核心交互。\n\n架构层次\n\n\n┌─────────────────────────────────────┐\n│ 外部层 (Adapters) │\n│ ┌─────────┐ ┌─────────┐ ┌────────┐ │\n│ │ 控制器 │ │ 存储库 │ │ 客户端 │ │\n│ │(Controllers)│(Repositories)│(Clients)│ │\n│ └────┬────┘ └────┬────┘ └───┬────┘ │\n│ │ │ │ │\n│ └───────────┼──────────┘ │\n│ ▼ │\n│ 端口 (Ports) │\n│ ┌─────────────────┐ │\n│ │ 应用服务接口 │ │\n│ │ 存储库接口 │ │\n│ │ 外部服务接口 │ │\n│ └────────┬────────┘ │\n└──────────────────┼──────────────────┘\n │\n ▼\n┌─────────────────────────────────────┐\n│ 核心层 (Domain) │\n│ ┌─────────┐ ┌─────────┐ ┌────────┐ │\n│ │ 领域模型 │ │ 领域服务 │ │ 值对象 │ │\n│ │ 聚合根 │ │ 领域事件 │ │ 实体 │ │\n│ └─────────┘ └─────────┘ └────────┘ │\n└─────────────────────────────────────┘\n\n\n这种分层带来显著优势：\n\n- 可测试性：核心业务逻辑不依赖框架或数据库，可用单元测试完全覆盖\n- 可替换性：Web框架或数据库可以更换而不影响业务逻辑\n- 可维护性：清晰的职责分离使代码更易于理解和修改\n\n## 支持的架构模式全景\n\nnestjs-hexagonal不仅支持六边形架构，还整合了多种企业级架构模式：\n\n领域驱动设计（DDD）\n\n插件引导开发者识别领域边界、定义聚合根、实体和值对象，建立统一的领域语言（Ubiquitous Language）。通过有界上下文（Bounded Context）划分，大型应用被分解为可独立演进的模块。\n\n命令查询职责分离（CQRS）\n\n读写操作分离架构：\n- 命令（Commands）：处理写操作，改变系统状态\n- 查询（Queries）：处理读操作，返回数据视图\n\n这种分离允许读模型和写模型独立优化，例如写模型保证数据一致性，读模型针对查询性能优化。\n\n事件驱动架构（Event-Driven）\n\n支持领域事件（Domain Events）的发布和订阅，实现：\n- 跨有界上下文的松耦合通信\n- 事件溯源（Event Sourcing）的基础\n- 最终一致性模型的实现\n\n测试驱动开发（TDD）\n\n插件内置TDD工作流支持，引导开发者先写测试再实现功能，确保代码的可测试性和设计质量。\n\n## 技能与智能体：AI辅助的架构实施\n\nnestjs-hexagonal的核心价值在于通过Claude Code的智能体和技能系统，将抽象的架构原则转化为可执行的开发步骤。\n\n10个核心技能\n\n项目提供10个预定义技能，覆盖常见开发任务：\n\n| 技能类别 | 功能描述 |\n|---------|---------|\n| 功能启动 | 引导新功能的完整开发流程 |\n| 领域建模 | 辅助设计领域模型和聚合 |\n| 命令开发 | 创建命令处理器和验证逻辑 |\n| 查询开发 | 构建查询处理器和DTO |\n| 事件接入 | 设置领域事件和处理器 |\n| 测试编写 | 生成单元测试和集成测试 |\n| 结构检查 | 验证代码符合架构规范 |\n| 代码清理 | 重构和优化建议 |\n\n这些技能不是简单的代码模板，而是理解架构原则的AI助手，能够根据具体场景提供定制化指导。\n\n8个专用智能体\n\n项目配置了8个针对不同任务的智能体，部分基于Claude 3 Opus，部分基于Claude 3 Sonnet：\n\n| 智能体 | 职责 | 模型 |\n|-------|------|------|\n| 规划智能体 | 功能分解和任务规划 | Opus |\n| 代码生成智能体 | 核心代码编写 | Sonnet |\n| 审查智能体 | 代码审查和优化建议 | Opus |\n| 测试智能体 | 测试用例生成 | Sonnet |\n| 领域智能体 | DDD建模指导 | Opus |\n| 事件智能体 | 事件驱动设计 | Sonnet |\n| 上下文智能体 | 有界上下文划分 | Opus |\n\n多智能体协作模拟了真实开发团队的工作流程，每个智能体专注于特定领域，共同完成复杂任务。\n\n## GSD工作流：目标-步骤-交付\n\n项目采用GSD（Goal-Steps-Delivery）风格的工作流，帮助开发者以稳定节奏推进任务：\n\n目标（Goal）\n\n明确定义当前迭代要达成的业务目标，确保技术实现服务于业务价值。\n\n步骤（Steps）\n\n将目标分解为可执行的步骤序列，每个步骤有明确的完成标准。\n\n交付（Delivery）\n\n每个步骤产出可验证的交付物，可能是代码、测试或文档。\n\n这种工作流与敏捷开发理念契合，同时通过AI辅助确保架构规范在每个步骤中得到遵守。\n\n## 项目结构与文件组织\n\nnestjs-hexagonal引导的NestJS项目具有清晰的文件结构：\n\n\nsrc/\n├── contexts/ # 有界上下文\n│ └── order-context/ # 订单上下文示例\n│ ├── domain/ # 领域层\n│ │ ├── models/ # 领域模型\n│ │ ├── services/ # 领域服务\n│ │ └── events/ # 领域事件\n│ ├── application/ # 应用层\n│ │ ├── commands/ # 命令处理器\n│ │ ├── queries/ # 查询处理器\n│ │ └── services/ # 应用服务\n│ ├── infrastructure/ # 基础设施层\n│ │ ├── repositories/ # 存储库实现\n│ │ ├── clients/ # 外部客户端\n│ │ └── config/ # 配置\n│ └── interface/ # 接口层\n│ ├── http/ # HTTP控制器\n│ └── dto/ # 数据传输对象\n└── shared/ # 共享内核\n ├── domain/ # 共享领域概念\n └── infrastructure/ # 共享基础设施\n\n\n这种结构严格遵循依赖规则：\n- 领域层不依赖任何其他层\n- 应用层仅依赖领域层\n- 基础设施层和接口层可以依赖所有内部层\n\n## 典型应用场景\n\nnestjs-hexagonal适用于多种企业级开发场景：\n\n新功能开发\n\n从零开始开发新功能时，插件引导完成：\n1. 识别有界上下文\n2. 设计领域模型\n3. 定义命令和查询\n4. 实现端口和适配器\n5. 编写测试验证\n\n遗留系统重构\n\n将现有NestJS应用重构为清洁架构：\n1. 分析现有代码的领域边界\n2. 逐步提取领域逻辑\n3. 引入端口抽象\n4. 重构为适配器模式\n5. 验证行为一致性\n\n大型应用拆分\n\n将单体应用拆分为有界上下文：\n1. 识别核心领域和支撑领域\n2. 定义上下文映射\n3. 提取独立上下文\n4. 建立上下文间通信\n5. 验证集成点\n\n团队规范落地\n\n在团队中推广架构规范：\n1. 通过智能体确保代码审查一致性\n2. 自动化架构合规检查\n3. 新成员通过AI辅助快速理解规范\n\n## 安装与配置\n\n使用nestjs-hexagonal需要：\n\n环境要求\n\n- Windows 10/11（或其他支持Claude Code的平台）\n- Claude Code已安装并配置\n- NestJS项目（新建或现有）\n\n安装步骤\n\n1. 访问GitHub仓库下载项目文件\n2. 将插件文件复制到项目目录\n3. 按README指引配置Claude Code\n4. 重启Claude Code加载插件\n5. 验证插件功能可用\n\n集成到现有项目\n\n对于已有NestJS项目，可以渐进式引入：\n1. 选择新功能作为试点\n2. 使用插件创建有界上下文\n3. 逐步迁移相关功能\n4. 保持新旧代码边界清晰\n\n## 局限性与注意事项\n\n学习曲线\n\n六边形架构和DDD本身概念较多，初学者可能需要时间理解端口、适配器、聚合根等概念。插件虽提供指导，但仍需开发者主动学习架构原则。\n\n过度设计风险\n\n对于简单CRUD应用，完整六边形架构可能显得冗余。插件更适合中等复杂度以上的业务应用。\n\nClaude Code依赖\n\n插件深度集成Claude Code，需要订阅Anthropic的服务。对于不使用Claude Code的团队，无法直接使用该插件。\n\n生成的代码仍需审查\n\nAI生成的代码虽遵循架构规范，但仍需人工审查确保业务逻辑正确。插件是辅助工具而非替代品。\n\n## 生态定位：Claude Code插件生态的一部分\n\nnestjs-hexagonal是Claude Code插件生态的组成部分。随着AI辅助编程工具的普及，这类专门化的架构插件将成为开发者工具链的重要一环：\n\n- 与通用IDE插件的区别：不仅提供代码片段，更提供架构指导和规范约束\n- 与代码生成器的区别：基于对话交互，可根据具体场景调整输出\n- 与咨询服务的区别：实时可用、成本可控、可重复调用\n\n## 结语：AI辅助的架构实践\n\nnestjs-hexagonal代表了AI辅助软件开发的一个有趣方向：不仅生成代码，更传播架构智慧。通过将六边形架构、DDD、CQRS等成熟模式编码为可执行的AI技能，它降低了这些高级架构模式的采用门槛。\n\n对于NestJS开发者而言，这是一个探索清洁架构的实用工具；对于架构师而言，这是团队赋能的新方式；对于AI辅助编程领域而言，这是从"代码补全"向"知识传递"演进的一次尝试。随着AI能力的提升，我们可以期待更多类似工具出现，帮助开发者在享受技术便利的同时，不丢失架构的优雅与严谨。

背景：企业级Node.js应用的架构挑战\n\nNestJS作为Node.js生态中最受欢迎的企业级框架，提供了模块化、依赖注入、装饰器等现代开发特性。然而，随着应用规模增长，许多团队面临一个共同问题：业务逻辑与技术实现紧密耦合，导致代码难以测试、修改和演进。\n\n六边形架构（Hexagonal Architecture）、领域驱动设计（DDD）和CQRS等模式为解决这些问题提供了理论指导，但在实际项目中落地往往需要大量样板代码和严格的规范约束。nestjs-hexagonal项目正是为解决这一痛点而生——它是一个Claude Code插件，通过AI智能体辅助开发者以正确的方式构建清洁架构的NestJS应用。\n\n核心理念：六边形架构与清洁架构\n\nnestjs-hexagonal的设计深受六边形架构（又称端口与适配器架构）和清洁架构（Clean Architecture）影响，其核心理念是将业务逻辑置于应用中心，外部依赖（Web框架、数据库、外部服务）通过明确的接口（端口）与核心交互。\n\n架构层次\n\n\n┌─────────────────────────────────────┐\n│ 外部层 (Adapters) │\n│ ┌─────────┐ ┌─────────┐ ┌────────┐ │\n│ │ 控制器 │ │ 存储库 │ │ 客户端 │ │\n│ │(Controllers)│(Repositories)│(Clients)│ │\n│ └────┬────┘ └────┬────┘ └───┬────┘ │\n│ │ │ │ │\n│ └───────────┼──────────┘ │\n│ ▼ │\n│ 端口 (Ports) │\n│ ┌─────────────────┐ │\n│ │ 应用服务接口 │ │\n│ │ 存储库接口 │ │\n│ │ 外部服务接口 │ │\n│ └────────┬────────┘ │\n└──────────────────┼──────────────────┘\n │\n ▼\n┌─────────────────────────────────────┐\n│ 核心层 (Domain) │\n│ ┌─────────┐ ┌─────────┐ ┌────────┐ │\n│ │ 领域模型 │ │ 领域服务 │ │ 值对象 │ │\n│ │ 聚合根 │ │ 领域事件 │ │ 实体 │ │\n│ └─────────┘ └─────────┘ └────────┘ │\n└─────────────────────────────────────┘\n\n\n这种分层带来显著优势：\n\n- 可测试性：核心业务逻辑不依赖框架或数据库，可用单元测试完全覆盖\n- 可替换性：Web框架或数据库可以更换而不影响业务逻辑\n- 可维护性：清晰的职责分离使代码更易于理解和修改\n\n支持的架构模式全景\n\nnestjs-hexagonal不仅支持六边形架构，还整合了多种企业级架构模式：\n\n领域驱动设计（DDD）\n\n插件引导开发者识别领域边界、定义聚合根、实体和值对象，建立统一的领域语言（Ubiquitous Language）。通过有界上下文（Bounded Context）划分，大型应用被分解为可独立演进的模块。\n\n命令查询职责分离（CQRS）\n\n读写操作分离架构：\n- 命令（Commands）：处理写操作，改变系统状态\n- 查询（Queries）：处理读操作，返回数据视图\n\n这种分离允许读模型和写模型独立优化，例如写模型保证数据一致性，读模型针对查询性能优化。\n\n事件驱动架构（Event-Driven）\n\n支持领域事件（Domain Events）的发布和订阅，实现：\n- 跨有界上下文的松耦合通信\n- 事件溯源（Event Sourcing）的基础\n- 最终一致性模型的实现\n\n测试驱动开发（TDD）\n\n插件内置TDD工作流支持，引导开发者先写测试再实现功能，确保代码的可测试性和设计质量。\n\n技能与智能体：AI辅助的架构实施\n\nnestjs-hexagonal的核心价值在于通过Claude Code的智能体和技能系统，将抽象的架构原则转化为可执行的开发步骤。\n\n10个核心技能\n\n项目提供10个预定义技能，覆盖常见开发任务：\n\n| 技能类别 | 功能描述 |\n|---------|---------|\n| 功能启动 | 引导新功能的完整开发流程 |\n| 领域建模 | 辅助设计领域模型和聚合 |\n| 命令开发 | 创建命令处理器和验证逻辑 |\n| 查询开发 | 构建查询处理器和DTO |\n| 事件接入 | 设置领域事件和处理器 |\n| 测试编写 | 生成单元测试和集成测试 |\n| 结构检查 | 验证代码符合架构规范 |\n| 代码清理 | 重构和优化建议 |\n\n这些技能不是简单的代码模板，而是理解架构原则的AI助手，能够根据具体场景提供定制化指导。\n\n8个专用智能体\n\n项目配置了8个针对不同任务的智能体，部分基于Claude 3 Opus，部分基于Claude 3 Sonnet：\n\n| 智能体 | 职责 | 模型 |\n|-------|------|------|\n| 规划智能体 | 功能分解和任务规划 | Opus |\n| 代码生成智能体 | 核心代码编写 | Sonnet |\n| 审查智能体 | 代码审查和优化建议 | Opus |\n| 测试智能体 | 测试用例生成 | Sonnet |\n| 领域智能体 | DDD建模指导 | Opus |\n| 事件智能体 | 事件驱动设计 | Sonnet |\n| 上下文智能体 | 有界上下文划分 | Opus |\n\n多智能体协作模拟了真实开发团队的工作流程，每个智能体专注于特定领域，共同完成复杂任务。\n\nGSD工作流：目标-步骤-交付\n\n项目采用GSD（Goal-Steps-Delivery）风格的工作流，帮助开发者以稳定节奏推进任务：\n\n目标（Goal）\n\n明确定义当前迭代要达成的业务目标，确保技术实现服务于业务价值。\n\n步骤（Steps）\n\n将目标分解为可执行的步骤序列，每个步骤有明确的完成标准。\n\n交付（Delivery）\n\n每个步骤产出可验证的交付物，可能是代码、测试或文档。\n\n这种工作流与敏捷开发理念契合，同时通过AI辅助确保架构规范在每个步骤中得到遵守。\n\n项目结构与文件组织\n\nnestjs-hexagonal引导的NestJS项目具有清晰的文件结构：\n\n\nsrc/\n├── contexts/ 有界上下文\n│ └── order-context/ 订单上下文示例\n│ ├── domain/ 领域层\n│ │ ├── models/ 领域模型\n│ │ ├── services/ 领域服务\n│ │ └── events/ 领域事件\n│ ├── application/ 应用层\n│ │ ├── commands/ 命令处理器\n│ │ ├── queries/ 查询处理器\n│ │ └── services/ 应用服务\n│ ├── infrastructure/ 基础设施层\n│ │ ├── repositories/ 存储库实现\n│ │ ├── clients/ 外部客户端\n│ │ └── config/ 配置\n│ └── interface/ 接口层\n│ ├── http/ HTTP控制器\n│ └── dto/ 数据传输对象\n└── shared/ 共享内核\n ├── domain/ 共享领域概念\n └── infrastructure/ 共享基础设施\n\n\n这种结构严格遵循依赖规则：\n- 领域层不依赖任何其他层\n- 应用层仅依赖领域层\n- 基础设施层和接口层可以依赖所有内部层\n\n典型应用场景\n\nnestjs-hexagonal适用于多种企业级开发场景：\n\n新功能开发\n\n从零开始开发新功能时，插件引导完成：\n1. 识别有界上下文\n2. 设计领域模型\n3. 定义命令和查询\n4. 实现端口和适配器\n5. 编写测试验证\n\n遗留系统重构\n\n将现有NestJS应用重构为清洁架构：\n1. 分析现有代码的领域边界\n2. 逐步提取领域逻辑\n3. 引入端口抽象\n4. 重构为适配器模式\n5. 验证行为一致性\n\n大型应用拆分\n\n将单体应用拆分为有界上下文：\n1. 识别核心领域和支撑领域\n2. 定义上下文映射\n3. 提取独立上下文\n4. 建立上下文间通信\n5. 验证集成点\n\n团队规范落地\n\n在团队中推广架构规范：\n1. 通过智能体确保代码审查一致性\n2. 自动化架构合规检查\n3. 新成员通过AI辅助快速理解规范\n\n安装与配置\n\n使用nestjs-hexagonal需要：\n\n环境要求\n\n- Windows 10/11（或其他支持Claude Code的平台）\n- Claude Code已安装并配置\n- NestJS项目（新建或现有）\n\n安装步骤\n\n1. 访问GitHub仓库下载项目文件\n2. 将插件文件复制到项目目录\n3. 按README指引配置Claude Code\n4. 重启Claude Code加载插件\n5. 验证插件功能可用\n\n集成到现有项目\n\n对于已有NestJS项目，可以渐进式引入：\n1. 选择新功能作为试点\n2. 使用插件创建有界上下文\n3. 逐步迁移相关功能\n4. 保持新旧代码边界清晰\n\n局限性与注意事项\n\n学习曲线\n\n六边形架构和DDD本身概念较多，初学者可能需要时间理解端口、适配器、聚合根等概念。插件虽提供指导，但仍需开发者主动学习架构原则。\n\n过度设计风险\n\n对于简单CRUD应用，完整六边形架构可能显得冗余。插件更适合中等复杂度以上的业务应用。\n\nClaude Code依赖\n\n插件深度集成Claude Code，需要订阅Anthropic的服务。对于不使用Claude Code的团队，无法直接使用该插件。\n\n生成的代码仍需审查\n\nAI生成的代码虽遵循架构规范，但仍需人工审查确保业务逻辑正确。插件是辅助工具而非替代品。\n\n生态定位：Claude Code插件生态的一部分\n\nnestjs-hexagonal是Claude Code插件生态的组成部分。随着AI辅助编程工具的普及，这类专门化的架构插件将成为开发者工具链的重要一环：\n\n- 与通用IDE插件的区别：不仅提供代码片段，更提供架构指导和规范约束\n- 与代码生成器的区别：基于对话交互，可根据具体场景调整输出\n- 与咨询服务的区别：实时可用、成本可控、可重复调用\n\n结语：AI辅助的架构实践\n\nnestjs-hexagonal代表了AI辅助软件开发的一个有趣方向：不仅生成代码，更传播架构智慧。通过将六边形架构、DDD、CQRS等成熟模式编码为可执行的AI技能，它降低了这些高级架构模式的采用门槛。\n\n对于NestJS开发者而言，这是一个探索清洁架构的实用工具；对于架构师而言，这是团队赋能的新方式；对于AI辅助编程领域而言，这是从"代码补全"向"知识传递"演进的一次尝试。随着AI能力的提升，我们可以期待更多类似工具出现，帮助开发者在享受技术便利的同时，不丢失架构的优雅与严谨。