software-patterns

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Software Patterns Primer

软件模式入门指南

Overview

概述

Architectural patterns solve specific structural problems. This skill provides a decision framework for when to apply each pattern, not a catalog to memorize.

Core philosophy: Patterns solve problems. No problem? No pattern needed.

架构模式用于解决特定的结构性问题。本技能提供的是何时应用每种模式的决策框架，而非需要死记硬背的模式目录。

核心理念： 模式是用来解决问题的。没有问题？就不需要模式。

When to Use This Skill

何时使用本技能

Activate when:

Designing a new system or major feature
Adding external service integrations
Code becomes difficult to test or modify
Services start calling each other in circles
Failures in one component cascade to others
Business logic scatters across multiple locations

在以下场景激活本技能：

设计新系统或核心功能
集成外部服务
代码变得难以测试或修改
服务之间开始循环调用
某个组件的故障扩散到其他组件
业务逻辑分散在多个位置

Pattern Hierarchy

模式层级

Foundational (Apply by Default)

基础模式（默认应用）

These patterns provide the structural foundation for maintainable systems. Apply unless you have specific reasons not to.

Pattern	Problem Solved	Signal to Apply
Dependency Injection	Tight coupling, untestable code	Classes instantiate their own dependencies
Service-Oriented Architecture	Monolithic tangles, unclear boundaries	Business logic scattered, no clear ownership

这些模式为可维护系统提供结构基础。除非有特殊理由，否则应默认应用。

模式	解决的问题	应用信号
Dependency Injection	紧耦合、不可测试的代码	类自行实例化依赖项
Service-Oriented Architecture	单体应用混乱、边界不清晰	业务逻辑分散，无明确归属

Situational (Apply When Triggered)

场景模式（按需应用）

These patterns address specific problems. Don't apply preemptively.

Pattern	Problem Solved	Signal to Apply
Repository	Data access coupling	Services know about database details
Domain Events	Circular dependencies, temporal coupling	Service A calls B calls C calls A
Anti-Corruption Layer	External system coupling	External API changes break your code
Circuit Breaker	Cascading failures	One slow service takes down everything

→ Foundational Patterns Detail → Situational Patterns Detail

这些模式用于解决特定问题。不要预先应用。

模式	解决的问题	应用信号
Repository	数据访问耦合	服务知晓数据库细节
Domain Events	循环依赖、时间耦合	服务A调用B，B调用C，C调用A
Anti-Corruption Layer	外部系统耦合	外部API变更导致你的代码崩溃
Circuit Breaker	故障扩散	一个缓慢的服务导致整个系统瘫痪

→ 基础模式详情 → 场景模式详情

Quick Decision Tree

快速决策树

Is code hard to test?
├─ Yes → Apply Dependency Injection
└─ No → Continue

Is business logic scattered?
├─ Yes → Apply Service-Oriented Architecture
└─ No → Continue

Do services know database details?
├─ Yes → Apply Repository Pattern
└─ No → Continue

Do services call each other in cycles?
├─ Yes → Apply Domain Events
└─ No → Continue

Does external API change break your code?
├─ Yes → Apply Anti-Corruption Layer
└─ No → Continue

Does one slow service break everything?
├─ Yes → Apply Circuit Breaker
└─ No → Current patterns sufficient

→ Complete Decision Trees

Is code hard to test?
├─ Yes → Apply Dependency Injection
└─ No → Continue

Is business logic scattered?
├─ Yes → Apply Service-Oriented Architecture
└─ No → Continue

Do services know database details?
├─ Yes → Apply Repository Pattern
└─ No → Continue

Do services call each other in cycles?
├─ Yes → Apply Domain Events
└─ No → Continue

Does external API change break your code?
├─ Yes → Apply Anti-Corruption Layer
└─ No → Continue

Does one slow service break everything?
├─ Yes → Apply Circuit Breaker
└─ No → Current patterns sufficient

→ 完整决策树

Pattern Selection by Problem

按问题选择模式

"My code is hard to test"

"我的代码难以测试"

Primary: Dependency Injection Why: Dependencies passed in = dependencies mockable

首选： Dependency Injection 原因： 传入依赖项 = 可模拟依赖项

"I don't know where business logic lives"

"我不知道业务逻辑在哪里"

Primary: Service-Oriented Architecture Secondary: Repository (if data access is the confusion) Why: Clear boundaries = clear ownership

首选： Service-Oriented Architecture 次选： Repository（如果混乱源于数据访问） 原因： 清晰的边界 = 明确的归属

"External API changes keep breaking my code"

"外部API变更总是导致我的代码崩溃"

Primary: Anti-Corruption Layer Why: Translation layer absorbs external volatility

