name: arc42-documentation description: arc42 架构文档模板和指导 allowed-tools: Read, Glob, Grep, Write, Edit

arc42 文档技能

何时使用此技能

使用此技能当：

Arc42 文档任务 - 处理 arc42 架构文档模板和指导
规划或设计 - 需要关于 Arc42 文档方法的指导
最佳实践 - 希望遵循已建立的模式和标准

概述

使用 arc42 模板创建全面的架构文档。

强制性：文档优先方法

在创建 arc42 文档之前：

调用 docs-management 技能 获取架构文档模式
通过 MCP 服务器验证 arc42 当前版本（例如 perplexity）
基于官方 arc42 模板提供指导

arc42 模板结构

arc42 模板（12 个部分）：

┌─────────────────────────────────────────────────────────────────────────────┐
│  1. 引言和目标                                                               │
│     需求概述、质量目标、利益相关者                                           │
├─────────────────────────────────────────────────────────────────────────────┤
│  2. 架构约束                                                                 │
│     技术、组织和惯例约束                                                     │
├─────────────────────────────────────────────────────────────────────────────┤
│  3. 系统范围与上下文                                                           │
│     业务上下文、技术上下文                                                   │
├─────────────────────────────────────────────────────────────────────────────┤
│  4. 解决方案策略                                                               │
│     技术决策、顶级分解、质量方法                                             │
├─────────────────────────────────────────────────────────────────────────────┤
│  5. 构建块视图                                                                 │
│     静态分解：多级别的白盒/黑盒                                               │
├─────────────────────────────────────────────────────────────────────────────┤
│  6. 运行时视图                                                                 │
│     重要场景、交互、行为                                                     │
├─────────────────────────────────────────────────────────────────────────────┤
│  7. 部署视图                                                                   │
│     技术基础设施、构建块的映射                                               │
├─────────────────────────────────────────────────────────────────────────────┤
│  8. 跨领域概念                                                                 │
│     重复模式、方法、原则                                                     │
├─────────────────────────────────────────────────────────────────────────────┤
│  9. 架构决策                                                                   │
│     重要决策及其理由（可链接到 ADRs）                                         │
├─────────────────────────────────────────────────────────────────────────────┤
│ 10. 质量要求                                                                   │
│     质量树、质量场景                                                         │
├─────────────────────────────────────────────────────────────────────────────┤
│ 11. 风险和技术债务                                                             │
│     已知风险、技术债务项                                                     │
├─────────────────────────────────────────────────────────────────────────────┤
│ 12. 术语表                                                                     │
│     重要领域和技术术语                                                       │
└─────────────────────────────────────────────────────────────────────────────┘

完整 arc42 模板

# 架构文档：[系统名称]

**版本：** 1.0
**日期：** [日期]
**状态：** 草稿 | 审查 | 最终

---

## 1. 引言和目标

### 1.1 需求概述

[简要描述系统及其目的。它解决什么业务问题？主要用户是谁？]

**关键特性：**
- [特性 1]
- [特性 2]
- [特性 3]

### 1.2 质量目标

| 优先级 | 质量目标 | 描述 |
|----------|--------------|-------------|
| 1 | [目标] | [描述] |
| 2 | [目标] | [描述] |
| 3 | [目标] | [描述] |

### 1.3 利益相关者

| 角色 | 姓名/团队 | 期望 |
|------|-----------|--------------|
| 产品负责人 | [姓名] | [期望] |
| 开发团队 | [团队] | [期望] |
| 运维 | [团队] | [期望] |
| 安全 | [团队] | [期望] |

---

## 2. 架构约束

### 2.1 技术约束

| 约束 | 描述 | 背景 |
|------------|-------------|------------|
| [TC-1] | [描述] | [为什么存在此约束] |
| [TC-2] | [描述] | [为什么存在此约束] |

### 2.2 组织约束

| 约束 | 描述 | 背景 |
|------------|-------------|------------|
| [OC-1] | [描述] | [为什么存在此约束] |
| [OC-2] | [描述] | [为什么存在此约束] |

### 2.3 惯例

| 惯例 | 描述 |
|------------|-------------|
| [CON-1] | [描述] |
| [CON-2] | [描述] |

---

## 3. 系统范围与上下文

### 3.1 业务上下文

[图表显示系统在其业务环境中的位置，包括与其交互的参与者和外部系统。]

