菜单
Stripe API 设计风格 Skill。蒸馏自 Stripe API 文档、Stripe Engineering Blog、 SDK 源码（stripe-python/stripe-node）、Patrick Collison 的 API 设计原则、 Stripe 工程师的技术演讲。 触发词：「Stripe 风格」「像 Stripe 一样设计 API」「stripe style」「REST API 最佳实践」。 适用：REST API 设计、SDK 开发、支付/金融系统 API、开发者体验设计。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
鲁班造器：输入项目名/代码片段/GitHub 链接，自动分析→提炼编码 DNA→生成可运行的代码风格 Skill。 触发词：「蒸馏XX」「学XX的代码风格」「XX怎么写代码」「生成XX.skill」「鲁班」「代码风格」。 也适用于：「帮我写得更像 Linux 风格」「这段代码不够 idiomatic」「参考 Vue3 的方式重构」。
antirez（Salvatore Sanfilippo，Redis 作者）代码审查视角 Skill。蒸馏自 Redis 源码、 antirez 的博客（antirez.com）、GitHub PR review、HackerNews 评论、 以及他在 Twitter/X 上二十年的系统编程思考。 触发词：「antirez 的视角」「Redis 风格 review」「C 语言审查」「极简系统设计」「数据结构优先」。 适用：系统级/底层代码、C/C++ 审查、数据结构设计、内存布局优化、高性能服务器代码。 不适用：纯业务 CRUD 代码、前端框架讨论、Java 企业架构审查。
Fabrice Bellard 代码审查视角 Skill。蒸馏自 FFmpeg、QEMU、TinyCC、QuickJS、 jslinux 等里程碑项目源码，以及 Bellard 在 USENIX、IOCCC 等场合的技术输出。 触发词：「Bellard 风格 review」「C 语言极致审查」「底层性能 review」「最小实现」。 适用：C/C++ 系统级代码、编解码/解释器/虚拟机、性能敏感路径、底层算法实现。 不适用：业务 CRUD 代码、纯 Web 框架选型、高层架构讨论。
John Carmack 代码审查视角 Skill。蒸馏自 Carmack 的 .plan 文件、id Software 源码（Quake/Doom）、 Facebook/Oculus 时期的技术分享、Twitter/X 上的技术论述、 以及 Masters of Doom 等传记中记录的开发哲学。 触发词：「Carmack 的视角」「游戏引擎风格」「性能优先 review」「纯函数审查」「C/C++ 审查」。 适用：系统级代码、游戏引擎、渲染管线、C/C++/Rust、性能敏感路径、副作用隔离审查。 不适用：纯业务 CRUD、Web 框架设计、快速原型（他会先问「这是 hot path 吗？」）。
Jeremy Howard（fast.ai 创始人）代码审查视角 Skill。蒸馏自 fast.ai 课程代码、 nbdev 库设计、Jupyter Notebook 实践哲学、fastai/fastcore 源码风格、 Practical Deep Learning for Coders 系列教材及大量公开演讲和采访。 触发词：「Jeremy Howard 的视角」「fast.ai 风格 review」「实验优先」「能跑起来再说」。 适用：机器学习/深度学习代码、数据处理 Pipeline、Python 库设计、Jupyter Notebook 工作流。 不适用：强类型系统设计、高并发后端服务、嵌入式系统代码。
Andrej Karpathy 代码审查视角 Skill。蒸馏自 nanoGPT / micrograd / makemore 源码、 Karpathy 的 YouTube 系列（"Neural Networks: Zero to Hero"）、 GitHub commit message、Twitter/X 技术评论、Stanford CS231n 讲义。 触发词：「Karpathy 的视角」「nanoGPT 风格」「可读 ML 代码」「教学型实现」「最小实现」。 适用：深度学习代码、Transformer 实现、训练循环、tensor 操作、研究原型。 不适用：高并发 Web 服务、数据库设计、前端 UI、嵌入式系统。
| name | stripe-api-style |
| description | Stripe API 设计风格 Skill。蒸馏自 Stripe API 文档、Stripe Engineering Blog、 SDK 源码（stripe-python/stripe-node）、Patrick Collison 的 API 设计原则、 Stripe 工程师的技术演讲。 触发词：「Stripe 风格」「像 Stripe 一样设计 API」「stripe style」「REST API 最佳实践」。 适用：REST API 设计、SDK 开发、支付/金融系统 API、开发者体验设计。 |
"An API is a product. Its users are developers. Their experience matters." — Stripe Engineering
此 Skill 激活后，你设计的 API 和 SDK 应该让开发者看 5 分钟文档就能上手， 而不是翻 3 天 StackOverflow。
Stripe 是 API 设计的行业标杆。 不是因为功能最多，而是因为每个细节都替开发者想到了。
这意味着：可预测、容错、开发者优先。
4 条直觉规则：
资源用复数名词，动作用 URL 后缀
# ✅ Stripe 风格
POST /v1/payment_intents # 创建
GET /v1/payment_intents/{id} # 获取
POST /v1/payment_intents/{id}/confirm # 动作（不用 PUT/PATCH 做动作）
POST /v1/payment_intents/{id}/cancel # 动作
# ❌ 常见错误
POST /v1/createPaymentIntent # 动词在 URL 里
PUT /v1/payment_intents/{id}/status # 用 HTTP 方法表达动作
嵌套资源最多一层
# ✅
GET /v1/customers/{customer_id}/sources
# ❌ 嵌套过深，URL 复杂化
GET /v1/customers/{id}/subscriptions/{sub_id}/items/{item_id}/discounts
资源 ID 带类型前缀，全局唯一
pi_3MtwBwLkdIwHu7ix28a3tqPa # PaymentIntent
cus_NffrFeUfNV2Hib # Customer
ch_3MmlLrLkdIwHu7ix0snN0B15 # Charge
这样通过 ID 就能知道是什么资源，debug 时省大力气。
版本在 URL 里，不在 header 里
# ✅ Stripe 风格 — 版本可见、可分享、可 bookmark
GET /v1/charges
# ❌ header 版本 — 不直觉，容易被代理丢掉
GET /charges
API-Version: 2024-04-10
请求：
POST /v1/payment_intents
Content-Type: application/x-www-form-urlencoded # Stripe 用 form encoding，不是 JSON
Authorization: Bearer sk_test_...
amount=2000¤cy=usd&payment_method=pm_xxx&confirm=true
响应结构（永远一致）：
{
"id": "pi_3MtwBwLkdIwHu7ix28a3tqPa",
"object": "payment_intent", // 类型标识，永远有
"amount": 2000,
"currency": "usd",
"status": "succeeded",
"created": 1679090702, // Unix timestamp，不是 ISO 8601
"livemode": false, // 测试/生产环境标识
"metadata": {} // 用户自定义字段，永远有
}
object 字段是 Stripe 的杀手锏：
object 字段标识类型Stripe 的错误设计是业界范本：
{
"error": {
"type": "card_error", // 错误大类
"code": "card_declined", // 机器可读的具体代码
"decline_code": "insufficient_funds", // 更细的子代码
"message": "Your card has insufficient funds.", // 人可读消息
"param": "card", // 哪个参数引起的
"doc_url": "https://stripe.com/docs/error-codes/card-declined" // 文档链接！
}
}
5 条错误设计规则：
type（大类）→ code（具体）→ decline_code（支付特有）400 — 参数错误（你的锅）401 — 认证失败402 — 支付失败（Stripe 特有）404 — 资源不存在429 — 限流500 — 我们的锅message 可以直接展示给终端用户Stripe SDK 的设计原则（以 Python 为例）：
# ✅ Stripe SDK 风格：资源.动作()，链式直觉
import stripe
# 简单操作
intent = stripe.PaymentIntent.create(
amount=2000,
currency="usd",
)
# 更新
intent = stripe.PaymentIntent.modify(
"pi_xxx",
metadata={"order_id": "6735"},
)
# 动作
intent = stripe.PaymentIntent.confirm("pi_xxx")
# 分页：自动处理，不暴露 cursor 细节
for customer in stripe.Customer.auto_paging_iter():
process(customer)
SDK 设计要点：
stripe.PaymentIntent、stripe.Customer）create → POST，retrieve → GET，modify → POST 更新，list → GET listStripe-Idempotency-Key 自动处理，POST 请求可重试auto_paging_iter() 透明迭代Stripe 的幂等键是工程杰作：
POST /v1/payment_intents
Idempotency-Key: a0d92f5c-e5c0-4d3d-b5b3-7a1c9f8c6b2e
amount=2000¤cy=usd
自己的 API 设计规则：
{
"id": "evt_3MtwBwLkdIwHu7ix2sRetfHb",
"object": "event",
"type": "payment_intent.succeeded", // 资源.事件，点分隔
"created": 1679090712,
"livemode": false,
"data": {
"object": { /* 完整的 PaymentIntent 对象 */ }
},
"api_version": "2023-10-16" // 快照时的 API 版本
}
Webhook 5 大原则：
type 格式：{resource}.{event}（payment_intent.succeeded）data.object 包含完整资源快照，不需要再调 API 查api_version，subscriber 知道 payload 格式Stripe-Signature header + 时间窗口防重放URL 里放动词
POST /api/createOrder # ❌
POST /api/orders # ✅
浮点数表示金额
{ "amount": 19.99 } // ❌ 精度噩梦
{ "amount": 1999 } // ✅ 最小单位（分）
没有 object 类型字段 — 无法区分不同资源的响应
错误只有 HTTP 状态码 — 机器无法理解具体原因
分页用 offset/page — 数据变化时分页结果不稳定，用 cursor
# ❌
GET /orders?page=2&per_page=10
# ✅ cursor 分页，稳定
GET /orders?starting_after=ord_xxx&limit=10
破坏性变更不版本化 — 字段重命名必须引入新版本
Webhook payload 不含完整对象 — 不要只发 ID，让用户再查一次