obsidian-vault/projects/frontend/api-guidelines.md

接口契约规范

前端接口定义、请求封装与数据消费的规范。

---

目标

前端接口层的职责是：

• 统一管理页面访问后端的请求入口
• 为页面、Hooks、组件提供稳定、易读的调用方式
• 隔离具体请求库、URL 拼接、参数序列化等实现细节
• 让页面开发只关心“调用什么接口、拿到什么数据”

当前仓库的接口文件统一放在 src/api/；现阶段不要为单个页面单独创建页面私有 api-* 文件，除非页面内已经形成明确且稳定的局部接口簇。

设计原则

• 接口方法名必须表达业务意图，而不是后端实现细节
• 一个方法只负责一个清晰的业务动作
• 页面层拿到的是“可直接消费的数据”，不要把请求库细节泄漏到页面
• 相同业务模块的接口按文件聚合，避免散落在多个目录
• 优先保持新增兼容，避免随意改动已有方法签名或返回结构

接口文件规范

• 文件名统一以 api- 开头，使用横杠连接
• 一个业务模块对应一个接口文件，例如 api-user.ts、api-order.ts
• 文件中只写接口定义与请求调用，不写页面逻辑、组件逻辑、复杂数据转换
• 所有接口通过 src/api/index.ts 统一导出
• 优先按业务域聚合到现有 api-*.ts，不要为单个接口随意新建文件

方法设计规范

• 方法名统一使用动词开头，表达查询、创建、更新、删除等业务动作
• 参数少且稳定时可直接传基础参数；参数较多或未来可能扩展时，统一使用对象参数
• 返回值应尽量稳定，避免同一接口一会儿返回数组、一会儿返回对象
• 不要让页面知道完整 URL、Header 拼装、重试策略等底层细节
• 不要在接口方法中混入 setState、弹窗提示、路由跳转等 UI 副作用

示例：

export function apiGetKnowledgeList(params: GetKnowledgeListParams) {
  return request<GetKnowledgeListResponse>({
    url: "/knowledge/list",
    method: "GET",
    params,
  });
}

参数与返回值规范

• 参数类型、返回值类型要明确，避免 any
• 字段命名以页面业务语义为准，不要直接照搬后端数据库字段语义
• 可选字段必须是“明确可选”，不能依赖不清晰的 null / undefined 约定
• 列表、分页、详情等场景的数据结构要保持一致性
• 如果页面需要二次加工，优先在页面侧的 Hook、组件组装层或局部工具中处理，而不是污染全局接口层

错误处理规范

• 接口层负责抛出或透传标准化错误，不负责直接渲染 UI
• 不要把底层错误文本原样暴露给页面做业务判断
• 页面只依赖可行动的信息，例如状态码、错误码、错误类型
• 同类接口的错误处理方式要一致，避免部分返回 null、部分直接抛错

变更与兼容性

修改已有接口前先检查：

• 是否已有页面、Hook、组件依赖当前签名
• 是否可以通过“新增字段/新增方法”代替破坏式修改
• 是否需要同步调整对应类型定义与页面消费逻辑

推荐顺序：

1. 先新增兼容字段或新方法
2. 逐步迁移调用方
3. 最后再移除旧结构