xuanzhi-service/web/.ai-specs/coding-specs/api-request-flow.md

api-request-flow

适用范围

• 涉及新增接口文件、修改请求封装、上传下载、统一错误处理时必读。

分层规则

• src/api 只负责请求函数和参数组织，统一调用 @/utils/request。
• src/utils/request.js 负责 token、loading、统一错误处理、401 跳转和基础 headers。
• 页面和 store 负责业务语义层的提示、页面状态更新和调用顺序。
• 插件接口优先放在 src/plugin/<plugin>/api，但仍必须复用全局 request.js。

强制规则

• 禁止在 src/api 里重复实现 token 注入、401 处理和全局 loading。
• 禁止在 src/api 里写页面展示逻辑，例如直接操作页面组件状态。
• 改接口返回结构时，必须同步回查调用页面、store 和错误提示。
• 使用特殊请求选项时，优先复用 donNotShowLoading 和 loadingOption 约定。

常见错误

• 在页面里直接拼接 axios 请求，绕过 src/api 和 request.js。
• 在 API 层直接弹 ElMessage，把展示逻辑和请求层耦合。
• 修改 request.js 后没有检查上传、下载、插件接口的兼容性。