<?xml version="1.0" encoding="utf-8"?>
<rss version="2.0" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/">
    <channel>
        <title>AntAPI Blog</title>
        <link>https://antapi.dev/zh-CN/blog</link>
        <description>AntAPI Blog</description>
        <lastBuildDate>Tue, 20 Oct 2026 00:00:00 GMT</lastBuildDate>
        <docs>https://validator.w3.org/feed/docs/rss2.html</docs>
        <generator>https://github.com/jpmonette/feed</generator>
        <language>zh-CN</language>
        <item>
            <title><![CDATA[API 文档需要覆盖完整生命周期]]></title>
            <link>https://antapi.dev/zh-CN/blog/documenting-api-lifecycles</link>
            <guid>https://antapi.dev/zh-CN/blog/documenting-api-lifecycles</guid>
            <pubDate>Tue, 20 Oct 2026 00:00:00 GMT</pubDate>
            <description><![CDATA[为什么接口参考还需要配套说明重试、批量处理和结算的接入指南。]]></description>
            <content:encoded><![CDATA[<p>接口 Schema 告诉你如何发送请求，却很少解释响应到达前连接断开该怎么办。AntAPI 将生成的 API Reference 与接入指南分开维护，让字段定义和实际工作流程都有明确的位置。</p>
<h2 class="anchor anchorTargetStickyNavbar_tleR" id="从能力出发解释它的生命周期">从能力出发，解释它的生命周期<a href="https://antapi.dev/zh-CN/blog/documenting-api-lifecycles#%E4%BB%8E%E8%83%BD%E5%8A%9B%E5%87%BA%E5%8F%91%E8%A7%A3%E9%87%8A%E5%AE%83%E7%9A%84%E7%94%9F%E5%91%BD%E5%91%A8%E6%9C%9F" class="hash-link" aria-label="从能力出发，解释它的生命周期的直接链接" title="从能力出发，解释它的生命周期的直接链接" translate="no">​</a></h2>
<p>API Reference 描述已发布的 Method、路径、参数和响应字段，产品页说明能力的用途。接入指南将这些内容连接成应用流程：鉴权、提交工作、保存执行身份、取得结果，再理解结算。</p>
<p>WHOIS 很适合说明这种区别。单条查询返回注册信息，批量提交先返回 Job ID，之后才是查询进度和分页读取结果。如果将提交的 HTTP <code>202</code> 当作完成，应用流程和计费解释都会缺少后半段。</p>
<h2 class="anchor anchorTargetStickyNavbar_tleR" id="受理执行与结算是不同事件">受理、执行与结算是不同事件<a href="https://antapi.dev/zh-CN/blog/documenting-api-lifecycles#%E5%8F%97%E7%90%86%E6%89%A7%E8%A1%8C%E4%B8%8E%E7%BB%93%E7%AE%97%E6%98%AF%E4%B8%8D%E5%90%8C%E4%BA%8B%E4%BB%B6" class="hash-link" aria-label="受理、执行与结算是不同事件的直接链接" title="受理、执行与结算是不同事件的直接链接" translate="no">​</a></h2>
<p>异步付费操作执行前，Gateway 预留授权范围内的最高费用。平台之后验证最终成功数量，扣除对应部分，再释放剩余预留。WHOIS 的进度查询、已有结果读取、取消和 TLD 支持范围查询免费，但仍需鉴权。</p>
<p>成功定义也应和流程一起说明。WHOIS 将已注册和明确未注册都视为成功结果，unknown 则不能作为明确结论。同批规范化后的重复域名共用处理，取消不会抹去已经完成的成功项。</p>
<p>这些区别既影响 Receipt 的理解，也影响产品界面的实现。界面应该能够展示任务已受理，而不会让用户误以为所有条目已成功，或预留已成为最终扣费。</p>
<h2 class="anchor anchorTargetStickyNavbar_tleR" id="把恢复步骤放进示例">把恢复步骤放进示例<a href="https://antapi.dev/zh-CN/blog/documenting-api-lifecycles#%E6%8A%8A%E6%81%A2%E5%A4%8D%E6%AD%A5%E9%AA%A4%E6%94%BE%E8%BF%9B%E7%A4%BA%E4%BE%8B" class="hash-link" aria-label="把恢复步骤放进示例的直接链接" title="把恢复步骤放进示例的直接链接" translate="no">​</a></h2>
<p>批量示例需要在提交前保存幂等键，收到响应后保存 Job ID，并解释响应丢失时如何处理。使用原 Key 恢复同一次逻辑操作，生成新 Key 则可能创建第二个任务。</p>
<p>同样的要求也让示例更适合直接使用：调用统一经过配置的 Gateway，Secret 只保存在可信服务端环境，文档不编造价格或通用限制。</p>
<p><a href="https://antapi.dev/zh-CN/docs">快速开始</a>介绍第一次请求，<a href="https://antapi.dev/zh-CN/docs/batch">批量查询指南</a>和<a href="https://antapi.dev/zh-CN/docs/billing">计费说明</a>覆盖后续生命周期。这些指南配合生成的接口参考使用，不重复维护字段 Schema。</p>]]></content:encoded>
            <category>engineering</category>
            <category>documentation</category>
        </item>
    </channel>
</rss>