Community编程与开发github.com

sk-api

设计和变更API合约(REST、gRPC、protobuf、事件),确保现有调用方正常工作,涵盖资源和方法的形态、错误模型、分页、版本控制以及断裂变更所需的部署顺序。在添加或修改端点、消息或事件时,或判断提议的变更是否会破坏消费者时使用。

sk-api 是什么?

sk-api 技能专为开发和维护 API 合约的场景设计,旨在帮助工程师在设计或变更 REST、gRPC、protobuf 及事件驱动的 API 时,避免对现有消费者造成破坏。它强调了合约的本质——对无法控制的代码做出的承诺,任何错误都将由他人承担。技能详细阐述了资源命名(名词+动词方法)、字段暴露需谨慎、幂等性设计、一致错误模型、以及优先使用游标分页等关键设计原则。同时,它明确列出了哪些变更属于破坏性(如删除字段、更改类型、改变错误码等)和哪些是安全的(如添加可选字段、新增端点)。技能还提供了安全的变更步骤(先加后删、双写过渡、逐步迁移)、版本策略、多组件部署顺序,并建议通过实际消费者代码验证而非仅凭文档检查,确保合约变更不产生隐性问题。该技能支持所有主流 API 平台和协议,是后端开发、API 网关管理者的实用参考指南。

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

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

在你喜欢的 AI 中提问

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

文档

API 合约

合约是对你无法控制、也无法修复的代码做出的承诺。这就是 API 变更与内部重构的区别:错误的成本由别人承担,在你无法选择的时间发生。

设计

将资源命名为名词,让方法携带动词。建模的是事物本身,而不是当前显示它的界面——一个围绕今日 UI 形状构造的负载,会在下次重新设计时变得不合时宜。

对于你所暴露的内容要深思熟虑。你返回的每一个字段,都必须保持返回。内部标识符、行版本号和实现细节会将你的模式泄露到调用方的代码中,并固化为该代码的一部分。

让操作具有幂等性,适用于调用方可能重试的任何场景——也就是任何通过网络可达的操作。对于任何创建或收费的操作,给调用方一个幂等键,这样超时后的重试不会导致重复操作。

返回一致的错误模型:一个稳定的机器可读代码、一个人类可读的消息,以及验证失败所涉及的字段。调用方依据代码进行分支,因此代码是合约的一部分——即使结构不变,更改代码也是一种破坏性变更。

对每个列表都进行分页,从第一个版本开始。一个返回全量数据的端点,在表不断变大之前工作良好,然后在拥有最多数据的客户那里崩溃。当行被并发插入时,优先使用游标而非偏移量。

什么会破坏调用方

破坏性变更,无论模式语言允许什么:

  • 删除或重命名字段、端点、方法或枚举值。
  • 将可选请求字段变为必填,或缩小字段的接受范围。
  • 更改类型,包括将整数改为字符串、将单个值改为列表。
  • 保持字段名称和类型不变但改变其含义——最糟糕的一种,因为没有事物会大声失败,而数据会静默地变错。
  • 在请求中添加新的必填字段。
  • 针对已有条件更改错误码或 HTTP 状态码。
  • 收紧默认值,或更改字段被省略时的行为。

安全:添加可选请求字段、添加响应字段、添加新端点或方法、添加枚举值仅当所有消费者已经能够容忍未知值——请验证这一点,而不要假设。

在 protobuf 中,切勿重用或重新编号字段标签,并且在移除字段时保留标签和名称。重用的标签会将旧数据解码到新字段中并静默地损坏它。

安全地变更合约

先添加再删除,并使两者至少在一个发布周期内同时工作:

  1. 在旧字段或方法旁边添加新字段或方法。
  2. 两者都写入,读取新字段并回退到旧字段。
  3. 迁移消费者,并确认每个消费者已完成迁移。
  4. 在后续发布中移除旧路径。

当资源的含义真正改变时才进行版本控制,而不是为每次添加都创建新版本。每次变更都创建一个版本会倍增你需要维护的表面区域。

部署顺序

生成的代码和服务器分别部署,中间的间隙就是故障发生的地方。首先推出能够容忍两种形态的一方:生产者发射新字段之前,消费者接受新字段;调用方发送新请求之前,生产者接受新请求。

当模式通过网关、代理或生成的客户端共享时,链路上的每个组件都需要重新生成和重新部署。在服务中添加但未在服务前端层中添加的字段,在到达调用方之前就会消失,而服务自身的测试是注意不到的。

验证

在改变形态之前检查实际消费者——通过 grep 调用方代码,而不是相信合约的文档。

测试合约本身:一个断言序列化形状的测试,能够捕获意外的重命名事件,而仅针对处理程序进行的单元测试会完全漏掉该事件。

Individual skills in this repo

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

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.

sk-system-design

Design or evaluate a distributed system from its constraints — service boundaries, synchronous versus event-driven communication, consistency, failure behaviour and capacity — and state the trade-off each choice buys. Use when splitting or merging services, choosing between a call and an event, deciding where data lives, reviewing an architecture proposal, or answering a system design question.

相关技能