摘要

  • APNIC 当前的 OpenAPI 把 RDNS、路由与 ASPA 批请求拆成 create、update、delete 三类数组，但每个结果项只声明 status 和 message 两个属性。
  • 合理的补充不是公开内部事务日志，而是给每个结果一个可验证的“回信地址”：请求数组与索引，或由客户端提供并由服务器原样返回的不透明键。

假设一个网络团队在没有事故、没有维护的普通工作日，通过 APNIC 注册局 API 新建两条路由对象、修改一条、删除一条。客户端把四项工作装进一个批次，服务器完成格式校验，返回可轮询的任务链接。稍后，任务对象中出现四条或更多结果。

问题不是有没有结果。公开规范明确给出三种状态：success、failure 和 notification，并允许一段 message。问题是每条结果没有地址。它没有说自己来自 create[0]、update[0] 还是 delete[0]；没有回显客户端键，没有资源 ID，没有 location，也没有在文字中规定响应数组必须按什么顺序对应请求数组。

这只是对一份公开机器契约的观察。此次核查固定的是 API 版本 0.0.2、OpenAPI 3.0.0 文件，共 59,622 字节、1,934 行。我们没有向 APNIC 发送任何需要认证的写请求，也没有制造失败来探测行为。没有证据显示线上服务打乱顺序、把结果配错、漏掉项目，或让某个会员发生了错误重试。

实际系统完全可能一直保持稳定顺序；message 也可能清楚写出目标；APNIC 的内部日志和测试或许保存了精确关联。本文能说的只有一件事：这些保证没有写进所检查的公开契约。

先把最强的辩护讲清楚

APNIC 已经避免了最粗糙的“发出即忘记”设计。规范称，所有 POST、PUT、DELETE 都通过异步任务处理。请求先接受模式校验；通过后，客户端得到任务地址，可以继续轮询。任务对象能够保留原请求，并在完成后携带处理时间、HTTP 状态码和响应内容。

批处理也不是只有一个全局的真假值。batch-response 被描述为针对每项动作分别给出结果，并在需要时加入通知。规范开头还说，批处理会“在可能的情况下”以事务方式生效；一般而言，除影响 Whois 的交互外，其余交互采用事务处理。客户端也可以通过读取接口、列表接口和 MyAPNIC 核对状态。

这套产品并非黑箱交付。APNIC 在正式上线前提供过测试环境，在 APNIC 57 举办过动手活动，在 APNIC 58 演示产品，并在规范中同时给出私下与公开的反馈地址。谨慎的集成团队有渠道验证假设并提出问题。

因此，一个紧凑的响应模式可能是有意选择。线上代码可能严格遵守一个从未变化的次序；消息可能足以让操作人员定位对象；同一事务组也可能天然减少分支。APNIC 还可能维护不适合公开的测试、审计关联和数据库边界。

这些可能性不能被当成客套话略过。本文不声称 APNIC 丢失、重复、重排或错误执行任何动作，不声称会员已经受到损害，也不要求公开凭证、私有对象、数据库拓扑或事务细节。批评只针对一个更窄的边界：自动化程序能否从权威契约本身确定“这条回答属于哪一个问题”。

请求端有坐标，响应端没有

并列阅读请求与响应模式，差异非常清楚。RDNS、路由与 ASPA 批次都把动作分成 create、update、delete。不同资源、不同动作拥有不同字段。删除路由可以指向既有 ID；删除 RDNS 记录会指明地址范围；更新 ASPA 可以携带 ID、客户 ASN 与上游 ASN 列表。

也就是说，每个请求项天然有一个坐标：资源族、动作类型、数组下标。即使对象内容敏感，客户端仍然知道自己提交了 delete[1]。

共同响应模式却把这个坐标压平了。results 内部对象精确声明的属性只有两个：status 与 message。前者给出宽泛结果，后者只是字符串；没有结构化字段表达“本行回答 delete[1]”。

