320 lines
14 KiB
Markdown
320 lines
14 KiB
Markdown
# 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) |