yuxuanhui
91861565bb
- Introduced API guidelines for interface contracts and request handling. - Added design tokens usage guidelines for consistent styling across the project. - Established DTO guidelines for defining request parameters and response data types. - Created frontend structure guidelines to clarify directory organization and code placement rules. - Compiled a comprehensive frontend development guideline document covering various aspects of the development process. - Implemented quality guidelines to ensure code maintainability and adherence to best practices.
82 lines
3.2 KiB
Markdown
82 lines
3.2 KiB
Markdown
# 接口契约规范
|
|
|
|
> 前端接口定义、请求封装与数据消费的规范。
|
|
|
|
---
|
|
|
|
## 目标
|
|
|
|
前端接口层的职责是：
|
|
|
|
- 统一管理页面访问后端的请求入口
|
|
- 为页面、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. 最后再移除旧结构
|