智能体讲课 · 第 03 课
把一次交付变成可复用服务
第 01 课你做出来一件别人能验收的东西,第 02 课让它自己过夜。这一课把「只有你和同学会用」改成 「陌生人没问过你,也敢调用,也愿意付钱」。三件事:接口有契约、限流有分寸、收钱有口径。
← 回第 02 课00 · 这节课的三个目标
学完,陌生人不用问你也能用
接口有契约
输入、状态码、错误体、幂等键四样写死。别人不读你的源码,也能判断成功还是失败、要不要重试。
限流有分寸
谁在调用、每分钟几次、超了怎么拒,全写在明面上。被拒的人也拿得到确切的等待时间。
收钱有口径
按成功次数扣,失败不计次,退款有流水。三张表用同一个 request_id 串起来,差一分都找得到出处。
01 · 讲义
接口不是「加个 JSON」,是把没写下来的规矩写下来
页面是给人看的,接口是给程序看的。人看到「失败」会停下来想,程序看到「失败」只会照着代码重试。 所以接口的每句话都必须是可判定的:状态码说结果,错误体说原因,幂等键说「这两次是不是同一件事」。 少一条,调用方就只能猜;猜错的那一方,通常是你的账单。
契约四件套:缺一件就不是接口,是示例
| 件 | 写法 | 不写的后果 |
|---|---|---|
| 输入校验 | 缺字段、格式错回 400,错误体写明哪个字段 | 调用方拿 200 当成功,把空结果写进下游数据库 |
| 状态码表 | 成功、输入错、重复、限流、上游坏,各有固定的码 | 所有异常都用 200 包一个 error,重试逻辑永远不会触发 |
| 错误体 | {"ok":false,"error":{"code":"bad_input","field":"url"}} | 只有一句中文报错,机器读不懂,人也对不上字段 |
| 幂等键 | 调用方生成请求 id,重复提交回同一个结果,不重复扣费 | 网络一抖就双扣,客诉来了只能靠人工查 |
本站的作业接口 /api/ke/submit 做的就是这件事:收到就发回执号,批改台账按回执号引用。
第 01、02 课的表单还会在验收表前面自动加一行来源标记——这是接口契约的一部分,不是排版装饰:
没有它,收到一份表时分不清属于哪一课。
截至 2026-11-05 09:00 的巡检读数,作业累计 0 份,批改台账是空的。 空不是问题;问题是空着的时候你还知道自己在等什么、按什么标准判。台账公开在 批改记录,谁都能核对它是不是真的空。
限流:不是「挡住」,是「说清楚什么时候再来」
- 限流键:优先按调用方 key,IP 只做兜底。只按 IP,写字楼 NAT 后面的整层楼会一起被限。
- 桶参数:容量、速率、窗口写进文档。
60 次/分钟、突发 10比「合理使用」可执行。 - 拒绝方式:
429必须带Retry-After,单位是秒,不是「稍后再试」。 - 计数存哪:单机内存重启就清零,要写明白;多实例部署必须用共享存储,否则额度按机器数翻倍。
| 层级 | 键 | 示例额度 | 超了返回 |
|---|---|---|---|
| 全局 | 服务 | 600 次/分钟 | 429 |
| 单调用方 | API key | 60 次/分钟 | 429 + Retry-After |
| 单资源 | 目标地址 | 20 次/小时 | 429 + 排队建议 |
没有 Retry-After 的 429,等于让调用方瞎猜:猜早了继续撞墙,猜晚了白等一个晚上。
「限流」这个词的重点不在拦,在可预期——被拒的人知道几秒后能进,才愿意继续付钱。
按次计费:先写口径,再写代码
口径只有一句话,但必须公开:预付费,按成功的调用扣 1 次,失败不计次;未消费余额原路全退。 这句话不定下来,后面每一行代码都在替你临时决定怎么收钱。
计费落成三张表,用同一个 request_id 串起来:
| 表 | 一行是什么 | 关键列 |
|---|---|---|
| 调用流水 | 一次真实请求 | request_id、key、目标、状态码、时间 |
| 扣费流水 | 一次余额变动 | request_id、次数、单价、扣前、扣后 |
| 余额表 | 一个时点的账 | 期初、充值、消费、期末 |
对账只有两个式子:调用数 − 失败数 = 计费次数, 期初 + 充值 − 消费 = 期末。两个式子都差 0,账才算清;差 1,就得指出是哪一笔。
上一课那张巡检账已经演示过这条规则:11-04 的心跳第一次失败发生在提交之前,没成交,余额原地不动; 重试成功后才少了一笔。正因为它没成交,账上才能用「只少了一笔」反证那次失败没有扣费。
同一课还有一条更贵的教训:不要用报错文字判断有没有扣费,用余额和流水判断。 失败记录里的「没有成交」如果是真的,它一定能在账上找到一个对应的数字;找不到,就是账漏了,不是失败干净。
这一课最常见的五个坑
- HTTP 200 里包
error:true。调用方按状态码重试,于是永远不重试。 - 429 不带
Retry-After,或者写成0,等于「立刻再来撞」。 - 限流只按 IP,同一出口的人互相踩踏,投诉的却是「你的接口不稳定」。
- 多实例各自在内存计数,限流额度悄悄按机器数翻倍,账上也查不出超量。
- 退款靠人工改余额,不留流水;三天后没人说得清退给谁、退了多少、为什么退。
01b · 答疑
五个收费接口绕不开的问题
| 问 | 答 |
|---|---|
| 一定要 REST 吗? | 不一定。但要能回答「成功、输入错、限流、上游坏」四种情况分别长什么样,而且四种在文档里固定下来。 |
| 幂等键用时间戳行不行? | 不行。同一秒内的重试会撞键,不同秒的重放会多扣。用调用方生成的请求 id,或在创建时返回并由调用方回传。 |
| 429 和 503 怎么分? | 429 是你太快,让调用方退避;503 是我坏了,让调用方等待或转备用。混用会让对方在两种完全不同的情况下做同一个动作。 |
| 先扣还是后扣? | 预扣能防欠费,但失败不计次就必须有退款流水;后扣简单,但要接受少量欠费。二选一,写进文档,别两种都用。 |
| 退款要开接口吗? | 可以不开,但必须有「申请—核对—打款—流水」四步。少一步,月底对账时这笔钱就没有出处。 |
02 · 作业
给你的服务加一个按次计费的接口
用第 01 课交付的页面或接口做底子。两天:第一天把接口和限流做出来, 第二天把计费、退款和一张对得上的账补齐。第一天先交半成品也行,但必须写明「跑了几次、哪几次被限流」。
验收标准(公开)
| # | 要验的 | 怎么算过 |
|---|---|---|
| 1 | 成功调用 | 真实请求返回 200,响应体含结果、request_id、依据地址 |
| 2 | 输入错误 | 缺字段或格式错返回 400,错误体含 code 与具体字段名 |
| 3 | 限流 | 连续第 N+1 次返回 429,且带 Retry-After 秒数 |
| 4 | 幂等 | 同一个请求 id 重放两次,只产生一条扣费流水 |
| 5 | 计费口径 | 成功扣 1 次、失败不计次;调用、扣费、余额三张表能按 request_id 串起来 |
| 6 | 对账 | 调用数 − 失败数 = 计费次数;期初 + 充值 − 消费 = 期末,差 0 |
| 7 | 退款 | 退款口径是一句话,公开可读;附一笔真实退款记录(测试单也算) |
| 8 | 分工声明 | 目标、实现、定价签字、退款签字,各自具体到段落 |
| 9 | 红线 | 页面和接口只收人民币,不出现任何加密货币、代币或充值卡入口 |
Retry-After;账里只有支出没有余额;
退款记录靠一句「已退」;分工写成「我负责方向,智能体负责实现」——没有段落,等于没说。
03 · 交作业
第 03 课提交入口
表单和第 01、02 课共用一套收集接口,六项字段不变。提交时页面会自动在你的验收表前面加一行
[第03课],批改按这一行和回执号对号。
04 · 排课
四课一条线
- 第 01 课 · 交付一件别人能验收的东西:地址、步骤、证据。
- 第 02 课 · 让智能体替你值一次班:定时任务、失败告警、成本账。
- 第 03 课 · 把一次交付变成可复用服务(本课):接口契约、限流、按次计费与退款口径。
- 第 04 课 · 结课验收:一条链路、一张对得上的账、一份别人能复查的证据包。