首选： Anti-Corruption Layer 原因： 转换层可吸收外部变化带来的影响

"Services call each other in circles"

"服务之间循环调用"

Primary: Domain Events Why: Publish/subscribe breaks circular dependencies

首选： Domain Events 原因： 发布/订阅模式可打破循环依赖

"One slow service takes down everything"

"一个缓慢的服务导致整个系统瘫痪"

Primary: Circuit Breaker Secondary: Retry with Backoff Why: Fail fast prevents cascade

首选： Circuit Breaker 次选： 退避重试（Retry with Backoff） 原因： 快速失败可防止故障扩散

"Database changes ripple through codebase"

"数据库变更影响整个代码库"

Primary: Repository Pattern Why: Abstraction layer isolates data access

→ Real-World Examples

首选： Repository Pattern 原因： 抽象层可隔离数据访问

→ 真实场景示例

Implementation Priority

实现优先级

When starting a new system:

First: Establish DI container/pattern
Second: Define service boundaries (SOA)
Third: Add Repository for data access
Then: Layer situational patterns as problems emerge

When refactoring existing system:

First: Identify the specific pain point
Second: Apply the minimal pattern that solves it
Third: Validate improvement before adding more

启动新系统时：

第一步： 建立DI容器/模式
第二步： 定义服务边界（SOA）
第三步： 为数据访问添加Repository
之后： 随着问题出现，逐步添加场景模式

重构现有系统时：

第一步： 识别具体痛点
第二步： 应用能解决问题的最简模式
第三步： 在添加更多模式前，验证改进效果

Key Principles

核心原则

Minimal Sufficient Pattern Apply the simplest pattern that solves the problem. Over-architecting creates its own maintenance burden.

Problem-First Selection Never ask "which patterns should I use?" Ask "what problem am I solving?"

Composition Over Prescription Patterns combine. Repository + Domain Events + Circuit Breaker is common for external data sources.

Explicit Over Implicit Dependencies should be visible. Service Locator hides them; DI exposes them.

最小足够模式 应用能解决问题的最简单模式。过度架构会带来自身的维护负担。

问题优先选择 永远不要问“我应该使用哪些模式？”，而要问“我正在解决什么问题？”

组合优于规定 模式可以组合使用。Repository + Domain Events + Circuit Breaker是外部数据源场景的常见组合。

显式优于隐式 依赖关系应该是可见的。Service Locator会隐藏依赖；DI则会暴露依赖。

Navigation

Red Flags - STOP

危险信号 - 立即停止

STOP when:

"Let me add all these patterns upfront" → Apply only what solves current problems
"This pattern is best practice" → Best practice for what problem?
"We might need this later" → YAGNI - add when needed
"Service Locator is simpler" → Hidden dependencies cause testing pain
"I'll just call this service directly" → Consider if events would decouple better
"External API is stable, no need for ACL" → APIs always change eventually

ALL of these mean: STOP. Identify the specific problem first.

在以下情况时立即停止：

“我要一次性添加所有这些模式” → 只应用能解决当前问题的模式
“这个模式是最佳实践” → 这个最佳实践是解决什么问题的？
“我们以后可能需要这个” → YAGNI（You Aren't Gonna Need It，你不会需要它）—— 需要时再添加
“Service Locator更简单” → 隐藏的依赖会导致测试困难
“我直接调用这个服务就行” → 考虑事件是否能更好地实现解耦
“外部API很稳定，不需要ACL” → API最终总会发生变更

以上所有情况都意味着：立即停止。先识别具体问题。

Integration with Other Skills

与其他技能的集成

test-driven-development: DI enables testability; TDD validates pattern application
systematic-debugging: Clear boundaries (SOA) simplify debugging
root-cause-tracing: Well-structured services have clearer call chains

test-driven-development：DI提升可测试性；TDD验证模式的应用效果
systematic-debugging：清晰的边界（SOA）简化调试过程
root-cause-tracing：结构良好的服务拥有更清晰的调用链

Pattern Combinations

模式组合

Common effective combinations:

Scenario	Patterns
New microservice	DI + SOA + Repository
External API integration	DI + ACL + Circuit Breaker
Event-driven system	DI + SOA + Domain Events
Data-heavy application	DI + SOA + Repository + Unit of Work

Remember: Patterns exist to solve problems. Start with the problem, not the pattern.

常见的有效组合：

场景	模式
新微服务	DI + SOA + Repository
外部API集成	DI + ACL + Circuit Breaker
事件驱动系统	DI + SOA + Domain Events
数据密集型应用	DI + SOA + Repository + Unit of Work

谨记： 模式的存在是为了解决问题。从问题出发，而非从模式出发。