designing-architecture

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Designing Architecture

架构设计

Architecture Decision Workflow

架构决策工作流程

Copy this checklist and track progress:

Architecture Design Progress:
- [ ] Step 1: Understand requirements and constraints
- [ ] Step 2: Assess project size and team capabilities
- [ ] Step 3: Select architecture pattern
- [ ] Step 4: Define directory structure
- [ ] Step 5: Document trade-offs and decision
- [ ] Step 6: Validate against decision framework

复制此清单并跟踪进度：

Architecture Design Progress:
- [ ] Step 1: Understand requirements and constraints
- [ ] Step 2: Assess project size and team capabilities
- [ ] Step 3: Select architecture pattern
- [ ] Step 4: Define directory structure
- [ ] Step 5: Document trade-offs and decision
- [ ] Step 6: Validate against decision framework

Pattern Selection Guide

模式选择指南

By Project Size

按项目规模

Size	Recommended Pattern
Small (<10K LOC)	Simple MVC/Layered
Medium (10K-100K)	Clean Architecture
Large (>100K)	Modular Monolith or Microservices

规模	推荐模式
小型（代码量<10K行）	简单MVC/分层架构
中型（代码量10K-100K行）	整洁架构
大型（代码量>100K行）	模块化单体或微服务

By Team Size

按团队规模

Team	Recommended
1-3 devs	Monolith with clear modules
4-10 devs	Modular Monolith
10+ devs	Microservices (if justified)

团队规模	推荐架构
1-3名开发者	带有清晰模块的单体应用
4-10名开发者	模块化单体应用
10名以上开发者	微服务（如有合理需求）

Common Patterns

常见架构模式

1. Layered Architecture

1. 分层架构

┌─────────────────────────────┐
│       Presentation          │  ← UI, API Controllers
├─────────────────────────────┤
│       Application           │  ← Use Cases, Services
├─────────────────────────────┤
│         Domain              │  ← Business Logic, Entities
├─────────────────────────────┤
│      Infrastructure         │  ← Database, External APIs
└─────────────────────────────┘

Use when: Simple CRUD apps, small teams, quick prototypes

┌─────────────────────────────┐
│       Presentation          │  ← UI, API Controllers
├─────────────────────────────┤
│       Application           │  ← Use Cases, Services
├─────────────────────────────┤
│         Domain              │  ← Business Logic, Entities
├─────────────────────────────┤
│      Infrastructure         │  ← Database, External APIs
└─────────────────────────────┘

适用场景：简单CRUD应用、小型团队、快速原型开发

2. Clean Architecture

2. 整洁架构

┌─────────────────────────────────────┐
│            Frameworks & Drivers      │
│  ┌─────────────────────────────┐    │
│  │     Interface Adapters       │    │
│  │  ┌─────────────────────┐    │    │
│  │  │   Application       │    │    │
│  │  │  ┌─────────────┐    │    │    │
│  │  │  │   Domain    │    │    │    │
│  │  │  └─────────────┘    │    │    │
│  │  └─────────────────────┘    │    │
│  └─────────────────────────────┘    │
└─────────────────────────────────────┘

Use when: Complex business logic, long-lived projects, testability is key

┌─────────────────────────────────────┐
│            Frameworks & Drivers      │
│  ┌─────────────────────────────┐    │
│  │     Interface Adapters       │    │
│  │  ┌─────────────────────┐    │    │
│  │  │   Application       │    │    │
│  │  │  ┌─────────────┐    │    │    │
│  │  │  │   Domain    │    │    │    │
│  │  │  └─────────────┘    │    │    │
│  │  └─────────────────────┘    │    │
│  └─────────────────────────────┘    │
└─────────────────────────────────────┘

适用场景：复杂业务逻辑、长期维护项目、可测试性优先

3. Hexagonal (Ports & Adapters)

3. 六边形架构（端口与适配器）

        ┌──────────┐
        │ HTTP API │
        └────┬─────┘
             │ Port
    ┌────────▼────────┐
    │                 │
    │   Application   │
    │     Core        │
    │                 │
    └────────┬────────┘
             │ Port
        ┌────▼─────┐
        │ Database │
        └──────────┘

Use when: Need to swap external dependencies, multiple entry points

        ┌──────────┐
        │ HTTP API │
        └────┬─────┘
             │ Port
    ┌────────▼────────┐
    │                 │
    │   Application   │
    │     Core        │
    │                 │
    └────────┬────────┘
             │ Port
        ┌────▼─────┐
        │ Database │
        └──────────┘

适用场景：需要替换外部依赖、多入口点的项目

4. Event-Driven Architecture

