架构文档(Architecture Documentation)是一个用于创建清晰、全面架构文档的技能,目标是向干系人传达设计决策与系统结构。
【用途与适用时机】 资料列出的使用场景包括:新系统设计、架构变更、团队上手(onboarding)、干系人沟通、技术评审、知识传递、合规要求、决策追踪。
【主要能力与核心概念】
- 架构决策记录(ADR):以结构化方式记录单个架构决策。资料给出的 ADR 示例包含:编号与标题(如“ADR 001: Use PostgreSQL for Primary Database”)、日期、状态(Accepted)、决策者、Context(背景与需求)、Decision(决策)、Alternatives Considered(备选方案及优缺点)、Rationale(理由)、Consequences(正面与负面后果)、Compliance(合规影响)、Notes(备注)。
- 系统架构文档:资料给出的结构包括——Overview(概述)、Architecture Principles(架构原则)、System Context(C4 第 1 层)、Container Diagram(C4 第 2 层,含前端、后端服务、数据存储、消息、外部系统)、Technology Stack(技术栈)、Security(安全)、Scalability(可扩展性)、Disaster Recovery(灾难恢复)、Monitoring & Observability(监控与可观测性)。
【C4 模型与文档组织】 文档使用 C4 模型表达不同层级视图:C4 Level 1 为系统上下文图,C4 Level 2 为容器图。示例系统上下文与容器图以文档描述形式呈现,涵盖用户、系统、外部系统,以及前端(React SPA、移动应用)、后端服务(API 网关、用户服务、商品服务、订单服务、支付服务、通知服务)、数据存储(PostgreSQL、Redis、S3)、消息(EventBridge、SQS)、外部服务(Stripe、SendGrid)等。
【使用方式】 资料以“编写与维护文档”的方式呈现:采用 ADR 模板记录重大决策,用系统架构文档模板组织整体结构,并结合可视化图表(架构图、时序图)表达。资料中未提供安装命令、代码调用或 CLI 使用步骤。
【最佳实践】 资料列出的实践包括:保持文档最新(随变更更新)、提供多视图(不同干系人需要不同层级)、使用可视化图表、记录决策理由(“为什么”而非仅“是什么”)、对重大决策使用 ADR、将文档作为“活文档”随系统演进、纳入版本控制、定期评审(如季度架构评审)。
【资源】 资料列出:C4 Model(https://c4model.com)、ADR Templates(https://adr.github.io)、Structurizr(架构图工具)。
【限制与未提供信息】 资料未说明该技能的具体安装方式、运行环境、支持平台、是否收费或价格、许可协议、自动化生成能力等,这些内容暂未提供。