跳到主要内容

架构决策记录（ADR）

概述​

架构决策记录（Architecture Decision Records, ADR）是记录重要架构决策的文档，用于捕获决策背景、决策内容、决策后果等信息。本文档记录了井云服务中心后端系统的关键架构决策。

非常推荐：记录"为什么当初这么选"，避免几年后重复争论。

ADR 格式规范​

ADR 结构​

每个 ADR 包含以下部分：

  • ADR 编号：唯一标识符
  • 标题：简短描述决策内容
  • 状态：提议中/已接受/已弃用/已替代
  • 背景：决策背景和上下文
  • 决策：具体的决策内容
  • 后果：决策带来的影响
  • 实施：实施细节和进度
  • 相关 ADR：相关的其他决策记录

ADR 状态定义​

  • 提议中（Proposed）：决策正在讨论中
  • 已接受（Accepted）：决策已确定并开始实施
  • 已弃用（Deprecated）：决策不再推荐但仍在使用
  • 已替代（Superseded）：决策已被新决策替代

架构决策记录​

ADR-001: 选择 Go + Kratos 微服务架构​

状态：已接受

背景：

  • 项目需要构建一个可扩展、高性能的后端系统
  • 团队具备 Go 语言开发经验
  • 需要支持多租户和微服务架构
  • 要求系统具备良好的可观测性和运维能力

决策：

  • 采用 Go 语言作为主要开发语言
  • 使用 Kratos v2 框架构建微服务架构
  • 采用 gRPC + HTTP 双协议支持
  • 使用 Protobuf 定义 API 接口

后果： 正面影响：

  • Go 语言提供优秀的并发性能
  • Kratos 框架提供完整的微服务工具链
  • gRPC 提供高性能的服务间通信
  • Protobuf 确保接口的类型安全和版本兼容性

负面影响：

  • 团队需要学习 Kratos 框架
  • gRPC 调试相对复杂
  • Protobuf 增加了开发复杂度

实施：

  • ✅ 完成：框架选型和技术验证
  • ✅ 完成：团队培训和技术调研
  • ✅ 完成：基础服务框架搭建
  • 🔄 进行中：服务逐步迁移到新架构

相关 ADR：

  • ADR-002: 数据库选型
  • ADR-003: 服务发现和配置管理

ADR-002: 选择 PostgreSQL 作为主数据库​

状态：已接受

背景：

  • 需要一个支持 ACID 事务的关系型数据库
  • 需要支持 JSON 字段存储灵活配置
  • 要求良好的并发性能和扩展性
  • 需要支持复杂查询和数据分析

决策：

  • 选择 PostgreSQL 17.5 作为主数据库
  • 使用 Ent ORM 进行数据库操作
  • 采用主从复制提高可用性
  • 使用连接池管理数据库连接

后果： 正面影响：

  • PostgreSQL 提供强大的关系型数据库功能
  • JSON 支持灵活的配置存储
  • Ent ORM 提供类型安全的数据库操作
  • 主从复制提供高可用性

负面影响：

  • PostgreSQL 相比 MySQL 学习成本更高
  • Ent ORM 有一定的性能开销
  • 需要额外的数据库维护工作

实施：

  • ✅ 完成：数据库环境搭建
  • ✅ 完成：数据模型设计和实现
  • ✅ 完成：主从复制配置
  • ✅ 完成：备份和恢复策略

相关 ADR：

  • ADR-001: 微服务架构选型
  • ADR-004: 缓存策略

ADR-003: 使用 Consul 进行服务发现和配置管理​

状态：已接受

背景：

  • 微服务架构需要服务注册和发现机制
  • 需要统一的配置管理方案
  • 要求支持动态配置更新
  • 需要服务健康检查功能

决策：

  • 使用 Consul 作为服务注册中心
  • 使用 Consul KV 存储配置信息
  • 实现配置热更新机制
  • 集成健康检查和服务发现

后果： 正面影响：

  • Consul 提供完整的服务治理功能
  • 支持动态配置更新
  • 提供服务健康检查
  • 支持多数据中心部署

负面影响：

  • 增加了系统复杂度
  • Consul 集群需要额外维护
  • 网络分区时可能影响服务发现

