这是
content/posts/indie/indie-api-and-developer-experience的目录页，收录 10 篇文章。前面十四组分别讲「要不要做」「在哪上架」「丢了怎么找回」「怎么合法立住」「多条线怎么加减」「怎么用接单换现金」「前 100 天怎么走」「怎么让人知道你」「人来了怎么留住」「收多少钱」「用户不在你的语言里怎么办」「怎么判断做的东西是对的」「怎么让产品看起来像样」「怎么把软件送到用户手里」。这一组换一种买家：当你的客户是开发者时，产品不再只是一个界面，而是一份契约、一把 key、一个配额和一条不能随便改的响应体。
这个系列解决什么问题
面向普通用户，界面能兜住大部分问题；面向开发者，一个字段的变化会被放大成线上事故。
常见的四种情形：
- 接口能跑，但没人知道怎么调，注册后第一周就流失。
- 同一个错误返回三种形状，客户写三套解析，最后把问题算在你头上。
- 免费层没有硬上限，某个月被一个用户跑掉整月预算。
- 想改一个「没人用」的字段，三个客户同时报错。
这一组不讨论协议选型与框架实现，只做一件事：把「对外 API」拆成一个人能维护、每步都有判据的动作。
核心主张：五条口径
第一，API 是产品，不是副产品。 文档、错误码、配额、弃用与支持都要进排期。
第二，契约先于实现。 OpenAPI 是单一事实源，破坏性变更必须走弃用窗口。
第三，凭据按最小权限发。 key 可审计、可轮换、可撤销，泄露有响应顺序。
第四，配额既防超支也防滥用。 免费层、突发、超额与硬上限四条线要同时定。
第五，DX 可验收。 首次成功时间、首次成功率、调用留存、工单密度都能算，算不过就是没准备好。
10 篇速览
| 文章 | 核心内容 | 阶段 |
|---|---|---|
| 要不要做 API：三类买家、收入结构与退出条件 | 三类买家的付费动机、三种收入结构、固定成本与四条退出条件 | 决策 |
| API 规范：OpenAPI 契约、统一错误模型与分页约定 | 契约作单一事实源、错误信封与状态码、分页过滤排序、幂等键 | 契约 |
| API key 管理：签发、最小权限、轮换与泄露响应 | 环境隔离、作用域与审计、轮换重叠期、泄露后 0–24 小时处置 | 鉴权 |
| 配额与限流：免费层、突发额度与超额计费 | 三种计量口径、令牌桶与突发、429 与 Retry-After、硬上限与滥用 | 配额 |
| 对外 Webhook：事件签名、重试、幂等与死信队列 | 事件信封与版本、HMAC 防重放、至少一次投递、死信与重放 | 事件 |
| SDK 与示例：薄封装边界、版本策略与多语言维护成本 | 三个判据、生成与手写分工、版本对应、每语言年维护成本 | 封装 |
| 文档站：五分钟跑通第一个请求与错误自查 | 五步 quickstart、端点页六块、搜索与版本化、错误码索引 | 文档 |
| 版本与弃用：兼容窗口、弃用公告与迁移指南 | 三种版本策略、兼容清单、公告五要素、Sunset 头与下线判据 | 版本 |
| 开发者支持：工单分级、状态页与事故沟通 | 工单五类与 P0–P3、状态页组件、首条公告五要素、分流顺序 | 支持 |
| 开发者体验验收：首次成功时间、留存口径与复算表 | 四个指标与分母、cohort 与埋点、复盘表、季度节奏 | 验收 |
三条阅读路径
路径 A：还没做 API，正在判断值不值得
读 01 算清买家结构与每千次调用成本，再用 07 写一页 quickstart 试水温；决定做之后按 02 定契约，03 定 key 模型。
路径 B：已有接口，但接入率低、工单多
先用 10 定位卡在注册、拿到 key 还是首次成功，再用 07 改 quickstart；重复问题按 09 分流到文档与产品，配额争议读 04。
路径 C：准备发新版或下线旧版
读 08 排弃用窗口与公告字段，05 检查事件投递与重试窗口，03 做一次 key 轮换演练；最后用 10 的复盘表收口。
与其它专题的边界
| 专题 | 它讲什么 | 本组的边界 |
|---|---|---|
| 面向开发者的低成本变现模型设计 | 其中一节讲 API/SDK 作为一种变现模型 | 本组讲变现成立之后的工程、运营与验收 |
| 模型选型：买断、订阅、按量与免费增值的五个判据 | 收费模型选型判据 | 本组只算 API 的成本结构与保本点 |
| 三档套餐：把「刚好够用」写成一张表 | 套餐横切与「只差配额」的错误 | 本组讲免费层、突发与 429 的机制 |
| API设计实战：REST、gRPC与GraphQL的选型、规范与版本管理 | 协议选型与技术规范 | 本组面向对外产品，不选协议栈 |
| API契约与版本治理：OpenAPI/Protobuf契约管理、兼容性检查与SDK自动生成 | 契约治理工具链与自动生成 | 本组讲契约背后的人、判断与验收 |
| API文档自动化：OpenAPI规范与Swagger实战指南 | 文档生成工具链 | 本组讲 quickstart 结构与首次成功时间 |
| API 优先的开发者体验设计：从消费到生产的完整路径 | DX 框架综述 | 本组按环节拆成 10 篇并给出算式 |
| API优先的短链服务设计：RESTful规范、多语言SDK、Webhook与开发者体验 | 案例型整体设计 | 本组是单人产品的通用验收口径 |
| Webhook 重试与幂等性设计：指数退避、死信队列与去重实战 | 通用重试与幂等机制 | 本组讲对外事件信封、签名与订阅方自助 |
| 《AI Agent 工程实战》6.3 限流与配额：按租户 token 预算的令牌桶 | 令牌桶实现 | 本组讲免费层、突发与超额计费的产品口径 |
| 客服不是成本：工单是免费的需求样本 | 消费者客服分诊与 P0–P3 | 本组讲开发者工单五类与状态页 |
| 合同与条款：服务条款、隐私政策、DPA、退款政策与试点协议 | 法律文本与条款 | 本组讲响应时限与事故沟通，不写条款 |
| 事故响应：被盗、被封、被停机、域名劫持的 72 小时 | 事故处置总顺序 | 本组只讲对外的状态页与沟通节奏 |
| 版本节奏与回滚：发布列车、兼容窗口与一次撤回 | 产品发版与回滚 | 本组讲 API 版本与弃用窗口 |
| 平台合规：隐私政策、数据最小化、封禁申诉与开源许可 | 合规义务与隐私政策 | 本组讲 key 作用域与送第三方的字段边界 |
| 空状态与示例数据：60 秒内看到成品 | 消费者首次成功率与留存 | 本组讲 API 首次调用时间与调用留存 |
| 翻译工作流：机翻、审校与术语表 | 多语言文案与质量阶梯 | 本组只讲文档站要翻哪几页 |
| Obsidian、Raycast 与 Alfred：轻量效率工具的社区目录与更新节奏 | 作为平台依赖方跟进 API 弃用 | 本组讲作为提供方怎么发弃用 |
| 一个人的借力：外包、自动化与协作边界 | 借力顺序与回本、任务边界、试单与背调、brief、发包成本、设计内容与代码交接、自动化与客服、合作分成、四张验收表 | 本组：API 契约、凭据、Webhook 与开发者支持；该专题：发包、协作交接与净回收工时。 |
| 一个人的自助支持：帮助中心、排查树与工单减少 | 工单分类与可自助比例、任务型帮助中心、FAQ 与排查树、教程与截图、搜索空结果、更新日志、模板答复、三级升级、四张验收表 | 本组：API 契约、凭据、Webhook 与开发者支持；该专题：自助内容、排查树与人工升级。 |
| 一个人的消息系统：事务邮件、通知分层与送达率 | 消息清点、事务邮件基线、SPF/DKIM/DMARC、送达率账本、通知分层、偏好中心、渠道分工、生命周期序列、同意与退订、四张验收表 | 那组讲面向终端用户的事务与生命周期消息；本组讲对外接口、开发者体验与支持 |
| 一个人的社区：冷启动、版规、版主与社群健康 | 社群该不该建、载体选型、前 100 人、版规与三档处置、版主与志愿者、内容节奏、答疑沉淀、活动与线下、商业化边界、四张验收表 | 那组讲终端用户社群；本组讲对外 API 的契约、凭据、Webhook 与开发者支持 |
| 一个人的财务：现金流、runway 与月度结账 | 四张表与四个收入、分账、收入确认、成本清点、13 周滚动、runway 与薪酬、15 分钟月结、税预提、现金预警与收缩、四维验收 | 那组讲产品的现金账；本组讲对外 API 的契约、凭据、Webhook 与开发者支持 |
| 一个人的运维：可用性、告警、事故与值班 | 可用性预算、五条探针、告警降噪、日志串联、状态页、容量水位、依赖降级、发布观察、事故复盘、四维验收 | 那组讲服务可用性与故障沟通；本组讲对外 API 的契约、凭据、Webhook 与开发者支持 |
| 一个人的多租户：组织、邀请、角色与数据隔离 | 组织引入判据、三层模型与迁移、邀请与成员生命周期、角色矩阵、三层校验、数据隔离、审计日志、席位一致、交接与四维验收 | 那组讲人的成员关系与角色；本组讲机器凭据、配额、Webhook 与开发者支持 |
| 一个人的产品度量：事件字典、指标口径与决策看板 | 六个决策与十二个指标、二十四事件字典、埋点三处校验、口径五要素、五步漏斗、一屏四区看板、四条校验与三方对账、采样与保留、样本量与灰度、九项验收 | 那组讲产品行为怎么度量；本组讲对外 API 的契约、凭据、Webhook 与开发者支持 |
| 一个人的架构：技术选型、模块边界与演进（10 篇） | 技术选型排除法、九个模块与依赖方向、数据迁移三步、四个升级窗口、技术债预算、三次规则、重构判据、可替换性、幂等与补偿、四维验收 | 那组讲内部模块的调用方向；本组讲对外接口的契约、凭据与开发者支持 |
| 一个人的计费系统：订阅状态机、按比例计费与失败重试（10 篇） | 订阅状态机、五个时点、按比例计费、按量计量、催收、退款拒付、发票税务、对账漏损、自建决策、十二项验收 | 那组讲计费状态与账单；本组讲对外接口的契约、凭据与配额 |
| 一个人的隐私工程：数据地图、最小化与删除权（10 篇） | 数据地图、最小化、合法性依据与同意、政策一致性、数据主体请求、删除、保留期、跨境与供应商、泄露响应、十二项验收 | 那组讲接口日志里该留与不该留的字段；本组讲契约、凭据、配额与 Webhook |
| 一个人的数据搬家：导入、去重、迁移与退出（10 篇） | 迁移漏斗、导入契约、字段映射、去重合并、幂等重跑、人工代导入、窗口与回滚、附件限额、导出退出、十项验收 | 那组讲文件导入与导出接口；本组讲契约、凭据、配额与 Webhook |
| 一个人的质量守门：验证预算、回归清单与发布门禁（10 篇） | 47 缺陷与三条红线、12 条关键路径、三层配比、38→26 回归、六项门禁、四级缺陷、测试数据、不可逆保护、测试债、十项验收 | 那组讲发布前验证；本组讲 API 契约、凭据、Webhook 与开发者支持 |
| 一个人的安全基线：十四个入口、十七个密钥与一次 72 小时响应 | 14 个攻击面、认证与枚举、会话撤销、17 个密钥三档、四条边界、41 个依赖与 186 条告警、四类限流、9 类审计日志、72 小时三段响应、20 项验收 | 那组讲服务端密钥与防滥用；本组讲对外 API 契约、key、配额与开发者支持 |
| 一个人的性能与账单：4.2 秒的首屏、一千二百次查询与每月 210 美元 | 4 项预算与 20 格、RUM 与慢查询、412→168 KB、1,200→3 次查询、0→86% 缓存、34 秒导出、7→4 个第三方、210→118 美元、3 次回归告警、10 项验收 | 那组讲服务端延迟与每次请求成本；本组讲对外 API 契约、key、配额与开发者支持 |
| 一个人的企业客户：九家询价、一百四十八道问卷与 134 天的第一单 | 9 家询价与 130 h、96 天采购、148 题问卷、7 个子处理者、SLA 43.2/216 分钟、26 h SSO、4 周试点、38 天到账、8 h 实施、10 项验收 | 那组讲企业采购与合同流程；本组讲对外 API 契约、key、配额与开发者支持 |
| 一个人的开源产品：4,200 个 star、一百八十个付费与一年 612 小时的维护 | 4,200 star 与 1,949 美元、612 h 维护、214 依赖、48,600 行 78/22、1,180 个 issue、214 条告警、23 个赞助者、9 家双许可、17 位贡献者、10 项验收 | 那组讲开源仓库的许可证与边界；本组讲对外 API 契约、key、配额与开发者支持 |
本组统一口径
- API 是产品：文档、错误码、配额、弃用与支持都写进排期，不留「以后再补」。
- 契约先于实现：所有对外端点先进 OpenAPI，再写代码；破坏性变更必须走弃用窗口。
- 凭据最小权限：按客户与环境签发，存哈希、可审计、可撤销，轮换有重叠期。
- 配额四条线：免费层、突发额度、超额计费、硬上限，缺一条就会出事故。
- 所有数字都是教学假设：每篇正文都标注了这一点，换成自己的调用量与成本重算才有意义。
使用说明
每篇都可以单独读，但建议按「先判断、再定契约、最后验收」的顺序。每篇末尾有行动清单与验收标准，验收标准写成一句可判断真假的话——做不到就是没做完，不需要再解释。
文中出现的人物、产品与数字均为教学假设，用于演示算法，不代表经核实的真实案例。涉及平台政策、合规义务与安全等级的部分只说明取向，不构成法律意见，具体口径请以所在地法规与服务条款为准。
本组的证据与使用方法
这十篇不引用任何 API 平台的实时定价，也不承诺接入率提升。可复算的部分全部用四则运算给出算式（每千次调用成本、契约覆盖率、泄露暴露时长、免费层覆盖率、有效投递率、每语言维护成本、首次成功时间、弃用窗口、响应达标率、调用留存），读者可以替换成自己的数字重跑；不可复算的部分（例如具体平台的配额政策、加密套件要求、合规等级）明确标注为需要自行核验，并给出核验方向。
建议的使用方式：先用 01 判断要不要做并算出保本调用量，再用 02 把契约写死；上线前按 03–07 处理凭据、配额、事件、SDK 与文档，发布后用 08–10 管版本、支持与验收。API 不是一次交付，是一条需要随调用方演进的线。