# 网络请求问题
**本文引用的文件**
- [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)
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能与可靠性考虑](#性能与可靠性考虑)
8. [故障排除指南](#故障排除指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本指南聚焦于网络请求相关的故障排除，结合仓库中网络请求封装与工具模块，系统梳理常见 HTTP 错误（如 401/403、404、500、502、503、504）、跨域问题、请求超时、参数与 URL 前缀配置错误、Cookie 传递问题以及加解密与全局配置的影响因素。文档提供可落地的排查步骤、调试工具使用建议与日志分析流程，帮助快速定位与解决问题。
## 项目结构
该工具包以“网络请求封装 + 工具模块”为核心，对外通过统一入口导出，便于在业务层集中管理请求行为与全局配置。
```mermaid
graph TB
A["index.js
统一导出"] --> B["src/https/TsHttpUtil.js
请求封装与错误处理"]
A --> C["src/utils/TsGlobalConfig.js
全局配置"]
A --> D["src/utils/TsStorage.js
本地存储与Token/Cookie相关"]
A --> E["src/utils/TsCommon.js
通用工具"]
A --> F["src/utils/TsCrypto.js
加密/解密"]
F --> G["src/utils/TsSM4.js
SM4实现"]
```
图表来源
- [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)
## 核心组件
- 请求封装与错误处理：基于 umi-request 的扩展，统一设置默认参数（携带 Cookie、JSON 请求体），内置错误映射与兜底处理。
- 全局配置：提供前缀、额外参数注入、HTTP 错误回调等可插拔配置项。
- 存储与 Token：负责用户 Token 的读取与持久化，以及是否启用请求体加密的开关。
- 加密模块：基于 SM4 的加解密实现，支持 ECB 模式与 Base64 输出。
- 通用工具：空值判断、JSON 解析、URL 参数解析等基础能力。
章节来源
- [TsHttpUtil.js:7-35](file://src/https/TsHttpUtil.js#L7-L35)
- [TsHttpUtil.js:40-44](file://src/https/TsHttpUtil.js#L40-L44)
- [TsHttpUtil.js:99-134](file://src/https/TsHttpUtil.js#L99-L134)
- [TsGlobalConfig.js:5-29](file://src/utils/TsGlobalConfig.js#L5-L29)
- [TsStorage.js:9-23](file://src/utils/TsStorage.js#L9-L23)
- [TsCrypto.js:5-31](file://src/utils/TsCrypto.js#L5-L31)
- [TsSM4.js:96-156](file://src/utils/TsSM4.js#L96-L156)
- [TsCommon.js:25-44](file://src/utils/TsCommon.js#L25-L44)
## 架构总览
下图展示从调用方到网络层的关键交互路径，以及错误处理与加解密的插入点。
```mermaid
sequenceDiagram
participant Caller as "调用方"
participant Http as "TsHttpUtil.req"
participant Conf as "TsGlobalConfig"
participant Store as "TsStorage"
participant Crypto as "TsCrypto"
participant Umi as "umi-request"
participant Srv as "后端服务"
Caller->>Http : "发起请求(get/post/form)"
Http->>Conf : "读取全局配置(prefix/httpParams/onHttpError)"
Http->>Store : "读取用户Token"
Http->>Http : "组装参数/附加额外参数/可选加密"
Http->>Umi : "执行请求(携带Cookie/JSON)"
Umi-->>Http : "响应/错误"
Http->>Crypto : "若响应标记加密则解密"
Http-->>Caller : "返回标准化结果或抛出错误"
Http->>Conf : "非200时触发onHttpError(res)"
```
图表来源
- [TsHttpUtil.js:99-134](file://src/https/TsHttpUtil.js#L99-L134)
- [TsHttpUtil.js:100-106](file://src/https/TsHttpUtil.js#L100-L106)
- [TsHttpUtil.js:109-111](file://src/https/TsHttpUtil.js#L109-L111)
- [TsHttpUtil.js:117-128](file://src/https/TsHttpUtil.js#L117-L128)
- [TsGlobalConfig.js:19-29](file://src/utils/TsGlobalConfig.js#L19-L29)
- [TsStorage.js:13-15](file://src/utils/TsStorage.js#L13-L15)
- [TsCrypto.js:19-30](file://src/utils/TsCrypto.js#L19-L30)
## 详细组件分析
### 请求封装与错误处理（TsHttpUtil）
- 默认行为
- 默认携带 Cookie（credentials: include），确保跨子域与第三方 Cookie 场景可用。
- 默认 JSON 请求体（requestType: json），POST 表单需显式选择 form。
- 统一错误处理：将响应状态映射为可读消息，未捕获时兜底为“参数错误或服务器异常”。
- 参数处理
- 支持分页参数转换（pagination -> pageNum/pageSize）。
- 支持 equals 对象转逗号分隔字符串。
- 支持全局额外参数注入（GET 合并 params；非表单 POST 合并 data）。
- 可选请求体加密：当开启 encrypt_body 时，将 data 包装为 encryptData 并加密。
- URL 前缀
- prefix 支持字符串或函数，函数形式可按 URL 动态决定前缀，避免硬编码。
- 响应处理
- 当 rawResponse 为真时直接返回原始响应；否则仅返回 data 与 recordsTotal。
- 若响应标记加密，自动解密并解析 JSON。
- 非 200 时触发 onHttpError 回调，同时 reject 标准化错误对象。
```mermaid
flowchart TD
Start(["进入 req"]) --> Prefix["读取全局配置prefix"]
Prefix --> HasPrefix{"prefix存在？"}
HasPrefix --> |是| Join["拼接url = prefix + url"]
HasPrefix --> |否| Skip["保持原url"]
Join --> Params["dealParamsBody处理参数/附加额外参数/可选加密"]
Skip --> Params
Params --> Headers["合并headers并注入用户Token"]
Headers --> Send["umi-request发送请求"]
Send --> Resp{"rawResponse？"}
Resp --> |是| ReturnRaw["返回原始响应"]
Resp --> |否| Code{"响应码=200？"}
Code --> |是| Decrypt{"响应标记加密？"}
Decrypt --> |是| Dec["解密+JSON解析"] --> ReturnData["返回{data,recordsTotal}"]
Decrypt --> |否| ReturnData
Code --> |否| Hook["触发onHttpError(res)"] --> Reject["reject标准化错误"]
```
图表来源
- [TsHttpUtil.js:99-134](file://src/https/TsHttpUtil.js#L99-L134)
- [TsHttpUtil.js:50-91](file://src/https/TsHttpUtil.js#L50-L91)
- [TsHttpUtil.js:117-128](file://src/https/TsHttpUtil.js#L117-L128)
章节来源
- [TsHttpUtil.js:7-35](file://src/https/TsHttpUtil.js#L7-L35)
- [TsHttpUtil.js:40-44](file://src/https/TsHttpUtil.js#L40-L44)
- [TsHttpUtil.js:50-91](file://src/https/TsHttpUtil.js#L50-L91)
- [TsHttpUtil.js:99-134](file://src/https/TsHttpUtil.js#L99-L134)
### 全局配置（TsGlobalConfig）
- 关键配置项
- base64Key：用于初始化加密模块的密钥缓冲区。
- prefix：统一请求前缀，支持函数按 URL 动态生成。
- onHttpError：非 200 时的回调钩子，便于统一处理错误。
- httpParams：返回额外参数对象，GET 合并到 params，POST 合并到 data。
- 读写方式
- 通过 window.httpConfig 注入全局配置，setConfig 支持增量合并。
章节来源
- [TsGlobalConfig.js:5-29](file://src/utils/TsGlobalConfig.js#L5-L29)
- [TsGlobalConfig.js:19-29](file://src/utils/TsGlobalConfig.js#L19-L29)
### 存储与 Token（TsStorage）
- 用户 Token
- 读取：getUserToken 从本地存储获取，为空时返回空字符串。
- 写入：saveUserToken 将 Token 持久化。
- 请求体加密开关
- getEncryptBody/getSaveEncryptBody 控制是否对请求体进行加密包装。
- Cookie 传递
- 默认 credentials: include，配合后端 SameSite/Cross-Origin 策略使用。
章节来源
- [TsStorage.js:9-23](file://src/utils/TsStorage.js#L9-L23)
### 加密模块（TsCrypto 与 TsSM4）
- 初始化
- 使用 base64Key 生成 16 字节密钥缓冲区，构造 SM4 实例。
- 加密/解密
- encrypt：对明文进行 SM4 加密（ECB 模式，Base64 输出）。
- decrypt：对密文进行 SM4 解密。
- 注意事项
- ECB 模式无 IV，适合小块数据；CBC 需要 IV，当前实现未使用 IV。
- cipherType 默认 Base64，与前端期望一致。
章节来源
- [TsCrypto.js:5-31](file://src/utils/TsCrypto.js#L5-L31)
- [TsSM4.js:96-156](file://src/utils/TsSM4.js#L96-L156)
- [TsSM4.js:338-387](file://src/utils/TsSM4.js#L338-L387)
- [TsSM4.js:395-452](file://src/utils/TsSM4.js#L395-L452)
## 依赖关系分析
- TsHttpUtil 依赖
- TsGlobalConfig：读取 prefix、httpParams、onHttpError。
- TsStorage：读取用户 Token、加密开关。
- TsCrypto：在开启加密时对请求体进行加密。
- TsCommon：参数处理与空值判断。
- TsCrypto 依赖
- TsGlobalConfig：读取 base64Key。
- TsSM4：SM4 算法实现。
- 外部依赖
- umi-request：HTTP 请求库。
- base64-js：Base64 编解码。
```mermaid
graph LR
Http["TsHttpUtil"] --> Conf["TsGlobalConfig"]
Http --> Store["TsStorage"]
Http --> Crypto["TsCrypto"]
Http --> Common["TsCommon"]
Crypto --> SM4["TsSM4"]
Http --> Umi["umi-request"]
Crypto --> Base64["base64-js"]
```
图表来源
- [TsHttpUtil.js:1-6](file://src/https/TsHttpUtil.js#L1-L6)
- [TsCrypto.js:1-4](file://src/utils/TsCrypto.js#L1-L4)
- [package.json:19-22](file://package.json#L19-L22)
章节来源
- [TsHttpUtil.js:1-6](file://src/https/TsHttpUtil.js#L1-L6)
- [TsCrypto.js:1-4](file://src/utils/TsCrypto.js#L1-L4)
- [package.json:19-22](file://package.json#L19-L22)
## 性能与可靠性考虑
- 请求并发与重试
- 当前未内置重试机制，建议在上层业务根据错误类型（如 502/503/504）进行指数退避重试。
- 超时控制
- 可通过 umi-request 的 timeout 配置项在扩展层增加超时控制，避免长时间阻塞。
- 日志与监控
- 在 onHttpError 中接入埋点或上报，记录状态码、URL、耗时、Token 状态等，便于后续分析。
- 加密开销
- 对大体量请求体加密会带来 CPU 开销，建议仅对敏感数据启用加密。
[本节为通用建议，不直接分析具体文件]
## 故障排除指南
### 一、常见 HTTP 错误与处理策略
- 200 成功
- 正常流程，无需处理。
- 201/202/204
- 业务状态正常，关注业务语义与后续处理。
- 400 客户端参数错误
- 排查请求体格式、必填字段、分页参数转换逻辑（pageNum/pageSize）。
- 401 未认证/令牌无效
- 检查 Token 是否存在、是否过期、是否正确写入存储。
- 确认请求头是否注入了 Token。
- 403 权限不足
- 检查用户角色与接口权限，确认 Token 有效但无访问权限。
- 404 资源不存在
- 检查 URL 是否正确、前缀是否匹配、路径参数是否缺失。
- 406/410/422
- 406：请求格式不可得；410：资源永久删除；422：创建对象时验证错误。
- 500 服务器内部错误
- 记录请求上下文，联系后端排查。
- 502/503/504 网关/服务不可用/网关超时
- 建议重试与降级策略，必要时提示用户稍后再试。
章节来源
- [TsHttpUtil.js:7-23](file://src/https/TsHttpUtil.js#L7-L23)
- [TsHttpUtil.js:28-35](file://src/https/TsHttpUtil.js#L28-L35)
### 二、跨域请求失败排查
- 关键点
- 浏览器同源策略限制，需后端设置正确的 Access-Control-Allow-*。
- 若携带 Cookie，需确保：
- credentials: include 生效（默认已开启）。
- 后端允许 Credentials（Access-Control-Allow-Credentials: true）。
- 前端指定具体 Origin（而非通配符），后端允许该 Origin。
- 建议
- 使用浏览器开发者工具 Network 面板查看预检请求与响应头。
- 确认域名、协议、端口一致或后端明确放行。
章节来源
- [TsHttpUtil.js:42](file://src/https/TsHttpUtil.js#L42)
### 三、请求超时
- 现状
- 当前未设置超时时间，可能出现长时间等待。
- 建议
- 在扩展层增加 timeout 配置，或在上层业务做超时控制。
- 对长耗时接口采用分页/分批策略。
[本节为通用建议，不直接分析具体文件]
### 四、401/403 权限错误
- 常见原因
- Token 不存在或为空。
- Token 过期或被撤销。
- 请求头未注入 Token。
- 排查步骤
- 检查存储中是否存在 Token。
- 确认请求头是否包含 Token。
- 若后端要求特定头名，需在上层统一注入。
- 处理策略
- 401：跳转登录或刷新 Token。
- 403：提示权限不足或引导用户联系管理员。
章节来源
- [TsStorage.js:13-15](file://src/utils/TsStorage.js#L13-L15)
- [TsHttpUtil.js:109-111](file://src/https/TsHttpUtil.js#L109-L111)
### 五、500 服务器错误
- 建议
- 记录完整请求上下文（URL、params/data、headers、Token）。
- 在 onHttpError 中接入日志上报，便于后端定位。
- 必要时进行降级或重试。
章节来源
- [TsHttpUtil.js:125](file://src/https/TsHttpUtil.js#L125)
### 六、请求参数配置问题
- 分页参数
- pagination 转换为 pageNum/pageSize，确认传入对象结构正确。
- equals 对象
- equals 对象中空值会被过滤，确保非空字段参与拼接。
- 全局额外参数
- httpParams 返回的对象会合并到 GET params 或 POST data，注意字段冲突与覆盖顺序。
章节来源
- [TsHttpUtil.js:50-91](file://src/https/TsHttpUtil.js#L50-L91)
- [TsGlobalConfig.js:10-12](file://src/utils/TsGlobalConfig.js#L10-L12)
### 七、URL 前缀配置错误
- 现状
- prefix 支持字符串或函数；函数形式可按 URL 动态生成。
- 排查
- 确认 prefix 是否为空或返回空字符串。
- 函数形式需保证返回值为合法前缀（含协议与结尾斜杠）。
- 建议
- 在开发环境与生产环境分别设置不同前缀，避免硬编码。
章节来源
- [TsHttpUtil.js:100-106](file://src/https/TsHttpUtil.js#L100-L106)
- [TsGlobalConfig.js:7](file://src/utils/TsGlobalConfig.js#L7)
### 八、Cookie 传递问题
- 现状
- 默认携带 Cookie（credentials: include），适用于同源与跨子域场景。
- 排查
- 确认后端是否正确设置 Domain/SameSite/Cross-Origin。
- 若跨域，需后端允许 Credentials 且指定具体 Origin。
- 建议
- 在上层统一设置 Cookie 与 Token，避免遗漏。
章节来源
- [TsHttpUtil.js:42](file://src/https/TsHttpUtil.js#L42)
### 九、加解密相关问题
- 现状
- 当开启 encrypt_body 时，请求体被包装为 encryptData 并加密；响应若标记加密则自动解密。
- 排查
- 确认 base64Key 与后端一致。
- 确认加密模式（ECB）与后端一致。
- 确认 cipherType 为 Base64。
- 建议
- 仅对敏感字段启用加密，避免大体积数据加密带来的性能损耗。
章节来源
- [TsStorage.js:17-23](file://src/utils/TsStorage.js#L17-L23)
- [TsHttpUtil.js:82-86](file://src/https/TsHttpUtil.js#L82-L86)
- [TsHttpUtil.js:119-122](file://src/https/TsHttpUtil.js#L119-L122)
- [TsCrypto.js:8-13](file://src/utils/TsCrypto.js#L8-L13)
- [TsSM4.js:128-141](file://src/utils/TsSM4.js#L128-L141)
### 十、调试工具与监控技巧
- 浏览器开发者工具
- Network：查看请求头、响应头、CORS、Cookie、状态码与耗时。
- Console：输出 onHttpError 回调中的错误信息。
- 日志与上报
- 在 onHttpError 中记录：URL、状态码、请求体摘要、Token 状态、时间戳。
- 对 5xx 错误进行聚合统计，辅助定位热点接口。
- 本地与线上差异
- 使用不同 prefix 区分开发/测试/生产环境。
- 在开发环境开启更详细的日志与断言。
章节来源
- [TsHttpUtil.js:125](file://src/https/TsHttpUtil.js#L125)
- [TsGlobalConfig.js:7](file://src/utils/TsGlobalConfig.js#L7)
### 十一、错误日志分析与问题定位流程
- 步骤
- 收集：URL、状态码、请求头、请求体、响应体、时间戳、Token 状态。
- 分类：4xx（参数/权限/资源）、5xx（服务/网关）、CORS/超时。
- 定位：依据状态码与日志，缩小范围至前端配置、Cookie/Token、加解密、后端接口。
- 复现：构造最小复现场景，逐步剔除变量（关闭加密、更换 prefix、清除 Cookie）。
- 验证：修复后回归测试，观察 onHttpError 是否仍触发。
- 建议
- 对高频错误建立告警阈值，结合用户反馈与日志进行联动。
[本节为通用建议，不直接分析具体文件]
## 结论
本工具包通过统一的请求封装、全局配置与加解密模块，提供了较为完善的网络请求基础设施。结合本文提供的故障排除清单与定位流程，可在大多数情况下快速识别并解决常见的网络请求问题。建议在生产环境中补充超时控制、重试与监控上报机制，持续优化用户体验与稳定性。
[本节为总结性内容，不直接分析具体文件]
## 附录
### A. 常见错误代码速查
- 200：成功
- 201：新建/修改成功
- 202：请求已进入后台排队
- 204：删除成功
- 400：请求参数错误
- 401：未认证/令牌无效
- 403：权限不足
- 404：资源不存在
- 406：请求格式不可得
- 410：资源永久删除
- 422：创建对象时验证错误
- 500：服务器内部错误
- 502：网关错误
- 503：服务不可用/过载
- 504：网关超时
章节来源
- [TsHttpUtil.js:7-23](file://src/https/TsHttpUtil.js#L7-L23)
### B. 关键配置与默认值
- 默认配置
- base64Key：默认密钥（用于加密模块初始化）。
- prefix：默认空字符串。
- onHttpError：默认空函数。
- httpParams：默认空函数。
- 请求默认
- credentials: include（携带 Cookie）。
- requestType: json（POST JSON）。
- 默认错误处理：将状态映射为可读消息。
章节来源
- [TsGlobalConfig.js:5-13](file://src/utils/TsGlobalConfig.js#L5-L13)
- [TsHttpUtil.js:40-44](file://src/https/TsHttpUtil.js#L40-L44)
- [TsHttpUtil.js:28-35](file://src/https/TsHttpUtil.js#L28-L35)
### C. 使用示例参考
- README 提供了基本使用方式与全局配置示例，可据此进行最小复现与验证。
章节来源
- [README.md:12-26](file://README.md#L12-L26)