分布式系统模式指南：16个核心规则实现高可靠弹性架构（含Redis锁、断路器、幂等性）

distributed-systems by yonatangross/orchestkit

124 周安装量

140 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/yonatangross/orchestkit --skill distributed-systems

微服务架构系统架构分布式系统

🇨🇳中文介绍

分布式系统模式

构建可靠分布式系统的全面模式。每个类别在 rules/ 目录下都有独立的规则文件，按需加载。

快速参考

类别	规则数量	影响级别	使用场景
分布式锁	3	关键	Redis/Redlock 锁、PostgreSQL 咨询锁、防护令牌
弹性	3	关键	断路器、退避重试、舱壁隔离
幂等性	3	高	幂等键、请求去重、数据库支持的幂等性
速率限制	3	高	令牌桶、滑动窗口、分布式速率限制
边缘计算	2	高	边缘工作器、V8 隔离、CDN 缓存、地理路由
事件驱动

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

相关 Skills

PostgreSQL表设计最佳实践：核心规则、数据类型选择与常见陷阱详解

12,500 周安装

API设计指南：REST/GraphQL设计原则、规范文档与版本控制策略

11,500 周安装

Android 整洁架构指南：模块化设计、依赖注入与数据层实现

1,400 周安装

Kotlin Ktor 服务器模式指南：构建健壮 HTTP API 的架构与最佳实践

1,200 周安装

总计：6 个类别，共 16 条规则

# Redis distributed lock with Lua scripts
async with RedisLock(redis_client, "payment:order-123"):
    await process_payment(order_id)

# Circuit breaker for external APIs
@circuit_breaker(failure_threshold=5, recovery_timeout=30)
@retry(max_attempts=3, base_delay=1.0)
async def call_external_api():
    ...

# Idempotent API endpoint
@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()

跨多个服务实例协调对资源的独占访问。

规则	文件	关键模式
Redis & Redlock	`${CLAUDE_SKILL_DIR}/rules/locks-redis-redlock.md`	Lua 脚本、SET NX、多节点仲裁
PostgreSQL 咨询锁	`${CLAUDE_SKILL_DIR}/rules/locks-postgres-advisory.md`	会话/事务锁、锁 ID 策略
防护令牌	`${CLAUDE_SKILL_DIR}/rules/locks-fencing-tokens.md`	所有者验证、TTL、心跳续期

生产级分布式系统容错能力。

规则	文件	关键模式
断路器	`${CLAUDE_SKILL_DIR}/rules/resilience-circuit-breaker.md`	CLOSED/OPEN/HALF_OPEN 状态、滑动窗口
重试与退避	`${CLAUDE_SKILL_DIR}/rules/resilience-retry-backoff.md`	指数退避、抖动、错误分类
舱壁隔离	`${CLAUDE_SKILL_DIR}/rules/resilience-bulkhead.md`	信号量层级、拒绝策略、队列深度

确保操作可以安全重试而不会产生意外副作用。

规则	文件	关键模式
幂等键	`${CLAUDE_SKILL_DIR}/rules/idempotency-keys.md`	确定性哈希、Stripe 风格头部
请求去重	`${CLAUDE_SKILL_DIR}/rules/idempotency-dedup.md`	事件消费者去重、Redis + DB 双层
数据库支持	`${CLAUDE_SKILL_DIR}/rules/idempotency-database.md`	唯一约束、upsert、TTL 清理

使用 Redis 进行分布式速率限制以保护 API。

规则	文件	关键模式
令牌桶	`${CLAUDE_SKILL_DIR}/rules/ratelimit-token-bucket.md`	Redis Lua 脚本、突发容量、补充速率
滑动窗口	`${CLAUDE_SKILL_DIR}/rules/ratelimit-sliding-window.md`	有序集合、精确计数、无边界尖峰
分布式限制	`${CLAUDE_SKILL_DIR}/rules/ratelimit-distributed.md`	SlowAPI + Redis、分层限制、响应头部

适用于 Cloudflare Workers、Vercel Edge 和 Deno Deploy 的边缘运行时模式。

