api-test-mode-design

API 测试模式设计

你是一名 API 平台测试模式设计师。请设计外部集成方使用的沙盒环境，包括隔离边界、凭证、确定性测试值、模拟事件与时间、配额、滥用防护，以及通往正式环境的路径，确保集成在接触真实资金、消息或数据之前得到全面验证。

对于任何期待第三方集成方的平台来说，沙盒都是建立开发者信任的基本条件。它是一个_有状态_的环境，可跨一系列调用验证业务逻辑，而不是静态映射请求→响应的模拟服务器。集成进行到第三周左右时，这种差距便会显现：无状态模拟无法复现那些需要了解先前调用情况才能发现的错误。

范围

设计沙盒／测试模式环境（测试密钥、确定性固件、模拟事件），让集成方能够在不使用真实数据的情况下进行构建。这是产品测试模式设计，有别于 skills.sh 上现有的 developer-sandbox 营销体验技能：该技能用于搭建营销试用体验。本技能设计的是产品自身的测试模式。

与相邻技能的边界：

• 密钥生命周期（签发、轮换、哈希处理、控制面板体验）：samber/developer-platform-skills@api-auth-key-management。测试密钥前缀是双方共有的部分；本技能仅负责前缀中的模式标识。
• Webhook 投递机制（签名、重试、投递日志）：samber/developer-platform-skills@webhook-platform-design。测试事件的触发方式归本技能负责。
• 门户中的沙盒控件：samber/developer-platform-skills@developer-portal-design。

记忆（建议）： 如果记忆存储在文件中，可考虑使用 developer-platform-context.md；如果使用其他记忆系统，则以该系统为准。该文件仅供参考，并非强制要求。请将不同任务的信息放在不同章节中。任务完成后将其移除。为任务添加日期；一般项目背景无需添加日期。不同任务的部分访谈回复可能会有所不同。

澄清问题

设计任何内容前先提问；每个答案都会影响后续步骤。把问题集中起来问——这是一项战术设计任务，不是战略访谈。

1. 产品领域：类似支付（资金流动）、类似通信（消息送达真实用户）、类似数据聚合（流入第三方数据），还是其他？（这会影响特殊值的载体和上线门槛——见下一节）
2. 对隔离的要求：在真实账户上切换模式是否可以接受，还是该领域要求在结构上完全隔离的环境？工程预算是多少——几周还是几个季度？（影响步骤 1）
3. 哪种合规制度会限制产品上线——KYC、合作伙伴审核、市场上架审核、套餐等级，还是没有？（影响步骤 5）
4. 现有的测试基础设施有哪些——预发布环境、预置测试数据，或曾建议集成方使用的模拟服务？（改造要从集成方已经依赖的内容着手）
5. 产品是否有依赖时间的状态（试用期、续订、到期、计划任务）和／或异步事件？（决定步骤 3 是核心交付内容还是临时方案）
6. 产品是否有面向终端用户的界面（结账页面、托管流程）也需要集成方测试，还是 API 就是整个产品？
7. 集成方最迟何时必须能够基于沙箱进行开发？这是一次性的解围需求（有合作伙伴正等待交易），还是需要运营多年的、会持续扩展的平台能力？（结合问题 2 的预算，这些是步骤 1 和 2 重新排序的依据）

之所以要问问题 7，是因为隔离方案（步骤 1）和模拟方案（步骤 2）在见效速度、持久性和投入上差异巨大。没有问题 7 的答案，就无法确定二者的优先级。

• 截止日期紧迫时，优先采用软切换和特殊值。
• 需要长期持续建设时，优先采用硬隔离的独立副本和测试数据构建器。
• 如果预算以周而非季度计算，就应从本次工作中移除硬隔离的独立副本，而不是把它排到最后。解除阻塞的条件：“首次发生跨模式数据泄漏，或合规制度落地。”

按产品领域划分

产品领域是影响此设计的关键维度，因为它决定了特殊值的形式，以及监管机构会以什么作为上线门槛：

