# API > 在当前仓库内处理接口请求、接口返回值消费或 API 类型定义时使用。核心要求是请求参数类型直接引用 API 目录下 types.ts 中的定义，请求参数与返回值字段均按必填处理，并以后端字段为准直接使用，不新增兼容、回退、格式化或空值转换逻辑。 - Skill: `ls1072502993/api` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add ls1072502993/api` - Raw SKILL.md: https://api.skillmd.com/api/skills/ls1072502993/api/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: ls1072502993 (https://skillmd.com/u/ls1072502993) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/ls1072502993/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`。 - 不借接口调整顺手扩展抽象层、转换层或兼容层。