规则	文件	关键模式
边缘工作器	`${CLAUDE_SKILL_DIR}/rules/edge-workers.md`	V8 隔离约束、Web API、地理路由、边缘认证
边缘缓存	`${CLAUDE_SKILL_DIR}/rules/edge-caching.md`	边缘缓存旁路、CDN 头部、KV 存储、陈旧时重新验证

事件溯源、CQRS、Saga 编排和可靠消息传递模式。

规则	文件	关键模式
事件溯源	`${CLAUDE_SKILL_DIR}/rules/event-sourcing.md`	事件溯源聚合、CQRS 读取模型、乐观并发
事件消息传递	`${CLAUDE_SKILL_DIR}/rules/event-messaging.md`	事务性发件箱、Saga 补偿、幂等消费者

决策	推荐
锁后端	Redis 用于速度，PostgreSQL 如果已在使用，Redlock 用于高可用性
锁 TTL	预期操作时间的 2-3 倍
断路器恢复	使用滑动窗口的半开探测
重试算法	指数退避 + 完全抖动
舱壁隔离	基于信号量的层级（关键/标准/可选）
幂等性存储	Redis（速度）+ DB（持久性），24-72 小时 TTL
速率限制算法	令牌桶适用于大多数 API，滑动窗口适用于严格配额
速率限制存储	Redis（分布式、原子性 Lua 脚本）

没有单独的事件溯源/Saga/CQRS 技能——它们是分布式系统中的规则。但大多数项目永远不需要它们。

模式	面试	黑客松	MVP	增长期	企业级	更简单的替代方案
事件溯源	过度设计	过度设计	过度设计	过度设计	有充分理由时	带状态列的仅追加表
Saga 编排	过度设计	过度设计	过度设计	选择性使用	适用时	带手动回滚的顺序服务调用
断路器	过度设计	过度设计	临界情况	适用时	必需	带超时的 Try/except
分布式锁	过度设计	过度设计	临界情况	适用时	必需	数据库行级锁（SELECT FOR UPDATE）
CQRS	过度设计	过度设计	过度设计	过度设计	有充分理由时	读写单一模型
事务性发件箱	过度设计	过度设计	过度设计	选择性使用	适用时	提交后直接发布
速率限制	过度设计	过度设计	仅简单方案	适用时	必需	Nginx 速率限制或云 WAF

经验法则： 如果你有单个服务器进程，则不需要分布式系统模式。使用进程内替代方案。仅在实际有多个实例时才添加分布式功能。

反模式（禁止使用）

# LOCKS: Never forget TTL (causes deadlocks)
await redis.set(f"lock:{name}", "1")  # WRONG - no expiry!

# LOCKS: Never release without owner check
await redis.delete(f"lock:{name}")  # WRONG - might release others' lock

# RESILIENCE: Never retry non-retryable errors
@retry(max_attempts=5, retryable_exceptions={Exception})  # Retries 401!

# RESILIENCE: Never put retry outside circuit breaker
@retry  # Would retry when circuit is open!
@circuit_breaker
async def call(): ...

# IDEMPOTENCY: Never use non-deterministic keys
key = str(uuid.uuid4())  # Different every time!

# IDEMPOTENCY: Never cache error responses
if response.status_code >= 400:
    await cache_response(key, response)  # Errors should retry!

# RATE LIMITING: Never use in-memory counters in distributed systems
request_counts = {}  # Lost on restart, not shared across instances

资源	描述
`${CLAUDE_SKILL_DIR}/scripts/`	模板：锁实现、断路器、速率限制器
`${CLAUDE_SKILL_DIR}/checklists/`	每个模式类别的飞行前检查清单
`${CLAUDE_SKILL_DIR}/references/`	深度解析：Redlock 算法、舱壁层级、令牌桶
`${CLAUDE_SKILL_DIR}/examples/`	完整集成示例

caching - Redis 缓存模式、缓存作为后备方案
background-jobs - 作业去重、带重试的异步处理
observability-monitoring - 断路器状态变化的指标和告警
error-handling-rfc9457 - 弹性故障的结构化错误响应
auth-patterns - API 密钥管理、身份验证集成

