architecture-design

架构设计

概述

此技能可帮助你设计全面的软件解决方案架构，包括系统组件、技术栈、集成模式、可扩展性策略和部署模型。

核心能力

启用后，此技能可提供：

1. 需求分析与架构规划

   • 分析功能需求和非功能需求
   • 确定架构驱动因素（可扩展性、安全性、性能）
   • 定义系统边界和约束
   • 制定架构目标和成功标准

2. 系统架构设计

   • 设计分层架构
   • 创建微服务和领域驱动设计
   • 设计事件驱动和基于消息的系统
   • 规划无服务器和云原生架构
   • 设计单体、模块化单体或分布式系统

3. 技术栈选择

   • 评估并说明编程语言和框架的选择理由
   • 选择数据库并说明理由（SQL、NoSQL、时序数据库、图数据库）
   • 选择中间件和集成平台（消息队列、API 网关）
   • 选择基础设施和云平台（评估供应商锁定风险）
   • 推荐 CI/CD 和 DevOps 工具
   • 在 ADR 中记录技术决策及考虑过的替代方案
   • 评估团队技能以及新技术的培训需求

4. 架构模式与最佳实践

   • 应用设计模式（MVC、MVVM、Clean Architecture、Hexagonal）
   • 实施集成模式（REST、GraphQL、gRPC、消息队列）
   • 设计可扩展性方案（横向/纵向扩展、缓存、CDN）
   • 实施安全模式（OAuth、JWT、零信任）
   • 应用弹性模式（断路器、重试、舱壁隔离）

5. 文档与交付物

   • 使用 Mermaid 格式创建 C4 模型图（上下文、容器、组件、代码）
   • 生成 Mermaid 图（类图、时序图、部署图）
   • 编写架构决策记录（ADR）
   • 编写技术规范和 API 契约
   • 制定实施路线图和迁移计划

架构设计工作流

遵循以下系统化流程：

步骤 1：探索与需求分析

1. 收集需求

   • 功能需求（功能特性、用例）
   • 非功能需求（性能、可扩展性、安全性）
   • 业务约束（预算、时间安排、合规要求）
   • 技术约束（现有系统、团队技能）

2. 分析架构驱动因素

   • 性能：延迟、吞吐量目标
   • 可扩展性：用户增长、数据量预测
   • 可用性：正常运行时间 SLA、灾难恢复需求
   • 安全性：身份验证、授权、合规要求
   • 可维护性：可测试性、模块化目标

3. 定义系统上下文

   • 确定利益相关者及其需求
   • 梳理外部系统和依赖项
   • 定义系统边界
   • 确定集成点

步骤 2：架构设计

1. 选择架构风格

根据需求和约束进行选择：

单体架构

• 适用于：简单应用、MVP、小型团队、紧迫的截止期限
• 优点：部署简单、一致性强、没有网络开销
• 权衡：扩展能力受限、技术锁定

模块化单体架构

• 适用于：中等复杂度、领域边界清晰的场景
• 优点：组织更清晰、具备一定隔离性、共享基础设施
• 权衡：仍需单次部署，独立扩展能力有限

微服务

• 适用于：大规模场景、多团队、使用不同技术栈的场景
• 优点：可独立扩展和部署、技术灵活
• 权衡：分布式复杂性、网络开销、最终一致性

无服务器架构

• 适用于：事件驱动、负载变化较大、需要快速开发的场景
• 优点：自动扩展、按使用量付费、无需管理基础设施
• 权衡：冷启动、供应商锁定、调试复杂

事件驱动架构

• 适用于：实时处理、松散耦合、高吞吐量的场景
• 优点：可扩展性、灵活性、异步处理
• 权衡：复杂性、最终一致性、调试困难

1. 设计系统组件

定义关键层和组件：

┌─────────────────────────────────┐
│   Presentation Layer            │  UI, Controllers, APIs
├─────────────────────────────────┤
│   Application Layer             │  Use Cases, Orchestration
├─────────────────────────────────┤
│   Domain Layer                  │  Business Logic, Entities
├─────────────────────────────────┤
│   Data Layer                    │  Databases, Caches
├─────────────────────────────────┤
│   Infrastructure Layer          │  External APIs, Services
└─────────────────────────────────┘

1. 定义数据架构

   • 设计数据模型和架构
   • 选择数据库类型（关系型、文档型、图型、时序型）
   • 规划数据分区和分片策略
   • 设计缓存层（Redis、Memcached）
   • 定义数据流和 ETL 流程

2. 设计集成点

   • API 设计（REST、GraphQL、gRPC）
   • 消息队列（Kafka、RabbitMQ、SQS）
   • 事件流架构
   • 身份验证和授权流程
   • 限流和节流策略

