Back to Details

architecture-decision-records

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Architecture Decision Records

架构决策记录（ADRs）

Comprehensive patterns for creating, maintaining, and managing Architecture Decision Records (ADRs) that capture the context and rationale behind significant technical decisions.
本文档提供创建、维护和管理架构决策记录（ADRs）的完整模式，用于捕获重要技术决策背后的背景和依据。

When to Use This Skill

何时使用该方法

  • Making significant architectural decisions
  • Documenting technology choices
  • Recording design trade-offs
  • Onboarding new team members
  • Reviewing historical decisions
  • Establishing decision-making processes
  • 制定重要架构决策
  • 记录技术选型
  • 记录设计取舍
  • 新团队成员入职培训
  • 回顾历史决策
  • 建立决策流程

Core Concepts

核心概念

1. What is an ADR?

1. 什么是ADR？

An Architecture Decision Record captures:
  • Context: Why we needed to make a decision
  • Decision: What we decided
  • Consequences: What happens as a result
架构决策记录（ADR）用于记录：
  • 背景：我们为何需要做出该决策
  • 决策：我们做出了什么决定
  • 影响：该决策带来的结果

2. When to Write an ADR

2. 何时编写ADR

Write ADRSkip ADR
New framework adoptionMinor version upgrades
Database technology choiceBug fixes
API design patternsImplementation details
Security architectureRoutine maintenance
Integration patternsConfiguration changes
应编写ADR的场景无需编写ADR的场景
新框架选型小版本升级
数据库技术选型Bug修复
API设计模式制定实现细节
安全架构设计日常维护
集成模式设计配置变更

3. ADR Lifecycle

3. ADR生命周期

Proposed → Accepted → Deprecated → Superseded
              ↓
           Rejected
Proposed → Accepted → Deprecated → Superseded
              ↓
           Rejected

Templates

模板

Template 1: Standard ADR (MADR Format)

模板1：标准ADR（MADR格式）

markdown
undefined
markdown
undefined

ADR-0001: Use PostgreSQL as Primary Database

ADR-0001: 选用PostgreSQL作为主数据库

Status

状态

Accepted
已接受

Context

背景

We need to select a primary database for our new e-commerce platform. The system will handle:
  • ~10,000 concurrent users
  • Complex product catalog with hierarchical categories
  • Transaction processing for orders and payments
  • Full-text search for products
  • Geospatial queries for store locator
The team has experience with MySQL, PostgreSQL, and MongoDB. We need ACID compliance for financial transactions.
我们需要为新的电商平台选择主数据库。系统需要处理：
  • 约10,000并发用户
  • 带有层级分类的复杂商品目录
  • 订单与支付的事务处理
  • 商品全文搜索
  • 门店定位的地理空间查询
团队具备MySQL、PostgreSQL和MongoDB的使用经验。我们需要ACID合规性来支持金融交易。

Decision Drivers

决策驱动因素

  • Must have ACID compliance for payment processing
  • Must support complex queries for reporting
  • Should support full-text search to reduce infrastructure complexity
  • Should have good JSON support for flexible product attributes
  • Team familiarity reduces onboarding time
  • 必须具备ACID合规性，以支持支付处理
  • 必须支持复杂查询，用于报表生成
  • 应支持全文搜索，以降低基础设施复杂度
  • 应具备良好的JSON支持，用于灵活的商品属性
  • 团队熟悉度，减少上手时间

Considered Options

备选方案

Option 1: PostgreSQL

方案1：PostgreSQL

  • Pros: ACID compliant, excellent JSON support (JSONB), built-in full-text search, PostGIS for geospatial, team has experience
  • Cons: Slightly more complex replication setup than MySQL
  • 优点：ACID合规，出色的JSONB支持，内置全文搜索，PostGIS地理空间扩展，团队有使用经验
  • 缺点：复制设置比MySQL略复杂

Option 2: MySQL

方案2：MySQL

  • Pros: Very familiar to team, simple replication, large community
  • Cons: Weaker JSON support, no built-in full-text search (need Elasticsearch), no geospatial without extensions
  • 优点：团队非常熟悉，复制设置简单，社区庞大
  • 缺点：JSON支持较弱，无内置全文搜索（需Elasticsearch），无原生地理空间支持（需扩展）

Option 3: MongoDB