4. 事件驱动架构

Producer → Event Bus → Consumer
              │
              ├─→ Consumer
              │
              └─→ Consumer

Use when: Loose coupling needed, async processing, scalability

Producer → Event Bus → Consumer
              │
              ├─→ Consumer
              │
              └─→ Consumer

适用场景：需要松耦合、异步处理、可扩展性的项目

5. CQRS (Command Query Responsibility Segregation)

5. CQRS（命令查询职责分离）

┌─────────────┐      ┌─────────────┐
│  Commands   │      │   Queries   │
│  (Write)    │      │   (Read)    │
└──────┬──────┘      └──────┬──────┘
       │                    │
       ▼                    ▼
  Write Model          Read Model
       │                    │
       └────────┬───────────┘
                ▼
           Event Store

Use when: Different read/write scaling, complex domains, event sourcing

┌─────────────┐      ┌─────────────┐
│  Commands   │      │   Queries   │
│  (Write)    │      │   (Read)    │
└──────┬──────┘      └──────┬──────┘
       │                    │
       ▼                    ▼
  Write Model          Read Model
       │                    │
       └────────┬───────────┘
                ▼
           Event Store

适用场景：读写扩展需求不同、复杂领域、事件溯源的项目

Directory Structure Patterns

目录结构模式

Feature-Based (Recommended for medium+)

基于功能（推荐用于中大型项目）

src/
├── features/
│   ├── users/
│   │   ├── api/
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── services/
│   │   └── types/
│   └── orders/
│       ├── api/
│       ├── components/
│       └── ...
├── shared/
│   ├── components/
│   ├── hooks/
│   └── utils/
└── app/
    └── ...

src/
├── features/
│   ├── users/
│   │   ├── api/
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── services/
│   │   └── types/
│   └── orders/
│       ├── api/
│       ├── components/
│       └── ...
├── shared/
│   ├── components/
│   ├── hooks/
│   └── utils/
└── app/
    └── ...

Layer-Based (Simple apps)

基于分层（简单应用）

src/
├── controllers/
├── services/
├── models/
├── repositories/
└── utils/

src/
├── controllers/
├── services/
├── models/
├── repositories/
└── utils/

Decision Framework

决策框架

When making architectural decisions, evaluate against these criteria:

Simplicity - Start simple, evolve when needed
Team Skills - Match architecture to team capabilities
Requirements - Let business needs drive decisions
Scalability - Consider growth trajectory
Maintainability - Optimize for change

制定架构决策时，需根据以下标准评估：

简洁性 - 从简单开始，按需演进
团队技能 - 架构与团队能力匹配
需求导向 - 让业务需求驱动决策
可扩展性 - 考虑未来增长趋势
可维护性 - 为变更优化设计

Trade-off Analysis Template

权衡分析模板

Use this template to document architectural decisions:

markdown

undefined

使用此模板记录架构决策：

markdown

undefined

Decision: [What we're deciding]

决策：[决策内容]

Context

背景

[Why this decision is needed now]

[当前为何需要此决策]

Options Considered

备选方案

Option A: [Description]
Option B: [Description]

方案A：[描述]
方案B：[描述]

Trade-offs

权衡对比

Criteria	Option A	Option B
Complexity	Low	High
Scalability	Medium	High
Team familiarity	High	Low

评估标准	方案A	方案B
复杂度	低	高
可扩展性	中等	高
团队熟悉度	高	低

Decision

最终决策

We chose [Option] because [reasoning].

我们选择[方案]，原因是[决策依据]。

Consequences

影响

[What this enables]
[What this constrains]

undefined

[此决策带来的优势]
[此决策带来的限制]

undefined

Validation Checklist

验证清单

After selecting an architecture, validate against:

Architecture Validation:
- [ ] Matches project size and complexity
- [ ] Aligns with team skills and experience
- [ ] Supports current requirements
- [ ] Allows for anticipated growth
- [ ] Dependencies flow inward (core has no external deps)
- [ ] Clear boundaries between modules/layers
- [ ] Testing strategy is feasible
- [ ] Trade-offs are documented

If validation fails, reconsider the pattern selection or adjust the implementation approach.

选定架构后，需对照以下内容验证：

Architecture Validation:
- [ ] Matches project size and complexity
- [ ] Aligns with team skills and experience
- [ ] Supports current requirements
- [ ] Allows for anticipated growth
- [ ] Dependencies flow inward (core has no external deps)
- [ ] Clear boundaries between modules/layers
- [ ] Testing strategy is feasible
- [ ] Trade-offs are documented

若验证不通过，请重新考虑模式选择或调整实现方案。