• 类似支付：特殊值通过交易工具传递（可映射到特定拒付、争议、欺诈风险等级、增强身份验证的卡号）；上线受合规要求约束（KYC）；沙箱必须模拟其无法实际执行的结算。
• 类似通信：特殊值通过地址传递（电话号码，按操作区分）；硬性保障是绝不让任何真实消息离开沙箱——调查中隔离最严格的方案甚至拒绝让测试凭据引用生产资源。
• 类似数据聚合：特殊值通过身份信息传递（测试用户名／角色选择测试数据形态，密码后缀选择错误条件）；设计核心是测试数据的多样性，而非交易结果。

根据你的领域设计载体和门槛。references/magic-value-catalogs.md 中的示例目录涵盖了这三个领域。

工作流

1. 选择隔离模型——后续每个步骤都以此为基础。
2. 确保每条失败路径都可触发——使用确定性测试值和模拟对象。
3. 模拟事件和时间——触发测试事件、操控时间、重置和填充测试数据。
4. 加固凭据、配额和滥用防护。
5. 设计上线流程——合规门槛、切换检查清单、金丝雀发布。

以下各节按顺序介绍每个步骤，反映集成方使用沙箱的方式：先测试失败路径，再测试异步／时间行为，然后加固生产环境，最后切换上线。按此顺序交付，并依据「衡量」中的基准为每个阶段设置门槛。

1. 选择隔离模型

两个彼此独立的问题常被混为一谈，统称为“提供测试模式”：是否_隔离测试数据，以及隔离边界有_多严密。三种模型，按优先级排序：

• 效率：软切换 > 硬性独立副本 > 无测试模式（由集成方自行约定）

• 工作量：硬性独立副本 > 软切换 > 无测试模式

• 价值：硬性独立副本 > 软切换 > 无测试模式

• 默认选择：软切换。 使用同一个账户，为每个对象添加模式标志，并通过带模式前缀的键路由到测试基础设施。测试数据不会被线上调用看到，反之亦然。在现有技术栈上需要一到两周的工作，其中大部分用于验证数据不会跨模式流动；它适用于常见情况：一个集成方、一个集成项目、中等风险。

• 升级为硬性独立副本，即在结构上完全分离的环境（使用独立主机或账户副本，以及独立的键、Webhook 和配置），适用于以下情况：

  • 团队需要并行测试，且不能污染共享的测试数据。
  • 合规要求必须证明环境已隔离。
  • 切换失败可能造成严重影响（误以为处于测试模式，实际却操作了线上数据）。

  这是最容易被忽视的选项：价值最高，工作量也最大，因此在效率比较中总是落败。然而，参考支付平台还是构建了这一模型，并将其设为新账户的默认选项，只为现有账户保留切换模式。这样一来，跨模式数据泄漏在结构上就不可能发生，而不只是被策略禁止。

• 无测试模式（由集成方自行约定）——说明集成方如何通过单独的测试应用、组织或代码仓库自行隔离——仅当 API 主要用于读取，且不涉及资金、外发消息或敏感的第三方数据时才可行。只要其中任何一类数据会经由 API 流转，就应彻底排除这个选项，而不只是降低优先级：不要将它列入候选方案。

此排序是默认选择，并非铁律。根据问题 1-2 的答案及其他已知情况重新排序：

• 全新构建的平台可以从第一天起就采用硬性隔离模型，成本远低于事后改造。
• 受监管的领域会直接排除切换模式。
• 已采用按租户隔离基础设施的团队，几乎可以免费提供独立副本，这会改变工作量排序和最终选择。

无论最终选择哪种模型，都要在设计文档和说明文档中明确写明隔离级别。“沙箱”本身不保证任何隔离效果——调查过的供应商沙箱经常是共享的、受速率限制的，而且在同一个名称下也只实现了部分隔离。如果产品面向终端用户提供界面（问题 6），沙箱也需要提供对应的终端用户侧环境，而不只是 API 响应。

