# 接口契约规范

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

---

## 目标

前端接口层的职责是：

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

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

## 设计原则

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

## 接口文件规范

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

## 方法设计规范

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

示例：

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

## 参数与返回值规范

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

## 错误处理规范

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

## 变更与兼容性

修改已有接口前先检查：

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

推荐顺序：

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