环境与测试

契约里的两个环境

契约定义了两个 server。

Server	形态	说明
https://api.foreshock.org	托管端点。	共享控制面，数据按客户隔离。
https://{host}	私有部署。	host 默认 foreshock.internal。客户地址簿不离开客户环境。

除此之外，请求与响应的形状在两者之间没有任何差别。如果你的客户端在其中一个上表现不同，那是你的客户端有 bug。

沙箱

是否提供托管沙箱、以什么条件提供，在开通时另行商定，这里不作承诺。不要把集成计划建立在「一定会有沙箱」这个前提上。下面描述的故障态演练不需要它，而且不用它反而更彻底。

沙箱用来跑通顺路径与各种形状：翻页、幂等重放、webhook 签名校验、证据取件。

降级测试该在哪里做

沙箱不是测失败的地方。任何在线服务——包括我们的——都没法在你的测试套件需要的那一刻，以你需要的那个形状按需失败。如果你唯一的失败测试是「沙箱有一次刚好返回了 503」，那你什么都没测到。

把客户端指向一个你自己控制的桩，把矩阵跑一遍：

• 每一种降级的 200——HOLD 裁决，逐个带上各个降级 reason code
• 契约里的每一个非 2xx——400、401、403、409、429、500、503、504
• 一个永远不到达的响应——把连接挂到超过你自己的超时
• 被拒绝的连接、失败的 TLS 握手、解析不出来的域名
• 一个 200 但响应体损坏

然后对每一行断言同一件事：这条代码路径没有贷记。

契约是机器可读的，所以桩不必手写。请求与响应的契约测试由 api/openapi.yaml 生成——本文档的接口参考也从同一个文件渲染。由契约生成的桩会随契约一起更新，手写的那份不会，而且不会告诉你。

完整矩阵与该写的断言在「fail-closed 客户端契约」一页。