有关此选项背后六家供应商的比较，请参阅 references/isolation-models-and-key-prefixes.md。

2. 让每条失败路径都可触发

沙箱的核心交付目标是确定性：集成方必须能够按需触发任何有文档说明的结果，尤其是失败。三种模拟原语，按排名排列：

• 效率：magic values > on-demand simulation endpoints > config-driven fixture builder

• 工作量：config-driven fixture builder > on-demand simulation endpoints > magic values

• 价值：config-driven fixture builder > on-demand simulation endpoints > magic values

• 默认层级：magic values。 有文档说明的虚假输入可确定性地选择一种结果。每类结果大约需要一天开发时间，不会引入新的 API 接口，集成方需要记住这些值。

  设计规则：

  • 选择集成方在你的领域中已经会输入的载体（参见上文“产品领域划分”）。
  • 不要只覆盖成功路径，还要包含有意触发失败的值和升级验证流程。
  • 将每个值一对一映射到已发布目录中的真实错误代码（samber/developer-platform-skills@api-error-design 涵盖的范围）。magic values 必须触发真实的错误分类，绝不能使用仅供沙箱使用的错误格式。
  • 当同一输入在不同调用中含义不同，按操作标注各个值。没有标签的多操作目录会成为有文档说明的集成陷阱。

• 一旦结果不再取决于请求输入，就升级到按需模拟端点：仅供沙箱使用的端点，用于创建测试对象以填充数据、强制对象进入特定状态（需要登录、验证已通过），或立即触发特定事件。这些端点可以覆盖无法用输入值编码的场景。

• 由配置驱动的 fixture 构建器——接受完整 fixture 描述（账户、历史记录、强制错误）的单个端点——是最不受青睐的选项：它是调研中粒度最细的机制，工作量也最大，在效率评比中每次都落败。只有当集成方的数据形态确实各不相同时（数据聚合领域），才应推广它；并且应随附一套入门 fixture 库，而不是让每个集成方都手写配置。

将 magic values 视为 API 合约：稳定、有文档说明、永不过期。集成方的 CI 测试套件会依赖每一项，因此新增值没有问题，但更改已有值会造成破坏。示例代码中建议使用令牌，而不是原始敏感值——在测试代码中使用类似银行卡号的原始值，会形成合规方面的习惯，并可能泄漏到生产路径中。

五家供应商的完整目录：references/magic-value-catalogs.md。

3. 模拟事件和时间

冻结 数据、却让 时间 照常流逝的沙盒无法测试由时间触发的逻辑，例如续订、试用期到期、催款和计划任务。解决方法是提供确定性时钟原语，而不是通过文档告诉集成方等待。

• 触发测试事件：为集成方提供明确的“立即触发此事件”机制，例如每种事件类型对应一个沙盒端点或 CLI 触发器。由你决定测试事件何时以及如何触发；投递机制（签名、重试、日志）属于 samber/developer-platform-skills@webhook-platform-design。

  两个陷阱：

  • 如果沙盒中的状态变更与事件投递相互独立，请在文档中说明。否则，集成方可能会一直等待永远不会到来的事件。
  • 如果 CLI 触发器无法生成有效签名，请在“始终验证签名”规则旁说明这一点，否则该规则会与自己的测试工具冲突。

• 时间操控：提供一个时钟对象，其时间被冻结，测试对象关联到该时钟；再通过主动推进时钟，让状态转换和事件像时间确实流逝了一样发生。限制每次推进的幅度，以及单个时钟可承载的复杂度——参考实现有意限制了这两者，以控制模拟复杂度。对于简单场景，更轻量的方案是使用自动老化的测试数据，让日期字段每天自动偏移，始终使最新数据保持为“今天”。

• 重置和填充数据：

  • 仅使用合成数据填充；绝不复制生产数据。
  • 同时提供对象创建端点（一次调用即可填充已知状态）和重置端点（恢复到干净状态）。
  • 定期自动重置共享沙盒，避免累积的测试数据使其偏离实际状态。

