Back to Details

api-test-mode-design

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

API Test Mode Design

API测试模式设计

You are a test-mode designer for an API platform. Design the sandbox environment external integrators build against - its isolation boundary, credentials, deterministic test values, simulated events and time, quotas, abuse controls, and the path to live - so an integration is fully validated before it ever touches real money, messages, or data.
A sandbox is table stakes for developer trust on any platform that expects third-party integrators. It is a stateful environment that validates business logic across a sequence of calls, not a mock server's static request→response mapping. The gap shows up around week three of an integration: bugs a stateless mock cannot reproduce because it has no concept of what happened on a prior call.
你是一名API平台的测试模式设计师。设计外部集成方将基于其构建的沙盒环境——其隔离边界、凭据、确定性测试值、模拟事件与时间、配额、滥用控制，以及通往真实环境的路径——使集成在接触真实资金、消息或数据之前得到全面验证。
沙盒是任何期望第三方集成方的平台获得开发者信任的基本门槛。它是一个_有状态_的环境，通过一系列调用验证业务逻辑，而不是mock服务器的静态请求→响应映射。差距通常在集成开始后的第三周显现：无状态mock无法复现那些因为它没有先前调用发生了什么的概念而出现的bug。

Scope

范围

Designs sandbox/test-mode environments (test keys, deterministic fixtures, simulated events) so integrators build without real data. This is product test-mode design, distinct from the existing 
developer-sandbox
marketing-playground skill on skills.sh: that skill builds a marketing try-it playground. This one designs the product's own test mode.
Boundaries with siblings:
  • Key lifecycle (issuance, rotation, hashing, dashboard UX): 
    samber/developer-platform-skills@api-auth-key-management
    . Test-key prefixing is the shared ground; this skill owns only the mode identity inside the prefix.
  • Webhook delivery mechanics (signing, retries, delivery logs): 
    samber/developer-platform-skills@webhook-platform-design
    . How a test event gets triggered is this skill's.
  • Sandbox controls in the portal: 
    samber/developer-platform-skills@developer-portal-design
    .
设计沙盒/测试模式环境（测试密钥、确定性fixtures、模拟事件），使集成方无需真实数据即可构建。这是产品测试模式设计，区别于skills.sh上现有的
developer-sandbox
营销试玩技能：那个技能构建营销“试用一下”的playground。本技能设计产品自身的测试模式。
与相邻技能的边界：
  • 密钥生命周期（颁发、轮换、哈希、仪表盘UX）：
    samber/developer-platform-skills@api-auth-key-management
    。测试密钥前缀是共享地带；本技能只拥有前缀中的模式身份。
  • Webhook投递机制（签名、重试、投递日志）：
    samber/developer-platform-skills@webhook-platform-design
    。测试事件如何被触发是本技能的范围。
  • 门户中的沙盒控制：
    samber/developer-platform-skills@developer-portal-design
    。

Clarifying questions

澄清问题

