签入版本

EasyGoAdmin_GoFrame_NaiveVue/zh/frontend/http.md

@@ -0,0 +1,88 @@
+# 9.4 HTTP 请求封装
+
+:::tip 概述
+HTTP 封装在 utils/http/axios：VAxios 类 + transform 链式处理。统一完成信封解包（code===0 返回 data）、错误消息提示、401 跳登录、请求取消管理。业务只需 `http.request({url, method, params/data})`。
+:::
+
+## 封装架构
+
+```text
+utils/http/axios/
+├── Axios.ts           VAxios 类（拦截器安装/请求实例管理）
+├── axiosTransform.ts  transform 抽象基类（钩子：请求前/响应后/错误处理）
+├── index.ts           实例配置（transform 实现 + 拦截器装配）
+├── checkStatus.ts     HTTP 层状态码处理（401/403/404/500…）
+├── axiosCancel.ts     请求取消管理（重复请求取消）
+├── helper.ts          日期格式化/时间戳拼接
+└── types.ts           RequestOptions / Result 类型
+```
+
+## 响应解包（transformRequestData，真实逻辑）
+
+```text
+1. isReturnNativeResponse → 返回原生响应头场景
+2. isTransformResponse=false → 直接返回 res.data（需自处理 code 时）
+3. 解构 {code, data, msg}：
+   hasSuccess = data && code === ResultEnum.SUCCESS（0）
+   成功：按 isShowSuccessMessage/successMessageText 提示 → 返回 data
+   失败：errMsg 含 \n → ElMessageBox.confirm（HTML 换行）
+        否则 → ElMessage.error(errMsg)
+4. 401 → 跳登录页（配合 token 清理）
+```
+
+## 使用方式（api 模块真实模式）
+
+```ts
+import { http } from '@/utils/http/axios';
+
+// GET（params）
+export function getExamplePage(params?: Record<string, any>) {
+  return http.request({
+    url: '/example/page',
+    method: 'GET',
+    params,
+  });
+}
+
+// POST（data）
+export function exampleAdd(data: any) {
+  return http.request({
+    url: '/example/add',
+    method: 'POST',
+    data,
+  });
+}
+```
+
+请求选项（RequestOptions）可按请求定制：isShowMessage / isShowErrorMessage / isTransformResponse 等。
+
+## 拦截器链
+
+```text
+请求拦截：
+  * token 注入（ACCESS_TOKEN 从 storage 读）
+  * 请求取消管理（axiosCancel，重复请求策略）
+  * 时间戳拼接（防缓存，可选）
+
+响应拦截：
+  * checkStatus：HTTP 层状态码统一处理
+  * transformRequestData：信封解包与消息
+  * 401 → 清 token → 跳登录（redirect 记录来源）
+```
+
+## 与后端信封的对应
+
+| 后端 code | 前端行为 |
+|-----------|---------|
+| 0 | 返回 data（解包完成，业务拿到纯数据） |
+| 1 | ElMessage.error(msg)（ResultEnum.ERROR） |
+| 401 | 跳登录页 |
+| 403/429 等 | msg 弹窗（细分码降级为前端统一处理） |
+
+## 开发规约
+
++ api 模块只写 url（不含 /api 前缀——baseURL 已含）
++ 默认走 transform 解包；需要看原始 code 时 `isTransformResponse: false`
++ 写操作成功提示用 `isShowSuccessMessage`（列表查询不弹成功）
++ 错误文案含多行时自动转 MessageBox（后端多行错误场景）
++ 排障：请求 404 → 查 url 是否重复拼了 /api 或 /v1；401 循环 → 查 refresh 逻辑与令牌存储