实施：

  • ✅ 完成：Consul 集群部署
  • ✅ 完成：服务注册和发现集成
  • ✅ 完成：配置管理实现
  • ✅ 完成：健康检查配置

相关 ADR：

  • ADR-001: 微服务架构选型
  • ADR-005: 消息队列选型

ADR-004: 采用 Redis 作为缓存和会话存储​

状态：已接受

背景：

  • 需要高性能的缓存解决方案
  • 需要分布式会话存储
  • 要求支持多种数据结构
  • 需要高可用性和持久化

决策：

  • 使用 Redis 作为主要缓存
  • 使用 Redis 存储用户会话
  • 采用 Redis 集群提高可用性
  • 实现多级缓存策略

后果： 正面影响：

  • Redis 提供优秀的缓存性能
  • 支持丰富的数据结构
  • 集群模式提供高可用性
  • 减少数据库压力

负面影响：

  • 增加了系统复杂度
  • 缓存一致性问题
  • 内存成本较高
  • 需要额外的运维工作

实施：

  • ✅ 完成：Redis 集群部署
  • ✅ 完成：缓存策略实现
  • ✅ 完成：会话存储集成
  • 🔄 进行中：缓存优化和监控

相关 ADR：

  • ADR-002: 数据库选型
  • ADR-006: 消息队列选型

ADR-005: 选择 RabbitMQ 作为消息队列​

状态：已接受

背景：

  • 微服务间需要异步通信机制
  • 需要可靠的消息传递保证
  • 要求支持消息持久化
  • 需要良好的管理界面和监控

决策：

  • 使用 RabbitMQ 作为消息队列
  • 采用镜像队列提高可用性
  • 实现消息持久化和重试机制
  • 集成监控和管理界面

后果： 正面影响：

  • RabbitMQ 提供成熟的消息队列功能
  • 支持多种消息模式
  • 提供管理界面便于运维
  • 支持消息持久化和重试

负面影响：

  • 增加了系统复杂度
  • 消息延迟可能影响实时性
  • 需要额外的集群维护
  • 消息顺序保证复杂

实施：

  • ✅ 完成：RabbitMQ 集群部署
  • ✅ 完成：消息队列集成
  • ✅ 完成：持久化和重试机制
  • ✅ 完成：监控和管理界面

相关 ADR：

  • ADR-003: 服务发现和配置管理
  • ADR-004: 缓存策略

ADR-006: 采用 JWT 进行身份认证​

状态：已接受

背景：

  • 需要无状态的身份认证方案
  • 支持微服务间的认证传递
  • 要求良好的安全性和性能
  • 需要支持多种登录方式

决策：

  • 使用 JWT Token 进行身份认证
  • 实现访问令牌和刷新令牌机制
  • 支持多种第三方登录
  • 实现令牌黑名单机制

后果： 正面影响：

  • JWT 支持无状态认证
  • 便于微服务间认证传递
  • 支持多种登录方式
  • 提供良好的性能

负面影响：

  • Token 泄露风险
  • 令牌撤销复杂
  • 需要处理令牌过期
  • 增加了认证复杂度

实施：

  • ✅ 完成：JWT 认证实现
  • ✅ 完成：多登录方式集成
  • ✅ 完成：令牌管理机制
  • ✅ 完成：安全加固措施

相关 ADR：

  • ADR-001: 微服务架构选型
  • ADR-012: 安全架构设计

ADR-007: 实现多租户架构​

状态：已接受

背景：

  • 业务需要支持多租户模式
  • 要求租户间数据完全隔离
  • 需要支持租户级别的配置
  • 要求良好的扩展性和性能

决策：

  • 采用数据库行级隔离
  • 实现租户上下文中间件
  • 支持租户级别的配置管理
  • 实现租户快照机制

后果： 正面影响：

  • 支持完整的租户隔离
  • 提供灵活的租户配置
  • 支持租户快照和版本管理
  • 便于业务扩展

负面影响：

  • 增加了系统复杂度
  • 数据库查询需要额外过滤
  • 租户管理复杂度高
  • 性能可能受影响

