后端接口直连规范

解决前后端数据契约错位

在前端工程中，我们常遇到一种“防御性编程”过度泛滥的场景：面对后端接口返回的数据，开发者习惯在前端再做一层包装。从 a || b 的同义字段兼容，到对 null、undefined、'' 的繁琐清洗，再到不必要的 Number() 或 String() 类型转换。这种做法看似增强了代码的健壮性，实则带来了巨大的隐患。它不仅增加了无意义的抽象层，更容易导致前端展示的数据结构与后端实际约定的契约发生根本性错位，为后续的维护埋下地雷。

技能工作机制：强制直连与类型对齐

@user_b8893874/api-ls 技能的核心目标是在代码库中强制执行“接口数据直连”规则，剥离多余的防御性逻辑。其关键约束如下：

• 拒绝二次封装与兜底：页面、组件或 store 中直接消费后端返回的字段。禁止为了兼容历史字段同时读取多个同义字段（如 a || b），也不允许编写空值清洗函数（如 toOptionalId）来转换 '' 或 undefined。
• 严格遵循类型契约：接口相关的 TypeScript 类型必须独立放置在同级目录的类型文件中。类型必须严格按后端实际返回结构书写，后端标注为 bigint 的字段，前端必须定义为 string 以避免精度丢失。后端必填字段不得随意添加 ? 可选标记。
• 禁止无意义的类型转换：除非需求明确规定，否则直接透传接口返回的 ID 或字段值，不新增 Number() 或 String() 等类型转换逻辑，也不在模板中对后端返回的文案字段做二次格式化映射。

适用边界与落地注意

该技能属于强制生效型规则。一旦在当前仓库中新增或修改接口请求、返回值消费逻辑、以及 API 相关的 TypeScript 类型时，所有命中的规则必须全量执行。

在适用边界上，该技能不负责前端的业务数据清洗，也不处理非接口来源的数据。当后端返回结构发生变更时，正确的做法是直接更新类型文件与消费代码，而不是在前端继续维护历史数据的兼容层。