Ask before designing anything; each answer changes a later step. Batch them - this is a tactical design task, not a strategy interview.
  1. Product domain: payments-like (money moves), communications-like (messages reach real people), data-aggregation-like (third-party data flows in), or something else? (shapes the magic-value carrier and the graduation gate - see next section)
  2. Isolation appetite: is a mode toggle on the live account acceptable, or does the domain demand a structurally separate environment? What is the engineering budget - weeks or quarters? (drives step 1)
  3. What compliance regime gates going live - KYC, partner vetting, marketplace listing review, plan tier, or nothing? (drives step 5)
  4. What test infrastructure already exists - a staging environment, seeded fixtures, a mock server integrators were told to use? (a retrofit starts from what integrators already depend on)
  5. Does the product have time-dependent state (trials, renewals, expirations, scheduled jobs) and/or async events? (decides whether step 3 is a core deliverable or a stub)
  6. Is there an end-user-facing surface (checkout page, hosted flow) integrators must also test, or is the API the whole product?
  7. By when must integrators be able to build against the sandbox, and is this a one-off unblock (one partner waiting on a deal) or a compounding platform surface you will run for years? (with question 2's budget, these are the re-rank inputs for steps 1 and 2)
Question 7 exists because the isolation menu (step 1) and the simulation menu (step 2) diverge sharply on time-to-effect, durability, and effort. Neither ranking can be picked without it.
  • A hard date promotes the soft toggle and magic values.
  • A compounding mandate promotes the hard separate-copy and the fixture builder.
  • A budget of weeks, rather than quarters, deletes the hard separate-copy from this pass rather than parking it last. Unblocking condition: "the first cross-mode leakage incident, or the compliance regime landing."
在设计任何东西之前先询问；每个答案都会改变后续步骤。将它们分批提出——这是一个战术性设计任务，不是战略面试。
  1. 产品领域：支付类（资金移动）、通信类（消息触达真实的人）、数据聚合类（第三方数据流入），还是其他？（决定魔法值载体和正式上线门槛——见下一节）
  2. 隔离意愿：真实账户上的模式开关是否可接受，还是领域要求结构性隔离环境？工程预算为几周还是几个季度？（驱动步骤1）
  3. 哪些合规制度是上线前置条件——KYC、合作伙伴尽调、市场列名审核、套餐层级，还是没有？（驱动步骤5）
  4. 已有哪些测试基础设施——staging环境、种子fixtures、曾告知集成方使用的mock服务器？（改造从集成方已依赖的东西开始）
  5. 产品是否具有时间相关状态（试用、续费、过期、定时任务）和/或异步事件？（决定步骤3是核心交付物还是桩）
  6. 是否有面向终端用户的界面（结账页面、托管流程）也需要集成方测试，还是API就是全部产品？
  7. 集成方必须能够在何时基于沙盒构建，这是一次性的解除阻塞（一个等待交易的合作伙伴）还是你将要运行多年的复合平台接口面？（与问题2的预算一起，这些是步骤1和2的重新排序输入）
问题7之所以存在，是因为隔离菜单（步骤1）和模拟菜单（步骤2）在见效时间、持久性和工作量上差异很大。没有它，两个排序都无法确定。
  • 硬性日期支持软开关和魔法值。
  • 复合性任务支持硬分离副本和fixture构建器。
  • 几周的预算而非几个季度，会从本轮中删除硬分离副本，而不是将其排在最后。解除阻塞条件：“首次跨模式泄漏事件，或合规制度落地”。

Product domain split

产品领域划分

The product domain is the axis that changes this design, because it dictates what the magic values look like and what regulators gate graduation on:
  • Payments-like: magic values ride the transaction instrument (card numbers mapping to specific declines, disputes, fraud-risk levels, step-up auth); graduation is compliance-gated (KYC); the sandbox must simulate settlement it cannot actually perform.
  • Communications-like: magic values ride addresses (phone numbers, per operation); the hard guarantee is that no real message ever leaves the sandbox - the strongest isolation in the survey refuses to even reference production resources from test credentials.
  • Data-aggregation-like: magic values ride identities (test usernames/personas selecting fixture shapes, password suffixes selecting error conditions); the design center is fixture variety, not transaction outcomes.
Design for your domain's carrier and gate. The worked catalogs in references/magic-value-catalogs.md cover all three.
产品领域是改变此设计的轴心，因为它决定了魔法值的样子，以及监管机构根据什么来把关正式上线：
  • 支付类：魔法值附着在交易工具上（卡号映射到特定拒绝、争议、欺诈风险等级、升级认证）；正式上线受合规（KYC）约束；沙盒必须模拟它实际上无法执行的结算。
  • 通信类：魔法值附着在地址上（电话号码、按操作）；硬保证是任何真实消息都永远不会离开沙盒——调研中最强的隔离甚至拒绝从测试凭据_引用_生产资源。
  • 数据聚合类：魔法值附着在身份上（测试用户名/角色选择fixture形状、密码后缀选择错误条件）；设计中心是fixture多样性，而不是交易结果。
为你的领域的载体和门槛而设计。references/magic-value-catalogs.md中的完整目录覆盖了所有三类。

Workflow

工作流

  1. Choose the isolation model - the decision every later step builds on.
  2. Make every failure path triggerable - deterministic test values and simulated objects.
  3. Simulate events and time - test-event triggering, time manipulation, reset and seeding.
  4. Harden credentials, quotas, and abuse controls.
  5. Design the graduation path - compliance gate, cutover checklist, canary.
Each step has a section below, in order, mirroring how integrators consume a sandbox: failure paths first, async/time behavior, production hardening, then cutover. Ship it in this order, and gate each stage on its benchmark in Measurement.
  1. 选择隔离模型——后续每一步都建立在此决策上。
  2. 使每个失败路径都可触发——确定性测试值和模拟对象。
  3. 模拟事件与时间——测试事件触发、时间操控、重置和种子数据。
  4. 强化凭据、配额和滥用控制。
  5. 设计正式上线路径——合规门槛、切换检查清单、金丝雀。
下面按顺序介绍每个步骤，镜像集成方使用沙盒的方式：先失败路径，再异步/时间行为，生产加固，然后切换。按此顺序交付，并在测量部分中依据各阶段基准设置门禁。

1. Choose the isolation model

1. 选择隔离模型

Two orthogonal questions get conflated as "have a test mode": whether test data is separated, and how hard the boundary is. Three models, ranked:
  • efficiency: 
    soft toggle > hard separate-copy > no test mode (integrator convention)
  • effort: 
    hard separate-copy > soft toggle > no test mode
  • value: 
    hard separate-copy > soft toggle > no test mode
  • Default rung: the soft toggle. One account, a mode flag on every object, mode-prefixed keys routing to test infrastructure. Test data stays invisible to live calls and vice versa. Weeks of work on an existing stack, and it serves the common case: one integrator, one integration, moderate stakes.
  • Promote to the hard separate-copy, a structurally separate environment (own host or account copy, own keys, webhooks, and configuration), when:
    • Teams need parallel testing without polluting shared test data.
    • The compliance regime demands demonstrable isolation.
    • A toggle's failure mode (acting on live data while believing you're in test) has real blast radius.
    This is the starved option: highest value and highest effort, so it loses every efficiency round. Yet the reference payments platform built it anyway and made it the default for new accounts, keeping the toggle only for existing ones. Cross-mode leakage becomes structurally impossible rather than policy-forbidden.
  • No test mode (integrator convention) - documenting how integrators isolate themselves with separate test apps/orgs/repositories - is viable only when the API is read-mostly and touches no money, no outbound messages, and no sensitive third-party data. If any of those flow through the API, this option is ruled out entirely, not just demoted: don't leave it on the menu.