```mermaid
C4Context
    title 系统上下文图

    Person(user, "用户", "系统的最终用户")
    System(system, "系统名称", "系统描述")
    System_Ext(ext1, "外部系统 1", "描述")
    System_Ext(ext2, "外部系统 2", "描述")

    Rel(user, system, "使用")
    Rel(system, ext1, "调用 API")
    Rel(system, ext2, "发送事件")

参与者/系统	描述	通信
[参与者 1]	[描述]	[协议/格式]
[外部系统 1]	[描述]	[协议/格式]

3.2 技术上下文

[集成技术细节：协议、数据格式、接口。]

接口	技术	描述
[API 1]	REST/JSON	[描述]
[队列 1]	Kafka	[描述]
[文件 1]	SFTP/CSV	[描述]

4. 解决方案策略

4.1 技术决策

决策	技术	理由
编程语言	C# (.NET 10)	[理由]
数据库	PostgreSQL	[理由]
消息代理	Kafka	[理由]
云平台	Azure	[理由]

4.2 顶级分解

[系统结构的高级描述。]

方法： [微服务 / 模块化单体 / 等。]

关键模块：

4.3 实现质量目标的方法

质量目标	方法
性能	缓存、异步处理、优化查询
可靠性	冗余、断路器、重试模式
安全	深度防御、加密、审计日志

5. 构建块视图

5.1 级别 1：整体系统白盒

C4Container
    title 容器图

    Container(api, "API 网关", "Kong", "路由和保护 API 调用")
    Container(web, "Web 应用", "Blazor", "用户界面")
    Container(svc1, "服务 1", ".NET", "业务逻辑")
    Container(svc2, "服务 2", ".NET", "业务逻辑")
    ContainerDb(db, "数据库", "PostgreSQL", "存储数据")
    ContainerQueue(queue, "消息队列", "Kafka", "异步消息")

    Rel(web, api, "调用", "HTTPS")
    Rel(api, svc1, "转发", "gRPC")
    Rel(api, svc2, "转发", "gRPC")
    Rel(svc1, db, "读取/写入")
    Rel(svc1, queue, "发布")
    Rel(svc2, queue, "订阅")

包含的构建块：

构建块	目的
API 网关	请求路由、认证、速率限制
Web 应用	用户界面和展示
服务 1	[核心业务功能]
服务 2	[核心业务功能]

5.2 级别 2：[构建块名称]

[特定构建块的白盒描述，显示其内部结构。]

责任： [此块的功能]

接口：

内部结构：

组件	责任
[组件 1]	[描述]
[组件 2]	[描述]

6. 运行时视图

6.1 场景：[用户创建订单]

sequenceDiagram
    participant U as 用户
    participant W as Web 应用
    participant A as API 网关
    participant O as 订单服务
    participant I as 库存服务
    participant D as 数据库
    participant Q as 消息队列

    U->>W: 提交订单
    W->>A: POST /orders
    A->>O: CreateOrder
    O->>I: CheckInventory
    I->>D: 查询库存
    D-->>I: 库存水平
    I-->>O: 可用
    O->>D: 保存订单
    O->>Q: 发布 OrderCreated
    O-->>A: 订单确认
    A-->>W: 201 已创建
    W-->>U: 订单确认

描述： [场景解释和任何重要细节]

6.2 场景：[另一个重要场景]

[类似结构…]

7. 部署视图

7.1 基础设施级别 1

C4Deployment
    title 部署图

    Deployment_Node(cloud, "Azure", "云平台") {
        Deployment_Node(aks, "AKS 集群", "Kubernetes") {
            Container(api, "API Pods", "3 个副本")
            Container(svc, "服务 Pods", "3 个副本")
        }
        Deployment_Node(data, "数据层") {
            ContainerDb(db, "Azure PostgreSQL", "托管数据库")
            ContainerDb(redis, "Azure Redis", "缓存")
        }
    }

7.2 基础设施元素

元素	技术	描述
Kubernetes 集群	AKS	容器编排
负载均衡器	Azure LB	流量分发
数据库	Azure PostgreSQL	持久存储
缓存	Azure Redis	内存缓存

8. 跨领域概念

8.1 领域模型

[核心领域实体及其关系]

8.2 安全

认证： OAuth 2.0 / OpenID Connect 授权： 基于角色的访问控制 (RBAC) 数据保护： 静态加密 (AES-256)、传输中加密 (TLS 1.3)

8.3 错误处理

策略： 带有相关 ID 的结构化错误响应 日志： 带有严重性级别的结构化日志 监控： 使用 OpenTelemetry 的分布式追踪

8.4 可测试性

单元测试： xUnit、Moq、FluentAssertions 集成测试： TestContainers 端到端测试： Playwright

9. 架构决策

ID	决策	状态	日期
ADR-001	[决策标题]	已接受	[日期]
ADR-002	[决策标题]	已接受	[日期]

[链接到详细 ADR 文档]

10. 质量要求

10.1 质量树

mindmap
    root((质量))
        性能
            响应时间
            吞吐量
        可靠性
            可用性
            可恢复性
        安全
            机密性
            完整性
        可维护性
            可修改性
            可测试性

10.2 质量场景

ID	场景	属性	目标
QS-1	负载下的 API 响应	性能	P95 < 200ms
QS-2	系统可用性	可靠性	99.9%
QS-3	添加新支付提供商	可修改性	< 5 天

11. 风险和技术债务

11.1 风险

ID	风险	影响	概率	缓解措施
R-1	[风险描述]	高	中	[缓解措施]
R-2	[风险描述]	中	低	[缓解措施]

11.2 技术债务

ID	债务项	影响	优先级
TD-1	[债务描述]	[影响]	高
TD-2	[债务描述]	[影响]	中

12. 术语表

术语	定义
[术语 1]	[定义]
[术语 2]	[定义]
[术语 3]	[定义]

部分指南

何时包含每个部分

部分	始终包含	包含如果…
1. 引言	✓	-
2. 约束	✓	-
3. 上下文	✓	-
4. 解决方案策略	✓	-
5. 构建块	✓	-
6. 运行时		存在重要场景
7. 部署	✓	-
8. 跨领域	✓	-
9. 决策	✓	-
10. 质量		定义了质量要求
11. 风险		存在已知风险
12. 术语表		有领域特定术语

工作流程

创建 arc42 文档时：

从上下文开始：第 1-3 部分建立“什么”和“为什么”
记录决策：第 4 部分捕捉战略选择
详细结构：第 5 部分展示如何构建
展示行为：第 6 部分演示如何工作
映射到基础设施：第 7 部分展示运行位置
捕捉模式：第 8 部分文档化重复解决方案
记录决策：第 9 部分链接到 ADRs
定义质量：第 10 部分设定期望
承认风险：第 11 部分显示意识
定义术语：第 12 部分确保共享理解

参考文献

详细指导：

最后更新： 2025-12-26