Saylo - 全栈开发工程师

背景

在使用 AI Agent（如 Claude、GPT）开发时，一个常见问题是：AI 生成的代码总是"差一点"——要么接口调错了，要么业务逻辑理解有偏差。

问题的根源往往是：AI Agent 没有足够的信息来理解你的业务接口语义。

问题：AI 为何总"差点意思"

假设我们有这样一个接口：

POST /api/hr/save
Body: { name: string, avatar: string }

如果直接让 AI 实现"保存 HR 信息"功能，AI 可能：

不知道 avatar 是什么格式（URL？Base64？）
不知道 name 是否有长度限制
不知道返回的 data 是什么结构
不知道有哪些错误码

根本原因

AI 缺少结构化的业务上下文，只能根据字段名做猜测。

解决方案：OpenAPI + 类型注解

1. OpenAPI 文档（结构化接口描述）

paths:
  /api/business/settings/hr/save:
    post:
      operationId: saveHr
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BusinessSettingsHrSaveValidate'
components:
  schemas:
    BusinessSettingsHrSaveValidate:
      type: object
      properties:
        name:
          type: string
          description: HR姓名，最大20字符
          maxLength: 20
        avatar:
          type: string
          format: uri
          description: 头像URL，必须是有效的HTTPS地址
      required:
        - name
        - avatar

2. 生成 Agent 友好的代码

用 qxun-api-generator 自动生成包含 JSDoc 的 TypeScript 代码：

/**
 * 保存 HR 账户信息
 * @description HR姓名最大20字符，头像必须是HTTPS URL
 */
async saveHr(params: BusinessSettingsHrSaveValidate): Promise<SaveHrResponse> {
  return this.request({
    path: '/api/business/settings/hr/save',
    method: 'POST',
    body: params,
  });
}

效果对比

之前（AI 猜测）

const avatarBase64 = await fileToBase64(file);
await saveHr({ name: '张三', avatar: avatarBase64 }); // ❌ 后端需要的是 URL

之后（结构化上下文）

const avatarUrl = await uploadToOSS(file);
await saveHr({ name: '张三', avatar: avatarUrl }); // ✅ 类型安全

关键实践

OpenAPI 文档要详细：每个字段都要有 description、format、constraint
错误码要枚举化：不要用魔法数字，用 enum
生成的代码要带 JSDoc：让 AI 能读懂业务语义
类型即文档：TypeScript 类型定义就是最好的接口文档

总结

AI Agent 的能力取决于你给它的上下文质量。通过 OpenAPI + 类型注解 + JSDoc，我们可以：

让 AI 准确理解接口语义
减少 AI 生成的 bug
实现"人做审查，AI 写代码"的高效工作流

本质上是：把接口文档写成 AI 能读懂的形式。

让 AI Agent 读懂你的接口：结构化上下文实践

背景