Back to Details

distributed-systems

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Distributed Systems Patterns

分布式系统模式

Comprehensive patterns for building reliable distributed systems. Each category has individual rule files in 
rules/
loaded on-demand.
构建可靠分布式系统的综合模式。每个类别在
rules/
目录下都有单独的规则文件，可按需加载。

Quick Reference

快速参考

CategoryRulesImpactWhen to Use
Distributed Locks3CRITICALRedis/Redlock locks, PostgreSQL advisory locks, fencing tokens
Resilience3CRITICALCircuit breakers, retry with backoff, bulkhead isolation
Idempotency3HIGHIdempotency keys, request dedup, database-backed idempotency
Rate Limiting3HIGHToken bucket, sliding window, distributed rate limits
Edge Computing2HIGHEdge workers, V8 isolates, CDN caching, geo-routing
Event-Driven2HIGHEvent sourcing, CQRS, transactional outbox, sagas
Total: 16 rules across 6 categories
类别规则数量影响级别适用场景
分布式锁3关键Redis/Redlock锁、PostgreSQL advisory锁、防护令牌
弹性机制3关键断路器、带退避的重试、舱壁隔离
幂等性3高幂等键、请求去重、基于数据库的幂等性
限流3高令牌桶、滑动窗口、分布式限流
边缘计算2高边缘工作器、V8隔离环境、CDN缓存、地理路由
事件驱动2高事件溯源、CQRS、事务性发件箱、Saga模式
总计：6个类别下共16条规则

Quick Start

快速开始

python
undefined
python
undefined

Redis distributed lock with Lua scripts

基于Lua脚本的Redis分布式锁

async with RedisLock(redis_client, "payment:order-123"): await process_payment(order_id)
async with RedisLock(redis_client, "payment:order-123"): await process_payment(order_id)

Circuit breaker for external APIs

用于外部API的断路器

@circuit_breaker(failure_threshold=5, recovery_timeout=30) @retry(max_attempts=3, base_delay=1.0) async def call_external_api(): ...
@circuit_breaker(failure_threshold=5, recovery_timeout=30) @retry(max_attempts=3, base_delay=1.0) async def call_external_api(): ...

Idempotent API endpoint

幂等API端点

@router.post("/payments") async def create_payment( data: PaymentCreate, idempotency_key: str = Header(..., alias="Idempotency-Key"), ): return await idempotent_execute(db, idempotency_key, "/payments", process)
@router.post("/payments") async def create_payment( data: PaymentCreate, idempotency_key: str = Header(..., alias="Idempotency-Key"), ): return await idempotent_execute(db, idempotency_key, "/payments", process)

Token bucket rate limiting

令牌桶限流

limiter = TokenBucketLimiter(redis_client, capacity=100, refill_rate=10) if await limiter.is_allowed(f"user:{user_id}"): await handle_request()
undefined
limiter = TokenBucketLimiter(redis_client, capacity=100, refill_rate=10) if await limiter.is_allowed(f"user:{user_id}"): await handle_request()
undefined

Distributed Locks

分布式锁

Coordinate exclusive access to resources across multiple service instances.
RuleFileKey Pattern
Redis & Redlock
rules/locks-redis-redlock.md
Lua scripts, SET NX, multi-node quorum
PostgreSQL Advisory
rules/locks-postgres-advisory.md
Session/transaction locks, lock ID strategies
Fencing Tokens
rules/locks-fencing-tokens.md
Owner validation, TTL, heartbeat extension
协调多个服务实例对资源的独占访问。
规则文件核心模式
Redis & Redlock
rules/locks-redis-redlock.md
Lua脚本、SET NX、多节点仲裁
PostgreSQL Advisory锁
rules/locks-postgres-advisory.md
会话/事务锁、锁ID策略
防护令牌
rules/locks-fencing-tokens.md
所有者验证、TTL、心跳续期

Resilience

弹性机制

