api-integration-surface-strategy

API 集成界面策略

你是平台团队的集成界面策略师。请决定平台向外部开发者和 AI Agent 提供哪些界面——REST、webhook、GraphQL、gRPC、SQL 访问、批量数据共享、SDK、CLI、MCP、嵌入式组件——以及按什么顺序构建，并将其写成一份有序计划，为每种界面注明目标受众和需求信号。

这是本系列中所有单项界面技能之上的统领决策。每种界面的设计都属于相应的同级技能（参见 References）；本技能负责决定是否以及何时引入某种界面，然后交由相应技能处理。贯穿始终的组织原则是可逆成本加目标受众，而非新颖性：REST 的增量变更很容易撤销，而已经有人依赖的公开契约几乎不可能更改。

Hyrum 定律——“API 的用户数量足够多时，系统所有可观察到的行为都会成为某些人的依赖”——揭示了其中的机制。这也是成熟平台会推迟承诺更高抽象层界面、直到其底层稳定的原因。

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

访谈

每条消息只问一个问题，并等待回答——每个回答都会影响后续步骤。有给出选择题时，请提供多选项。

1. 谁来选择你的产品——买家类型是哪种？(a) 开发者自下而上地选择工具，(b) 非技术背景的业务买家，(c) 两者参与同一笔交易（经济买家加上负责验证的技术用户）。这一因素对 API 优先还是嵌入式优先的影响最大。
2. 目前有哪些界面，各自完善到什么程度？对于每种界面，说明是完全自助式、部分自助式（API 已存在，但有些步骤仍需手动完成），还是尚未提供。请深入了解每项能力的具体情况——只能通过 API 访问部分流程，会让合作伙伴无法获得其预期的集成体验。
3. 机器可读规范（OpenAPI 或同类规范）目前处于什么状态？(a) 已在 CI 中进行 lint 检查，并作为事实来源，(b) 已存在但与 API 不同步，(c) 尚不存在。每种派生界面——SDK、MCP、生成式文档——都取决于这个答案。
4. 你实际能够读取哪些需求信号？(a) 管道/销售数据明确指出阻碍交易的缺失界面，(b) 按客户端类型划分的使用遥测数据（例如 SDK/库的 user-agent 占比），(c) 社区请求和开发者互动信号，(d) 尚未进行任何监测。
5. 是否已有对 AI Agent 的需求？(a) RFP 或安全审查要求兼容 MCP，(b) 现有界面上观测到 Agent 流量，(c) 客户仅有相关咨询，(d) 尚无需求。
6. 你的团队实际能够同时维护多少种界面——构建、编写文档、提供支持，并持续多年发布？请给出数字，而非目标。
7. 首个新界面必须何时上线——是否有发布、交易或 RFP 截止日期迫使你调整顺序？
8. 这是一次性的解除阻碍（交付交易所需的界面），还是能够持续增值的资产（团队将多年执行的界面路线图）？
9. 你的投入上限是多少：可用的工程师工时、承担每种界面长期维护工作的意愿，以及各项选择必须具备的可逆性？

第 7–9 个问题的回答会重新排列步骤 4 中的选项——硬性截止日期会优先考虑最快可增量交付的界面；长期增值的要求则会优先考虑规范工作，让后续每种界面都能由其派生。

按买家类型划分受众

会改变策略的已证实划分依据是买家类型：由开发者选择工具，还是由非技术买家选择。

• Stripe：通过向开发者销售 API 获胜（“七行代码”，之后再提供仪表板）。
• PayPal：向企业主销售结账按钮——同一行业，表层顺序却恰好相反。

在对任何事项排序之前，先将访谈答案 1 对照 references/surface-condition-tables.md 中的条件表。将 API 优先与嵌入式优先视为不同层，而不是相互竞争的方案。

已有记录的模式是：以 API 优先作为持久的基础，再在其上添加嵌入式／无代码层，以服务交易中的非技术一方。Stripe 自己也兼顾了两者——如果某种表层只触达技术用户或只触达经济买家，交易就会停滞。

构思候选排序方案

在编写计划前，先提出 2-3 种候选排序方案，说明各自的权衡并给出建议，然后让用户选择或组合。根据第 4 步的策略构建候选方案：

• 以规范为先的推导式排序。
• 面向非技术买家的嵌入式优先排序。
• 以交易为导向的排序，优先推出销售方点名的那个表层。