实施：

  • ✅ 完成：多租户架构设计
  • ✅ 完成：数据隔离实现
  • ✅ 完成：租户管理功能
  • ✅ 完成：租户快照机制

相关 ADR：

  • ADR-002: 数据库选型
  • ADR-003: 服务发现和配置管理

ADR-008: 采用 OpenTelemetry 进行可观测性​

状态：已接受

背景：

  • 微服务架构需要完整的可观测性
  • 需要统一的指标、日志和链路追踪
  • 要求支持多种监控后端
  • 需要符合业界标准

决策：

  • 使用 OpenTelemetry 进行数据收集
  • 使用 Prometheus 进行指标存储
  • 使用 Loki 进行日志收集
  • 使用 Jaeger 进行链路追踪

后果： 正面影响：

  • 提供完整的可观测性
  • 符合业界标准
  • 支持多种监控后端
  • 便于问题诊断和性能优化

负面影响：

  • 增加了系统复杂度
  • 需要额外的存储资源
  • 监控系统需要维护
  • 可能影响应用性能

实施：

  • ✅ 完成：OpenTelemetry 集成
  • ✅ 完成：监控系统部署
  • ✅ 完成：告警规则配置
  • 🔄 进行中：监控优化和扩展

相关 ADR：

  • ADR-001: 微服务架构选型
  • ADR-011: 监控和告警策略

ADR-009: 实现点数系统的 FIFO 消费策略​

状态：已接受

背景：

  • 需要实现点数的生命周期管理
  • 要求点数按过期时间优先消费
  • 需要支持跨账本消费
  • 要求完整的交易记录追踪

决策：

  • 实现 FIFO（先进先出）消费策略
  • 支持多账本点数合并消费
  • 实现自动过期处理机制
  • 提供完整的交易流水

后果： 正面影响：

  • 优化点数使用效率
  • 减少点数浪费
  • 提供完整的追踪记录
  • 支持复杂的业务场景

负面影响：

  • 实现复杂度较高
  • 数据库查询压力大
  • 需要处理并发问题
  • 性能优化要求高

实施：

  • ✅ 完成：FIFO 算法设计
  • ✅ 完成：点数系统实现
  • ✅ 完成：过期处理机制
  • ✅ 完成：交易记录系统

相关 ADR：

  • ADR-002: 数据库选型
  • ADR-005: 消息队列选型

ADR-010: 采用 Wire 进行依赖注入​

状态：已接受

背景：

  • 需要管理复杂的依赖关系
  • 要求编译时依赖检查
  • 需要支持测试时的依赖替换
  • 要求良好的代码组织结构

决策：

  • 使用 Google Wire 进行依赖注入
  • 采用分层 ProviderSet 组织
  • 实现接口绑定机制
  • 支持测试时的依赖替换

后果： 正面影响：

  • 提供编译时依赖检查
  • 便于测试和调试
  • 提高代码的可维护性
  • 支持灵活的依赖管理

负面影响：

  • 学习成本较高
  • 代码生成增加了编译时间
  • 调试相对复杂
  • 可能过度设计

实施：

  • ✅ 完成：Wire 集成
  • ✅ 完成：依赖注入重构
  • ✅ 完成：测试支持
  • ✅ 完成：代码生成优化

相关 ADR：

  • ADR-001: 微服务架构选型
  • ADR-014: 测试策略

ADR-011: 实现分级监控和告警策略​

状态：已接受

背景：

  • 需要建立完整的监控体系
  • 要求分级告警机制
  • 需要支持多种通知渠道
  • 要求智能告警和降噪

决策：

  • 实现四级告警机制
  • 支持多种通知渠道
  • 实现告警聚合和降噪
  • 建立应急响应流程

后果： 正面影响：

  • 提供及时的问题发现
  • 减少告警噪音
  • 提高运维效率
  • 支持快速故障响应

负面影响：

  • 告警规则配置复杂
  • 需要持续优化
  • 可能产生误报
  • 维护成本较高

实施：

  • ✅ 完成：监控系统部署
  • ✅ 完成：告警规则配置
  • ✅ 完成：通知渠道集成
  • ✅ 完成：应急响应流程