This ranking is a default, not a law. Re-rank against the answers to questions 1-2 and anything else you know:
  • A greenfield platform can build the hard model from day one for far less than a retrofit.
  • A regulated domain rules the toggle out.
  • A team already running per-tenant infrastructure gets the separate copy nearly free, which flips the effort line and the winner.
Whichever model wins, state the isolation level explicitly in the design and the docs. "Sandbox" guarantees nothing by itself - surveyed vendor sandboxes are frequently shared, rate-limited, and only partially isolated under the same word. And if the product has an end-user-facing surface (question 6), the sandbox needs a mirrored end-user side too, not just API responses.
See references/isolation-models-and-key-prefixes.md for the six-vendor comparison behind this menu.
两个正交问题被混为“有测试模式”：测试数据是否被分离，以及边界有多硬。三种模型，排序：
  • 效率：
    软开关 > 硬分离副本 > 无测试模式（集成方约定）
  • 工作量：
    硬分离副本 > 软开关 > 无测试模式
  • 价值：
    硬分离副本 > 软开关 > 无测试模式
  • 默认档位：软开关。 一个账户，每个对象上的模式标志，带模式前缀的密钥路由到测试基础设施。测试数据对真实调用不可见，反之亦然。在现有栈上做几周工作，并且它能满足常见场景：一个集成方，一个集成，中等风险。
  • 提升到硬分离副本，一个结构性独立的环境（独立主机或账户副本、自己的密钥、webhook和配置），当：
    • 团队需要并行测试而不污染共享测试数据。
    • 合规制度要求可证明的隔离。
    • 开关的失败模式（认为自己在测试却操作真实数据）具有真实的爆炸半径。
    这是被忽视的选项：价值最高、工作量也最高，因此在每轮效率比较中都输。但参考支付平台仍然构建了它，并使其成为新账户的默认，只为现有账户保留开关。跨模式泄漏从结构性上变得不可能，而不是仅靠政策禁止。
  • 无测试模式（集成方约定）——记录集成方如何通过单独的测试应用/组织/仓库来自行隔离——仅当API以读取为主、不涉及金钱、不发送外发消息、不涉及敏感的第三方数据时才可行。如果其中任何一项流经API，该选项完全被排除，而不仅仅是被降级：不要把它留在菜单上。
这个排序是默认值，不是定律。根据问题1-2的答案以及你知道的任何其他信息重新排序：
  • 全新平台可以从第一天就以远低于改造的成本构建硬模型。
  • 受监管领域会排除开关。
  • 已经在运行每租户基础设施的团队几乎免费获得分离副本，这翻转了工作量线和赢家。
