# HTTP 请求配置

<cite>
**本文引用的文件**
- [TsHttpUtil.js](file://src/https/TsHttpUtil.js)
- [TsGlobalConfig.js](file://src/utils/TsGlobalConfig.js)
- [TsStorage.js](file://src/utils/TsStorage.js)
- [TsCommon.js](file://src/utils/TsCommon.js)
- [TsCrypto.js](file://src/utils/TsCrypto.js)
- [TsSM4.js](file://src/utils/TsSM4.js)
- [index.js](file://index.js)
- [package.json](file://package.json)
- [README.md](file://README.md)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能与缓存策略](#性能与缓存策略)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录：完整配置示例与最佳实践](#附录完整配置示例与最佳实践)

## 简介
本文件面向使用 TsHttpUtil 的开发者，系统性说明 HTTP 请求配置项、请求头设置、超时控制、重试机制、httpParams 回调、请求拦截与响应处理、错误处理 onHttpError、认证与代理、SSL 与加密、性能优化与缓存策略，以及调试与监控方法。文档基于仓库源码进行逐层解析，并提供可直接落地的配置建议与流程图示。

## 项目结构
该工具包以“功能域”组织：https 层负责网络请求封装，utils 层提供全局配置、存储、通用工具、加解密等支撑能力；入口 index.js 汇总导出模块。

```mermaid
graph TB
subgraph "入口"
IDX["index.js"]
end
subgraph "HTTPS 层"
HTTP["TsHttpUtil.js"]
end
subgraph "工具层"
GC["TsGlobalConfig.js"]
ST["TsStorage.js"]
CM["TsCommon.js"]
CR["TsCrypto.js"]
SM["TsSM4.js"]
end
IDX --> HTTP
HTTP --> GC
HTTP --> ST
HTTP --> CM
HTTP --> CR
CR --> SM
```

图表来源
- [index.js:1-16](file://index.js#L1-L16)
- [TsHttpUtil.js:1-171](file://src/https/TsHttpUtil.js#L1-L171)
- [TsGlobalConfig.js:1-34](file://src/utils/TsGlobalConfig.js#L1-L34)
- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
- [TsCommon.js:1-98](file://src/utils/TsCommon.js#L1-L98)
- [TsCrypto.js:1-34](file://src/utils/TsCrypto.js#L1-L34)
- [TsSM4.js:1-456](file://src/utils/TsSM4.js#L1-L456)

章节来源
- [index.js:1-16](file://index.js#L1-L16)
- [package.json:1-24](file://package.json#L1-L24)

## 核心组件
- TsHttpUtil：统一请求入口，封装 GET/POST/FORM，内置默认错误处理、请求头注入、参数合并与加密逻辑。
- TsGlobalConfig：全局配置中心，支持 prefix 前缀、onHttpError 错误回调、httpParams 动态参数注入。
- TsStorage：本地存储与用户 Token 管理，支持开关 body 加密。
- TsCommon：通用工具，含空值判断、JSON 解析、开发环境判断等。
- TsCrypto/TsSM4：SM4 对称加密实现，配合 base64 密钥与模式配置。

章节来源
- [TsHttpUtil.js:25-171](file://src/https/TsHttpUtil.js#L25-L171)
- [TsGlobalConfig.js:1-34](file://src/utils/TsGlobalConfig.js#L1-L34)
- [TsStorage.js:1-55](file://src/utils/TsStorage.js#L1-L55)
- [TsCommon.js:1-98](file://src/utils/TsCommon.js#L1-L98)
- [TsCrypto.js:1-34](file://src/utils/TsCrypto.js#L1-L34)
- [TsSM4.js:1-456](file://src/utils/TsSM4.js#L1-L456)

## 架构总览
TsHttpUtil 在 umi-request 基础上扩展了：
- 默认错误处理 errorHandler
- 默认携带 cookie、JSON 请求体类型
- 统一参数处理 dealParamsBody（分页、equals、动态参数注入）
- 请求前缀 prefix 注入
- 自动注入用户 Token
- 响应体解密与数据提取
- 错误回调 onHttpError

```mermaid
sequenceDiagram
participant App as "应用"
participant Http as "TsHttpUtil"
participant Umi as "umi-request"
participant Cfg as "TsGlobalConfig"
participant Store as "TsStorage"
participant Crypto as "TsCrypto/TsSM4"
App->>Http : 调用 get/post/form(req)
Http->>Cfg : 读取 prefix/httpParams/onHttpError
Http->>Store : 读取用户 Token
Http->>Http : 合并动态参数/分页/equals
Http->>Http : 条件加密 encryptBody
Http->>Umi : request(url, options)
Umi-->>Http : 返回响应
Http->>Http : 解密/提取 data/recordsTotal
Http-->>App : Promise.resolve(data, recordsTotal)
Http->>Cfg : onHttpError(res)失败时
```

图表来源
- [TsHttpUtil.js:99-134](file://src/https/TsHttpUtil.js#L99-L134)
- [TsGlobalConfig.js:19-29](file://src/utils/TsGlobalConfig.js#L19-L29)
- [TsStorage.js:13-23](file://src/utils/TsStorage.js#L13-L23)
- [TsCrypto.js:5-31](file://src/utils/TsCrypto.js#L5-L31)
- [TsSM4.js:96-453](file://src/utils/TsSM4.js#L96-L453)

## 详细组件分析

### 1) 请求配置与默认行为
- 默认错误处理：对无响应或状态码映射到统一消息。
- 凭据策略：默认携带 Cookie。
- 请求体类型：默认 JSON。
- 请求前缀：支持字符串或函数式前缀，按 URL 动态拼接。
- 动态参数注入：通过 httpParams 回调注入到 GET 查询参数或非表单 POST 请求体中。
- 用户 Token：自动从本地存储读取并注入到请求头 token 字段。
- 响应处理：默认仅返回 data 与 recordsTotal；若响应标记加密，则自动解密并解析 JSON。

章节来源
- [TsHttpUtil.js:28-44](file://src/https/TsHttpUtil.js#L28-L44)
- [TsHttpUtil.js:99-134](file://src/https/TsHttpUtil.js#L99-L134)
- [TsGlobalConfig.js:5-21](file://src/utils/TsGlobalConfig.js#L5-L21)
- [TsStorage.js:13-15](file://src/utils/TsStorage.js#L13-L15)

### 2) httpParams 回调函数详解
- 触发时机：在 GET 请求合并查询参数、或非表单 POST 请求合并请求体之前。
- 参数与返回：回调接收当前请求上下文（由全局配置提供），返回一个对象作为额外参数注入。
- 使用场景：统一注入业务维度参数（如租户 ID、版本号、traceId）、环境标识、签名参数等。
- 注意事项：GET 与非表单 POST 的注入位置不同，避免覆盖关键字段。

章节来源
- [TsHttpUtil.js:70-88](file://src/https/TsHttpUtil.js#L70-L88)
- [TsGlobalConfig.js:10-12](file://src/utils/TsGlobalConfig.js#L10-L12)

### 3) 请求头设置与认证
- 自动头注入：每次请求自动附加 token 头部，值来自用户 Token。
- 手动头覆盖：可通过 options.headers 传入自定义头，会与默认头合并。
- 认证策略：建议在 httpParams 或 headers 中注入 Authorization/Bearer 等，结合用户 Token 管理。

章节来源
- [TsHttpUtil.js:108-112](file://src/https/TsHttpUtil.js#L108-L112)
- [TsStorage.js:13-15](file://src/utils/TsStorage.js#L13-L15)

### 4) 超时与重试机制
- 超时：umi-request 支持 timeout 配置，可在 options 中传入；TsHttpUtil 不在内部强制设置。
- 重试：未内置重试逻辑，可在上层封装或通过 umi-request 的 retry 选项实现（需在调用侧传入）。

章节来源
- [TsHttpUtil.js:108-112](file://src/https/TsHttpUtil.js#L108-L112)
- [package.json:19-22](file://package.json#L19-L22)

### 5) 请求拦截器与响应处理器
- 请求拦截：通过 options.headers、httpParams 注入参数与头；prefix 前缀在请求发起前拼接。
- 响应处理：默认解析 data/recordsTotal；若响应带加密标记则自动解密。
- 自定义处理：通过 rawResponse 可直接返回原始响应对象，交由调用方自行处理。

章节来源
- [TsHttpUtil.js:108-134](file://src/https/TsHttpUtil.js#L108-L134)

### 6) 错误处理 onHttpError
- 默认行为：将错误映射为统一结构（code/message）。
- 自定义回调：通过 TsGlobalConfig.setConfig 注入 onHttpError，用于统一上报、埋点、登录态失效处理等。
- 触发条件：当响应 code 非 200 时触发。

章节来源
- [TsHttpUtil.js:28-35](file://src/https/TsHttpUtil.js#L28-L35)
- [TsHttpUtil.js:125-127](file://src/https/TsHttpUtil.js#L125-L127)
- [TsGlobalConfig.js:8-9](file://src/utils/TsGlobalConfig.js#L8-L9)

### 7) 加密与安全
- 加密开关：通过 TsStorage.saveEncryptBody(true/false) 控制是否对请求体进行加密。
- 加密算法：SM4（ECB/可选 CBC），密钥来自 TsGlobalConfig.base64Key。
- 解密：响应体若标记加密，自动解密并解析 JSON。
- 建议：生产环境务必使用强密钥与 HTTPS，避免明文传输。

章节来源
- [TsHttpUtil.js:82-86](file://src/https/TsHttpUtil.js#L82-L86)
- [TsHttpUtil.js:119-122](file://src/https/TsHttpUtil.js#L119-L122)
- [TsStorage.js:17-23](file://src/utils/TsStorage.js#L17-L23)
- [TsCrypto.js:5-31](file://src/utils/TsCrypto.js#L5-L31)
- [TsSM4.js:96-453](file://src/utils/TsSM4.js#L96-L453)

### 8) 参数处理与分页/equals
- 分页：将 pagination 对象转换为 pageSize/pageNum 并移除 pagination。
- equals：将对象转为逗号分隔的键值串，过滤空值。
- 动态参数：通过 httpParams 注入，GET 合并到查询参数，非表单 POST 合并到请求体。

章节来源
- [TsHttpUtil.js:50-91](file://src/https/TsHttpUtil.js#L50-L91)

### 9) 环境差异化配置策略
- 开发环境：可启用 httpParams 注入调试参数、开启日志输出；prefix 指向本地/联调服务。
- 测试环境：启用 httpParams 注入测试标识；开启轻量级错误上报；必要时开启加密。
- 生产环境：严格启用 HTTPS、固定密钥、关闭敏感日志；onHttpError 上报统一错误；限制 httpParams 注入范围。

章节来源
- [TsCommon.js:63-65](file://src/utils/TsCommon.js#L63-L65)
- [TsGlobalConfig.js:5-21](file://src/utils/TsGlobalConfig.js#L5-L21)

## 依赖关系分析

```mermaid
graph LR
HTTP["TsHttpUtil.js"] --> GC["TsGlobalConfig.js"]
HTTP --> ST["TsStorage.js"]
HTTP --> CM["TsCommon.js"]
HTTP --> CR["TsCrypto.js"]
CR --> SM["TsSM4.js"]
IDX["index.js"] --> HTTP
PKG["package.json"] --> HTTP
```

图表来源
- [TsHttpUtil.js:1-5](file://src/https/TsHttpUtil.js#L1-L5)
- [TsGlobalConfig.js:1-34](file://src/utils/TsGlobalConfig.js#L1-L34)
- [TsStorage.js:1-5](file://src/utils/TsStorage.js#L1-L5)
- [TsCommon.js:1-4](file://src/utils/TsCommon.js#L1-L4)
- [TsCrypto.js:1-3](file://src/utils/TsCrypto.js#L1-L3)
- [TsSM4.js:1-3](file://src/utils/TsSM4.js#L1-L3)
- [index.js:1-6](file://index.js#L1-L6)
- [package.json:19-22](file://package.json#L19-L22)

章节来源
- [TsHttpUtil.js:1-5](file://src/https/TsHttpUtil.js#L1-L5)
- [package.json:19-22](file://package.json#L19-L22)

## 性能与缓存策略
- 请求合并：优先使用 httpParams 合并公共参数，减少重复字段。
- 数据压缩：在服务端支持前提下，考虑 gzip/deflate 传输。
- 缓存策略：对 GET 请求可结合业务缓存（如内存/LocalStorage）避免重复请求；注意缓存失效与一致性。
- 超时与并发：合理设置 timeout，避免阻塞；对批量请求采用并发控制。
- 加密成本：加密/解密为 CPU 密集型，建议仅对敏感数据启用，或在高频接口中评估开销。

[本节为通用指导，不直接分析具体文件]

## 故障排查指南
- 无法登录/鉴权失败：检查 headers 中 token 是否正确注入；确认 httpParams 是否覆盖了必要的认证头。
- 参数丢失：确认 GET 与非表单 POST 的参数注入位置；避免与 options.params/data 冲突。
- 加密异常：确认 TsStorage.encryptBody 开关、base64Key 正确、服务端密钥一致。
- 错误未上报：确认 onHttpError 是否正确注入；检查响应 code/message 映射。
- 调试方法：开启浏览器 Network 面板，观察请求头、参数、响应体；在 httpParams 中注入 traceId 便于后端定位。

章节来源
- [TsHttpUtil.js:108-134](file://src/https/TsHttpUtil.js#L108-L134)
- [TsGlobalConfig.js:8-9](file://src/utils/TsGlobalConfig.js#L8-L9)
- [TsStorage.js:17-23](file://src/utils/TsStorage.js#L17-L23)
- [TsCrypto.js:5-31](file://src/utils/TsCrypto.js#L5-L31)

## 结论
TsHttpUtil 提供了简洁而强大的 HTTP 封装，通过全局配置与工具层能力，实现了参数注入、认证、加密、错误处理与响应解密等关键能力。建议在不同环境下采用差异化的配置策略，并结合调试与监控手段持续优化性能与稳定性。

[本节为总结，不直接分析具体文件]

## 附录：完整配置示例与最佳实践

### 1) 全局配置示例（开发/测试/生产）
- 开发环境
  - prefix: 指向本地/联调地址
  - httpParams: 注入 debug=true、env=dev、traceId
  - onHttpError: 输出到控制台或轻量上报
  - encryptBody: false
- 测试环境
  - prefix: 指向测试域名
  - httpParams: 注入 env=test、version、tenantId
  - onHttpError: 轻量上报
  - encryptBody: 可选开启
- 生产环境
  - prefix: 指向生产域名
  - httpParams: 仅注入必要参数（如 tenantId、version）
  - onHttpError: 完整上报（含堆栈）
  - encryptBody: 必须开启；base64Key 固定且保密

章节来源
- [TsGlobalConfig.js:5-21](file://src/utils/TsGlobalConfig.js#L5-L21)
- [TsCommon.js:63-65](file://src/utils/TsCommon.js#L63-L65)

### 2) 认证配置
- 方案一：在 headers 中注入 Authorization/Bearer
- 方案二：在 httpParams 中注入 token 参数
- 方案三：结合用户 Token 管理（TsStorage.getUserToken）

章节来源
- [TsHttpUtil.js:108-112](file://src/https/TsHttpUtil.js#L108-L112)
- [TsStorage.js:13-15](file://src/utils/TsStorage.js#L13-L15)

### 3) 代理与 SSL
- 代理：通过网络层或构建工具配置；TsHttpUtil 不直接处理代理。
- SSL：生产环境必须启用 HTTPS；确保证书有效与中间人攻击防护。

[本节为通用指导，不直接分析具体文件]

### 4) 性能优化与缓存
- 合理设置 timeout，避免长时间阻塞
- 对高频 GET 接口增加本地缓存
- 仅对敏感数据启用加密，评估 CPU 开销
- 使用 httpParams 合并公共参数，减少请求体积

[本节为通用指导，不直接分析具体文件]

### 5) 调试与监控
- 在 httpParams 中注入 traceId、version、env
- onHttpError 上报统一错误，包含 code/message/URL
- 使用浏览器 Network 面板与后端日志联动定位问题

章节来源
- [TsGlobalConfig.js:8-9](file://src/utils/TsGlobalConfig.js#L8-L9)