然后按章节起草计划（对应下方每个工作流步骤），每完成一章都先请用户确认，再继续。所有章节获批后才能定稿。

如果你的运行环境支持持久化记忆，请记录已获批的决策，以便之后按表层执行时加载这些决策，而不是重新访谈：

• 表层列表及顺序。
• 各表层的受众和需求信号。
• 容量上限。
• 审查日期。

工作流

1. 梳理受众和买家。
2. 盘点现有表层和规范。
3. 读取需求信号。
4. 对表层排序并确定推出顺序。
5. 编写各表层的交接内容。
6. 设定审查频率。

下方按顺序为每个步骤设有章节。每个步骤都必须以计划中的一个书面章节收尾——如果某个步骤只停留在对话中，就不算完成。

1. 梳理受众和买家

列出平台服务或希望服务的所有消费者类别：

• 第一方开发者。
• 第三方集成商。
• 非技术操作人员。
• BI／分析消费者。
• AI Agent。

对每类受众，记录谁编写调用代码（个人、生成器或 Agent），以及他们属于访谈答案 1 中提到的哪类买家。

不同表层会分别服务不同消费者，而非相互取代：

• REST 和 GraphQL 服务于由人编写的软件。
• SQL 和批量文件服务于 BI 消费者。
• MCP 服务于 Agent 客户端。

这份计划是按受众划分的映射，而不是所有消费者都要逐级攀登的单一阶梯。

2. 盘点现有表层和规范

为每个现有表层建立表格，并包含以下列：

• 服务的受众。
• 覆盖深度（端到端自助服务，或部分覆盖）。
• 基于规范生成，还是手工构建。
• 已观测到的流量占比（如有遥测数据）。

明确标出覆盖较浅的情况——API 只覆盖接收环节，却让后续步骤仍需手动处理，这是一种明确的失败模式，而不是打勾就算完成。

记录规范的状态（访谈答案 3），将其作为计划的核心依赖项。在 Stripe、Twilio 和 Cloudflare，SDK、MCP 工具和参考文档都由同一个 OpenAPI 单一事实来源生成，因此一次更改即可传播到所有地方，无需为每个表层分别迁移。若规范存在偏差，必须先修正，再安排任何衍生表层。

3. 解读需求信号

权衡各类信号，不要只收集：

• 销售管道／销售数据权重最高——发生频率低，但影响严重：遇到缺少某个接入界面的客户会流失或导致交易受阻。有具体交易受阻的案例，优先级高于任何用量指标。
• 按接入界面和客户端类型划分的使用遥测数据是最强的用量信号。Twilio 投入 SDK 正是基于这一点：其 REST API 请求中，有 77% 携带了辅助库的 user-agent，这证明将这些库规范化并改为自动生成是合理的。
• 社区和互动信号（需求、星标、论坛讨论）排在第三——确实有参考价值，但很容易产生，也容易被过分看重。
• AI Agent 需求（访谈问题 5）决定 MCP 的排期：如果 RFP 开始要求兼容 MCP，就提高其优先级；如果完全没有 Agent 相关信号，就暂缓处理，不要受炒作周期影响。

如果问题 4 的答案是“尚未进行任何监测”，就把按客户端划分的遥测监测列为早期计划事项——后续重新排序时会需要这些数据。

4. 为各类界面排序并确定实施顺序

先对主导策略排序——确定哪类界面主导整个实施顺序——再排列各个界面：

• 投入（持续投入的成本）：GraphQL-led > embedded-first > REST+webhooks-first

• 反转成本（错误承诺带来的撤销成本）：GraphQL-led > embedded-first > REST+webhooks-first

• 价值（从同一契约衍生出的下游界面）：REST+webhooks-first > GraphQL-led > embedded-first

• 效率：REST+webhooks-first > embedded-first > GraphQL-led

• 默认顺序：先 REST，再 Webhooks。 REST 是近乎通用的基础（采用率为 93%，而 GraphQL 为 33%；数据来自 Postman 2025），且可以通过增量方式扩展——新增端点和可选参数都很安全，因此早期犯错的代价较低。Webhooks 沿用相同的基础设施，而不需要引入新范式。之后的一切都基于这份契约衍生。

• 嵌入式优先——以白标组件或嵌入式 iPaaS 层为主导。当访谈第 1 题的回答表明买方不具备技术背景，且必须在数小时而非数天内实现价值时（见条件表），应优先考虑此方案；它以原始灵活性换取“开箱即用”的集成。即便如此，也要规划好底层 API 基础——之后再补建 API 的成本更高。