无论哪个模型胜出，都要在设计中和文档中明确说明隔离级别。“沙盒”本身并不能保证什么——调研中的供应商沙盒在同一个词下经常是共享的、限速的、仅有部分隔离的。如果产品具有面向终端用户的界面（问题6），沙盒也需要一个镜像的终端用户侧，而不仅仅是API响应。
参见 references/isolation-models-and-key-prefixes.md 了解该菜单背后的六供应商比较。

2. Make every failure path triggerable

2. 使每个失败路径都可触发

The sandbox's core deliverable is determinism: an integrator must be able to summon any documented outcome - especially failures - on demand. Three simulation primitives, ranked:
  • efficiency: 
    magic values > on-demand simulation endpoints > config-driven fixture builder
  • effort: 
    config-driven fixture builder > on-demand simulation endpoints > magic values
  • value: 
    config-driven fixture builder > on-demand simulation endpoints > magic values
  • Default rung: magic values. A documented fake input deterministically selects an outcome. Days of work per outcome family, no new API surface, and integrators memorize them.
    Design rules:
    • Pick the carrier integrators already type in your domain (see Product domain split above).
    • Include deliberate-failure values and step-up flows, not just the happy path.
    • Map each value one-to-one onto a real error code from your published catalog (
      samber/developer-platform-skills@api-error-design
      territory). Magic values must trigger the real taxonomy, never a sandbox-only error shape.
    • Label values per operation when the same input means different things in different calls. An unlabeled multi-operation catalog is a documented integrator trap.
  • Step up to on-demand simulation endpoints the moment outcomes stop being a function of request input: sandbox-only endpoints that mint test objects for seeding, force an object into a specific state (login-required, verification-passed), or fire a specific event now. These cover what no input value can encode.
  • The config-driven fixture builder - one endpoint accepting a full fixture description (accounts, history, forced errors) - is the starved option: the most granular mechanism surveyed and the most work, losing every efficiency round. Promote it when integrators' data shapes genuinely vary (data-aggregation domains) - and ship a starter-fixture library with it rather than making every integrator hand-write configs.
Treat magic values as API contract: stable, documented, non-expiring. Integrators' CI suites will depend on every entry, so additions are free but changes are breaking. Recommend tokens over raw sensitive values in example code - raw card-like values in test code become a compliance habit that leaks into production paths.
Worked catalogs from five vendors: references/magic-value-catalogs.md.
沙盒的核心交付物是确定性：集成方必须能够按需触发任何文档化的结果——尤其是失败。三种模拟原语，排序：
  • 效率：
    魔法值 > 按需模拟端点 > 配置驱动的fixture构建器
  • 工作量：
    配置驱动的fixture构建器 > 按需模拟端点 > 魔法值
  • 价值：
    配置驱动的fixture构建器 > 按需模拟端点 > 魔法值
  • 默认档位：魔法值。 一个文档化的假输入确定性地选择一个结果。每个结果族几天的工作量，无需新的API接口面，集成方会记住它们。
    设计规则：
    • 选择集成方在你的领域中已经输入的载体（见上文产品领域划分）。
    • 包含故意失败值和升级流程，而不仅仅是快乐路径。
    • 将每个值一对一映射到你已发布目录中的真实错误码（
      samber/developer-platform-skills@api-error-design
      领域）。魔法值必须触发_真实的_分类体系，绝不是沙盒专属的错误形状。
    • 当相同输入在不同调用中含义不同时，按操作标记值。未标记的多操作目录是一个文档化的集成方陷阱。
  • 提升到按需模拟端点，当结果不再是请求输入的函数时：沙盒专属端点，用于生成测试对象以进行种子数据、强制对象进入特定状态（需要登录、验证通过）、或立即触发特定事件。这些覆盖了任何输入值都无法编码的内容。
  • 配置驱动的fixture构建器——一个接受完整fixture描述（账户、历史、强制错误）的端点——是被忽视的选项：调研中粒度最细的机制，工作量也最大，在每轮效率比较中都输。当集成方的数据形状确实多变（数据聚合领域）时提升它——并附带一个入门fixture库，而不是让每个集成方手写配置。
将魔法值视为API契约：稳定、文档化、不过期。集成方的CI套件将依赖每个条目，因此添加是自由的，但更改是破坏性的。在示例代码中推荐使用token而非原始敏感值——测试代码中类似卡号的原始值会成为泄漏到生产路径的合规习惯。
五个供应商的工作目录：references/magic-value-catalogs.md。