方案3：MongoDB

  • Pros: Flexible schema, native JSON, horizontal scaling
  • Cons: No ACID for multi-document transactions (at decision time), team has limited experience, requires schema design discipline
  • 优点：灵活的 schema，原生JSON支持，水平扩展能力
  • 缺点：（决策时）不支持多文档事务的ACID合规，团队经验有限，需要严格的schema设计规范

Decision

决策

We will use PostgreSQL 15 as our primary database.
我们将选用PostgreSQL 15作为主数据库。

Rationale

依据

PostgreSQL provides the best balance of:
  1. ACID compliance essential for e-commerce transactions
  2. Built-in capabilities (full-text search, JSONB, PostGIS) reduce infrastructure complexity
  3. Team familiarity with SQL databases reduces learning curve
  4. Mature ecosystem with excellent tooling and community support
The slight complexity in replication is outweighed by the reduction in additional services (no separate Elasticsearch needed).
PostgreSQL在以下方面达到最佳平衡：
  1. ACID合规性：对电商交易至关重要
  2. 内置能力（全文搜索、JSONB、PostGIS）：减少基础设施复杂度
  3. 团队熟悉度：团队具备SQL数据库经验，降低学习曲线
  4. 成熟生态：拥有优秀的工具和社区支持
复制设置的轻微复杂度，远低于减少额外服务（无需独立Elasticsearch）带来的收益。

Consequences

影响

Positive

积极影响

  • Single database handles transactions, search, and geospatial queries
  • Reduced operational complexity (fewer services to manage)
  • Strong consistency guarantees for financial data
  • Team can leverage existing SQL expertise
  • 单一数据库处理事务、搜索和地理空间查询
  • 降低运维复杂度（需管理的服务更少）
  • 金融数据具备强一致性保障
  • 团队可利用现有SQL经验

Negative

消极影响

  • Need to learn PostgreSQL-specific features (JSONB, full-text search syntax)
  • Vertical scaling limits may require read replicas sooner
  • Some team members need PostgreSQL-specific training
  • 需要学习PostgreSQL特定功能（JSONB、全文搜索语法）
  • 垂直扩展限制可能更早需要读写分离
  • 部分团队成员需要PostgreSQL专项培训

Risks

风险

  • Full-text search may not scale as well as dedicated search engines
  • Mitigation: Design for potential Elasticsearch addition if needed
  • 全文搜索的扩展性可能不如专用搜索引擎
  • 缓解方案：若有需要，设计可扩展至Elasticsearch的架构

Implementation Notes

实施说明

  • Use JSONB for flexible product attributes
  • Implement connection pooling with PgBouncer
  • Set up streaming replication for read replicas
  • Use pg_trgm extension for fuzzy search
  • 使用JSONB存储灵活的商品属性
  • 使用PgBouncer实现连接池
  • 配置流复制以实现读写分离
  • 使用pg_trgm扩展实现模糊搜索

Related Decisions

相关决策

  • ADR-0002: Caching Strategy (Redis) - complements database choice
  • ADR-0005: Search Architecture - may supersede if Elasticsearch needed
  • ADR-0002：缓存策略（Redis）- 与数据库选型互补
  • ADR-0005：搜索架构 - 若需Elasticsearch则替代本决策

References

参考资料

undefined
undefined

Template 2: Lightweight ADR

模板2：轻量型ADR

markdown
undefined
markdown
undefined

ADR-0012: Adopt TypeScript for Frontend Development

ADR-0012：前端开发采用TypeScript

Status: Accepted Date: 2024-01-15 Deciders: @alice, @bob, @charlie
状态：已接受 日期：2024-01-15 决策人：@alice, @bob, @charlie

Context

背景

Our React codebase has grown to 50+ components with increasing bug reports related to prop type mismatches and undefined errors. PropTypes provide runtime-only checking.
我们的React代码库已扩展至50+组件，与prop类型不匹配和未定义错误相关的Bug报告日益增多。PropTypes仅提供运行时检查。

Decision

决策

Adopt TypeScript for all new frontend code. Migrate existing code incrementally.
所有新前端代码采用TypeScript，现有代码逐步迁移。

Consequences

影响