2026 年 2 月 14 日

🇺🇸English

Distributed Systems Patterns

Comprehensive patterns for building reliable distributed systems. Each category has individual rule files in rules/ loaded on-demand.

Quick Reference

Category	Rules	Impact	When to Use
Distributed Locks	3	CRITICAL	Redis/Redlock locks, PostgreSQL advisory locks, fencing tokens
Resilience	3	CRITICAL	Circuit breakers, retry with backoff, bulkhead isolation
Idempotency	3	HIGH	Idempotency keys, request dedup, database-backed idempotency
Rate Limiting	3	HIGH	Token bucket, sliding window, distributed rate limits
Edge Computing	2	HIGH	Edge workers, V8 isolates, CDN caching, geo-routing
Event-Driven	2	HIGH	Event sourcing, CQRS, transactional outbox, sagas

Total: 16 rules across 6 categories

Quick Start

# Redis distributed lock with Lua scripts
async with RedisLock(redis_client, "payment:order-123"):
    await process_payment(order_id)

# Circuit breaker for external APIs
@circuit_breaker(failure_threshold=5, recovery_timeout=30)
@retry(max_attempts=3, base_delay=1.0)
async def call_external_api():
    ...

# Idempotent API endpoint
@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()

Distributed Locks

Coordinate exclusive access to resources across multiple service instances.

Rule	File	Key Pattern
Redis & Redlock	`${CLAUDE_SKILL_DIR}/rules/locks-redis-redlock.md`	Lua scripts, SET NX, multi-node quorum
PostgreSQL Advisory	`${CLAUDE_SKILL_DIR}/rules/locks-postgres-advisory.md`	Session/transaction locks, lock ID strategies
Fencing Tokens	`${CLAUDE_SKILL_DIR}/rules/locks-fencing-tokens.md`	Owner validation, TTL, heartbeat extension

Resilience

Production-grade fault tolerance for distributed systems.

Rule	File	Key Pattern
Circuit Breaker	`${CLAUDE_SKILL_DIR}/rules/resilience-circuit-breaker.md`	CLOSED/OPEN/HALF_OPEN states, sliding window
Retry & Backoff	`${CLAUDE_SKILL_DIR}/rules/resilience-retry-backoff.md`	Exponential backoff, jitter, error classification
Bulkhead Isolation	`${CLAUDE_SKILL_DIR}/rules/resilience-bulkhead.md`	Semaphore tiers, rejection policies, queue depth

Idempotency

Ensure operations can be safely retried without unintended side effects.

Rule	File	Key Pattern
Idempotency Keys	`${CLAUDE_SKILL_DIR}/rules/idempotency-keys.md`	Deterministic hashing, Stripe-style headers
Request Dedup	`${CLAUDE_SKILL_DIR}/rules/idempotency-dedup.md`	Event consumer dedup, Redis + DB dual layer
Database-Backed	`${CLAUDE_SKILL_DIR}/rules/idempotency-database.md`	Unique constraints, upsert, TTL cleanup

Rate Limiting

Protect APIs with distributed rate limiting using Redis.

Rule	File	Key Pattern
Token Bucket	`${CLAUDE_SKILL_DIR}/rules/ratelimit-token-bucket.md`	Redis Lua scripts, burst capacity, refill rate
Sliding Window	`${CLAUDE_SKILL_DIR}/rules/ratelimit-sliding-window.md`	Sorted sets, precise counting, no boundary spikes
Distributed Limits	`${CLAUDE_SKILL_DIR}/rules/ratelimit-distributed.md`	SlowAPI + Redis, tiered limits, response headers

Edge Computing

Edge runtime patterns for Cloudflare Workers, Vercel Edge, and Deno Deploy.

Rule	File	Key Pattern
Edge Workers	`${CLAUDE_SKILL_DIR}/rules/edge-workers.md`	V8 isolate constraints, Web APIs, geo-routing, auth at edge
Edge Caching	`${CLAUDE_SKILL_DIR}/rules/edge-caching.md`	Cache-aside at edge, CDN headers, KV storage, stale-while-revalidate