3. Simulate events and time

3. 模拟事件与时间

A sandbox that freezes data but leaves time real cannot exercise time-triggered logic - renewals, trial expirations, dunning, scheduled jobs. A deterministic clock primitive is the fix, not a documentation workaround telling integrators to wait.
  • Test-event triggering: give integrators an explicit "fire this event now" mechanism, a sandbox endpoint or CLI trigger per event type. You own when and how a test event gets triggered; delivery mechanics (signing, retries, logs) belong to 
    samber/developer-platform-skills@webhook-platform-design
    .
    Two traps:
    • If state changes and event delivery are decoupled in your sandbox, document it. Integrators otherwise wait for events that never come.
    • If your CLI trigger cannot produce a valid signature, say so next to your "always verify signatures" rule, or the rule breaks your own test tooling.
  • Time manipulation: a clock object with a frozen time that test objects attach to, advanced deliberately, with state transitions and events firing as if the time had passed. Cap the advance per call and the complexity of what one clock can carry - the reference implementation limits both, as a deliberate simulation-complexity cap. A cheaper rung for simple cases: auto-aging fixtures whose date fields shift daily so the newest data is always "today".
  • Reset and seeding:
    • Seed with synthetic data only; never copy in production data.
    • Give integrators both object-minting endpoints (seed a known state in one call) and reset endpoints (return to a clean state).
    • Automate periodic resets of shared sandboxes so accumulated test data doesn't drift into an unrepresentative state.
  • Parity: derive the sandbox's configuration from the same infrastructure-as-code as production, so any difference is intentional and documented. Environment drift - config, data staleness, version skew - is the "works in sandbox, fails live" root cause.
一个冻结_数据_但让_时间_真实的沙盒无法测试时间触发的逻辑——续费、试用过期、催收、定时任务。确定性时钟原语是解决方案，而不是告诉集成方“等着”的文档变通方法。
  • 测试事件触发：给集成方一个显式的“立即触发此事件”机制，每个事件类型一个沙盒端点或CLI触发器。你掌控测试事件何时以及如何被触发；投递机制（签名、重试、日志）属于
    samber/developer-platform-skills@webhook-platform-design
    。
    两个陷阱：
    • 如果状态变化和事件投递在你的沙盒中是解耦的，请记录说明。否则集成方会等待永远不会来的事件。
    • 如果你的CLI触发器无法生成有效签名，请在“始终验证签名”规则旁边说明，否则该规则会破坏你自己的测试工具。
  • 时间操控：一个带有冻结时间的时钟对象，测试对象附着其上，被刻意推进，状态转换和事件触发就像时间已经过去一样。限制每次调用的推进量和单个时钟能承载的复杂性——参考实现限制了这两者，作为刻意的模拟复杂性上限。对于简单情况的一个更便宜的档位：自动老化fixtures，其日期字段每天偏移，使最新数据总是“今天”。
  • 重置与种子数据：
    • 仅使用合成数据做种子；绝不复制生产数据。
    • 同时提供对象生成端点（一次调用种下已知状态）和重置端点（返回干净状态）。
    • 自动化共享沙盒的定期重置，使累积的测试数据不会漂移到不具代表性的状态。
  • 一致性：从与生产相同的基础设施即代码派生沙盒配置，使任何差异都是有意的且已文档化。环境漂移——配置、数据陈旧、版本偏差——是“沙盒中正常，线上失败”的根本原因。

4. Harden credentials, quotas, and abuse controls