如果服务器严格保持顺序，列表当然可以工作。但顺序只有写入契约后才是控制。是先依次返回所有 create，再返回 update 与 delete 吗？notification 是否单独占一行？在执行前就未通过校验的项目会不会有结果行？一个事务组回滚时，是每项一行，还是一条组级结果？当前文件没有给出规范性答案。

OpenAPI 本身还带来第二层界限。在 OpenAPI 3.0 中，对象模式列出某个属性，并不自动意味着该属性必定出现；只有进入 required 数组才构成必选项。所检查的 batch-response 顶层没有这个数组。因此，文件描述了 type 与 results 可以出现，却没有把它们写成最低保证。task、task-link 和 success-response 顶层也有相同情况。

这仍然不是说线上响应真的缺字段。它说明的是：仅凭该文件生成的客户端或契约测试，无法把这些字段当成硬保证。

未声明的顺序会变成长期依赖

再做一个纯粹的测试设想。某批次包含三项新增、两项删除，返回顺序是 success、failure、success、success、notification。若没有公开规则，程序就得自己发明解释：按三组数组拼接后的次序配对；从消息里找对象名称；把通知从计数中排除；或者重新读取所有相关资源。

每种办法都有临界点。新增一种通知，可能让位置整体偏移。消息措辞一改，文本解析器就失效。把批次拆成单项调用，可以减少歧义，却放弃批处理的吞吐量，甚至放弃事务价值。全量读后核对更稳妥，但会增加延迟、请求数和限流压力。

成本也并不平均。大型运营商能维护适配层、回归测试与人工队列；小团队往往复制一段示例代码，把隐藏假设带进多年运行。开源库维护者或咨询商最终变成非正式的语义裁判，而权威规范只需增加几个字节就能统一答案。

真正的风险不是一条错误消息，而是局部不确定性向外扩散。客户端不知道哪一项失败，就可能重试整个批次；为了避免重试，又可能对整个对象集合执行昂贵核对。明确关联能够把处置范围收回到单项或明确的事务组。

最小的结果映射

最轻的方案，是让每条结果返回来源数组和零起点索引，例如 create:0、update:2、delete:1。更耐久的方案，是允许客户端为每项动作提供不透明键，服务器只负责原样回显。这个键不需要含有前缀、ASN、联系人或任何业务信息；它只在会员自己的任务中有意义。

关联字段旁边，可以放置动作类型与稳定的机器结果码。在安全且适用时，返回资源 ID 或 location，方便精确读取。失败可使用结构化问题对象，而不是让自由文本承担主键功能。处置建议也应有边界：修正后重试、继续轮询、执行核对，或不要重复提交。

若多项动作共享一个原子事务，则可以增加事务组 ID 与组级结果。这样不会把一次整体回滚伪装成五个彼此独立的失败，也无需泄露事务日志。公开的是对应关系，不是内部实现。

还有一个更小的改法：规范性地声明响应顺序，并给出混合新增、修改、删除、失败和通知的完整示例。这比沉默好。不透明键更能抵抗稀疏响应、过滤与未来重排，但具体选型属于 APNIC。最先需要作出的决定只是：让规则可见、可测、可版本化。

规范文件本身就是运行面

APNIC 上线注册局 API，是为了让会员自动化原本在 MyAPNIC 完成的工作。预览、测试环境、黑客松和产品演示都说明，它期待软件长期依赖这项接口。由此，OpenAPI 不再只是服务旁边的说明书；它会生成类型、SDK、验证器、测试与操作手册。

当前规范值得肯定的地方很多：它主动说明异步任务、限流、事务限定和反馈渠道。缺少请求项关联字段，并不证明产品失控；恰恰说明这项 API 已经成熟到值得审视细小契约缝隙。

APNIC 无须等待一次真实的配错才能修补。它只需让每条结果带着返回原问题的地址。届时，success、failure 与 notification 才不只是需要人来摆放的标签，而是机器可以安全采取下一步的证据。

来源