Good: Catch type errors at compile time, better IDE support, self-documenting code.
Bad: Learning curve for team, initial slowdown, build complexity increase.
Mitigations: TypeScript training sessions, allow gradual adoption with 
allowJs: true
.
undefined
有利：编译时捕获类型错误，更好的IDE支持，代码自文档化。
不利：团队存在学习曲线，初期开发速度放缓，构建复杂度增加。
缓解方案：提供TypeScript培训课程，通过
allowJs: true
支持逐步迁移。
undefined

Template 3: Y-Statement Format

模板3：Y-陈述格式

markdown
undefined
markdown
undefined

ADR-0015: API Gateway Selection

ADR-0015：API网关选型

In the context of building a microservices architecture, facing the need for centralized API management, authentication, and rate limiting, we decided for Kong Gateway and against AWS API Gateway and custom Nginx solution, to achieve vendor independence, plugin extensibility, and team familiarity with Lua, accepting that we need to manage Kong infrastructure ourselves.
undefined
在构建微服务架构的背景下， 面临集中式API管理、认证和限流的需求， 我们决定选用Kong Gateway， 放弃AWS API Gateway和自定义Nginx方案， 以实现厂商独立性、插件可扩展性和团队对Lua的熟悉度， 同时接受需要自行管理Kong基础设施的代价。
undefined

Template 4: ADR for Deprecation

模板4：弃用类ADR

markdown
undefined
markdown
undefined

ADR-0020: Deprecate MongoDB in Favor of PostgreSQL

ADR-0020：弃用MongoDB，改用PostgreSQL

Status

状态

Accepted (Supersedes ADR-0003)
已接受（替代ADR-0003）

Context

背景

ADR-0003 (2021) chose MongoDB for user profile storage due to schema flexibility needs. Since then:
  • MongoDB's multi-document transactions remain problematic for our use case
  • Our schema has stabilized and rarely changes
  • We now have PostgreSQL expertise from other services
  • Maintaining two databases increases operational burden
ADR-0003（2021年）因schema灵活性需求，选择MongoDB存储用户资料。自那时起：
  • MongoDB的多文档事务仍无法满足我们的使用场景
  • 我们的schema已趋于稳定，很少变更
  • 团队已在其他服务中积累了PostgreSQL经验
  • 维护两个数据库增加了运维负担

Decision

决策

Deprecate MongoDB and migrate user profiles to PostgreSQL.
弃用MongoDB，将用户资料迁移至PostgreSQL。

Migration Plan

迁移计划

  1. Phase 1 (Week 1-2): Create PostgreSQL schema, dual-write enabled
  2. Phase 2 (Week 3-4): Backfill historical data, validate consistency
  3. Phase 3 (Week 5): Switch reads to PostgreSQL, monitor
  4. Phase 4 (Week 6): Remove MongoDB writes, decommission
  1. 阶段1（第1-2周）：创建PostgreSQL schema，启用双写
  2. 阶段2（第3-4周）：回填历史数据，验证一致性
  3. 阶段3（第5周）：切换读请求至PostgreSQL，监控运行
  4. 阶段4（第6周）：移除MongoDB写请求，下线服务

Consequences

影响

Positive

积极影响

  • Single database technology reduces operational complexity
  • ACID transactions for user data
  • Team can focus PostgreSQL expertise
  • 单一数据库技术降低运维复杂度
  • 用户数据具备ACID事务保障
  • 团队可专注于PostgreSQL经验积累

Negative

消极影响

  • Migration effort (~4 weeks)
  • Risk of data issues during migration
  • Lose some schema flexibility
  • 迁移工作量（约4周）
  • 迁移过程中存在数据问题风险
  • 损失部分schema灵活性

Lessons Learned

经验总结

Document from ADR-0003 experience:
  • Schema flexibility benefits were overestimated
  • Operational cost of multiple databases was underestimated
  • Consider long-term maintenance in technology decisions
undefined
从ADR-0003的经验中总结：
  • 高估了schema灵活性的收益
  • 低估了多数据库的运维成本
  • 技术决策需考虑长期维护成本
undefined

Template 5: Request for Comments (RFC) Style

模板5：请求评论（RFC）风格

markdown
undefined
markdown
undefined

RFC-0025: Adopt Event Sourcing for Order Management

RFC-0025：订单管理采用事件溯源模式

Summary

概述

Propose adopting event sourcing pattern for the order management domain to improve auditability, enable temporal queries, and support business analytics.
提议在订单管理领域采用事件溯源模式，以提升可审计性、支持时态查询并助力业务分析。