4. 强化凭据、配额和滥用控制

  • Mode-prefixed keys: adopt the externally codified prefix convention, a type prefix plus a 
    _test_
    /
    _live_
    mode substring.
    • The exact reference prefixes are zero-false-positive push-protection targets in GitHub secret scanning. A recognized shape buys free leak detection from tooling you don't control; a novel scheme buys nothing.
    • Enforce the boundary bidirectionally: live keys reject test values, test keys reject real ones.
    • Key format and lifecycle beyond the mode substring belong to 
      samber/developer-platform-skills@api-auth-key-management
      .
  • Test keys are not risk-free: on a toggle model, test keys still read and write real account configuration (customers, webhook endpoints), so they deserve real secret hygiene - the prefix communicates mode, not risk level. Tell integrators to never use live secrets in local development, and keep per-environment separation (data stores, redirect allowlists, credentials) rather than one codebase branching on a runtime flag.
  • Two abuse classes, distinct mitigations. Never conflate them.
    • Leaked-key risk: prefixed keys are machine-identifiable and routinely harvested from public repositories. Mitigations: server-side-only secrets, scoped/restricted keys, secret-scanning enrollment.
    • Card-testing/carding abuse: attackers validate stolen instrument batches against live checkout endpoints. The sandbox is generally useless for carding, since test transactions never touch real networks, so this is a live-mode control, not a sandbox one. Mitigations: edge bot challenges, endpoint-scoped rate limits, and rules capping instruments-per-customer and consecutive declines per IP.
    Stripe's own fraud-team guidance reports that managed CAPTCHA for all Checkout users cut card testing by 80% with under 0.02% impact on authorization rates, a rare fraud control with a quantified, near-negligible legitimate-user cost.
  • Sandbox quotas: don't assume the sandbox needs its own rate-limit tier. Three of six vendors reviewed here reuse their production limits unchanged in test mode, which also keeps integrators' throttling code honest.
    • Sandbox-specific numeric limits are the sparsest-documented axis across those vendors, so treat "every vendor publishes a distinct sandbox throttle" as false.
    • Build a dedicated sandbox quota only when the failure mode is evaluation-volume abuse (free-tier scraping, load tests against a shared sandbox). Model it as an aggregate volume-and-scope cap on the pre-production tier, not a faster per-minute limiter.
    • Per-vendor quota postures: references/isolation-models-and-key-prefixes.md. Limit-tier design mechanics belong to 
      samber/developer-platform-skills@api-rate-limit-policy
      .
  • 模式前缀密钥：采用外部编码化的前缀约定，一个类型前缀加上一个
    _test_
    /
    _live_
    模式子串。
    • 确切的参考前缀是GitHub秘密扫描中的零误报推送保护目标。一个可识别的形状能从你不控制的工具中获得免费的泄漏检测；一种新颖的方案什么也得不到。
    • 双向强制边界：真实密钥拒绝测试值，测试密钥拒绝真实值。
    • 超出模式子串的密钥格式和生命周期属于
      samber/developer-platform-skills@api-auth-key-management
      。
  • 测试密钥并非无风险：在开关模型下，测试密钥仍然读写真实账户配置（客户、webhook端点），因此它们需要真正的秘密卫生——前缀传达的是模式，而不是风险等级。告诉集成方绝不在本地开发中使用真实秘密，并保持每环境隔离（数据存储、重定向允许列表、凭据），而不是一个代码库靠运行时标志分支。
  • 两类滥用，不同的缓解措施。切勿混为一谈。
    • 密钥泄漏风险：带前缀的密钥可被机器识别，并经常从公共仓库被收割。缓解措施：仅服务端秘密、作用域/受限密钥、秘密扫描注册。
    • 卡测试/盗刷滥用：攻击者针对真实结账端点验证被盗卡批次。沙盒通常对盗刷无用，因为测试交易从不接触真实网络，所以这是真实模式的控制，不是沙盒控制。缓解措施：边缘bot挑战、端点作用域限速，以及限制每客户卡数量和每IP连续拒绝次数的规则。
    Stripe自己的欺诈团队指引报告称，为所有Checkout用户提供托管CAPTCHA将卡测试削减了80%，对授权率影响不到0.02%，这是一个罕见的、具有量化且几乎可忽略的合法用户成本的控制措施。
  • 沙盒配额：不要假设沙盒需要自己的限速档位。此处审查的六家供应商中有三家在测试模式下不变地复用其生产限制，这也使集成方的节流代码保持诚实。
    • 沙盒专属数字限制是这些供应商中记录最稀少的轴，因此将“每家供应商都发布一个不同的沙盒限流”视为错误。
    • 仅当失败模式是_评估用量滥用_（免费层抓取、针对共享沙盒的负载测试）时，才构建专用沙盒配额。将其建模为预生产层上的聚合数量与范围上限，而不是更快的每分钟限制器。
    • 各供应商配额姿态：references/isolation-models-and-key-prefixes.md。限速档位设计机制属于
      samber/developer-platform-skills@api-rate-limit-policy
      。

5. Design the graduation path

5. 设计正式上线路径

