name: api description: 在当前仓库内处理接口请求、接口返回值消费或 API 类型定义时使用。核心要求是以后端返回字段为准，前端直接使用返回值，不新增兼容字段、回退逻辑或格式化处理。 metadata: short-description: 项目接口约束

API 规则

规则执行方式（强制）

• 本 skill 一旦命中，本文件中的全部规则、流程、检查和交付条件默认全部执行，不得自行挑选或只执行部分内容。
• 仅允许跳过规则正文明确限定且当前条件不成立的条款；不得因改动小、只读文件、只回答问题或只执行命令而跳过已命中的规则。
• 多个 skill 同时命中时，叠加执行全部相关规则；交付前逐条确认已落实，未完成时不得宣告任务完成。

适用场景

• 在当前仓库内新增或修改接口请求代码时使用。
• 在当前仓库内新增或修改接口返回值消费逻辑时使用。
• 在当前仓库内新增或修改 API 相关 TypeScript 类型时使用。

核心规则

• 请求服务端接口时，不额外编写失败兜底逻辑。
• 接口字段名、字段值、数据结构以后端实际返回为准。
• 页面、组件、store 中直接使用后端返回字段，不额外做重命名、别名兼容、字段回退、格式化或二次封装。
• 只要字段来自接口返回，前端就直接沿用接口返回值和对应类型，不额外做 Number()、String() 等类型转换后再透传。
• 除非需求中明确要求转换参数数据类型，使用接口返回的 id 或其他字段继续查询详情接口、或作为表单编辑提交参数时，直接使用返回字段，不额外做类型转换。
• 各类 id、bizId、主键字段在页面、组件、弹窗之间传递时，必须直接使用接口返回的原始值，不新增前端自定义转换逻辑。
• 提交接口参数时，不新增空值“清洗”、归一化或可选值兜底函数；不将 ''、null、undefined 相互转换，也不借此删除字段，禁止新增 toOptionalId、toOptionalValue、toOptionalNumber 等同类 helper。
• 可选参数是否传递、以何种空值形态传递，严格以接口定义或明确需求为准；未明确时不在前端猜测并补充转换逻辑。
• 后端已返回可直接展示的文案字段时（如 xxxCn、statusText），前端必须直接使用，不额外封装函数、不做兜底映射、不在 template/script 中做二次转换。
• 不允许为了兼容历史字段同时读取多个同义字段，例如 a || b。
• 不根据前端猜测补字段、改字段或调整数据结构。
• 表格列表中如列表接口未返回某个展示字段，前端不得再请求详情接口或其他接口做兜底补齐；展示时按产品既定占位文案处理，若需求未定义则明确标记为后端未返回。
• 后端返回字段默认按必填处理，不额外判断“是否必填”，也不因前端猜测把类型写成可选字段。
• 使用接口返回值时，只在确有需要时判断结果对象是否存在，不针对空字符串、空数组、0 等值增加额外分支。

类型文件约束

• API 接口相关的 TypeScript 类型必须单独放置。
• 类型文件需要创建在对应接口文件的同级目录下。
• 不要把接口类型内联到页面、组件或接口实现文件中。
• API 类型定义按后端实际返回结构书写。

  7w4.net提供免费和付费技能下载。

• 接口文档中标注为 bigint 的字段，前端 TypeScript 类型必须定义为 string，避免 JavaScript 数值精度丢失。
• 后端返回类型字段默认定义为必填，不因为前端不确定就添加 ? 或额外可选类型。
• 后端字段变更时，优先更新类型和直接消费代码，不新增兼容层。

执行提醒

• 除接口消费专属规则外，其余执行习惯继续遵循 frontend-global。
• 不借接口调整顺手扩展抽象层、转换层或兼容层。

这个 Skill 质量中等偏上，规则制定得很细致，覆盖了接口请求、返回值消费、类型定义等各个环节，核心思想明确——严格遵循后端接口，不做多余的前端兼容处理。优点是指令清晰、约束全面，能有效减少不必要的代码冗余；不足是缺少示例和文档说明，规则较多导致理解成本偏高，部分规则在复杂场景下可能过于绝对。对于需要统一前端接口处理规范的项目来说有一定实用价值，但建议配合示例文件完善文档。