步骤 3：编写架构文档

1. 创建架构图

使用 Mermaid 格式的 C4 模型编写完整文档：

• 上下文：系统所处环境及用户和外部系统（使用 Mermaid C4Context）
• 容器：高层技术选择和通信方式（使用 Mermaid C4Container）
• 组件：容器的内部结构（使用 Mermaid C4Component）
• 代码：复杂组件的类图（使用 Mermaid classDiagram）

所有图表都应使用 Mermaid 语法，便于在 Markdown 中进行版本管理和渲染。

1. 编写架构决策记录（ADR）

使用结构化 ADR 记录所有重要决策：

# ADR-001: [Decision Title]

## Status
Proposed | Accepted | Deprecated | Superseded

## Context
[Problem and constraints requiring decision]

## Decision
[Chosen solution and approach]

## Consequences
[Benefits and trade-offs]

完整 ADR 模板：完整结构和示例请参阅 adr-template.md

1. 编写技术规范
   • 系统概述和目标
   • 组件说明和职责
   • API 契约和接口
   • 数据模型和架构
   • 安全和合规措施
   • 部署和运维指南

第 4 步：验证与审查

1. 质量属性评估

   • 性能：响应时间、吞吐量
   • 可扩展性：水平／垂直扩展能力
   • 可用性：容错能力、灾难恢复
   • 安全性：身份验证、授权、加密
   • 可维护性：代码组织、可测试性
   • 成本：基础设施和运营开支

2. 设计验证清单

确保架构已准备好接受审查：

• 已满足所有功能性和非功能性需求
• 已说明架构风格的合理性，并记录权衡
• 已定义可扩展性策略（水平／垂直扩展、容量规划）
• 已实施安全措施（身份验证、授权、加密）
• 已验证数据架构（存储、一致性、复制）
• 已明确集成模式（同步／异步、API、事件）
• 已规划监控和可观测性（指标、日志、追踪、告警）
• 已记录灾难恢复和备份策略（RPO／RTO）
• 已提供成本估算（基础设施、运营、扩展）
• 已针对重大决策创建架构决策记录（ADR）

参考文件

根据具体需求加载参考文件：

• 架构设计流程：在以下情况下参阅 architecture-design-process.md：

  • 需要复杂架构的详细分步指导
  • 按照系统化流程逐一完成各个阶段
  • 需要全面的清单和注意事项

• 架构模式：在以下情况下参阅 architecture-patterns.md：

  • 需要包含优势和权衡的详细模式说明
  • 比较多种架构风格
  • 查找特定模式的实现方式和示例

• 技术栈指南：在以下情况下参阅 technology-stack-guide.md：

  • 评估特定技术或框架
  • 需要有关数据库、语言或云平台的建议
  • 根据特定需求比较技术选项

• 最佳实践：在以下情况下参阅 best-practices.md：

  • 需要设计原则和指南
  • 查找 API 设计标准
  • 需要安全或运营方面的最佳实践

• 设计考量：在以下情况下参阅 design-considerations.md：

  • 评估质量属性（性能、可扩展性、安全性）
  • 需要有关特定架构问题的指导
  • 规划可观测性、弹性或成本优化

• 常见反模式：在以下情况下参阅 common-anti-patterns-to-avoid.md：

  • 检查现有架构中的问题
  • 验证设计决策
  • 需要了解不应该怎么做的示例

• 迁移模式：在以下情况下参阅 migration-patterns.md：

  • 现代化遗留应用
  • 规划迁移策略
  • 需要分阶段迁移或绞杀者无花果模式的相关模式

• 示例：在以下情况下参阅 examples.md：

  • 需要常见场景的完整架构示例
  • 查找真实世界的参考实现
  • 想了解如何在实践中应用模式

• 资源和参考资料：在以下情况下参阅 resources-and-references.md：

  • 需要外部文档链接
  • 查找更多学习资源
  • 需要规范或标准参考

输出格式

请生成清晰、全面的架构文档：

1. 架构概览

   • 系统的目的和范围
   • 关键架构决策及其理由
   • 高层组件图

2. 详细设计

   • 组件说明及职责
   • 数据模型和架构
   • API 规范
   • 集成模式

3. 图表（全部使用 Mermaid 格式）

   • C4 上下文图（Mermaid C4Context）
   • C4 容器图（Mermaid C4Container）
   • 关键流程的时序图（Mermaid sequenceDiagram）
   • 部署图（Mermaid flowchart 或 C4Deployment）

4. 实施路线图

   • 阶段划分及里程碑
   • 依赖关系和顺序安排
   • 资源需求
   • 风险缓解策略

5. 架构决策记录

   • 记录所有重要决策
   • 包含背景、备选方案和权衡