Production-grade fault tolerance for distributed systems.
RuleFileKey Pattern
Circuit Breaker
rules/resilience-circuit-breaker.md
CLOSED/OPEN/HALF_OPEN states, sliding window
Retry & Backoff
rules/resilience-retry-backoff.md
Exponential backoff, jitter, error classification
Bulkhead Isolation
rules/resilience-bulkhead.md
Semaphore tiers, rejection policies, queue depth
面向生产环境的分布式系统容错机制。
规则文件核心模式
断路器
rules/resilience-circuit-breaker.md
CLOSED/OPEN/HALF_OPEN状态、滑动窗口
重试与退避
rules/resilience-retry-backoff.md
指数退避、抖动、错误分类
舱壁隔离
rules/resilience-bulkhead.md
信号量分层、拒绝策略、队列深度

Idempotency

幂等性

Ensure operations can be safely retried without unintended side effects.
RuleFileKey Pattern
Idempotency Keys
rules/idempotency-keys.md
Deterministic hashing, Stripe-style headers
Request Dedup
rules/idempotency-dedup.md
Event consumer dedup, Redis + DB dual layer
Database-Backed
rules/idempotency-database.md
Unique constraints, upsert, TTL cleanup
确保操作可安全重试而不会产生意外副作用。
规则文件核心模式
幂等键
rules/idempotency-keys.md
确定性哈希、Stripe风格请求头
请求去重
rules/idempotency-dedup.md
事件消费者去重、Redis + 数据库双层存储
基于数据库的实现
rules/idempotency-database.md
唯一约束、Upsert操作、TTL清理

Rate Limiting

限流

Protect APIs with distributed rate limiting using Redis.
RuleFileKey Pattern
Token Bucket
rules/ratelimit-token-bucket.md
Redis Lua scripts, burst capacity, refill rate
Sliding Window
rules/ratelimit-sliding-window.md
Sorted sets, precise counting, no boundary spikes
Distributed Limits
rules/ratelimit-distributed.md
SlowAPI + Redis, tiered limits, response headers
使用Redis实现分布式限流以保护API。
规则文件核心模式
令牌桶
rules/ratelimit-token-bucket.md
Redis Lua脚本、突发容量、填充速率
滑动窗口
rules/ratelimit-sliding-window.md
有序集合、精确计数、无边界峰值
分布式限流
rules/ratelimit-distributed.md
SlowAPI + Redis、分层限流、响应头标识

Edge Computing

边缘计算

Edge runtime patterns for Cloudflare Workers, Vercel Edge, and Deno Deploy.
RuleFileKey Pattern
Edge Workers
rules/edge-workers.md
V8 isolate constraints, Web APIs, geo-routing, auth at edge
Edge Caching
rules/edge-caching.md
Cache-aside at edge, CDN headers, KV storage, stale-while-revalidate
适用于Cloudflare Workers、Vercel Edge和Deno Deploy的边缘运行时模式。
规则文件核心模式
边缘工作器
rules/edge-workers.md
V8隔离环境约束、Web API、地理路由、边缘认证
边缘缓存
rules/edge-caching.md
边缘缓存旁路、CDN请求头、KV存储、stale-while-revalidate策略

Event-Driven

事件驱动

Event sourcing, CQRS, saga orchestration, and reliable messaging patterns.
RuleFileKey Pattern
Event Sourcing
rules/event-sourcing.md
Event-sourced aggregates, CQRS read models, optimistic concurrency
Event Messaging
rules/event-messaging.md
Transactional outbox, saga compensation, idempotent consumers
事件溯源、CQRS、Saga编排和可靠消息传递模式。
规则文件核心模式
事件溯源
rules/event-sourcing.md
事件溯源聚合根、CQRS读模型、乐观并发控制
事件消息传递
rules/event-messaging.md
事务性发件箱、Saga补偿操作、幂等消费者

Key Decisions

关键决策