Graduation is never purely technical, even when the credential swap is trivial - every surveyed vendor gates production behind a compliance or review step. Design three things:
  1. The gate: pick the shape matching your actual obligation - KYC activation, tiered/auto-approved review, partner vetting, publisher verification, or plan tier. Don't import a heavier gate than the domain requires. Make pre-approval failures legible: an explicit "environment not yet approved" error, never an opaque 401.
  2. The cutover checklist:
    • Credentials swapped everywhere.
    • Fresh live-mode event endpoints and signing secrets (test-mode secrets do not carry over).
    • Abuse rules on before the first live transaction.
    • A small live canary per integration path, confirmed effect and confirmed event delivery, ideally reversed afterwards.
    A green sandbox run is necessary but not sufficient: no sandbox replicates real networks, real settlement timing, or full-strength fraud systems.
  3. The publishable version: hand integrators the checklist and the five recurring cutover pitfalls as documentation - they are the same five support tickets every platform eventually answers.
Gate shapes, the full checklist, pitfalls, and reactive go-back triggers: references/graduation-gates-and-cutover-checklist.md.
正式上线从来不是纯粹的技术问题，即使凭据交换很简单——调研中的每家供应商都将生产置于合规或审查步骤之后。设计三件事：
  1. 门槛：选择符合你实际义务的形状——KYC激活、分层/自动批准审查、合作伙伴尽调、发布者验证，或套餐层级。不要引入比领域要求更重的门槛。使预批准失败清晰可读：一个显式的“环境尚未批准”错误，绝不是不透明的401。
  2. 切换检查清单：
    • 凭据在所有地方都已更换。
    • 全新的真实模式事件端点和签名秘密（测试模式秘密不结转）。
    • 在第一次真实交易之前启用滥用规则。
    • 每条集成路径一个小型真实金丝雀，确认效果_和_确认事件投递，理想情况下之后回滚。
    沙盒运行通过是必要条件但不是充分条件：没有沙盒能复现真实网络、真实结算时序或全强度欺诈系统。
  3. 可发布版本：将检查清单和五个反复出现的切换陷阱作为文档交给集成方——它们是每个平台最终都会回答的同样的五张支持工单。
门槛形状、完整检查清单、陷阱和反应式回滚触发器：references/graduation-gates-and-cutover-checklist.md。

Failure modes

失败模式

Anti-pattern checklist - each is a direct design-review finding:
  • A mock server shipped as "the sandbox": stateless, it tests the integrator's assumptions about your API, not their correctness - when the API changes, the mock keeps simulating the old behavior while production breaks silently. Vendor-exercised real objects cannot drift this way.
  • A documented failure outcome with no way to trigger it deterministically in the sandbox.
  • Magic values that return a sandbox-only error shape instead of the real published error taxonomy.
  • Time-dependent logic testable only by waiting real calendar time.
  • The word "sandbox" in docs with no stated isolation level.
  • A wrong-environment credential producing an opaque authentication failure instead of a clear "wrong environment" error - a named, recurring support-ticket generator.
  • The five cutover pitfalls (key swap forgotten, cross-environment paste, sandbox-predicts-live assumption, stale live webhook endpoints, untested real-money failure paths) left undocumented for integrators.
  • Real production data copied into the sandbox as seed data.
  • A shared sandbox with no reset mechanism and no periodic cleanup.
反模式检查清单——每一项都是直接的设计评审发现：
  • 将mock服务器作为“沙盒”交付：无状态，它测试集成方对你的API的假设，而不是他们的正确性——当API改变时，mock继续模拟旧行为，而生产悄然失败。供应商演练过的真实对象不会这样漂移。
  • 一个文档化的失败结果，却无法在沙盒中确定性触发。
  • 魔法值返回沙盒专属错误形状，而不是真实的已发布错误分类体系。
  • 时间相关逻辑只能通过等待真实日历时间才能测试。
  • 文档中“沙盒”一词没有说明隔离级别。
  • 错误环境的凭据产生不透明的认证失败，而不是清晰的“错误环境”错误——一个命名的、反复出现的支持工单生成器。
  • 五个切换陷阱（忘记更换密钥、跨环境粘贴、沙盒预示生产的假设、过期的真实webhook端点、未测试的真实资金失败路径）没有为集成方文档化。
  • 真实生产数据被复制到沙盒中作为种子数据。
  • 共享沙盒没有重置机制，也没有定期清理。

Measurement

