你的 API 是给实习生写的?聊聊怎么设计一套 AI 能一次调对的接口

2026-11-22 9 0

先说个扎心的事实:你写的那个 POST /api/v2/user/update 接口,人类同事靠"问一句"就能用明白,而 AI Agent 只能靠"猜"。

Agent 调接口失败,九成不是模型笨,而是你的接口压根没打算被机器调用。它要求调用方知道字段含义、知道业务前置条件、知道出错后该重试还是该放弃。一个熟练工程师看一眼文档就能脑补出来的东西,Agent 只能靠踩坑来学——踩一次坑,可能就是你线上的一笔脏数据。

这篇讲怎么设计一套"能被 Agent 调对"的 API。顺便说,这套设计对人类调用者同样友好,毕竟写文档的精力是省不掉的。


一、语义化动词 + 无状态资源,别再设计"万能接口"

最常见的反模式是万能接口:/api/doSomething,靠参数区分行为。这类接口对人和机器都是灾难——参数一多,语义就塌了。

正确做法是让 URL 自己讲清楚意图,用 HTTP 方法表达动作语义,让"调用"这件事变成零推理的:

# 不好:语义藏在参数里
POST /api/action
{"type": "cancel_order", "id": 8823, "force": true}

# 好:意图写在路径里
POST /api/v1/orders/8823/cancellation
Idempotency-Key: 7f3a-9c21

这里有个关键细节:请求体应该尽可能小、参数尽可能少且必填。Agent 每多理解一个可选参数,出错概率就高一分。把判断逻辑收回服务端——"能不能取消"由服务端根据订单状态判定,而不是让调用方先查一遍再传 force=true。

经验法则:一个接口的必填参数超过三个,就该考虑拆分了;可选参数超过五个,基本可以断定设计有问题。


二、错误响应是给机器读的,别只写给人看

这是最被忽视、也最能拉开差距的一块。多数团队的错误响应长这样:

{"error": "订单状态不允许取消"}

人能看懂,Agent 抓瞎——它是该重试?该改参数?还是直接放弃?

把错误做成结构化、可枚举、带处置建议的:

{
  "error": {
    "code": "ORDER_STATE_CONFLICT",
    "message": "订单当前状态为 PAID,无法取消",
    "retryable": false,
    "action_hint": "改为调用 POST /api/v1/orders/{id}/refund",
    "details": {
      "current_state": "PAID",
      "allowed_transitions": ["SHIPPED", "COMPLETED"]
    }
  }
}

三个字段是命门:

  • code:机器可枚举的稳定标识,不要用中文当码,那是给人看的
  • retryable:直接告诉调用方"别重试"或"可以重试",别让它自己猜
  • action_hint:告诉它下一步该干什么,甚至给出可用的替代接口

最后一条尤其值钱。你的 API 是业务知识的唯一沉淀入口,把"业务规则"编成机器可执行的路线,等于免费给 Agent 配了个业务专家。


三、幂等性:让重试变成免费的而不是灾难

网络环境下重试是必然,Agent 环境下更必然——模型不确定调用是否成功时,最朴素的策略就是再试一次。如果你的接口不幂等,一次 Agent 任务可能创建三个订单。

工业界的通用解法是幂等键:

POST /api/v1/orders
Idempotency-Key: 8c1e-4a77-b002

# 首次调用 → 201 Created,响应头回传
Idempotency-Key: 8c1e-4a77-b002
X-Idempotent-Replay: false

# 重复调用 → 返回首次的同一份响应
X-Idempotent-Replay: true

服务端要做的:键 + 请求指纹 + 响应快照存起来,重复请求直接回放旧响应。键的 TTL 给个 24 小时差不多。别用参数指纹当幂等键——同一张单据本来就应该支持多次合法的相同调用,参数一样不代表是同一次意图。

顺便说一句,把 Idempotency-Key 做成 HTTP 头而不是 body 字段,好处是网关层、日志层、限流层都能直接看见它,不需要认识你的业务。


