Community编程与开发github.com

sk-system-design

根据约束条件设计或评估分布式系统——服务边界、同步与事件驱动通信、一致性、故障行为及容量——并明确每个选择带来的权衡。适用于拆分或合并服务、选择调用方式、决策数据位置、审查架构方案或回答系统设计问题。

sk-system-design 是什么?

该技能(sk-system-design)是一个系统化的分布式系统设计方法论,旨在帮助AI开发者或工程师从约束条件出发,而非直接跳转到组件选择。它强调先明确负载、数据、一致性、可用性、延迟和所有权等关键约束,再据此划分服务边界。技能详细讨论了同步调用与事件驱动通信的适用场景与代价,指出每个远程调用都应预设失败,并提前定义超时、重试、幂等性和降级策略。同时,它严格区分严格一致性与最终一致性领域,建议将不可违反的不变量保持在同一服务的单次事务中,而其余部分可容忍最终一致性。最后,技能要求将设计文档化,包括约束、组件、流程、故障处理、权衡和拒绝的方案,从而将一张纯粹的示意图转变为可评估的架构设计。该技能适用于Claude Code、Cursor等AI编程助手或编码代理,帮助用户避免常见的设计陷阱(如无根据的队列、缓存或分片),并做出显式的权衡决策。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/vanhuydotcom/sk-skills/tree/HEAD/skills/sk-system-design

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

系统设计

失败模式是直接跳到组件。一个在列出约束之前先命名服务的设计,不过是画了框的猜测,无法被评估,因为没人知道它原本要达成什么。

1. 约束优先于组件

先写下这些。每一项都会排除一些设计:

  • 负载 —— 峰值每秒请求数,以及读写比例。读和写完全以不同的方式扩展,因此比例比绝对数值更能决定架构。
  • 数据 —— 总容量、增长速率以及单个条目的大小。
  • 一致性 —— 哪些内容必须立即正确,哪些可以容忍过时。几乎不会是“全部”;指出那必须严格的一小部分,正是让其余部分变得廉价的关键。
  • 可用性 —— 当该组件不可用时,对业务的影响是什么,以及可接受的降级行为。
  • 延迟 —— 用户面临路径的预算,基于百分位数而非平均值。
  • 所有权 —— 哪个团队部署并负责每个部分的告警。跨越团队边界会导致每次变更都产生协调成本。

大致估算即可,并明确说明。数量级足够用来选择架构,你没有的精度不值得花费精力。

2. 边界

按照共同变化的内容以及谁拥有数据来划分,而不是按名词来划分。如果一个服务不依赖另一个服务同时部署就无法部署,那么它只是一个服务分散在两个仓库里,还多了网络调用。

每份数据只有一个所有者负责写入。其他人通过所有者的接口或所有者发布的数据副本来读取。两个服务写入同一张表就是分布式单体:独立部署、共享故障,并且没有明确的位置来实施不变量。

倾向于更少、更大的服务,直到有真正的力量要求拆分——独立扩缩、独立所有权、确实不同的可用性需求。拆分做起来容易,撤销起来代价高昂,而且每一条边界都会把一次函数调用变成一次可能失败、需要重试、可能重复到达的网络调用。

3. 同步还是事件驱动

当调用方没有答案就无法继续,并且用户在等待时,使用同步调用。每个同步依赖都会将其停机时间加入你的停机时间,将其延迟加入你的预算,因此要数一数:同步接触五个服务的请求,其可用性低于其中任何一个服务。

当系统的其他部分需要知道某件事情发生了,但调用方不需要它们的响应时,发布一个事件。这解耦了可用性——消费者可以宕机而不导致写入失败。

诚实地面对代价。事件会带来最终一致性、乱序和重复投递,以及一条不再出现在单一堆栈跟踪中的调试路径。当你需要解耦时再接受这个权衡,而不是因为听起来现代。

当一次写入必须同时更新本地状态并通知其他人时,二者不能出现偏离。将事件与状态变更写入同一事务,并从那里发布事件,而不是先写入行再调用消息代理——这两个调用之间的间隙就是丢失消息的地方。

4. 假设每个远程调用都会失败

针对每一个远程调用,提前决定:

  • 超时 —— 一个显式的超时,要短于调用方自己的预算。没有超时的调用会把慢速依赖变成一次故障,因为线程会堆积起来。
  • 重试 —— 仅针对瞬时故障,仅带有退避和抖动,且仅当操作是幂等的。重试非幂等的写入会导致重复;所有客户端同步重试会把一个小问题变成一场踩踏。
  • 幂等性 —— 调用方提供的一个键,以便超时后的重试能被识别。调用方无法区分请求丢失和响应丢失,因此它会重试。
  • 降级 —— 当该依赖保持不可用时用户看到什么。提供缓存或部分结果通常优于错误页面,而在设计时决定这一点才使其成为可能。

5. 一致性

识别出绝不能破坏的不变量——资金守恒、库存不超卖、不重复收费——并将其保持在单个服务的单个事务内。这个约束比其他任何约束都更应该决定你的边界。

该不变量之外的一切都可以是最终一致的。当工作流跨多个服务时,将其建模为一系列本地事务,每个步骤附带补偿操作,并接受中间状态对外可见。

跨服务的分布式事务是最后的手段。补偿操作设计更难思考,但远更容易运维。

6. 写下来

约束条件   <负载、数据、一致性、可用性、延迟、所有权>
设计       <组件及每个组件拥有的内容>
流程       <两或三个重要的路径,按顺序>
故障       <每个依赖不可用时发生什么,以及用户看到什么>
权衡       <这个设计使得什么变得困难,以及在10倍负载下首先会改变什么>
已拒绝     <替代方案及其原因>

故障和已拒绝这两行将真正的设计与草图区分开。一个只描述幸福路径的方案,根本未经评估。

不要做

  • 不要为尚未测量或估计的负载添加队列、缓存或分片。
  • 不要在1倍规模时设计100倍规模的方案。要设计得让已知的下一步可行,并说明超出后首先会出什么问题。
  • 不要将单一选项呈现为不可避免。要指明你拒绝的方案。

Individual skills in this repo

This repo contains 5 individual skills — each has its own dedicated page.

sk-api

Design and change API contracts (REST, gRPC, protobuf, events) so existing callers keep working, covering resource and method shape, error models, pagination, versioning and the deploy order a breaking change requires. Use when adding or altering an endpoint, message or event, or when judging whether a proposed change breaks a consumer.

sk-code-review

Shows an agent how to design, debug, or review "sk code review" so the concrete output is a code change with a check. The procedure moves through Code review, Establish the diff first, What to look for, in priority order. Use it when a new assignment calls for this craft.

sk-go-service

Implement, extend or debug a handler, service or repository in a Go backend service, covering context propagation, error wrapping, transaction boundaries, tenancy scoping and table-driven tests. Use when writing or changing Go server code, adding an endpoint or gRPC method, touching a repository query, or diagnosing a panic, leak or flaky test in a Go service.

sk-python

Write and debug Python with attention to the traps that produce silent wrong behaviour — mutable defaults, late-binding closures, shallow copies, swallowed exceptions — plus typing, environment and packaging with uv or venv, and pytest structure. Use when writing a Python script, service or library, setting up a Python project, or debugging behaviour that looks impossible.

sk-react

Build and fix React and TypeScript components, covering state placement, effect dependencies, data fetching, list rendering and the re-render traps that cause stale or looping UI. Use when writing or changing a React component or hook, debugging stale data, an infinite render loop or a lost input, or reviewing frontend code.

相关技能