Motivation

动机

Current challenges:
  1. Audit requirements need complete order history
  2. "What was the order state at time X?" queries are impossible
  3. Analytics team needs event stream for real-time dashboards
  4. Order state reconstruction for customer support is manual
当前面临的挑战：
  1. 审计要求需要完整的订单历史
  2. 无法查询“X时间点的订单状态是什么？”
  3. 分析团队需要事件流来构建实时仪表盘
  4. 客服重建订单状态需手动操作

Detailed Design

详细设计

Event Store

事件存储


OrderCreated { orderId, customerId, items[], timestamp }
OrderItemAdded { orderId, item, timestamp }
OrderItemRemoved { orderId, itemId, timestamp }
PaymentReceived { orderId, amount, paymentId, timestamp }
OrderShipped { orderId, trackingNumber, timestamp }


OrderCreated { orderId, customerId, items[], timestamp }
OrderItemAdded { orderId, item, timestamp }
OrderItemRemoved { orderId, itemId, timestamp }
PaymentReceived { orderId, amount, paymentId, timestamp }
OrderShipped { orderId, trackingNumber, timestamp }

Projections

投影

  • CurrentOrderState: Materialized view for queries
  • OrderHistory: Complete timeline for audit
  • DailyOrderMetrics: Analytics aggregation
  • CurrentOrderState：用于查询的物化视图
  • OrderHistory：用于审计的完整时间线
  • DailyOrderMetrics：用于分析的聚合数据

Technology

技术选型

  • Event Store: EventStoreDB (purpose-built, handles projections)
  • Alternative considered: Kafka + custom projection service
  • 事件存储：EventStoreDB（专用存储，支持投影）
  • 备选方案：Kafka + 自定义投影服务

Drawbacks

缺点

  • Learning curve for team
  • Increased complexity vs. CRUD
  • Need to design events carefully (immutable once stored)
  • Storage growth (events never deleted)
  • 团队存在学习曲线
  • 比CRUD复杂度更高
  • 需要谨慎设计事件（一旦存储则不可变）
  • 存储量增长（事件永不删除）

Alternatives

替代方案

  1. Audit tables: Simpler but doesn't enable temporal queries
  2. CDC from existing DB: Complex, doesn't change data model
  3. Hybrid: Event source only for order state changes
  1. 审计表：更简单但不支持时态查询
  2. 现有数据库CDC：复杂度高，不改变数据模型
  3. 混合模式：仅对订单状态变更使用事件溯源

Unresolved Questions

未解决问题

  • Event schema versioning strategy
  • Retention policy for events
  • Snapshot frequency for performance
  • 事件schema版本化策略
  • 事件保留策略
  • 性能快照频率

Implementation Plan

实施计划

  1. Prototype with single order type (2 weeks)
  2. Team training on event sourcing (1 week)
  3. Full implementation and migration (4 weeks)
  4. Monitoring and optimization (ongoing)
  1. 单一订单类型原型开发（2周）
  2. 团队事件溯源培训（1周）
  3. 完整实现与迁移（4周）
  4. 监控与优化（持续进行）

References

参考资料

undefined
undefined

ADR Management

ADR管理

Directory Structure

目录结构

docs/
├── adr/
│   ├── README.md           # Index and guidelines
│   ├── template.md         # Team's ADR template
│   ├── 0001-use-postgresql.md
│   ├── 0002-caching-strategy.md
│   ├── 0003-mongodb-user-profiles.md  # [DEPRECATED]
│   └── 0020-deprecate-mongodb.md      # Supersedes 0003
docs/
├── adr/
│   ├── README.md           # 索引与指南
│   ├── template.md         # 团队ADR模板
│   ├── 0001-use-postgresql.md
│   ├── 0002-caching-strategy.md
│   ├── 0003-mongodb-user-profiles.md  # [已弃用]
│   └── 0020-deprecate-mongodb.md      # 替代0003

ADR Index (README.md)

ADR索引（README.md）

markdown
undefined
markdown
undefined

Architecture Decision Records

架构决策记录

This directory contains Architecture Decision Records (ADRs) for [Project Name].
本目录包含[项目名称]的架构决策记录（ADRs）。

Index

索引