四、分页与部分失败:不要让 Agent 拿到一半的世界

很多接口一上来就返回全量列表。前端无所谓,Agent 会被 5000 条数据撑爆上下文,然后做出一堆蠢事。正确的姿势是强制分页,并且把分页做成一等公民:

GET /api/v1/orders?limit=50&cursor=eyJpZCI6ODgyM30
→ {
    "data": [...],
    "next_cursor": "eyJpZCI6ODgzMn0",
    "has_more": true
  }

用游标(cursor)而不是 offset:offset 分页在数据变动时会漏行、会重复,Agent 处理几万条数据时偶发的"漏单"多半来源于此。

另外,大批量操作别设计成"一个请求返回 1000 条结果"。给一个异步任务接口:

POST /api/v1/bulk/jobs
→ { "job_id": "job_8f21", "status": "PENDING" }

GET /api/v1/jobs/job_8f21
→ { "status": "RUNNING", "progress": 0.42, "result_url": "..." }

Agent 会乖乖轮询。人不会,人会干等。人机接口的分歧点,要主动设计。


五、给每个接口挂"用法说明",而不只是字段文档

最后是最省力也最有效的一招:让接口自己携带使用说明。

业界已有雏形——MCP 协议把工具描述放在 schema 里,OpenAPI 规范有 description、examples、x-usage 这类扩展位。我的建议是给每个写操作至少准备三样东西:

  • 一句人话描述:这个接口干什么,什么时候该用
  • 一个真实示例:不是文档模板里的假数据,是能跑通的真参数
  • 明确的禁用场景:"不要用这个接口批量查询",比"这个接口可以批量查询"有用得多

第三条是反直觉的。人喜欢看能做什么,Agent 同样任务上失败的很大一部分原因,是它选了"能力更强但不该用"的那个接口——比如用导出接口做单条查询。能删掉能力,也是一种设计能力。


六、一份可以直接抄的检查清单

发布接口前,对着这个表过一遍:

  • 路径和方法是否自解释意图
  • 必填参数是否 ≤ 3,可选参数是否 ≤ 5
  • 错误响应是否有稳定的 code 和 retryable
  • 写操作是否支持幂等键
  • 列表接口是否强制分页,是否用游标
  • 批量操作是否提供异步任务 + 进度查询
  • 是否有真实示例和明确的禁用场景
  • 响应体里有没有敏感字段被顺手带出来

最后一条是老生常谈,但值得单列:Agent 会把看到的一切都当成"可以外传"的信息。给接口加字段之前想想,它会不会被写进一篇分享帖子里。


写在最后

过去写 API,我们服务的是开发者——只要文档清楚、命名合理,人就能自己摸索出正确用法。现在服务对象里多了一个不会疲惫、不会脸红、但会一本正经执行错语义的物种。

好消息是,对机器友好的 API,恰好也是对人类友好的 API。语义清晰、错误可枚举、操作可重试,这三条本来就该是 API 的基本素养,只不过过去我们靠"文档 + 口头传承 + 报错时查日志"来兜底,现在要靠设计本身来兜底。

所以别把这事儿当成给 AI 额外加一层糖衣。它是把你接口里那些"只有老员工知道"的隐性知识,翻译成机器能读的形式。

翻译完你会发现——不少隐性知识,其实连你自己都说不清。🐞

相关文章

我把生产数据库换成 SQLite,账单砍掉九成,结果被一个文件锁教育了一整天
你的 async fn 忘了 await,一行代码都没跑:Rust 异步世界的七个真坑
你的 JWT 能不能撤销?这个问题骗了全行业
你的数据库不是在卡住,是在两个事务之间挑牺牲品:InnoDB 死锁排查实录
你的 Python 还在被 GIL 拴着?自由线程实测:单线程慢了 40%,但它敢让 CPU 真的跑满
缓存雪崩、击穿、穿透:别再混着讲,三兄弟得用三套连招

发布评论