421 lines
9.7 KiB
Markdown
421 lines
9.7 KiB
Markdown
|
# 架构决策记录 (ADR) 模板
|
|||
|
|
|
|||
|
|
Architecture Decision Records - 记录技术决策的标准化方法。
|
|||
|
|
|
|||
|
|
## ADR的价值
|
|||
|
|
|
|||
|
|
- **知识传承**：新成员理解历史决策的背景与原因
|
|||
|
|
- **避免重蹈覆辙**：明确为何不选择某些方案
|
|||
|
|
- **决策审计**：追溯技术演进的脉络
|
|||
|
|
- **促进讨论**：结构化的决策流程
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## ADR模板
|
|||
|
|
|
|||
|
|
```markdown
|
|||
|
|
# ADR-[编号]: [决策标题]
|
|||
|
|
|
|||
|
|
- **状态**: [提议 | 已接受 | 已废弃 | 已替代]
|
|||
|
|
- **决策日期**: YYYY-MM-DD
|
|||
|
|
- **决策者**: [姓名/团队]
|
|||
|
|
- **技术领域**: [架构 | 语言 | 框架 | 基础设施 | 安全 | ...]
|
|||
|
|
|
|||
|
|
## 背景
|
|||
|
|
|
|||
|
|
[描述导致此决策的背景、问题或需求。
|
|||
|
|
- 当前面临什么挑战？
|
|||
|
|
- 什么触发了这个决策需求？
|
|||
|
|
- 有什么约束条件？]
|
|||
|
|
|
|||
|
|
## 决策驱动因素
|
|||
|
|
|
|||
|
|
[列出影响决策的关键因素，按优先级排序]
|
|||
|
|
|
|||
|
|
1. [驱动因素1，如：性能需求]
|
|||
|
|
2. [驱动因素2，如：团队技能]
|
|||
|
|
3. [驱动因素3，如：成本预算]
|
|||
|
|
|
|||
|
|
## 考虑的选项
|
|||
|
|
|
|||
|
|
### 选项A: [名称]
|
|||
|
|
|
|||
|
|
**描述**: [简要描述该选项]
|
|||
|
|
|
|||
|
|
**优势**:
|
|||
|
|
- [优势1]
|
|||
|
|
- [优势2]
|
|||
|
|
|
|||
|
|
**劣势**:
|
|||
|
|
- [劣势1]
|
|||
|
|
- [劣势2]
|
|||
|
|
|
|||
|
|
**风险**:
|
|||
|
|
- [风险1]
|
|||
|
|
|
|||
|
|
### 选项B: [名称]
|
|||
|
|
|
|||
|
|
[同上结构]
|
|||
|
|
|
|||
|
|
### 选项C: [名称]
|
|||
|
|
|
|||
|
|
[同上结构]
|
|||
|
|
|
|||
|
|
## 决策
|
|||
|
|
|
|||
|
|
选择 **[选项X]**
|
|||
|
|
|
|||
|
|
### 决策理由
|
|||
|
|
|
|||
|
|
[解释为什么选择这个选项，特别是相对于其他选项的理由。
|
|||
|
|
引用上面列出的驱动因素来支持决策。]
|
|||
|
|
|
|||
|
|
### 权衡取舍
|
|||
|
|
|
|||
|
|
[明确说明这个决策带来的权衡：
|
|||
|
|
- 我们获得了什么
|
|||
|
|
- 我们放弃了什么
|
|||
|
|
- 我们接受了什么风险]
|
|||
|
|
|
|||
|
|
## 后果
|
|||
|
|
|
|||
|
|
### 正面后果
|
|||
|
|
|
|||
|
|
- [预期收益1]
|
|||
|
|
- [预期收益2]
|
|||
|
|
|
|||
|
|
### 负面后果
|
|||
|
|
|
|||
|
|
- [需要承担的成本/风险1]
|
|||
|
|
- [需要承担的成本/风险2]
|
|||
|
|
|
|||
|
|
### 需要的后续行动
|
|||
|
|
|
|||
|
|
- [ ] [行动项1]
|
|||
|
|
- [ ] [行动项2]
|
|||
|
|
|
|||
|
|
## 验证计划
|
|||
|
|
|
|||
|
|
[如何验证这个决策是正确的？
|
|||
|
|
- 关键指标是什么？
|
|||
|
|
- 多久后评估？
|
|||
|
|
- 什么情况下需要重新评估？]
|
|||
|
|
|
|||
|
|
## 相关决策
|
|||
|
|
|
|||
|
|
- [ADR-XXX](./adr-xxx.md) - [关联说明]
|
|||
|
|
- [ADR-YYY](./adr-yyy.md) - [关联说明]
|
|||
|
|
|
|||
|
|
## 参考资料
|
|||
|
|
|
|||
|
|
- [参考链接1]
|
|||
|
|
- [参考链接2]
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## ADR示例
|
|||
|
|
|
|||
|
|
### ADR-001: 采用Go作为后端服务主要语言
|
|||
|
|
|
|||
|
|
```markdown
|
|||
|
|
# ADR-001: 采用Go作为后端服务主要语言
|
|||
|
|
|
|||
|
|
- **状态**: 已接受
|
|||
|
|
- **决策日期**: 2024-03-15
|
|||
|
|
- **决策者**: 技术架构委员会
|
|||
|
|
- **技术领域**: 语言
|
|||
|
|
|
|||
|
|
## 背景
|
|||
|
|
|
|||
|
|
公司正在从单体架构向微服务架构转型。当前主要使用Python和Node.js，
|
|||
|
|
但在高并发场景下遇到性能瓶颈，且运行时资源占用较高。需要为新的
|
|||
|
|
微服务选择一门适合的主要编程语言。
|
|||
|
|
|
|||
|
|
## 决策驱动因素
|
|||
|
|
|
|||
|
|
1. **高并发性能** - 核心服务需要处理10K+ RPS
|
|||
|
|
2. **资源效率** - 降低云资源成本
|
|||
|
|
3. **团队学习曲线** - 现有团队主要是Python/JS背景
|
|||
|
|
4. **生态系统** - 云原生工具链支持
|
|||
|
|
5. **招聘市场** - 人才可获得性
|
|||
|
|
|
|||
|
|
## 考虑的选项
|
|||
|
|
|
|||
|
|
### 选项A: Go
|
|||
|
|
|
|||
|
|
**描述**: Google开发的静态类型编译语言，专为云服务设计
|
|||
|
|
|
|||
|
|
**优势**:
|
|||
|
|
- 编译为单一二进制，部署简单
|
|||
|
|
- 内置并发原语(goroutines)，高并发性能优秀
|
|||
|
|
- 内存占用低，启动快
|
|||
|
|
- Kubernetes/Docker等云原生核心项目均使用Go
|
|||
|
|
- 语法简单，学习曲线相对平缓
|
|||
|
|
|
|||
|
|
**劣势**:
|
|||
|
|
- 泛型支持较晚引入(Go 1.18+)
|
|||
|
|
- 错误处理冗长
|
|||
|
|
- 包管理历史复杂(已通过Go Modules改善)
|
|||
|
|
|
|||
|
|
**风险**:
|
|||
|
|
- 团队需要学习新语言
|
|||
|
|
|
|||
|
|
### 选项B: Rust
|
|||
|
|
|
|||
|
|
**描述**: 系统级编程语言，强调安全性和性能
|
|||
|
|
|
|||
|
|
**优势**:
|
|||
|
|
- 极致性能，与C/C++相当
|
|||
|
|
- 内存安全，无GC暂停
|
|||
|
|
- 强大的类型系统
|
|||
|
|
|
|||
|
|
**劣势**:
|
|||
|
|
- 学习曲线陡峭
|
|||
|
|
- 编译时间长
|
|||
|
|
- 生态系统相对年轻
|
|||
|
|
|
|||
|
|
**风险**:
|
|||
|
|
- 招聘困难
|
|||
|
|
- 开发效率可能受影响
|
|||
|
|
|
|||
|
|
### 选项C: 继续使用Node.js (TypeScript)
|
|||
|
|
|
|||
|
|
**描述**: 保持现有技术栈，优化现有代码
|
|||
|
|
|
|||
|
|
**优势**:
|
|||
|
|
- 团队熟悉，无学习成本
|
|||
|
|
- 前后端统一语言
|
|||
|
|
- NPM生态丰富
|
|||
|
|
|
|||
|
|
**劣势**:
|
|||
|
|
- 单线程模型，高CPU任务受限
|
|||
|
|
- 内存占用相对较高
|
|||
|
|
- 动态语言的类型安全依赖工具链
|
|||
|
|
|
|||
|
|
**风险**:
|
|||
|
|
- 无法根本解决性能问题
|
|||
|
|
|
|||
|
|
## 决策
|
|||
|
|
|
|||
|
|
选择 **Go (选项A)**
|
|||
|
|
|
|||
|
|
### 决策理由
|
|||
|
|
|
|||
|
|
1. **性能与效率平衡**: Go在保持接近C性能的同时，提供远高于脚本语言的开发效率
|
|||
|
|
2. **云原生生态一致性**: Kubernetes、Docker、Prometheus等核心工具均为Go编写，深度集成更顺畅
|
|||
|
|
3. **可接受的学习曲线**: 语法简单，团队可在1-2个月内达到生产力
|
|||
|
|
4. **部署简化**: 单二进制无依赖，容器镜像可压缩至10MB以下
|
|||
|
|
|
|||
|
|
### 权衡取舍
|
|||
|
|
|
|||
|
|
- **获得**: 高性能、低资源占用、简单部署
|
|||
|
|
- **放弃**: 语言表达力(相比Rust)、成熟泛型(相比Java)
|
|||
|
|
- **接受**: 团队学习成本约2个月
|
|||
|
|
|
|||
|
|
## 后果
|
|||
|
|
|
|||
|
|
### 正面后果
|
|||
|
|
|
|||
|
|
- 预计服务内存占用降低60%
|
|||
|
|
- 容器启动时间从5s降至500ms
|
|||
|
|
- 与Kubernetes生态深度集成
|
|||
|
|
|
|||
|
|
### 负面后果
|
|||
|
|
|
|||
|
|
- 需要投入培训资源
|
|||
|
|
- 短期内(3个月)开发效率可能下降
|
|||
|
|
- 部分库需要评估Go生态替代方案
|
|||
|
|
|
|||
|
|
### 需要的后续行动
|
|||
|
|
|
|||
|
|
- [ ] 制定Go编码规范
|
|||
|
|
- [ ] 建立Go服务模板(黄金路径)
|
|||
|
|
- [ ] 组织为期2周的Go培训
|
|||
|
|
- [ ] 选择首个试点项目
|
|||
|
|
|
|||
|
|
## 验证计划
|
|||
|
|
|
|||
|
|
- **关键指标**: P99延迟、内存占用、开发者满意度
|
|||
|
|
- **评估时间**: 首个服务上线后3个月
|
|||
|
|
- **重新评估条件**: 性能未达预期或团队适应困难
|
|||
|
|
|
|||
|
|
## 相关决策
|
|||
|
|
|
|||
|
|
- ADR-002: 选择Gin作为Go Web框架
|
|||
|
|
- ADR-003: 建立Go微服务模板
|
|||
|
|
|
|||
|
|
## 参考资料
|
|||
|
|
|
|||
|
|
- [Go官方性能基准测试](https://golang.org/doc/faq#Performance)
|
|||
|
|
- [TechEmpower框架基准测试](https://www.techempower.com/benchmarks/)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
### ADR-002: 采用ArgoCD作为GitOps部署工具
|
|||
|
|
|
|||
|
|
```markdown
|
|||
|
|
# ADR-002: 采用ArgoCD作为GitOps部署工具
|
|||
|
|
|
|||
|
|
- **状态**: 已接受
|
|||
|
|
- **决策日期**: 2024-04-01
|
|||
|
|
- **决策者**: 平台工程团队
|
|||
|
|
- **技术领域**: 基础设施
|
|||
|
|
|
|||
|
|
## 背景
|
|||
|
|
|
|||
|
|
当前使用Jenkins进行CI/CD，部署流程依赖脚本，存在以下问题：
|
|||
|
|
- 部署状态不透明，需登录集群查看
|
|||
|
|
- 配置漂移(Drift)无法自动检测和修复
|
|||
|
|
- 多环境配置管理复杂
|
|||
|
|
- 回滚操作依赖人工执行
|
|||
|
|
|
|||
|
|
需要引入GitOps实践，以Git仓库作为部署状态的唯一真实来源。
|
|||
|
|
|
|||
|
|
## 决策驱动因素
|
|||
|
|
|
|||
|
|
1. **声明式配置** - 以Git为中心管理集群状态
|
|||
|
|
2. **自动同步** - 检测并自动修复配置漂移
|
|||
|
|
3. **多集群支持** - 管理开发/测试/生产多个集群
|
|||
|
|
4. **可视化** - 提供直观的部署状态Dashboard
|
|||
|
|
5. **与Backstage集成** - 融入现有开发者门户
|
|||
|
|
|
|||
|
|
## 考虑的选项
|
|||
|
|
|
|||
|
|
### 选项A: ArgoCD
|
|||
|
|
|
|||
|
|
**优势**:
|
|||
|
|
- Web UI直观，可视化应用拓扑
|
|||
|
|
- 支持多种配置管理工具(Helm/Kustomize/Jsonnet)
|
|||
|
|
- CNCF毕业项目，社区活跃
|
|||
|
|
- 与Backstage有成熟插件集成
|
|||
|
|
- 支持ApplicationSet实现多环境自动化
|
|||
|
|
|
|||
|
|
**劣势**:
|
|||
|
|
- 需要独立部署和维护
|
|||
|
|
- 学习曲线适中
|
|||
|
|
|
|||
|
|
### 选项B: Flux v2
|
|||
|
|
|
|||
|
|
**优势**:
|
|||
|
|
- 轻量级，模块化设计
|
|||
|
|
- 原生支持Helm Controller
|
|||
|
|
- GitOps Toolkit可组合使用
|
|||
|
|
|
|||
|
|
**劣势**:
|
|||
|
|
- 无内置Web UI(需Weave GitOps)
|
|||
|
|
- 可视化能力弱于ArgoCD
|
|||
|
|
- Backstage集成不如ArgoCD成熟
|
|||
|
|
|
|||
|
|
### 选项C: 继续使用Jenkins
|
|||
|
|
|
|||
|
|
**优势**:
|
|||
|
|
- 团队熟悉
|
|||
|
|
- 无迁移成本
|
|||
|
|
|
|||
|
|
**劣势**:
|
|||
|
|
- 非声明式，难以实现真正的GitOps
|
|||
|
|
- 无法自动检测配置漂移
|
|||
|
|
- 维护成本高
|
|||
|
|
|
|||
|
|
## 决策
|
|||
|
|
|
|||
|
|
选择 **ArgoCD (选项A)**
|
|||
|
|
|
|||
|
|
### 决策理由
|
|||
|
|
|
|||
|
|
1. **可视化优势**: Web UI对开发者友好，降低GitOps学习门槛
|
|||
|
|
2. **Backstage集成**: 官方插件成熟，可无缝嵌入开发者门户
|
|||
|
|
3. **ApplicationSet**: 支持通过模板自动化管理多环境部署
|
|||
|
|
4. **社区活跃**: CNCF毕业项目，长期维护有保障
|
|||
|
|
|
|||
|
|
### 权衡取舍
|
|||
|
|
|
|||
|
|
- **获得**: 声明式部署、自动同步、可视化Dashboard
|
|||
|
|
- **放弃**: Flux的轻量级和模块化
|
|||
|
|
- **接受**: 需要维护ArgoCD本身
|
|||
|
|
|
|||
|
|
## 后果
|
|||
|
|
|
|||
|
|
### 正面后果
|
|||
|
|
|
|||
|
|
- 部署状态实时可见
|
|||
|
|
- 配置漂移自动修复
|
|||
|
|
- 回滚一键完成
|
|||
|
|
- 审计日志完整
|
|||
|
|
|
|||
|
|
### 负面后果
|
|||
|
|
|
|||
|
|
- 需要专人维护ArgoCD
|
|||
|
|
- 现有Jenkins流水线需要迁移
|
|||
|
|
|
|||
|
|
### 需要的后续行动
|
|||
|
|
|
|||
|
|
- [ ] 部署ArgoCD到管理集群
|
|||
|
|
- [ ] 配置SSO集成
|
|||
|
|
- [ ] 迁移现有应用
|
|||
|
|
- [ ] 集成到Backstage门户
|
|||
|
|
- [ ] 制定GitOps规范文档
|
|||
|
|
|
|||
|
|
## 验证计划
|
|||
|
|
|
|||
|
|
- **关键指标**: 部署频率、变更失败率、MTTR
|
|||
|
|
- **评估时间**: 全量迁移完成后1个月
|
|||
|
|
- **重新评估条件**: 运维复杂度过高或性能问题
|
|||
|
|
|
|||
|
|
## 相关决策
|
|||
|
|
|
|||
|
|
- ADR-003: Git仓库结构规范
|
|||
|
|
- ADR-004: 多环境配置管理策略
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## ADR管理最佳实践
|
|||
|
|
|
|||
|
|
### 编号规则
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
ADR-[4位序号]-[可选简短描述]
|
|||
|
|
例如: ADR-0001-go-language.md
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 目录结构
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
docs/
|
|||
|
|
└── adr/
|
|||
|
|
├── README.md # ADR索引
|
|||
|
|
├── adr-0001-xxx.md
|
|||
|
|
├── adr-0002-xxx.md
|
|||
|
|
└── templates/
|
|||
|
|
└── adr-template.md
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### 状态流转
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
提议 (Proposed)
|
|||
|
|
│
|
|||
|
|
├──────────────────┐
|
|||
|
|
▼ ▼
|
|||
|
|
已接受 (Accepted) 已拒绝 (Rejected)
|
|||
|
|
│
|
|||
|
|
├──────────────────┐
|
|||
|
|
▼ ▼
|
|||
|
|
已废弃 (Deprecated) 已替代 (Superseded by ADR-XXX)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
### ADR索引模板
|
|||
|
|
|
|||
|
|
```markdown
|
|||
|
|
# 架构决策记录索引
|
|||
|
|
|
|||
|
|
| 编号 | 标题 | 状态 | 日期 |
|
|||
|
|
|------|------|------|------|
|
|||
|
|
| [ADR-0001](./adr-0001.md) | 采用Go作为后端主要语言 | 已接受 | 2024-03-15 |
|
|||
|
|
| [ADR-0002](./adr-0002.md) | 采用ArgoCD作为GitOps工具 | 已接受 | 2024-04-01 |
|
|||
|
|
| [ADR-0003](./adr-0003.md) | 微服务间通信协议选择 | 提议中 | 2024-04-10 |
|
|||
|
|
```
|