相关 ADR：

  • ADR-008: 可观测性方案
  • ADR-015: 运维自动化

ADR-012: 实现多层次安全架构​

状态：已接受

背景：

  • 需要保护敏感数据和系统安全
  • 要求符合安全合规要求
  • 需要防范多种安全威胁
  • 要求完整的安全审计

决策：

  • 实现网络、应用、数据多层次安全
  • 采用零信任安全模型
  • 实现完整的安全审计
  • 建立安全监控和响应机制

后果： 正面影响：

  • 提供全面的安全保护
  • 符合合规要求
  • 提高安全事件响应能力
  • 降低安全风险

负面影响：

  • 增加了系统复杂度
  • 可能影响性能
  • 安全管理成本高
  • 需要专业的安全团队

实施：

  • ✅ 完成：安全架构设计
  • ✅ 完成：安全措施实施
  • ✅ 完成：审计系统建设
  • 🔄 进行中：安全优化和加固

相关 ADR：

  • ADR-006: 身份认证方案
  • ADR-013: 数据加密策略

ADR-013: 实现数据加密和脱敏策略​

状态：已接受

背景：

  • 需要保护敏感数据安全
  • 要求符合数据保护法规
  • 需要实现数据脱敏
  • 要求密钥安全管理

决策：

  • 实现传输和存储加密
  • 采用数据脱敏技术
  • 实现密钥轮换机制
  • 建立数据分类管理制度

后果： 正面影响：

  • 保护敏感数据安全
  • 符合法规要求
  • 降低数据泄露风险
  • 提高用户信任度

负面影响：

  • 增加了系统复杂度
  • 可能影响性能
  • 密钥管理复杂
  • 数据使用受限

实施：

  • ✅ 完成：加密方案实施
  • ✅ 完成：脱敏策略实现
  • ✅ 完成：密钥管理系统
  • ✅ 完成：数据分类管理

相关 ADR：

  • ADR-002: 数据库选型
  • ADR-012: 安全架构设计

ADR-014: 采用分层测试策略​

状态：已接受

背景：

  • 需要保证代码质量和系统稳定性
  • 要求高测试覆盖率
  • 需要支持多种测试类型
  • 要求自动化测试流程

决策：

  • 实现单元测试、集成测试、端到端测试
  • 要求 90% 以上的测试覆盖率
  • 使用 sqlmock 进行数据库测试
  • 实现自动化测试和持续集成

后果： 正面影响：

  • 提高代码质量
  • 减少生产环境问题
  • 支持快速迭代
  • 提高开发效率

负面影响：

  • 增加了开发工作量
  • 测试维护成本高
  • 可能影响开发速度
  • 需要测试专业知识

实施：

  • ✅ 完成：测试框架搭建
  • ✅ 完成：测试规范制定
  • ✅ 完成：自动化测试实现
  • 🔄 进行中：测试覆盖率优化

相关 ADR：

  • ADR-010: 依赖注入策略
  • ADR-015: 运维自动化

ADR-015: 实现运维自动化和 CI/CD​

状态：已接受

背景：

  • 需要提高部署效率和可靠性
  • 要求支持多环境部署
  • 需要自动化运维流程
  • 要求快速回滚能力

决策：

  • 实现 CI/CD 自动化流水线
  • 采用 GitOps 部署模式
  • 实现自动化运维工具
  • 建立监控和告警机制

后果： 正面影响：

  • 提高部署效率
  • 减少人为错误
  • 支持快速发布
  • 提高系统可靠性

负面影响：

  • 初始投入成本高
  • 需要专业知识
  • 系统复杂度增加
  • 需要持续维护

实施：

  • ✅ 完成：CI/CD 流水线搭建
  • ✅ 完成：自动化部署实现
  • ✅ 完成：监控集成
  • 🔄 进行中：运维工具优化

相关 ADR：

  • ADR-011: 监控和告警策略
  • ADR-014: 测试策略

ADR-016: 采用容器化和 Kubernetes 部署​

状态：已接受

背景：

  • 需要支持弹性扩缩容
  • 要求标准化部署环境
  • 需要支持多环境一致性
  • 要求高可用部署

