Files

曾文豪 523cc777f8 docs(readme): 重构README并补充详细文档内容

2026-04-29 11:20:18 +08:00

14 KiB

Raw Permalink Blame History

HTTP 请求配置

**本文引用的文件** - [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)

简介

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

项目结构

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

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

图表来源

章节来源

核心组件

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

章节来源

架构总览

TsHttpUtil 在 umi-request 基础上扩展了：

默认错误处理 errorHandler
默认携带 cookie、JSON 请求体类型
统一参数处理 dealParamsBody（分页、equals、动态参数注入）
请求前缀 prefix 注入
自动注入用户 Token
响应体解密与数据提取
错误回调 onHttpError

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)失败时

图表来源

详细组件分析

1) 请求配置与默认行为

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

章节来源

2) httpParams 回调函数详解

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

章节来源

3) 请求头设置与认证

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

章节来源

4) 超时与重试机制

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

章节来源

5) 请求拦截器与响应处理器

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

章节来源

TsHttpUtil.js:108-134

6) 错误处理 onHttpError

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

章节来源

7) 加密与安全

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

章节来源

8) 参数处理与分页/equals

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

章节来源

TsHttpUtil.js:50-91

9) 环境差异化配置策略

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

章节来源

依赖关系分析

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

图表来源

章节来源

性能与缓存策略

请求合并：优先使用 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 提供了简洁而强大的 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 固定且保密

章节来源

2) 认证配置

方案一：在 headers 中注入 Authorization/Bearer
方案二：在 httpParams 中注入 token 参数
方案三：结合用户 Token 管理（TsStorage.getUserToken）

章节来源

3) 代理与 SSL

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

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

4) 性能优化与缓存

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

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

5) 调试与监控

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

章节来源

TsGlobalConfig.js:8-9

14 KiB Raw Permalink Blame History Unescape Escape

HTTP 请求配置

目录

简介

项目结构

核心组件

架构总览

详细组件分析

1) 请求配置与默认行为

2) httpParams 回调函数详解

3) 请求头设置与认证

4) 超时与重试机制

5) 请求拦截器与响应处理器

6) 错误处理 onHttpError

7) 加密与安全

8) 参数处理与分页/equals

9) 环境差异化配置策略

依赖关系分析

性能与缓存策略

故障排查指南

结论

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

1) 全局配置示例（开发/测试/生产）

2) 认证配置

3) 代理与 SSL

4) 性能优化与缓存

5) 调试与监控

14 KiB

Raw Permalink Blame History