API

API 规则

规则执行方式（强制）

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

适用场景

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

核心规则

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

类型文件约束

• API 接口相关的 TypeScript 类型必须单独放置。
• 类型文件统一使用对应 API 目录下的 types.ts。
• 不要把接口类型内联到页面、组件或接口实现文件中。
• 请求接口时，参数类型必须直接 import type 并引用对应 API 目录下 types.ts 中已经定义的请求参数类型；禁止在接口文件、页面、组件或 store 中重新声明、复制、继承、组合或别名封装一层参数类型。
• API 类型定义按后端实际返回结构书写。
• 接口文档中标注为 bigint 的字段，前端 TypeScript 类型必须定义为 string，避免 JavaScript 数值精度丢失。
• 请求参数类型和接口返回类型中的字段全部定义为必填，不添加可选标记 ?；即使后端将请求字段标注为非必填，前端请求参数类型中也必须定义为必填。
• 禁止为了绕过必填约束给请求参数字段额外添加 | undefined、| null，或在调用接口时使用类型断言伪造完整参数；若后端契约明确字段值本身可为 null，只按后端原始类型定义和传递，不做 undefined、null 转换。
• 后端字段变更时，优先更新类型和直接消费代码，不新增兼容层。

执行提醒

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