区分描述和执行
固定工具支持的规范版本，描述参数、正文、响应和安全要求。声明安全要求之后，应用及网关仍须实际落实。
| 要素 | 描述内容 | 额外验证 |
|---|---|---|
| 模式 | 结构和约束 | 实际校验与业务规则。 |
| 文档中的响应 | 预期状态和内容 | 实际响应是否符合约定。 |
| 安全要求 | 声明的机制和权限 | 每项操作的真实访问控制。 |
| 示例 | 一个说明性场景 | 一致性、无秘密及边界情况。 |
共享前进行审查
- 检查必填字段、类型、范围、分页、错误和内容格式，使用符合模式的虚构示例，不含秘密或客户数据。
- 在受控环境中对照描述和真实请求响应，测试无凭据、权限不足及账户之间的隔离。
- 检查外部引用及解析它们的工具。清理公开描述中的敏感信息，保护私有环境与操作。
持续维护文档
逐次审查差异并指定负责人。生成的客户端或示例即使结构有效，也可能忽略业务规则。交互控制台应使用合适环境和有限权限，清晰标明会改变状态的操作。
一手资料
将 OpenAPI 与运行中的服务进行比较。
一份有效的 OpenAPI 描述应包含失败响应、模式以及客户端实际遇到的示例。如果文档与 API 不符，集成可能在演示环境中运行正常，但在生产环境中却会失败。
- 将成功和错误案例与描述进行比较。
- 记录可选值、分页和操作限制。
- 在更改合同之前，测试一个具有代表性的客户端。
一手资料：IETF RFC 9457 — Problem Details for HTTP APIs. 相关方法：阅读实用指南.
ZIP与TAR：在目录和资源预算内解压
发布解压文件前验证路径、链接和实际解压数据量。
- 在最小权限的新建非公开目录解压。拒绝绝对路径、向上遍历、不必要的链接和特殊文件。按目标系统规则检查实际解析目标及冲突，包括大小写。文本前缀本身不能证明目录限制。
- 对实际写入字节、条目数、深度、时间和进程资源设单文件及累计上限。不仅依据压缩或声明大小。不需要嵌套档案就拒绝；允许时所有层共享总预算。更新库和过滤器。
- 测试../、绝对路径、链接、重复项和预算超限。中止应使批次不可发布且不覆盖现有文件。发布前验证文件类型与内容；清理隔离目录时确认目标位置。
可复现的验收案例
虚构示例：数据不代表客户或实际观察结果。
查看案例输入
{
"compressed_mb": 2,
"expanded_mb": 600,
"aggregate_budget_mb": 100,
"first_files_valid": true,
"expected": "stop_on_actual_overrun_and_do_not_promote"
}预期判断
虚构例：2 MB压缩数据产生600 MB，预算为100 MB。实际写入字节超限即停止；即使前几个文件看似有效也不发布该批次。
Python — tarfile extraction filters and further verification
小档案或过滤器能保证安全吗？
不能。小档案可能大幅膨胀。需加入资源上限、路径规则及解压文件验证。
一手资料：Python — tarfile extraction filters and further verification. 相关方法：阅读实用指南.
API错误：类型、状态与证据
此语言版本的详细参考说明以英语提供。
Include errors in contract tests
A new type URI, removed extension or changed status may alter consumer behaviour. Failure examples are part of the contract alongside successful responses.
- Replay existing clients against representative refusals.
- Check tolerance of unknown extensions and localised text.
- Document migration of a problem identity and actually observed use.
Explore problem types and eight fictional responses →
IETF · M. Nottingham, E. Wilde, S. Dalal · RFC 9457 · July 2023 · obsoletes RFC 7807 · §3.1, §3.2, §4.2, §5