一、前置认知：人和 AI 的能力图谱是互补的

人和 AI 擅长的事情是互补的，不是重叠的。

这个认知直接决定了接口设计的重点——你要弥补的是 AI 缺失的那一半，而不是人类早已擅长的那一半。搞清楚这一点，后面所有设计决策才有根基。

1.1 你觉得很复杂的，AI 可能觉得很简单

用户说：

“帮我查一下华南区域过去一个月超 48 小时未处理的审批单，按部门分组统计”

如果让人操作，需要打开报表系统、设时间范围、选区域、选状态、选业务类型、配聚合条件。如果系统没有现成的组合筛选入口，还得导出数据手动处理。

对 AI 来说，这是一次结构化的意图解析，而意图解析是 AI 的强项。AI 从自然语言中提取出结构化的查询参数后，秒级完成查询和汇总。多条件的结构化组合查询是 AI 的舒适区——条件越多、组合越复杂，AI 相对于人的效率优势越明显。

再看多接口编排：

“查一下这个需求单关联的审批记录，如果有待审批的，帮我看一下审批意见”

人需要先查需求单 → 找关联审批记录 → 切换系统 → 查详情，每步都要手动完成。AI 直接串联多个接口调用，完成整个流程。逻辑链条越长，AI 越不怵——每一步都是确定的接口调用，没有歧义，且 AI 不会因步骤多而疲劳出错。

1.2 你觉得很简单的，AI 可能反复踩坑

用户说：

“帮我看看 A 渠道的申请单”

人听到"A 渠道"立刻知道指的是"通过该渠道提交的申请单"。但 AI 面对的歧义是：

• "A 渠道"是提交渠道（submit_channel），还是来源系统（source_system）？
• 如果是提交渠道，"A 渠道"对应的是该渠道下全部子渠道的 ID 集合，还是只有某个特定子渠道？
• 用户说的是泛指的"渠道"还是某个具体的子渠道（如"A 渠道移动端"）？前者应展开为所有子渠道，后者只是单一 ID。

人一秒完成的语义消歧，AI 需要经历完整的实体解析流程——先判断维度归属，再执行枚举匹配，再处理候选项消歧，才能最终确定查询参数。

再看一个更典型的例子：

“截止目前各个部门的视频面试完成量”

业务熟练的人一眼知道"视频面试"是一个面试形式名称。AI 面对的是一个三层消歧难题：

第一层：词义归属。"视频面试"属于哪个维度？

三句话结构几乎一模一样，但"视频面试"、“初面”、"远程"分别归属三个完全不同的维度。人凭业务经验瞬间区分，AI 必须逐个匹配枚举表才能确定。

第二层：标准名称不匹配。即使 AI 正确判断出"视频面试"是面试形式，在系统的面试形式分类里也可能找不到精确匹配——实际对应的可能是"线上视频面试"或"云端面试"等标准名称。AI 需要做模糊匹配，可能返回多个候选，还需要暂停流程、向用户确认。

第三层：语义交叉。AI 必须理解"视频面试"是整体概念（面试形式名），而不是"视频"（协作方式）+“面试”（面试阶段的某一环节）的组合。如果错误拆分，查出的是两个维度的交叉结果，与用户意图完全不同。

人的操作流程：进入报表系统 → 面试形式筛选框输入 → 从下拉候选中选择 → 完成。UI 的分类筛选框已经帮人分好了维度，用户根本不需要思考"这个词属于什么维度"。

这就是 UI 与 AI 最本质的差别：UI 给用户提供了结构化的上下文（每个维度有哪些选项），AI 没有 UI，接口必须主动将这些上下文结构化地提供出来。

1.3 设计启示

强项不需要你费心设计；弱项才是 AI 友好接口设计的核心。

设计 AI 友好的接口，本质上是在弥补 AI 缺失的"视觉直觉"——把人通过 UI 一眼获取的信息，通过结构化的方式塞进 API 里。

二、五个设计原则

原则一：返回值要自描述——AI 没有 UI，返回值是它的全部视野

UI 通过标签文字、下拉框选项、禁用态按钮传递上下文；AI 只有接口返回值。接口不自描述，AI 就只能猜。

枚举字段永远同时返回编码和描述

