开发者体验验收：首次成功时间、留存口径与复算表

注册数在涨，不等于有人在用你的接口。

一、注册人数在涨，调用人数没涨

教学案例：独立开发者周野的图片压缩 API 上线第一个完整月，注册页带来 200 个新账号，他在周报里写下「新增开发者 200，环比增长 65%」。

以下情境为教学假设，人物、引语和数字不代表经核实的真实案例。

第二个月他打开调用日志，才发现 200 人里只有 140 人真正创建了 key，84 人成功发出过第一个请求，而第二周仍在调用的只有 31 人。也就是说，从注册到「还在用」，转化是 15.5%。

更刺眼的是分布：31 人中有 9 人来自同一个社区帖子，剩下 22 人分散在两个月里。他此前只看注册数，因为注册数最容易拿到，也最容易变好看。

注册是营销指标，调用才是产品指标。 一个 API 产品的验收至少要回答三个问题：拿到 key 的人有没有跑通第一次请求、跑通的人第二周还在不在、还在用的人是否在持续消耗配额。三者对应漏斗、留存与用量，缺一个都会误判。

从那以后，周野把周报的第一行改成「本周首次成功人数 / 新增 key 数」，注册数退到附录。这个改动很小，但它让团队第一次看见「注册很多、调用很少」的结构性缺口。

还有一个更隐蔽的问题：84 个首次成功的人里，有 27 个是在注册当天完成的，其余 57 个分散在第 2 到第 19 天。这说明「当天跑通」不是默认路径，而是一条需要被设计的捷径。

二、四个验收指标与分母

指标不难，难的是分母。同一个名字换一个分母，结论可以完全相反。

TTFHW 用中位数和 P90 一起看。 中位数告诉你典型体验，P90 告诉你尾部有多长。中位数 8 分钟、P90 三天，说明有一批人卡在某个具体环节；只看平均值会把这批人平均掉。

首次调用成功率的分母是「拿到 key」，不是「注册」。 从注册到拿 key 之间还有邮箱验证、创建应用、选套餐几步，那是另一个漏斗。混在一起算，会把 onboarding 的问题误判成 API 的问题。

28 天留存要固定「首周激活」的定义。 建议定义为「注册后 7 天内至少有一次 2xx 请求」。定义一旦定下，连续四个季度不要改，否则趋势不可比。

每千次调用工单数衡量支持负担。 它把工单量和用量绑在一起：调用涨了、工单同比例涨，说明支持效率没变；调用涨、工单不涨，说明文档与错误信息在起作用。

四个指标要一起读。 首次成功率高、28 天留存低，说明接入顺但价值不足；留存高、工单数高，说明产品有用但文档欠债；TTFHW 短、首次成功率低，说明示例跑得快但真实场景对不上。

目标值不是行业标准，是自己的基线。 第一个季度先测出真实值，第二个季度再定目标。照搬别人的「留存 40%」，只会得到一个既达不到、也无法解释的数字。

三、cohort 口径、埋点事件与样本量

按注册周做 cohort，是唯一能区分「整体在涨」和「新批次变好」的方法。

cohort 表按周排列。 行是注册周，列是第 0、7、14、28 天是否仍有调用。每一列的分母都是该周激活人数，不是全站人数。跨周对比时，只比较已经走完 28 天的 cohort，否则新 cohort 会拉低整体留存。

去重按人去，不按 key 去。 一个人建了三个 key，仍然只算一个人。匿名试用要单独标记，不能和注册用户混在一个分母里；否则试用流量会把首次成功率抬高。

样本量不足时只看方向。 一周新增激活少于 30 人时，留存率的置信区间会宽到没有决策价值。此时只回答「比上周好还是差」，不下「留存提升了 8 个点」这样的结论。

埋点要能被复算。 每个指标都要能用原始事件重算一遍。只存聚合结果、不存明细，三个月后就无法解释数字为什么变。事件表保留至少 180 天，聚合表可以更长。

cohort 的人数要对得上。 每周的 cohort 人数之和，应该等于同期新增激活人数。对不上就说明有重复用户 ID、时区错位或事件丢失。先修数据，再谈趋势。

流失要区分「不用了」和「删号了」。 主动删除 key 的用户和单纯停止调用的用户，召回策略完全不同。前者需要问原因，后者只需要提醒。

样本量按周看，不按月看。 月度汇总会掩盖某一周的异常，例如一次发帖带来的低质量注册。按周排列，异常周会自己显形。

四、复盘表与季度节奏