决策：

  • 采用 Docker 容器化
  • 使用 Kubernetes 编排
  • 实现自动化扩缩容
  • 支持多环境部署

后果： 正面影响：

  • 支持弹性扩缩容
  • 环境一致性保证
  • 提高资源利用率
  • 支持高可用部署

负面影响：

  • 学习成本高
  • 系统复杂度增加
  • 需要额外的运维工作
  • 调试相对复杂

实施：

  • ✅ 完成：容器化改造
  • ✅ 完成：Kubernetes 集群部署
  • ✅ 完成：自动化扩缩容
  • ✅ 完成：多环境支持

相关 ADR：

  • ADR-015: 运维自动化
  • ADR-011: 监控和告警策略

ADR 管理流程​

ADR 提议流程​

1. 提议阶段​

  • 识别需要决策的架构问题
  • 收集相关背景信息和技术调研
  • 起草 ADR 提议文档
  • 提交给架构委员会评审

2. 评审阶段​

  • 架构委员会组织评审会议
  • 讨论决策的必要性和可行性
  • 评估决策的影响和风险
  • 提出修改意见和建议

3. 决策阶段​

  • 架构委员会进行投票决策
  • 记录决策结果和理由
  • 更新 ADR 状态为"已接受"
  • 通知相关团队和人员

ADR 维护流程​

1. 定期审查​

  • 每季度审查所有已接受的 ADR
  • 评估决策的当前有效性
  • 识别需要更新或替代的 ADR
  • 制定相应的改进计划

2. 更新流程​

  • 当技术或业务发生变化时，评估现有 ADR
  • 如需要更新，创建新的 ADR 版本
  • 标记原 ADR 为"已替代"
  • 更新相关文档和系统

3. 废弃流程​

  • 当 ADR 不再适用时，标记为"已弃用"
  • 记录废弃的原因和时间
  • 制定替代方案
  • 通知相关团队和人员

ADR 文档管理​

1. 版本控制​

  • 所有 ADR 使用 Git 进行版本控制
  • 每个 ADR 有唯一的编号和版本
  • 记录所有变更历史
  • 支持版本回溯和对比

2. 访问权限​

  • ADR 文档对所有团队开放
  • 支持评论和反馈
  • 架构委员会负责最终决策
  • 定期发布 ADR 状态报告

3. 知识传承​

  • 新成员入职时培训 ADR 流程
  • 定期组织 ADR 回顾会议
  • 建立 ADR 知识库
  • 鼓励团队参与 ADR 讨论

最佳实践​

1. ADR 编写原则​

  • 简洁明了：用简单易懂的语言描述决策
  • 背景充分：提供足够的背景和上下文信息
  • 后果清晰：明确说明决策的正面和负面影响
  • 实施具体：提供详细的实施计划和进度

2. 决策原则​

  • 数据驱动：基于数据和事实进行决策
  • 渐进式：采用渐进式的架构演进方式
  • 可逆性：优先选择可逆的决策方案
  • 风险可控：评估和控制决策风险

3. 沟通原则​

  • 透明公开：决策过程和结果对所有团队公开
  • 及时沟通：及时通知相关人员决策进展
  • 充分讨论：鼓励充分的讨论和反馈
  • 文档记录：完整记录决策过程和理由

4. 持续改进​

  • 定期回顾：定期回顾和评估 ADR 的有效性
  • 学习总结：从决策中学习经验和教训
  • 优化流程：持续优化 ADR 管理流程
  • 知识积累：建立和完善架构决策知识库

总结​

架构决策记录（ADR）是井云服务中心后端系统架构治理的重要组成部分。通过系统化的决策记录和管理，我们能够：

  1. 提高决策质量：通过结构化的决策流程，提高架构决策的质量和可靠性
  2. 促进知识传承：通过文档化的决策记录，促进团队知识传承和经验积累
  3. 支持架构演进：通过持续的 ADR 管理和优化，支持架构的渐进式演进
  4. 降低风险：通过充分的评估和讨论，降低架构决策的风险

通过遵循 ADR 管理流程和最佳实践，我们能够建立一个健康、可持续的架构决策文化，为系统的长期发展提供坚实的架构基础。