接口只返回status: "UNDER_REVIEW"或status: 3，AI 回复用户时只能原样输出——用户完全看不懂。解决方案是同时返回可读描述：

// ❌ AI 不知道 UNDER_REVIEW / 3 代表什么{"status":"UNDER_REVIEW"}{"status":3}// ✅ AI 直接使用 statusDesc 向用户展示{"status":"UNDER_REVIEW","statusDesc":"审核中"}

这不只是 AI 友好——前端展示同样受益，是一次多方受益的改造。

关联实体同时返回 ID 和可读名称，消除 N+1 问题

接口只返回operatorId: 10086，展示姓名还需再调一次查询接口。如果单次结果包含 N 条记录、每条的处理人各不相同，就产生了经典的N+1 查询问题——1 次主查询 + N 次关联查询。

// ❌ AI 需要额外 N 次调用才能展示姓名{"operatorId":"U10086"}// ✅ 后端一次 batch 查询，消除 N+1{"operatorId":"U10086","operatorName":"张三"}

返回可执行的操作列表，而不只是当前状态

接口只告诉 AI 当前是什么状态，但 AI 下一步能做什么、能调哪些接口——完全不知道。

// ❌ AI 只知道现在是什么状态，不知道下一步能做什么{"status":"UNDER_REVIEW","statusDesc":"审核中"}// ✅ 当前状态 + 可执行操作清单{"status":"UNDER_REVIEW","statusDesc":"审核中","availableActions":[{"action":"approve","desc":"审批通过"},{"action":"reject","desc":"驳回申请"},{"action":"transfer","desc":"转交他人"}]}

这是HATEOAS（Hypermedia As The Engine Of Application State）思想在 AI 场景下的实践——REST 架构成熟度模型（Richardson Maturity Model）第 3 级定义的原则：响应自身携带"接下来能做什么"的导航信息，客户端不需要提前背下所有业务规则。

就像浏览网页不需要背所有 URL，页面上的链接和按钮告诉你下一步能去哪——availableActions对 AI 起的是同样的作用。人类 UI 里，"可见即可得"通过下拉框和按钮实现；AI 的"UI"就是接口返回值本身。

原则二：失败时给结构化诊断——AI 靠返回信息自我纠正

AI 调接口出错是常态，不是异常。和人不同——人会看日志、查文档、搜索引擎；AI 只有接口返回的信息。错误响应不结构化，AI 的自愈能力直接归零。

一个优秀的结构化错误码设计示例：

AI 靠error.code就能构建决策树，判断"需要等用户确认"、“需要自行修正重试"还是"不可恢复”。如果所有错误都返回同一个码加一段自然语言描述，AI 必须做文本理解来分类——增加了一层不确定性。

这与 HTTP 状态码的设计哲学一致：2xx/4xx/5xx 让客户端不需要解析响应体就能判断大类结果。面向 AI 的错误码应遵循同样的原则——机器可读的状态分类。

// ✅ AI 可以精确自愈：知道是哪个字段出了什么问题、应该怎么修{"ok":false,"error":{"code":"VALIDATION_FAILED","field":"requestType","message":"requestType 值 99 不合法","suggestion":"合法值：PROMOTE=晋升评审, ADJUST=薪资调整, TRANSFER=岗位调动, LEAVE=离职申请"}}// ❌ AI 无从下手：不知道哪里错了，不知道怎么改{"ok":false,"message":"参数错误"}

suggestion字段相当于人类在 UI 上看到的"表单校验提示"，告诉 AI 怎么改才对，一轮即可自愈。

原则三：参数语义化——命名贴业务，不贴存储实现

后端接口的参数命名往往反映的是存储层实现，而非业务语义。看一个典型的抽象场景对比：

如果让 AI 直接使用存储层字段名，它需要记住几十个字段的命名规律：为什么部门字段叫orgNodeCode而不是department？为什么业务类型字段要加Arr后缀？为什么审批人字段包含Long类型提示？这些命名是存储层的历史遗产，AI 没有途径推断。

结果是：要么把这张映射表硬编码在 AI 工作流指令集（Skill）里，要么在中间层写一个翻译模块——无论哪种方式，都是在为历史债务买单。

设计建议：

