# HTTP 客户端集成

<cite>
**本文档引用的文件**
- [src/libs/http.js](file://src/libs/http.js)
- [packages/libs/request.js](file://packages/libs/request.js)
- [packages/components/ProTable.vue](file://packages/components/ProTable.vue)
- [packages/core/src/components/ProTable.vue](file://packages/core/src/components/ProTable.vue)
- [packages/index.js](file://packages/index.js)
- [src/main.js](file://src/main.js)
- [types/ProTable.d.ts](file://types/ProTable.d.ts)
- [src/views/Home.vue](file://src/views/Home.vue)
- [src/views/ProTable.vue](file://src/views/ProTable.vue)
- [package.json](file://package.json)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)

## 简介
本文件面向 Pro-IVIEW V3 的使用者与维护者，系统性说明如何在项目中集成与使用 HTTP 客户端（以 Axios 为主），覆盖请求拦截器配置、响应处理、错误处理、认证令牌管理、在 ProTable 的 request 函数中使用自定义 HTTP 客户端、以及超时与可选的重试策略建议。文档同时提供可直接定位到源码位置的“章节来源”与“图表来源”，便于快速查阅与二次开发。

## 项目结构
围绕 HTTP 客户端集成的关键目录与文件如下：
- 应用入口与全局注入
  - [src/main.js](file://src/main.js)：应用挂载与全局依赖导入
  - [packages/index.js](file://packages/index.js)：组件库安装时向全局注入 $http 与 $dayjs、$lodash 等
- 全局 HTTP 客户端封装
  - [src/libs/http.js](file://src/libs/http.js)：基于 Axios 的全局拦截器与默认配置
  - [packages/libs/request.js](file://packages/libs/request.js)：统一请求适配器，兼容字符串、对象与函数三种 request 形态
- 组件层对接
  - [packages/components/ProTable.vue](file://packages/components/ProTable.vue)：ProTable 组件内部通过 customRequest 调用 HTTP
  - [packages/core/src/components/ProTable.vue](file://packages/core/src/components/ProTable.vue)：核心版本的 ProTable 实现
  - [types/ProTable.d.ts](file://types/ProTable.d.ts)：ProTable 的类型定义，明确 request 支持的多种形态
- 示例与使用
  - [src/views/Home.vue](file://src/views/Home.vue)：演示如何在页面中直接使用 $http 与 ProTable 的 request
  - [src/views/ProTable.vue](file://src/views/ProTable.vue)：演示 ProTable 的基础配置与请求映射

```mermaid
graph TB
subgraph "应用层"
Main["src/main.js"]
App["App.vue"]
Views["src/views/*.vue"]
end
subgraph "组件库层"
Index["packages/index.js"]
ProTableComp["packages/components/ProTable.vue"]
CoreProTable["packages/core/src/components/ProTable.vue"]
RequestAdapter["packages/libs/request.js"]
end
subgraph "HTTP 封装层"
GlobalHttp["src/libs/http.js"]
Axios["axios(外部依赖)"]
end
Main --> App
Main --> Index
Views --> ProTableComp
ProTableComp --> RequestAdapter
RequestAdapter --> GlobalHttp
GlobalHttp --> Axios
Index --> Axios
```

**图表来源**
- [src/main.js:1-14](file://src/main.js#L1-L14)
- [packages/index.js:12-42](file://packages/index.js#L12-L42)
- [src/libs/http.js:1-70](file://src/libs/http.js#L1-L70)
- [packages/libs/request.js:1-78](file://packages/libs/request.js#L1-L78)
- [packages/components/ProTable.vue:157-158](file://packages/components/ProTable.vue#L157-L158)

**章节来源**
- [src/main.js:1-14](file://src/main.js#L1-L14)
- [packages/index.js:12-42](file://packages/index.js#L12-L42)
- [src/libs/http.js:1-70](file://src/libs/http.js#L1-L70)
- [packages/libs/request.js:1-78](file://packages/libs/request.js#L1-L78)
- [packages/components/ProTable.vue:157-158](file://packages/components/ProTable.vue#L157-L158)

## 核心组件
- 全局 HTTP 客户端（Axios）
  - 默认超时时间、请求/响应拦截器、错误提示与消息提示配置
  - 参考：[src/libs/http.js:10-69](file://src/libs/http.js#L10-L69)
- 请求适配器（customRequest）
  - 支持字符串 URL、对象配置、函数回调三种 request 形态；自动拼接 params/data、替换模板变量、合并 headers
  - 参考：[packages/libs/request.js:39-77](file://packages/libs/request.js#L39-L77)
- ProTable 组件
  - 通过 customRequest 发起请求；支持分页映射、成功判断、错误提示
  - 参考：[packages/components/ProTable.vue:665-737](file://packages/components/ProTable.vue#L665-L737)
- 组件库安装与全局注入
  - 在安装组件库时将 axios 或用户提供的自定义 axios 实例注入为 $http
  - 参考：[packages/index.js:12-19](file://packages/index.js#L12-L19)
- 类型定义
  - ProTable 的 request 支持字符串、函数或对象
  - 参考：[types/ProTable.d.ts:41](file://types/ProTable.d.ts#L41)

**章节来源**
- [src/libs/http.js:10-69](file://src/libs/http.js#L10-L69)
- [packages/libs/request.js:39-77](file://packages/libs/request.js#L39-L77)
- [packages/components/ProTable.vue:665-737](file://packages/components/ProTable.vue#L665-L737)
- [packages/index.js:12-19](file://packages/index.js#L12-L19)
- [types/ProTable.d.ts:41](file://types/ProTable.d.ts#L41)

## 架构总览
下图展示了从视图到组件再到请求适配器与全局 HTTP 客户端的整体调用链路。

```mermaid
sequenceDiagram
participant View as "视图组件<br/>src/views/Home.vue"
participant PT as "ProTable 组件<br/>packages/components/ProTable.vue"
participant Req as "请求适配器<br/>packages/libs/request.js"
participant Http as "全局 HTTP 客户端<br/>src/libs/http.js"
participant AX as "Axios 实例"
View->>PT : 传入 request/headers/method 等配置
PT->>Req : customRequest({ request, method, headers, datas })
Req->>Http : 获取 $http 或默认 Axios
Http->>AX : 使用 axios 实例
Req->>AX : 发起请求(含 params/data/headers/URL 替换)
AX-->>Req : 返回响应
Req-->>PT : 返回标准化后的结果
PT-->>View : 更新表格数据/总数/状态
```

**图表来源**
- [src/views/Home.vue:173-193](file://src/views/Home.vue#L173-L193)
- [packages/components/ProTable.vue:665-737](file://packages/components/ProTable.vue#L665-L737)
- [packages/libs/request.js:39-77](file://packages/libs/request.js#L39-L77)
- [src/libs/http.js:42](file://src/libs/http.js#L42)

## 详细组件分析

### 全局 HTTP 客户端（src/libs/http.js）
- 默认超时时间：60000ms
- 请求拦截器
  - 从本地存储读取认证令牌并写入 Authorization 头
  - 固定 Content-Type 为 application/json
  - 超时错误时弹出消息并返回 Promise
- 响应拦截器
  - 非 200 状态时根据 nomsg 控制是否提示错误
  - 成功时为响应体附加 success 标记
  - 错误时根据状态码与错误类型进行分类提示

```mermaid
flowchart TD
Start(["进入请求拦截器"]) --> GetToken["读取本地令牌并设置 Authorization 头"]
GetToken --> SetHeaders["设置 Content-Type 为 application/json"]
SetHeaders --> Next["放行请求"]
RespStart(["进入响应拦截器"]) --> CheckStatus{"状态码是否为 200?"}
CheckStatus --> |否| MsgCheck{"是否需要显示错误消息?"}
MsgCheck --> |是| ShowErr["提示错误消息"]
MsgCheck --> |否| SkipMsg["跳过提示"]
CheckStatus --> |是| MarkSuccess["标记 success=true"]
ShowErr --> ReturnData["返回响应数据"]
SkipMsg --> ReturnData
MarkSuccess --> ReturnData
ReturnData --> End(["结束"])
```

**图表来源**
- [src/libs/http.js:12-67](file://src/libs/http.js#L12-L67)

**章节来源**
- [src/libs/http.js:10-69](file://src/libs/http.js#L10-L69)

### 请求适配器（packages/libs/request.js）
- 支持三种 request 形态
  - 字符串：直接发起请求，支持 URL 模板变量替换与 params/data 自动拆分
  - 对象：支持 request/url、keys、method 等字段；若包含 request 函数则直接调用
  - 函数：直接执行传入函数
- 自动合并 headers：优先使用传入 headers，其次从 URL 查询参数提取 token 并设置 Authorization
- 选择 axios 实例：优先使用全局 $http（由组件库安装时注入），否则回退到默认 Axios

```mermaid
flowchart TD
In(["接收 { request, method, keys, datas, headers }"]) --> Type{"request 类型?"}
Type --> |字符串| BuildStr["解析 URL 模板变量<br/>拆分 params/data<br/>合并 headers"]
Type --> |对象| BuildObj["处理 request/url/function<br/>合并 headers"]
Type --> |函数| CallFn["直接调用函数"]
BuildStr --> AxiosCall["使用 axios 发起请求"]
BuildObj --> AxiosCall
CallFn --> Done(["返回结果"])
AxiosCall --> Done
```

**图表来源**
- [packages/libs/request.js:39-77](file://packages/libs/request.js#L39-L77)

**章节来源**
- [packages/libs/request.js:39-77](file://packages/libs/request.js#L39-L77)

### ProTable 组件中的请求流程（packages/components/ProTable.vue）
- fetch 方法
  - 组装分页参数与搜索表单数据
  - 调用 customRequest 获取数据
  - 依据 map 配置提取 dataPath 与 totalPath
  - 触发 successHandle 判定成功条件并提示
- 删除/提交等动作
  - 通过 tableAction 调用 customRequest，并在成功后刷新表格

```mermaid
sequenceDiagram
participant PT as "ProTable.fetch"
participant Req as "customRequest"
participant RA as "request.js"
participant GH as "http.js(Axios)"
participant API as "后端接口"
PT->>Req : 传入 { request, method, headers, datas }
Req->>RA : 解析 request/keys/headers
RA->>GH : 获取 $http/Axios 实例
GH->>API : 发起请求
API-->>GH : 返回响应
GH-->>RA : 返回响应
RA-->>PT : 返回标准化结果
PT->>PT : 提取 dataPath/totalPath<br/>触发 successHandle
```

**图表来源**
- [packages/components/ProTable.vue:665-737](file://packages/components/ProTable.vue#L665-L737)
- [packages/libs/request.js:39-77](file://packages/libs/request.js#L39-L77)
- [src/libs/http.js:42](file://src/libs/http.js#L42)

**章节来源**
- [packages/components/ProTable.vue:665-737](file://packages/components/ProTable.vue#L665-L737)

### 在 ProTable 的 request 中使用自定义 HTTP 客户端
- 方式一：字符串 URL
  - 直接传入字符串，支持模板变量替换与自动 params/data 拆分
  - 参考：[src/views/Home.vue:173-173](file://src/views/Home.vue#L173-L173)
- 方式二：对象配置
  - 支持 request/url、method、keys 等字段；若包含 request 函数则直接调用
  - 参考：[src/views/Home.vue:175-183](file://src/views/Home.vue#L175-L183)
- 方式三：函数回调
  - 自行构造 axios 请求，适合复杂场景（如动态 headers、多段式请求）
  - 参考：[src/views/Home.vue:175-183](file://src/views/Home.vue#L175-L183)
- 类型约束
  - request 支持字符串、函数或对象
  - 参考：[types/ProTable.d.ts:41](file://types/ProTable.d.ts#L41)

**章节来源**
- [src/views/Home.vue:173-183](file://src/views/Home.vue#L173-L183)
- [types/ProTable.d.ts:41](file://types/ProTable.d.ts#L41)

### 认证令牌管理与请求头
- 全局拦截器从本地存储读取令牌并写入 Authorization 头
- 适配器会从 URL 查询参数提取 token 并合并到 headers
- 若需在特定请求禁用消息提示，可在 headers 中设置 nomsg

**章节来源**
- [src/libs/http.js:15-17](file://src/libs/http.js#L15-L17)
- [packages/libs/request.js:32-37](file://packages/libs/request.js#L32-L37)

### 错误处理机制
- 响应拦截器
  - 非 200 状态时按状态码分类提示
  - 超时错误（ECONNABORTED + timeout）提示“请求超时!”
  - 其他错误提示 message 或“未知错误!”
- ProTable 层
  - 通过 successHandle 判定成功条件（支持 map.success 表达式）
  - 失败时统一提示错误消息

**章节来源**
- [src/libs/http.js:43-67](file://src/libs/http.js#L43-L67)
- [packages/components/ProTable.vue:782-798](file://packages/components/ProTable.vue#L782-L798)

### 超时与重试策略建议
- 超时
  - 全局默认超时已设置为 60000ms
  - 如需调整，可在自定义 axios 实例中设置
  - 参考：[src/libs/http.js:10](file://src/libs/http.js#L10)
- 重试
  - 项目未内置重试逻辑
  - 建议在自定义 axios 实例中通过拦截器或 axios 的 retry 插件实现
  - 参考：[packages/index.js:13](file://packages/index.js#L13)

**章节来源**
- [src/libs/http.js:10](file://src/libs/http.js#L10)
- [packages/index.js:13](file://packages/index.js#L13)

## 依赖关系分析
- 组件库安装时将 axios 注入为 $http，供全局与组件库内使用
- ProTable 内部通过 customRequest 调用 $http 或默认 Axios
- 适配器层负责 request 形态解析与参数拼装

```mermaid
graph LR
PkgIndex["packages/index.js"] --> GlobalHttp["src/libs/http.js"]
ProTable["packages/components/ProTable.vue"] --> CustomReq["packages/libs/request.js"]
CustomReq --> GlobalHttp
GlobalHttp --> AxiosDep["axios(外部依赖)"]
```

**图表来源**
- [packages/index.js:12-19](file://packages/index.js#L12-L19)
- [packages/libs/request.js:40-42](file://packages/libs/request.js#L40-L42)
- [src/libs/http.js:42](file://src/libs/http.js#L42)

**章节来源**
- [packages/index.js:12-19](file://packages/index.js#L12-L19)
- [packages/libs/request.js:40-42](file://packages/libs/request.js#L40-L42)
- [src/libs/http.js:42](file://src/libs/http.js#L42)

## 性能考虑
- 合理设置超时时间，避免长时间阻塞 UI
- 对高频请求启用缓存策略（如按查询参数生成缓存键）
- 控制一次性请求的数据量，结合分页与懒加载
- 在 ProTable 中仅传递必要的 keys，减少不必要的字段传输

## 故障排查指南
- 请求未携带认证信息
  - 检查本地存储中是否存在 token
  - 确认请求拦截器是否正确设置 Authorization 头
  - 参考：[src/libs/http.js:15-17](file://src/libs/http.js#L15-L17)
- 请求超时
  - 查看全局超时配置与网络状况
  - 参考：[src/libs/http.js:10](file://src/libs/http.js#L10)
- 响应未触发成功提示
  - 检查 map.success 表达式与后端返回字段
  - 参考：[packages/components/ProTable.vue:782-798](file://packages/components/ProTable.vue#L782-L798)
- URL 模板变量未生效
  - 确认传入 datas 是否包含对应键值
  - 参考：[packages/libs/request.js:23-31](file://packages/libs/request.js#L23-L31)

**章节来源**
- [src/libs/http.js:10-17](file://src/libs/http.js#L10-L17)
- [packages/components/ProTable.vue:782-798](file://packages/components/ProTable.vue#L782-L798)
- [packages/libs/request.js:23-31](file://packages/libs/request.js#L23-L31)

## 结论
Pro-IVIEW V3 通过全局 HTTP 客户端与统一请求适配器，实现了对 Axios 的灵活封装与复用。开发者既可通过字符串/对象/函数三种方式在 ProTable 的 request 中自由组合 HTTP 请求，又能在全局层面统一处理认证、超时与错误提示。对于重试等高级能力，建议在自定义 axios 实例中扩展实现，以保持与现有拦截器体系的一致性。

## 附录
- 外部依赖
  - axios 版本：参见 [package.json:22](file://package.json#L22)
- 全局注入
  - 安装组件库时注入 $http：参见 [packages/index.js:12-19](file://packages/index.js#L12-L19)
- ProTable 类型
  - request 支持字符串/函数/对象：参见 [types/ProTable.d.ts:41](file://types/ProTable.d.ts#L41)