npm-tool/.qoder/repowiki/zh/content/故障排除/网络请求问题.md

网络请求问题

**本文引用的文件** - [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 传递问题以及加解密与全局配置的影响因素。文档提供可落地的排查步骤、调试工具使用建议与日志分析流程，帮助快速定位与解决问题。

项目结构

该工具包以“网络请求封装 + 工具模块”为核心，对外通过统一入口导出，便于在业务层集中管理请求行为与全局配置。

graph TB
A["index.js<br/>统一导出"] --> B["src/https/TsHttpUtil.js<br/>请求封装与错误处理"]
A --> C["src/utils/TsGlobalConfig.js<br/>全局配置"]
A --> D["src/utils/TsStorage.js<br/>本地存储与Token/Cookie相关"]
A --> E["src/utils/TsCommon.js<br/>通用工具"]
A --> F["src/utils/TsCrypto.js<br/>加密/解密"]
F --> G["src/utils/TsSM4.js<br/>SM4实现"]

图表来源

• index.js:1-16
• TsHttpUtil.js:1-171
• TsGlobalConfig.js:1-34
• TsStorage.js:1-55
• TsCommon.js:1-98
• TsCrypto.js:1-34
• TsSM4.js:1-456

章节来源

• index.js:1-16
• package.json:1-24

核心组件

• 请求封装与错误处理：基于 umi-request 的扩展，统一设置默认参数（携带 Cookie、JSON 请求体），内置错误映射与兜底处理。
• 全局配置：提供前缀、额外参数注入、HTTP 错误回调等可插拔配置项。
• 存储与 Token：负责用户 Token 的读取与持久化，以及是否启用请求体加密的开关。
• 加密模块：基于 SM4 的加解密实现，支持 ECB 模式与 Base64 输出。
• 通用工具：空值判断、JSON 解析、URL 参数解析等基础能力。

章节来源

• TsHttpUtil.js:7-35
• TsHttpUtil.js:40-44
• TsHttpUtil.js:99-134
• TsGlobalConfig.js:5-29
• TsStorage.js:9-23
• TsCrypto.js:5-31
• TsSM4.js:96-156
• TsCommon.js:25-44

架构总览

下图展示从调用方到网络层的关键交互路径，以及错误处理与加解密的插入点。

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
• TsHttpUtil.js:100-106
• TsHttpUtil.js:109-111
• TsHttpUtil.js:117-128
• TsGlobalConfig.js:19-29
• TsStorage.js:13-15
• TsCrypto.js:19-30

详细组件分析

请求封装与错误处理（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 标准化错误对象。

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
• TsHttpUtil.js:50-91
• TsHttpUtil.js:117-128

章节来源

• TsHttpUtil.js:7-35
• TsHttpUtil.js:40-44
• TsHttpUtil.js:50-91
• TsHttpUtil.js:99-134

全局配置（TsGlobalConfig）

• 关键配置项
  • base64Key：用于初始化加密模块的密钥缓冲区。
  • prefix：统一请求前缀，支持函数按 URL 动态生成。
  • onHttpError：非 200 时的回调钩子，便于统一处理错误。
  • httpParams：返回额外参数对象，GET 合并到 params，POST 合并到 data。
• 读写方式
  • 通过 window.httpConfig 注入全局配置，setConfig 支持增量合并。

章节来源

• TsGlobalConfig.js:5-29
• TsGlobalConfig.js:19-29

存储与 Token（TsStorage）

• 用户 Token
  • 读取：getUserToken 从本地存储获取，为空时返回空字符串。
  • 写入：saveUserToken 将 Token 持久化。
• 请求体加密开关
  • getEncryptBody/getSaveEncryptBody 控制是否对请求体进行加密包装。
• Cookie 传递
  • 默认 credentials: include，配合后端 SameSite/Cross-Origin 策略使用。

章节来源

• TsStorage.js:9-23

加密模块（TsCrypto 与 TsSM4）

• 初始化
  • 使用 base64Key 生成 16 字节密钥缓冲区，构造 SM4 实例。
• 加密/解密
  • encrypt：对明文进行 SM4 加密（ECB 模式，Base64 输出）。
  • decrypt：对密文进行 SM4 解密。
• 注意事项
  • ECB 模式无 IV，适合小块数据；CBC 需要 IV，当前实现未使用 IV。
  • cipherType 默认 Base64，与前端期望一致。

章节来源

• TsCrypto.js:5-31
• TsSM4.js:96-156
• TsSM4.js:338-387
• TsSM4.js:395-452

依赖关系分析

• TsHttpUtil 依赖
  • TsGlobalConfig：读取 prefix、httpParams、onHttpError。
  • TsStorage：读取用户 Token、加密开关。
  • TsCrypto：在开启加密时对请求体进行加密。
  • TsCommon：参数处理与空值判断。
• TsCrypto 依赖
  • TsGlobalConfig：读取 base64Key。
  • TsSM4：SM4 算法实现。
• 外部依赖
  • umi-request：HTTP 请求库。
  • base64-js：Base64 编解码。

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
• TsCrypto.js:1-4
• package.json:19-22

章节来源

• TsHttpUtil.js:1-6
• TsCrypto.js:1-4
• package.json:19-22

性能与可靠性考虑

• 请求并发与重试
  • 当前未内置重试机制，建议在上层业务根据错误类型（如 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
• TsHttpUtil.js:28-35

二、跨域请求失败排查

• 关键点
  • 浏览器同源策略限制，需后端设置正确的 Access-Control-Allow-*。
  • 若携带 Cookie，需确保：
    • credentials: include 生效（默认已开启）。
    • 后端允许 Credentials（Access-Control-Allow-Credentials: true）。
    • 前端指定具体 Origin（而非通配符），后端允许该 Origin。
• 建议
  • 使用浏览器开发者工具 Network 面板查看预检请求与响应头。
  • 确认域名、协议、端口一致或后端明确放行。

章节来源

• TsHttpUtil.js:42

三、请求超时

• 现状
  • 当前未设置超时时间，可能出现长时间等待。
• 建议
  • 在扩展层增加 timeout 配置，或在上层业务做超时控制。
  • 对长耗时接口采用分页/分批策略。

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

四、401/403 权限错误

• 常见原因
  • Token 不存在或为空。
  • Token 过期或被撤销。
  • 请求头未注入 Token。
• 排查步骤
  • 检查存储中是否存在 Token。
  • 确认请求头是否包含 Token。
  • 若后端要求特定头名，需在上层统一注入。
• 处理策略
  • 401：跳转登录或刷新 Token。
  • 403：提示权限不足或引导用户联系管理员。

章节来源

• TsStorage.js:13-15
• TsHttpUtil.js:109-111

五、500 服务器错误

• 建议
  • 记录完整请求上下文（URL、params/data、headers、Token）。
  • 在 onHttpError 中接入日志上报，便于后端定位。
  • 必要时进行降级或重试。

章节来源

• TsHttpUtil.js:125

六、请求参数配置问题

• 分页参数
  • pagination 转换为 pageNum/pageSize，确认传入对象结构正确。
• equals 对象
  • equals 对象中空值会被过滤，确保非空字段参与拼接。
• 全局额外参数
  • httpParams 返回的对象会合并到 GET params 或 POST data，注意字段冲突与覆盖顺序。

章节来源

• TsHttpUtil.js:50-91
• TsGlobalConfig.js:10-12

七、URL 前缀配置错误

• 现状
  • prefix 支持字符串或函数；函数形式可按 URL 动态生成。
• 排查
  • 确认 prefix 是否为空或返回空字符串。
  • 函数形式需保证返回值为合法前缀（含协议与结尾斜杠）。
• 建议
  • 在开发环境与生产环境分别设置不同前缀，避免硬编码。

章节来源

• TsHttpUtil.js:100-106
• TsGlobalConfig.js:7

八、Cookie 传递问题

• 现状
  • 默认携带 Cookie（credentials: include），适用于同源与跨子域场景。
• 排查
  • 确认后端是否正确设置 Domain/SameSite/Cross-Origin。
  • 若跨域，需后端允许 Credentials 且指定具体 Origin。
• 建议
  • 在上层统一设置 Cookie 与 Token，避免遗漏。

章节来源

• TsHttpUtil.js:42

九、加解密相关问题

• 现状
  • 当开启 encrypt_body 时，请求体被包装为 encryptData 并加密；响应若标记加密则自动解密。
• 排查
  • 确认 base64Key 与后端一致。
  • 确认加密模式（ECB）与后端一致。
  • 确认 cipherType 为 Base64。
• 建议
  • 仅对敏感字段启用加密，避免大体积数据加密带来的性能损耗。

章节来源

• TsStorage.js:17-23
• TsHttpUtil.js:82-86
• TsHttpUtil.js:119-122
• TsCrypto.js:8-13
• TsSM4.js:128-141

十、调试工具与监控技巧

• 浏览器开发者工具
  • Network：查看请求头、响应头、CORS、Cookie、状态码与耗时。
  • Console：输出 onHttpError 回调中的错误信息。
• 日志与上报
  • 在 onHttpError 中记录：URL、状态码、请求体摘要、Token 状态、时间戳。
  • 对 5xx 错误进行聚合统计，辅助定位热点接口。
• 本地与线上差异
  • 使用不同 prefix 区分开发/测试/生产环境。
  • 在开发环境开启更详细的日志与断言。

章节来源

• TsHttpUtil.js:125
• TsGlobalConfig.js:7

十一、错误日志分析与问题定位流程

• 步骤
  • 收集：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

B. 关键配置与默认值

• 默认配置
  • base64Key：默认密钥（用于加密模块初始化）。
  • prefix：默认空字符串。
  • onHttpError：默认空函数。
  • httpParams：默认空函数。
• 请求默认
  • credentials: include（携带 Cookie）。
  • requestType: json（POST JSON）。
  • 默认错误处理：将状态映射为可读消息。

章节来源

• TsGlobalConfig.js:5-13
• TsHttpUtil.js:40-44
• TsHttpUtil.js:28-35

C. 使用示例参考

• README 提供了基本使用方式与全局配置示例，可据此进行最小复现与验证。

章节来源

• README.md:12-26