ADRTitleStatusDate
0001Use PostgreSQL as Primary DatabaseAccepted2024-01-10
0002Caching Strategy with RedisAccepted2024-01-12
0003MongoDB for User ProfilesDeprecated2023-06-15
0020Deprecate MongoDBAccepted2024-01-15
ADR标题状态日期
0001选用PostgreSQL作为主数据库已接受2024-01-10
0002Redis缓存策略已接受2024-01-12
0003MongoDB存储用户资料已弃用2023-06-15
0020弃用MongoDB已接受2024-01-15

Creating a New ADR

创建新ADR

  1. Copy 
    template.md
    to 
    NNNN-title-with-dashes.md
  2. Fill in the template
  3. Submit PR for review
  4. Update this index after approval
  1. 复制
    template.md
    为
    NNNN-title-with-dashes.md
  2. 填写模板内容
  3. 提交PR进行评审
  4. 批准后更新本索引

ADR Status

ADR状态

  • Proposed: Under discussion
  • Accepted: Decision made, implementing
  • Deprecated: No longer relevant
  • Superseded: Replaced by another ADR
  • Rejected: Considered but not adopted
undefined
  • Proposed：讨论中
  • Accepted：已决策，实施中
  • Deprecated：不再相关
  • Superseded：被其他ADR替代
  • Rejected：已考虑但未采纳
undefined

Automation (adr-tools)

自动化工具（adr-tools）

bash
undefined
bash
undefined

Install adr-tools

安装adr-tools

brew install adr-tools
brew install adr-tools

Initialize ADR directory

初始化ADR目录

adr init docs/adr
adr init docs/adr

Create new ADR

创建新ADR

adr new "Use PostgreSQL as Primary Database"
adr new "Use PostgreSQL as Primary Database"

Supersede an ADR

替代现有ADR

adr new -s 3 "Deprecate MongoDB in Favor of PostgreSQL"
adr new -s 3 "Deprecate MongoDB in Favor of PostgreSQL"

Generate table of contents

生成目录

adr generate toc > docs/adr/README.md
adr generate toc > docs/adr/README.md

Link related ADRs

关联相关ADR

adr link 2 "Complements" 1 "Is complemented by"
undefined
adr link 2 "Complements" 1 "Is complemented by"
undefined

Review Process

评审流程

markdown
undefined
markdown
undefined

ADR Review Checklist

ADR评审检查清单

Before Submission

提交前

  • Context clearly explains the problem
  • All viable options considered
  • Pros/cons balanced and honest
  • Consequences (positive and negative) documented
  • Related ADRs linked
  • 背景清晰说明问题
  • 考虑了所有可行方案
  • 优缺点平衡且客观
  • 记录了（积极和消极）影响
  • 关联了相关ADR

During Review

评审中

  • At least 2 senior engineers reviewed
  • Affected teams consulted
  • Security implications considered
  • Cost implications documented
  • Reversibility assessed
  • 至少2名资深工程师评审
  • 咨询了受影响团队
  • 考虑了安全影响
  • 记录了成本影响
  • 评估了可逆性

After Acceptance

接受后

  • ADR index updated
  • Team notified
  • Implementation tickets created
  • Related documentation updated
undefined
  • 更新了ADR索引
  • 通知了团队
  • 创建了实施工单
  • 更新了相关文档
undefined

Best Practices

最佳实践

Do's

建议做法

  • Write ADRs early - Before implementation starts
  • Keep them short - 1-2 pages maximum
  • Be honest about trade-offs - Include real cons
  • Link related decisions - Build decision graph
  • Update status - Deprecate when superseded
  • 尽早编写ADR - 在开始实现之前
  • 保持简洁 - 最多1-2页
  • 客观记录取舍 - 如实记录优缺点
  • 关联相关决策 - 构建决策图谱
  • 更新状态 - 过时后标记为已弃用

Don'ts

避免做法

  • Don't change accepted ADRs - Write new ones to supersede
  • Don't skip context - Future readers need background
  • Don't hide failures - Rejected decisions are valuable
  • Don't be vague - Specific decisions, specific consequences
  • Don't forget implementation - ADR without action is waste
  • 不要修改已接受的ADR - 编写新ADR替代
  • 不要省略背景 - 未来读者需要了解上下文
  • 不要隐藏失败 - 被拒绝的决策也有价值
  • 不要模糊表述 - 决策和影响要具体
  • 不要忘记实施 - 无行动的ADR毫无意义

Resources

参考资料

undefined