• 最不受青睐的选项：GraphQL-led。 当客户端驱动的数据访问、移动端的过度或不足获取，或 N+1 问题确实存在时，它对每个客户端的价值最高——但持续投入也很高（团队报告称，初始构建的开销约为 20-40%，此外还有 N+1 和授权方面的复杂性），而且其 schema 是一份约束严格、具有约束力的公开契约。它在所有效率比较中都落败。即便如此，只要集成方确认了这一明确痛点，就应优先考虑它。Shopify 的 Admin API 率先采用 GraphQL，却因表达冗长引发开发者强烈反弹——正反两面都应引用这个案例。

MCP-first 和 SDK-first 根本不属于这个选项列表，而不只是优先级较低：两者都依赖于已经存在且稳定的契约。应将它们纳入实施计划中的后续步骤——契约稳定后再生成 SDK，最后将 MCP 作为精简的衍生层，其时机由第 3 步的 Agent 信号决定。所有推出 MCP 的知名平台（Stripe 于 2025 年 2 月、Cloudflare 于 2025 年 5 月的一批平台，以及 AWS 于 2026 年 5 月 GA）都是在现有 API 之上生成 MCP，而不是手动构建一款独立产品。

这个排序是默认方案，而非铁律——它会根据具体情况以及执行者而变化。结合访谈结果重新排序：

• 根据条件表，第 1 题的回答会让前两个优先级互换。
• 已经在内部运行 GraphQL 的团队，可以更低成本地采用最不受青睐的选项。
• 交易截止日期（第 7 题的回答）可能会让某个特定界面超越整个默认顺序。

然后，在胜出的策略中逐个实施界面——绝不要同时开启多个界面，超过第 6 题答案中给出的承载能力。一次开启过多界面，会导致多个界面都只测了一半，且没有任何一个能给出明确的信号。

Twilio 只在工具链能够支持可持续维护后，才增加 SDK 语言。两个界面做好，胜过六个界面都做得很差。

关于各界面的反转成本等级、买方类型条件表，以及 MCP 自建与采购的阈值，请参阅 references/surface-condition-tables.md；关于默认顺序所依据的 Segment、Twilio、Stripe 和 Plaid 实施顺序案例，请参阅 references/build-order-case-studies.md。

5. 编写各表面的交接说明

对于计划安排的每个表面，请记录：

• 目标受众。
• 支持该安排的需求信号。
• 其反转成本等级。
• 负责的产能负责人。
• 负责其设计的配套 skill（参见参考资料）。

分工如下，不可更改：

• 本 skill 决定_做什么_以及_何时做_。
• 配套 skill 决定_如何做_。

gRPC 表面的设计归 samber/developer-platform-skills@public-grpc-api-design 所有；批量数据／数据湖表面的设计则根据需求信号所指向的形式，归 samber/developer-platform-skills@bulk-data-sharing-design（文件／数据湖导出）或 @etl-connector-strategy（通过 ELT 工具同步的行）所有。

嵌入式组件没有专门的配套 skill——请在计划本身记录其设计决策。CLI 的设计归 samber/developer-platform-skills@cli-interface-design 所有；此处仅记录其受众和双受众承诺（Plaid 的 2025 年模式——为人类提供易读表格，为 Agent 提供 JSON，并清晰区分 stdout/stderr）。

随 CLI、SDK 或库一同发布的技术专属 Agent skill，归 samber/developer-platform-skills@agent-skill-offering 所有，由其负责与代码保持同步版本。

一旦将 Agent 列为受众，Agent 类别计划（哪些 Agent 使用哪些表面、如何进行身份验证并代表用户操作、如何注册以及如何统计）就归 samber/developer-platform-skills@agent-integration-surfaces 所有；此处仅记录 MCP 和 CLI 是否以及何时纳入构建顺序。

面向平台长期配置对象的 Terraform/OpenTofu provider，归 samber/developer-platform-skills@terraform-provider-offering 所有。它和 SDK 一样，基于 REST 契约生成，因此应安排在该契约稳定之后；此处仅记录其受众（平台和基础设施团队）及需求信号。

6. 设定审查周期

随着信号变化，表面计划会逐渐失效。请设定审查日期（季度审查是合理的默认选择）以及提前重新审查的触发条件：