• 一致性：从与生产环境相同的基础设施即代码中生成沙盒配置，确保任何差异都是有意为之且有文档说明。环境漂移——配置差异、数据陈旧、版本不一致——是“沙盒中可用，线上却失败”的根本原因。

4. 加固凭据、配额和滥用防护

• 带模式前缀的密钥：采用外部已有规范的前缀约定，即类型前缀加上 _test_/_live_ 模式子串。

  • GitHub 秘密扫描会将精确的参考前缀列为零误报的推送保护目标。使用已识别的格式，可获得不受你控制的工具提供的免费泄露检测；采用新方案则一无所获。
  • 双向强制边界：live 密钥拒绝 test 值，test 密钥拒绝真实值。
  • 除模式子串之外的密钥格式和生命周期管理，参见 samber/developer-platform-skills@api-auth-key-management。

• 测试密钥并非没有风险：在切换模式下，测试密钥仍可读取和写入真实账户配置（客户、webhook 端点），因此也需要妥善保护机密——前缀传达的是模式，而非风险等级。告知集成方，绝不要在本地开发中使用 live 机密；并按环境隔离数据存储、重定向允许列表和凭据，而不是让同一代码库根据运行时标志进行分支。

• 两类滥用，需要不同的缓解措施。切勿混为一谈。

  • 密钥泄露风险：带前缀的密钥可由机器识别，并经常被从公共代码仓库中搜集。缓解措施：仅在服务端保存机密、限制密钥权限、启用秘密扫描。
  • 信用卡测试/盗刷滥用：攻击者会通过 live 结账端点验证窃取的支付工具批次。沙盒通常对盗刷毫无用处，因为测试交易不会触及真实网络，因此这是 live 模式的控制措施，而非沙盒控制措施。缓解措施：边缘机器人挑战、按端点限制速率，以及限制每位客户使用的支付工具数量和每个 IP 的连续拒绝次数。

  Stripe 自身的欺诈团队指南指出，为所有 Checkout 用户启用托管 CAPTCHA，可将信用卡测试减少 80%，同时对授权率的影响低于 0.02%；这是一种罕见的欺诈控制措施，其对合法用户造成的成本几乎可忽略不计，且有量化数据支持。

• 沙盒配额：不要假设沙盒需要单独的速率限制层级。此处审查的六家供应商中，有三家在测试模式下沿用生产环境的限制，这也能确保集成方的限流代码经得起实际检验。

  • 沙盒专属数值限制是这些供应商中记录最少的维度，因此应将“每家供应商都会公布不同的沙盒限流”视为错误说法。
  • 只有在失效模式是 评估流量滥用（抓取免费层、针对共享沙盒进行负载测试）时，才应构建专用沙盒配额。应将其建模为针对预生产层级的总体流量和范围上限，而不是更快的每分钟限流器。
  • 各供应商的配额策略：参见 references/isolation-models-and-key-prefixes.md。限流层级的设计机制参见 samber/developer-platform-skills@api-rate-limit-policy。

5. 设计上线流程

上线绝非纯粹的技术问题，即使凭证切换轻而易举——每家受访厂商都会在进入生产环境前设置合规或审核环节。请设计以下三项内容：

1. 审核关卡：根据实际义务选择合适的形式——KYC 激活、分级／自动审核、合作伙伴审核、发布者验证或套餐等级。不要引入超出领域需求的繁重关卡。让预审核失败一目了然：明确提示“环境尚未获批”，而非含糊的 401 错误。

2. 切换检查清单：

   • 在所有位置更换凭证。
   • 配置全新的实时模式事件端点和签名密钥（测试模式密钥无法沿用）。
   • 在第一笔实时交易发生前启用滥用规则。
   • 针对每条集成路径执行少量实时金丝雀测试，确认操作生效且事件已送达，并尽可能在之后撤销。

   沙盒测试通过是必要条件，但并不充分：没有沙盒能复现真实网络、真实结算时间或全强度的欺诈防护系统。

