npm-tool/.qoder/repowiki/zh/content/API 参考手册/HTTP 请求 API.md

HTTP 请求 API

**本文引用的文件** - [TsHttpUtil.js](file://src/https/TsHttpUtil.js) - [TsGlobalConfig.js](file://src/utils/TsGlobalConfig.js) - [TsCrypto.js](file://src/utils/TsCrypto.js) - [TsStorage.js](file://src/utils/TsStorage.js) - [TsCommon.js](file://src/utils/TsCommon.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 请求模块的完整 API 参考文档，聚焦于四个核心方法：req、get、post、form。内容涵盖：

• 方法签名与参数类型（url、params、data、options）
• 返回值结构与错误处理
• 请求前缀处理、参数自动转换（分页器、equals）、加密开关
• 响应处理、状态码映射与异常情况说明
• 与全局配置的集成方式与自定义选项
• 实际使用场景示例（GET 查询、POST 提交、表单上传）

项目结构

该模块以“工具类 + HTTP 封装”的方式组织，核心入口通过 index.js 暴露统一导出；HTTP 请求封装位于 src/https/TsHttpUtil.js，配合全局配置、存储、通用工具与加解密实现。

graph TB
subgraph "入口与导出"
IDX["index.js"]
end
subgraph "HTTP 封装层"
HTTP["TsHttpUtil.js<br/>req/get/post/form"]
end
subgraph "配置与存储"
CFG["TsGlobalConfig.js<br/>setConfig/getConfig"]
STO["TsStorage.js<br/>getUserToken/saveEncryptBody/getEncryptBody"]
end
subgraph "通用与加解密"
COM["TsCommon.js<br/>isEmpty/parseJSON 等"]
CRY["TsCrypto.js<br/>encrypt/decrypt"]
SM4["TsSM4.js<br/>SM4 实现"]
end
IDX --> HTTP
HTTP --> CFG
HTTP --> STO
HTTP --> COM
HTTP --> CRY
CRY --> 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

核心组件

• HTTP 封装与请求调度：req、get、post、form
• 全局配置：setConfig/getConfig，支持 prefix、onHttpError、httpParams、base64Key 等
• 存储与加密开关：getUserToken、saveEncryptBody/getEncryptBody
• 通用工具：isEmpty、parseJSON 等
• 加解密：基于 SM4 的 TsCrypto，内部使用 TsSM4

章节来源

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

架构总览

下图展示了从调用到响应的整体流程，包括请求前缀拼接、参数转换、加密开关、响应解密与错误处理。

sequenceDiagram
participant Caller as "调用方"
participant Http as "TsHttpUtil.req"
participant Ext as "umi-request.extend"
participant Cfg as "TsGlobalConfig"
participant Sto as "TsStorage"
participant Cph as "TsCrypto"
participant Com as "TsCommon"
Caller->>Http : "调用 req(url, options)"
Http->>Cfg : "读取 prefix/onHttpError/httpParams/base64Key"
Http->>Http : "拼接前缀 url = prefix + url"
Http->>Http : "dealParamsBody(params/data/equals/pagination)"
Http->>Sto : "读取 token"
Http->>Ext : "request(url, {headers : {token}, ...})"
Ext-->>Http : "Promise.then(res)"
Http->>Http : "根据 rawResponse/encrypt 判定"
Http->>Cph : "若 encrypt 则 decrypt 并 parseJSON"
Http-->>Caller : "resolve({data, recordsTotal}) 或 reject(res)"
Ext-->>Http : "Promise.catch(err)"
Http-->>Caller : "reject({code, message})"

图表来源

• TsHttpUtil.js:99-134
• TsHttpUtil.js:50-91
• TsGlobalConfig.js:19-29
• TsStorage.js:13-23
• TsCrypto.js:19-30
• TsCommon.js:34-44

详细组件分析

方法概览与签名

• req(url, options)
  • 参数
    • url: 字符串，可带查询参数
    • options: 对象，支持 method、params、data、headers、rawResponse、requestType 等
  • 返回
    • Promise，成功解析为 {data, recordsTotal}；失败解析为 {code, message}
• get(url, params = {}, options = {})
  • 参数
    • url: 字符串
    • params: 查询参数对象
    • options: 自定义选项
  • 返回
    • Promise，成功解析为 {data, recordsTotal}
• post(url, data = {}, options = {})
  • 参数
    • url: 字符串
    • data: 请求体对象
    • options: 自定义选项
  • 返回
    • Promise，成功解析为 {data, recordsTotal}
• form(url, data = {}, options = {})
  • 参数
    • url: 字符串
    • data: 表单数据
    • options: 自定义选项（requestType 默认为 form）
  • 返回
    • Promise，成功解析为 {data, recordsTotal}

章节来源

• TsHttpUtil.js:136-165
• TsHttpUtil.js:99-134

请求前缀处理

• 支持字符串或函数形式的 prefix
• 若 prefix 为函数，则以 url 作为入参计算前缀
• 最终拼接为 prefix + url

章节来源

• TsHttpUtil.js:100-106
• TsGlobalConfig.js:19-21

参数自动转换

• 分页器转换
  • 将 options.params.pagination 转换为 pageSize 和 pageNum，并删除 pagination
• equals 转换
  • 将 options.params.equals 对象转为逗号分隔的键值对字符串
• 额外参数注入
  • GET 请求：合并 GlobalConfig.httpParams 返回的对象到 params
  • 非 GET 且非 form：合并 GlobalConfig.httpParams 返回的对象到 data
• 加密开关
  • 当 Storage.getEncryptBody() 为真时，将 data 包裹为 {encryptData: 加密结果}，否则按原样透传

章节来源

• TsHttpUtil.js:50-91
• TsStorage.js:21-23

加密与解密

• 加密
  • 使用 TsCrypto.encrypt 对 data 进行 SM4 加密（ECB 模式），密钥来自 GlobalConfig.base64Key
• 解密
  • 若响应标记为加密（res.encrypt），则使用 TsCrypto.decrypt 解密，并尝试 parseJSON
• 密钥
  • base64Key 来源于 GlobalConfig，初始化时转换为字节数组

章节来源

• TsCrypto.js:5-31
• TsSM4.js:96-453
• TsHttpUtil.js:82-86
• TsHttpUtil.js:119-122

响应处理与错误映射

• 成功路径
  • 当 res.code === 200 时，提取 data；若 res.encrypt 为真，执行解密与 parseJSON
  • 返回 {data, recordsTotal}
• 失败路径
  • 调用 GlobalConfig.onHttpError(res)，并 reject(res)
• 异常路径
  • Promise.catch 捕获后，返回 {code: status, message: error}

章节来源

• TsHttpUtil.js:117-132
• TsHttpUtil.js:7-23
• TsGlobalConfig.js:8-12

请求头与认证

• 自动注入 token
  • 从 Storage.getUserToken() 读取并写入 headers.token
• 默认行为
  • credentials: include（携带 cookie）
  • requestType: json（用于 form 提交）

章节来源

• TsHttpUtil.js:109-112
• TsStorage.js:13-15
• TsHttpUtil.js:40-44

API 定义与使用示例

req(url, options)

• 功能：发起通用请求，支持 GET/POST 等方法与自定义选项
• 关键点
  • 自动拼接前缀、参数转换、加密开关、响应解密
  • 支持 rawResponse 直接返回原始响应
• 示例（路径）
  • TsHttpUtil.js:99-134

章节来源

• TsHttpUtil.js:99-134

get(url, params, options)

• 功能：发起 GET 请求
• 关键点
  • 自动合并 GlobalConfig.httpParams 到 params
  • 支持 equals 与 pagination 转换
• 示例（路径）
  • TsHttpUtil.js:142-144

章节来源

• TsHttpUtil.js:142-144

post(url, data, options)

• 功能：发起 POST 请求（JSON）
• 关键点
  • 非 form 时合并 GlobalConfig.httpParams 到 data
  • 可启用加密开关
• 示例（路径）
  • TsHttpUtil.js:152-154

章节来源

• TsHttpUtil.js:152-154

form(url, data, options)

• 功能：发起表单提交（POST）
• 关键点
  • requestType 设为 form，适合上传文件或表单数据
• 示例（路径）
  • TsHttpUtil.js:163-165

章节来源

• TsHttpUtil.js:163-165

错误处理与状态码映射

• 内置状态码映射（codeMessage）
  • 200、201、202、204、400、401、403、404、406、410、422、500、502、503、504
• errorHandler
  • 统一捕获 umi-request 抛出的错误，返回 {code, message}
• onHttpError
  • 在非 200 时触发，便于业务侧统一处理

章节来源

• TsHttpUtil.js:7-23
• TsHttpUtil.js:125
• TsGlobalConfig.js:8-12

与全局配置的集成

• setConfig(obj)
  • 合并 window.httpConfig 与默认配置
  • 支持字段：prefix、onHttpError、httpParams、base64Key
• getConfig()
  • 返回当前配置对象

章节来源

• TsGlobalConfig.js:19-29

自定义选项与扩展

• options 支持
  • method、params、data、headers、rawResponse、requestType
• 与 Storage 的交互
  • 读取/设置 token、加密开关
• 与 Common 的交互
  • isEmpty、parseJSON 等工具

章节来源

• TsHttpUtil.js:108-112
• TsStorage.js:13-23
• TsCommon.js:25-44

依赖关系分析

graph LR
A["TsHttpUtil.js"] --> B["TsGlobalConfig.js"]
A --> C["TsStorage.js"]
A --> D["TsCommon.js"]
A --> E["TsCrypto.js"]
E --> F["TsSM4.js"]
G["index.js"] --> A

图表来源

• TsHttpUtil.js:1-5
• index.js:1-6

章节来源

• TsHttpUtil.js:1-5
• index.js:1-6

性能考量

• 参数转换与加密
  • equals 与 pagination 转换为 O(n) 操作，通常开销较小
  • 加密/解密涉及 SM4 计算，建议仅在必要时开启加密开关
• 请求头与 cookies
  • credentials: include 会携带 Cookie，注意跨域与安全策略
• 响应处理
  • 解密与 parseJSON 仅在 res.encrypt 为真时执行，避免不必要的 CPU 开销

故障排查指南

• 常见问题
  • 未设置 token：headers.token 为空，可能导致鉴权失败
  • 加密开关未生效：确认 Storage.getEncryptBody() 返回 true
  • 前缀无效：prefix 为函数时需确保返回有效字符串
  • 参数未合并：GlobalConfig.httpParams 必须返回对象
• 排查步骤
  • 打印 options 与最终请求 URL，确认前缀拼接正确
  • 检查 params/data 是否经过 equals/pagination 转换
  • 观察响应是否包含 encrypt 字段，确认解密逻辑是否执行
  • 使用 rawResponse 查看原始响应，定位业务错误码与消息

章节来源

• TsHttpUtil.js:100-106
• TsHttpUtil.js:75-88
• TsHttpUtil.js:119-122
• TsStorage.js:13-23

结论

本模块提供了简洁一致的 HTTP 请求抽象，具备以下特性：

• 统一的请求前缀、参数转换与加密开关
• 明确的成功/失败响应结构与错误映射
• 与全局配置、存储、通用工具与加解密的深度集成
• 适用于 GET 查询、POST 提交与表单上传等多种场景

附录

API 完整签名与参数说明

• req(url, options)
  • url: 字符串
  • options.method: GET/POST 等
  • options.params: 查询参数对象
  • options.data: 请求体对象
  • options.headers: 自定义头部
  • options.rawResponse: 是否返回原始响应
  • options.requestType: json/form
• get(url, params = {}, options = {})
  • params: 查询参数对象（支持 equals、pagination）
• post(url, data = {}, options = {})
  • data: 请求体对象（支持 httpParams 注入与加密）
• form(url, data = {}, options = {})
  • data: 表单数据（requestType 默认为 form）

章节来源

• TsHttpUtil.js:136-165
• TsHttpUtil.js:99-134

使用示例（路径）

• GET 查询
  • TsHttpUtil.js:142-144
• POST 数据提交
  • TsHttpUtil.js:152-154
• 表单上传
  • TsHttpUtil.js:163-165
• 全局配置与加密
  • README.md:17-26
  • TsGlobalConfig.js:19-29
  • TsStorage.js:17-23