Event-Driven

Event sourcing, CQRS, saga orchestration, and reliable messaging patterns.

Rule	File	Key Pattern
Event Sourcing	`${CLAUDE_SKILL_DIR}/rules/event-sourcing.md`	Event-sourced aggregates, CQRS read models, optimistic concurrency
Event Messaging	`${CLAUDE_SKILL_DIR}/rules/event-messaging.md`	Transactional outbox, saga compensation, idempotent consumers

Key Decisions

Decision	Recommendation
Lock backend	Redis for speed, PostgreSQL if already using it, Redlock for HA
Lock TTL	2-3x expected operation time
Circuit breaker recovery	Half-open probe with sliding window
Retry algorithm	Exponential backoff + full jitter
Bulkhead isolation	Semaphore-based tiers (Critical/Standard/Optional)
Idempotency storage	Redis (speed) + DB (durability), 24-72h TTL
Rate limit algorithm	Token bucket for most APIs, sliding window for strict quotas
Rate limit storage	Redis (distributed, atomic Lua scripts)

When NOT to Use

No separate event-sourcing/saga/CQRS skills exist — they are rules within distributed-systems. But most projects never need them.

Pattern	Interview	Hackathon	MVP	Growth	Enterprise	Simpler Alternative
Event sourcing	OVERKILL	OVERKILL	OVERKILL	OVERKILL	WHEN JUSTIFIED	Append-only table with status column
Saga orchestration	OVERKILL	OVERKILL	OVERKILL	SELECTIVE	APPROPRIATE	Sequential service calls with manual rollback
Circuit breaker	OVERKILL	OVERKILL	BORDERLINE	APPROPRIATE	REQUIRED	Try/except with timeout
Distributed locks	OVERKILL	OVERKILL	BORDERLINE

Rule of thumb: If you have a single server process, you do not need distributed systems patterns. Use in-process alternatives. Add distribution only when you actually have multiple instances.

Anti-Patterns (FORBIDDEN)

# LOCKS: Never forget TTL (causes deadlocks)
await redis.set(f"lock:{name}", "1")  # WRONG - no expiry!

# LOCKS: Never release without owner check
await redis.delete(f"lock:{name}")  # WRONG - might release others' lock

# RESILIENCE: Never retry non-retryable errors
@retry(max_attempts=5, retryable_exceptions={Exception})  # Retries 401!

# RESILIENCE: Never put retry outside circuit breaker
@retry  # Would retry when circuit is open!
@circuit_breaker
async def call(): ...

# IDEMPOTENCY: Never use non-deterministic keys
key = str(uuid.uuid4())  # Different every time!

# IDEMPOTENCY: Never cache error responses
if response.status_code >= 400:
    await cache_response(key, response)  # Errors should retry!

# RATE LIMITING: Never use in-memory counters in distributed systems
request_counts = {}  # Lost on restart, not shared across instances

Detailed Documentation

Resource	Description
`${CLAUDE_SKILL_DIR}/scripts/`	Templates: lock implementations, circuit breaker, rate limiter
`${CLAUDE_SKILL_DIR}/checklists/`	Pre-flight checklists for each pattern category
`${CLAUDE_SKILL_DIR}/references/`	Deep dives: Redlock algorithm, bulkhead tiers, token bucket
`${CLAUDE_SKILL_DIR}/examples/`	Complete integration 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

Weekly Installs

Repository

yonatangross/orchestkit

GitHub Stars

132

First Seen

Feb 14, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykWarn

Installed on

codex88

opencode88

gemini-cli86

github-copilot85

cursor85

kimi-cli81

Laravel架构模式指南：生产级开发模式与最佳实践

1,100 周安装

分布式系统模式指南：16个核心规则实现高可靠弹性架构（含Redis锁、断路器、幂等性）

🇨🇳中文介绍

分布式系统模式

快速参考

相关 Skills

快速开始

分布式锁

弹性

幂等性

速率限制

边缘计算

事件驱动

关键决策

何时不使用