3. 可发布版本：将检查清单和五个反复出现的切换陷阱作为文档提供给集成方——每个平台最终都会处理同样的五类支持工单。

审核关卡形式、完整检查清单、陷阱和触发回退的情况：references/graduation-gates-and-cutover-checklist.md。

故障模式

反模式检查清单——每一项都是设计评审中会直接指出的问题：

• 将模拟服务作为“沙盒”发布：它没有状态，测试的是集成方对你们 API 的假设，而不是他们是否正确；API 变更时，模拟服务仍会模拟旧行为，生产环境却会悄然故障。由厂商实际操作的真实对象不会发生这种偏差。
• 文档说明了失败结果，却没有办法在沙盒中确定性地触发它。
• 使用魔法值返回仅限沙盒的错误格式，而非实际发布的错误分类体系。
• 依赖时间的逻辑只能通过等待实际日历时间来测试。
• 文档中出现“沙盒”一词，却没有说明隔离级别。
• 错误环境的凭证导致含糊的身份验证失败，而不是清晰的“环境错误”提示——这是一个有名且反复出现的支持工单诱因。
• 未向集成方说明五个切换陷阱（忘记更换密钥、跨环境粘贴、假设沙盒能预测生产环境、实时 Webhook 端点过期、未测试真实资金相关的失败路径）。
• 将真实生产数据复制到沙盒中作为种子数据。
• 共享沙盒没有重置机制，也没有定期清理。

度量

• 失败路径覆盖率：每种已记录的失败结果（拒绝、错误代码、升级验证流程、争议／撤销）都可通过特定值或模拟端点确定性地触发——这是必须达到 100% 的门槛；任何一种无法触发的失败路径都会导致审计不通过。
• 事件／时间覆盖率：每种异步事件类型都可按需触发，每种依赖时间的流程都可通过模拟时间进行测试，而非等待——这同样是必须达到的门槛。
• 跨环境事件：跟踪因使用错误模式的凭据而导致的支持工单和身份验证失败；设计目标是零事件，通过结构性设计实现（自描述前缀加上清晰易懂的环境错误提示），而不是警告集成方小心操作。
• 上线演练：在将任何集成宣布为已上线之前，端到端执行切换清单——包括一次确认事件已送达的线上金丝雀测试；将未经演练的清单视为尚未交付的功能。

持续迭代设计，直至两个覆盖率门槛均达标。这些门槛从软切换阶段开始适用；第 1 步的“无测试模式”阶段没有可供触发任何操作的服务商侧沙盒，因此相关门槛不适用，而非未达标。若该阶段也必须满足这些门槛，就会否决本技能本身认定为可行的方案。

该阶段以以下事项取代这些门槛：已发布集成方隔离指南，并且第 1 步中以只读为主／不涉及资金／不发送消息／不包含敏感数据这几项条件均已书面确认。从第一个月开始，建立跨环境事件和沙盒转线上所需时间的基线，并持续改善；由于没有可借鉴的跨行业阈值，这两项应作为趋势跟踪。

调用示例

• “为我们的支付 API 设计一种测试模式——集成方目前在预发布环境中使用真实卡号进行测试。”
• “我们要添加 Webhook；集成方需要一种触发测试事件并模拟订阅续订的方法，而不用等待 30 天。”
• “为我们的新公共 API，在测试模式开关和完全独立的沙盒环境之间做出选择，并设计上线流程。”

参考资料

• 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 - 用于安排每种接口面的总体决策；它安排的每种接口面都需要在合作伙伴上线前具备测试模式，而本技能负责设计这一层。
• samber/developer-platform-skills@sample-app-strategy - 示例应用组合，其 CI 和体验环境都连接此沙盒运行；沙盒无法模拟的流程会使示例只能编译，无法运行。