必须在项目根目录下创建 .cursor/rules/api-contract.mdc 文件并配置路径、响应格式等规则，才能让 cursor ai 遵循团队接口规范；否则 ai 将按通用模板生成不符合要求的代码。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
要让 Cursor 的 AI 在写接口代码时自动遵循你团队的 URL 路径格式、参数校验方式、响应结构和错误码体系，必须通过项目级 Rules 显式声明这些约束，否则 AI 会按通用模板生成，比如用 /users/:id 而不是你们规定的 /v3/api/user/{userId}，或返回裸 data 而非统一的 {code: 0, msg: 'ok', data: {...}}。
创建接口规范规则文件
在项目根目录下执行：mkdir -p .cursor/rules → 进入该目录 → 新建文件 api-contract.mdc。
这一步不能跳过。.cursor/rules 是 Cursor 识别项目规则的唯一路径，放在其他位置（如 .cursorrules 或根目录下的 rules/）AI 完全不会读取。
定义接口路径与版本控制规则
在 .cursor/rules/api-contract.mdc 中写入以下内容：
rule_id: api-path-versioning<br>trigger: file_match<br>context:<br> include: ["src/**/api/*.ts", "src/**/controller/*.java"]<br>prompt: |<br> 你正在为 Spring Boot + TypeScript 全栈项目编写接口代码。<br> 所有 REST API 必须以 /v3/api/ 开头，后接小写字母+短横线风格资源名，如 /v3/api/user-profile。<br> ID 路径参数必须使用花括号语法：{userId}、{orderId}，禁止用冒号 :userId。<br> 查询参数一律用 ?page=1&size=20 格式，禁用嵌套对象传参如 ?filter[name]=xxx。
注意：include 路径必须精确匹配你的实际目录结构。如果 controller 不在 src/**/controller/ 下，而是放在 backend/src/main/java/com/example/controller/，就必须改成 【include: ["backend/src/**/controller/**/*.java"]】，否则规则永不生效。
强制统一响应格式
方法一：针对 Java 后端控制器
添加新规则块：
rule_id: java-api-response<br>trigger: function_call<br>context:<br> include: ["**/controller/**/*.java"]<br>prompt: |<br> 你是一名资深 Spring Boot 开发者，严格遵守本项目响应规范：<br> - 所有 @RestController 方法必须返回 Result<t> 泛型包装类；<br> - 成功时 code=200，data 字段非空，msg="success"；<br> - 异常统一由 @ControllerAdvice 拦截，返回 code=500/400/401 并附带标准化 errorDetail 对象；<br> - 禁止直接 return new ResponseEntity(...) 或裸 map 返回。</t>
方法二：针对 TypeScript 接口调用层
在同一文件中追加：
rule_id: ts-api-client-response<br>trigger: import_statement<br>context:<br> include: ["src/**/api/*.ts"]<br>prompt: |<br> 你正在编写前端 API 客户端，所有 fetch 调用必须封装进统一的 request 函数。<br> request 返回 Promise<result>>，其中 Result = { code: number; msg: string; data: T };<br> 禁止在组件中直接调用 fetch 或 axios.get()；<br> 若后端返回 code ≠ 200，必须 throw new ApiError(result) 并携带 msg 和 code。</result>
启用并验证规则
第一步：打开 Cursor 设置 → Editor → AI → 勾选 【Enable Rules Engine】；
第二步：重启 Cursor 编辑器；
第三步：打开一个匹配 context.include 的文件（例如 src/api/user.ts），输入 fetchUser → 触发 AI 补全 → 检查生成代码是否自动包含 return request<user>('/v3/api/user/{userId}', { method: 'GET' })</user> 且返回类型为 Promise<result>></result>；
第四步：若未触发，按 Cmd+Shift+P 输入 Cursor: Show Rules Logs，查看日志中是否有 matched_context: true 和对应 rule_id 的记录。