// ✅ 参数名贴近业务语义，AI 可直接理解和填写{"filters":{"department":"产品部","requestType":"晋升评审","approvalStatus":"审核中"}}// ❌ 参数名暴露存储实现，AI 必须靠外部映射才能正确填写{"filters":{"orgNodeCode":"ORG_001","flowStateCode":1,"bizTypeCodeArr":[0,1,2,...]}}

如果由于历史原因接口必须保留内部参数格式，至少在 CLI 层做一次翻译——让面向 AI 的命令参数保持语义化，翻译工作由 CLI 层承担。这是 CLI 作为防腐层（Anti-Corruption Layer）的核心价值之一：在不修改后端 API 的前提下，为 AI 消费者提供语义化接口。

原则四：批量优先——消除 N+1，降低多轮调用成本

AI 和人调接口的成本模型有本质差异。

• 人操作系统：网络请求是异步的，等待响应的几百毫秒无感知，整体是并行的用户体验。
• AI 调接口：每次调用意味着一轮推理上下文的完整处理——读取返回值、判断成功与否、决策下一步。如果需要串行发起 N 次单独请求才能获取 N 条数据，就是 N 轮串行推理开销，同时也放大了每一步出错的概率。

具体影响：

设计建议：查询接口支持批量输入（如--request-id ID1,ID2,ID3,...）。对后端来说是一次IN查询的改造；对 AI 来说是数量级的调用开销节省。

原则五：写操作接口必须幂等——AI 的重试行为与人完全不同

一个常被忽视的要点：写操作接口的幂等性，对 AI 消费者比对人类消费者重要得多。

人操作 UI 时，"提交"按钮通常有防重复点击保护，即使误触，人会感知到异常（按钮灰掉、弹出提示）并停止操作。

AI 调用写操作接口时，如果遭遇网络超时或响应解析异常，AI 的标准决策是重试。如果接口不幂等，重试就可能造成业务重复——重复提交审批、重复发送通知、重复触发下游工作流。AI 不像人那样能从 UI 反馈中感知到"已成功"，它只能依赖接口返回值来判断是否需要重试。

设计建议：

// 写操作接口使用 idempotencyKey 保证幂等POST/approval/submit{"requestId":"REQ20260422001","idempotencyKey":"submit-REQ20260422001-operator-U1001"// 调用方生成，相同 key 只处理一次}// 接口响应中明确告知是否为重复请求{"ok":true,"isDuplicate":false,"data":{...}}

声明幂等语义后，AI 可以安全重试失败的写操作，而不需要先查询当前状态再决定是否重试——这简化了 AI 的决策逻辑，同时避免了业务重复的风险。

三、一句话总结

设计 AI 友好的接口，本质上是在把人通过 UI 一眼获取的信息，结构化地塞进 API 里：

• 把人看下拉框获取的合法枚举，放进xxxDesc和availableActions
• 把人凭经验完成的 ID→名称转换，在后端 batch 完成后随正文返回（消除 N+1）
• 把人看表单校验提示获取的修复建议，放进结构化error.suggestion
• 把人在 UI 里隐式感知的维度划分，显式化为语义化参数名称
• 把人点"确认"后浏览器的防重复提交，转换为接口层的幂等性保证

UI 帮人类用户完成了这些决策；接口设计要为 AI 消费者完成同样的工作。

四、结语：不要等最佳实践

AI 能力在月级别迭代。今天必须依赖大量手写枚举映射才能完成的语义消歧，也许明天模型就能直接理解业务领域的概念体系。"等行业沉淀出最佳实践再动手"是一个糟糕的策略——等到的时候，起点可能已经变了。

而且，AI 辅助实施本身就大幅降低了试错成本。接口改造、适配层实现、联调验证全程可由 AI 执行，人只需做判断和验证——一次尝试的成本从"开发者写几天代码"降低到"AI 写 + 人审小时级别"。

你以为复杂的事（多接口编排、多维聚合统计），AI 做起来很轻松；你以为简单的事（选个枚举、改个状态），对 AI 来说可能格外困难。好的接口设计，本质上是在弥合这个认知差。

这些认知不难，但需要你真正跑一遍才能深刻体会。最佳实践不是等出来的，是边干边讨论出来的。