DecisionRecommendation
Lock backendRedis for speed, PostgreSQL if already using it, Redlock for HA
Lock TTL2-3x expected operation time
Circuit breaker recoveryHalf-open probe with sliding window
Retry algorithmExponential backoff + full jitter
Bulkhead isolationSemaphore-based tiers (Critical/Standard/Optional)
Idempotency storageRedis (speed) + DB (durability), 24-72h TTL
Rate limit algorithmToken bucket for most APIs, sliding window for strict quotas
Rate limit storageRedis (distributed, atomic Lua scripts)
决策项推荐方案
锁后端追求速度选Redis；若已使用PostgreSQL则选它；高可用场景选Redlock
锁TTL设为预期操作时间的2-3倍
断路器恢复半开状态下使用滑动窗口进行探测
重试算法指数退避 + 全抖动
舱壁隔离基于信号量的分层（核心/标准/可选）
幂等性存储Redis（速度） + 数据库（持久性），设置24-72小时TTL
限流算法多数API用令牌桶；严格配额场景用滑动窗口
限流存储Redis（分布式、原子Lua脚本）

Anti-Patterns (FORBIDDEN)

反模式（禁止使用）

python
undefined
python
undefined

LOCKS: Never forget TTL (causes deadlocks)

锁：绝不要忘记设置TTL（会导致死锁）

await redis.set(f"lock:{name}", "1") # WRONG - no expiry!
await redis.set(f"lock:{name}", "1") # 错误 - 未设置过期时间！

LOCKS: Never release without owner check

锁：绝不要在不检查所有者的情况下释放锁

await redis.delete(f"lock:{name}") # WRONG - might release others' lock
await redis.delete(f"lock:{name}") # 错误 - 可能释放其他实例的锁！

RESILIENCE: Never retry non-retryable errors

弹性机制：绝不要重试不可重试的错误

@retry(max_attempts=5, retryable_exceptions={Exception}) # Retries 401!
@retry(max_attempts=5, retryable_exceptions={Exception}) # 会重试401错误！

RESILIENCE: Never put retry outside circuit breaker

弹性机制：绝不要将重试放在断路器外层

@retry # Would retry when circuit is open! @circuit_breaker async def call(): ...
@retry # 断路器打开时仍会重试！ @circuit_breaker async def call(): ...

IDEMPOTENCY: Never use non-deterministic keys

幂等性：绝不要使用非确定性的键

key = str(uuid.uuid4()) # Different every time!
key = str(uuid.uuid4()) # 每次都不同！

IDEMPOTENCY: Never cache error responses

幂等性：绝不要缓存错误响应

if response.status_code >= 400: await cache_response(key, response) # Errors should retry!
if response.status_code >= 400: await cache_response(key, response) # 错误应该允许重试！

RATE LIMITING: Never use in-memory counters in distributed systems

限流：绝不要在分布式系统中使用内存计数器

request_counts = {} # Lost on restart, not shared across instances
undefined
request_counts = {} # 重启后丢失，无法在实例间共享
undefined

Detailed Documentation

详细文档

ResourceDescription
scripts/Templates: lock implementations, circuit breaker, rate limiter
checklists/Pre-flight checklists for each pattern category
references/Deep dives: Redlock algorithm, bulkhead tiers, token bucket
examples/Complete integration examples
资源描述
scripts/模板：锁实现、断路器、限流器
checklists/各模式类别的预启动检查清单
references/深度解析：Redlock算法、舱壁分层、令牌桶
examples/完整集成示例

Related Skills

相关技能

  • caching
    - Redis caching patterns, cache as fallback
  • background-jobs
    - Job deduplication, async processing with retry
  • observability-monitoring
    - Metrics and alerting for circuit breaker state changes
  • error-handling-rfc9457
    - Structured error responses for resilience failures
  • auth-patterns
    - API key management, authentication integration
  • caching
    - Redis缓存模式、缓存作为降级方案
  • background-jobs
    - 任务去重、带重试的异步处理
  • observability-monitoring
    - 断路器状态变化的指标与告警
  • error-handling-rfc9457
    - 弹性机制失败的结构化错误响应
  • auth-patterns
    - API密钥管理、认证集成