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.
3.2 KiB
3.2 KiB
接口契约规范
前端接口定义、请求封装与数据消费的规范。
目标
前端接口层的职责是：
- 统一管理页面访问后端的请求入口
- 为页面、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、组件依赖当前签名
- 是否可以通过“新增字段/新增方法”代替破坏式修改
- 是否需要同步调整对应类型定义与页面消费逻辑
推荐顺序：
- 先新增兼容字段或新方法
- 逐步迁移调用方
- 最后再移除旧结构