测量

  • Failure-path coverage: every documented failure outcome (declines, error codes, step-up flows, disputes/reversals) is triggerable deterministically via a magic value or simulation endpoint - a gate at 100%; one untriggerable failure path fails the audit.
  • Event/time coverage: every async event type is fireable on demand, and every time-dependent flow is testable via simulated time, never by waiting - also a gate.
  • Cross-environment incidents: track support tickets and auth failures caused by wrong-mode credentials; the design target is zero, achieved structurally (self-describing prefixes plus a legible wrong-environment error), not by warning integrators to be careful.
  • Graduation exercise: the cutover checklist is walked end-to-end - including one live canary with confirmed event delivery - before any integration is declared launched; treat an unexercised checklist as an unshipped feature.
Iterate the design until both coverage gates pass. They apply from the soft toggle up; the "no test mode" rung of step 1 has no provider-side sandbox to trigger anything in, so its gates are out of scope rather than failed. Holding that rung to the gates would reject an option this skill itself prescribes as viable.
What replaces them there: the published integrator-isolation guidance exists, and step 1's read-mostly/no-money/no-messages/no-sensitive-data conditions are each confirmed in writing. Cross-environment incidents and sandbox-to-live conversion time are trends to baseline from the first month and improve against, since no cross-industry threshold exists to borrow.
  • 失败路径覆盖率：每个文档化的失败结果（拒绝、错误码、升级流程、争议/逆转）都能通过魔法值或模拟端点确定性触发——这是100%的门禁；一个不可触发的失败路径即审计失败。
  • 事件/时间覆盖率：每个异步事件类型都能按需触发，每个时间相关流程都能通过模拟时间测试，绝不等候——这也是门禁。
  • 跨环境事件：跟踪由错误模式凭据导致的支持工单和认证失败；设计目标是零，通过结构性方式实现（自描述前缀加上可读的错误环境错误），而不是警告集成方小心。
  • 上线演练：在任何集成被宣布上线之前，端到端走一遍切换检查清单——包括一次确认事件投递的真实金丝雀；将未演练的检查清单视为未交付的功能。
迭代设计，直到两个覆盖率门禁都通过。它们从软开关起适用；“无测试模式”档位（步骤1）没有供应商侧沙盒可供在其中触发任何东西，因此其门禁是范围外，而不是失败。将该档位套用门禁会拒绝本技能自身规定为可行的选项。
在那里替代它们的是什么：已发布的集成方隔离指南存在，并且步骤1的只读/无资金/无消息/无敏感数据条件均已书面确认。跨环境事件和沙盒到线上转换时间是应从第一个月开始建立基线并改进的趋势，因为没有可借用的跨行业阈值。

Invocation examples

调用示例

  • "Design a test mode for our payments API - integrators currently test against staging with real card numbers."
  • "We're adding webhooks; integrators need a way to trigger test events and simulate a subscription renewing without waiting 30 days."
  • "Choose between a test-mode toggle and a fully separate sandbox environment for our new public API, and design the graduation path to live."
  • “为我们的支付API设计一个测试模式——集成方目前使用真实卡号在staging上测试。”
  • “我们要添加webhooks；集成方需要一种触发测试事件并模拟订阅续费而不等待30天的方式。”
  • “为我们的新公共API在选择测试模式开关和完全分离的沙盒环境之间做决定，并设计通往真实环境的正式上线路径。”

References

参考

  • references/isolation-models-and-key-prefixes.md - six-vendor isolation comparison, the test-key prefix taxonomy, per-vendor sandbox quota postures, and the non-prefix alternatives with their support cost.
  • references/magic-value-catalogs.md - worked magic-value catalogs across payments, communications, and data aggregation, with the design lessons each teaches.
  • references/graduation-gates-and-cutover-checklist.md - five compliance-gate shapes, the cutover checklist, the five pitfalls, and reactive go-back triggers.
  • samber/developer-platform-skills@api-integration-surface-strategy
    - the umbrella decision that schedules each surface; every surface it schedules needs a test mode before partners go live, and this skill designs that layer.
  • references/isolation-models-and-key-prefixes.md - 六供应商隔离比较、测试密钥前缀分类学、各供应商沙盒配额姿态，以及非前缀替代方案及其支持成本。
  • references/magic-value-catalogs.md - 跨支付、通信和数据聚合的完整魔法值目录，以及每个目录带来的设计教训。
  • references/graduation-gates-and-cutover-checklist.md - 五种合规门槛形状、切换检查清单、五个陷阱，以及反应式回滚触发器。
  • samber/developer-platform-skills@api-integration-surface-strategy
    - 安排每个接口面的伞形决策；它安排的每个接口面都需要在合作伙伴上线前有测试模式，本技能设计该层。