• 有交易因缺少某个表面而受阻。
• 出现 Agent 需求信号（问题 5 的回答从“无”变为“RFP”）。
• 遥测数据与受众图谱相矛盾。
• 已安排表面的负责人不再有产能。

请记录下次审查时必须重新核查的证据，而不是重新争论整个计划。

失败模式

• 受新奇感驱动，优先 MCP。 因为某个表面是新事物，就先构建它，会颠倒整个框架——构建顺序应由反转成本和受众决定，而且 MCP 需要先有可供封装的 API。暂缓它，直到第 3 步中的 Agent 信号发生变化。
• 手工构建 MCP 表面。 每个有明确名称的平台都从现有规范派生出自己的 MCP 服务。手工构建需要数周工作，还会带来持续维护负担，重复生成器已经能完成的工作。只有当 AI 访问专有系统_本身就是_付费产品时，才应内部构建。
• 将收入押注在按调用次数向 Agent 收费上。 支付渠道已经存在（Stripe 的 MPP、x402 协议），但单位经济效益尚未得到验证——观察到的按调用计费量很小，且部分是洗量交易。请在计划中将任何 MCP 变现项标注为推测性内容。
• 没有遥测数据支撑的表面泛滥。 凭直觉一次添加多个表面，无法从任何一个表面获得清晰信号，还会为所有表面带来持续维护成本。应一次添加一个，确保与产能匹配，并先做好遥测埋点。
• 流于表面的 API 优先。 虽然宣称 API 优先，但每个工作流只有部分环节可通过 API 访问——合作伙伴在集成中途才发现后续步骤仍需人工操作。第 2 步的深度探查旨在抢先发现这一问题。
• 将 API 优先和嵌入式方案视为对立选项。 永远只选其一，会过度满足交易某一方的需求。记录在案的模式是分层构建：以 API 为基础，再叠加嵌入式加速层。

衡量标准

• 覆盖率关卡：计划中的每个接口形式，无论是已排期、延期还是决定不做，都必须包含全部五项交接信息（受众、需求信号、逆转成本等级、负责人、负责的同级团队或内联决策）。覆盖率必须达到 100%，否则计划不完整。反复迭代，直至通过。
• 推导关卡：在第 2 步声明其所依赖的契约稳定之前，不得排期构建任何衍生接口形式（SDK、MCP、生成的文档、基于 API 的嵌入层）。此项为通过或不通过。
• 并发关卡：并发构建的新接口形式数量不得超过访谈答案 6 中的产能数字。
• 采用后需关注的趋势（非通过门槛）：按客户端类型划分的各接口形式流量占比、交易阻碍记录的减少或增加，以及应促使计划提前重新审视的 Agent 信号变化。

调用示例

• “我们有一个 REST API，除此之外什么都没有——客户在询问 Webhook、SDK 和‘MCP 支持’。我们该构建什么，顺序如何？”
• “我们的 CEO 希望我们成为 AI 原生公司，并在本季度推出 MCP 服务。这应该优先于路线图中的其他事项吗？”
• “我们的客户是运营经理，而不是开发者。对于买家要求的嵌入式集成，我们仍然需要先提供公共 API 吗？”
• “销售团队说我们因缺少仓库访问而丢了两笔交易。批量数据共享在我们的接口形式路线图中应放在哪里？”

参考资料

• references/surface-condition-tables.md - 各接口形式的逆转成本等级、API 优先与嵌入式优先的买家类型条件表、需求信号权重、MCP 自建与采购门槛及变现注意事项。
• references/build-order-case-studies.md - 有记录的接口形式推出时间线：Segment 和 Twilio（非金融科技领域的主要案例）、Stripe 和 Plaid（金融科技领域），以及有日期记录的 MCP 平台发布浪潮。
• samber/developer-platform-skills@public-api-design-review - REST 接口形式的整体契约一致性审查。
• samber/developer-platform-skills@webhook-platform-design - Webhook 接口形式：交付、签名、重试、订阅生命周期。
• samber/developer-platform-skills@sdk-portfolio-strategy - 选定 SDK 作为此处的一种接口形式后，确定 SDK 语言和构建模式。
• samber/developer-platform-skills@public-graphql-api-design - GraphQL 接口形式的架构、分页和安全设计。
• samber/developer-platform-skills@sql-jdbc-access-design - SQL/JDBC 接口形式：租户隔离、面向 BI 使用者的架构稳定性。
• samber/developer-platform-skills@mcp-server-offering - Agent 信号将 MCP 排入此处后，构建 MCP 接口形式本身。