验收不是月末看一眼，而是固定节奏：月度看漏斗，季度看留存。

一次只改一个变量。 同一周既改注册流程又改示例代码，数字变好也说不清是哪一项起作用。改动的观察窗至少两周，覆盖一个完整的 cohort 周期。

复盘表要写「没做什么」。 例如「本期未处理 P90 尾部，因为样本只有 11 人」。不写的动作和没做的动作一样重要，它防止下一期重复讨论同一个提议。

季度看留存，不看单周波动。 单周留存受发帖、节假日、一次故障影响很大。季度视角看的是「新批次是否比老批次更好」，这才是产品改进的证据。

指标变差时先查口径。 埋点改版、去重规则调整、试用政策变化，都会让数字跳变。先确认口径没变，再谈产品。口径变了却直接归因产品，是最常见的误判。

复盘要有记录，不靠记忆。 每次改动写下日期、假设、指标和观察窗。三个月后回看，才能知道哪个假设被验证、哪个被放弃。没有记录的改动，会在半年后被人重新提出。

季度复盘只问三件事。 新批次比老批次好在哪里、哪条动作真正改变了数字、下一季度只改哪一处。三个问题答完，复盘就结束了，不必把所有指标再念一遍。

数字变好也要找原因。 指标上升可能来自一次社区推荐，而不是产品改动。找不到原因的好数字，不能作为下季度决策的依据。

五、行动清单与复算验收

• 明确「拿到 key」「首次成功」「首周激活」三个口径并写进文档
• 补齐五个埋点事件，确认每个都带用户 ID 与时间
• 按注册周建 cohort 表，只比较走完 28 天的批次
• 计算最近一个月的 TTFHW 中位数与 P90
• 计算首次调用成功率，分母用拿到 key 的人数
• 计算 28 天调用留存，分母用首周激活人数
• 把四个指标填进复盘表，写清本期动作与负责人
• 样本少于 30 人时，只记录方向，不下结论

验收标准：能复算出四个指标并说明每个分母的来源；任何一个分母说不清，这项验收就不算通过。

首次成功率 = 首次调用返回 2xx 的人数 ÷ 拿到 key 的人数
示例：200 注册 → 140 拿到 key → 84 首次成功 = 60%

28 天调用留存 = 第 28 天仍有调用的人数 ÷ 首周激活人数
示例：31 ÷ 84 = 36.9%

TTFHW 中位数与 P90 同窗口对比，样本 < 30 时只看方向

使用边界与实操验收

本文讲 API 产品的漏斗、cohort 与验收表，不涉及消费者产品的空状态与示例数据；那部分见空状态与示例数据：60 秒内看到成品 。本文也不展开 DX 的框架与设计原则，那属于API 优先的开发者体验设计：从消费到生产的完整路径 ；本文只给可复算的验收口径。

注册数可以继续看，但不要放在第一行。 它反映获客，不反映产品是否被用起来。把首次成功人数放在周报首行，团队的注意力才会落到 onboarding 的具体环节上。

指标不是越多越好。 四个指标已经覆盖「能不能跑通、跑通后留不留、支持负担重不重」。再加第五个之前，先问它会不会改变下一步动作；不会，就不加。

验收的终点是动作。 一张复盘表如果只记录数字变化，没有负责人和下一步，它只是报表。每个月至少有一条动作被完成，验收才算闭环。

不要用注册数考核自己。 一个人的产品最容易自欺的地方，是把获客当成进展。调用留存不动的月份，注册再多也只是把漏斗的入口撑大。

指标要能被外人复核。 把分母、时间窗和去重规则写进一页说明，交给一个没参与的人，他应该能算出同样的数。算不出，说明口径还停留在脑子里。

关键参考与核验范围

本文的数值、比例与案例均为教学演示。核验日期：2026-10-25。

• OpenAPI Specification ：公开的接口描述规范，可用于统一示例、端点数与错误响应的口径。
• Google SRE Workbook: Implementing SLOs ：SLO 的公开实践章节，可对照本文关于时间窗、分母与样本量的取舍。

上述两条只用于说明公开规范与实践，不构成对任何指标阈值或合规要求的承诺。具体目标须按自身流量与客户结构确定。

系列导航

• 上一篇：开发者支持：工单分级、状态页与事故沟通
• 回到目录：一个人把 API 做成产品：对外接口、开发者体验与支持
• 相关阅读：空状态与示例数据：60 秒内看到成品 、API 优先的开发者体验设计：从消费到生产的完整路径