bt-request

一个基于 Axios 的轻量请求封装，内置参数签名、统一拦截、可选 Loading 与 Toast 回调，并提供 UMD 打包产物用于浏览器直接引入。

项目概览

• 核心类：HttpRequest，封装 GET/POST，统一处理请求/响应拦截与错误提示。
• 参数签名：请求体自动附加时间戳并按键名排序后计算 HMAC-SHA256 签名；签名通过请求头 s 传递。
• 打包：使用 Webpack 生成 dist/BtRequest.js 与 dist/BtRequest.min.js 两个 UMD 文件，库名为 bt-request（默认导出）。

目录结构

/                项目根
├─ index.js      主入口，转发到 src/index.js
├─ package.json  项目配置与脚本
├─ webpack.config.js 打包配置（UMD + 压缩）
├─ src/
│  ├─ index.js   HttpRequest 封装与拦截器
│  └─ sign.js    参数时间戳、排序与签名逻辑
└─ dist/
   ├─ BtRequest.js     UMD 未压缩版本
   └─ BtRequest.min.js UMD 压缩版本

安装与构建

• 安装依赖：
  • yarn
• 构建打包：
  • yarn build（等价于 webpack，输出到 dist/）

依赖要点：

• 运行时依赖：axios, crypto-js, lodash, qs
• 开发依赖：webpack, webpack-cli, terser-webpack-plugin

快速开始

在 Node/打包环境中使用

const HttpRequest = require('bt-request')

const request = new HttpRequest({
  baseURL: 'https://example.com',
  toast: (msg) => console.log('[toast]', msg),
})

request.setBaseInfo({
  uid: '123',
  token: 'token-xxx',
  fullResponseData: false, // true 返回后端完整响应体，false 仅返回 data 字段
})

// GET 示例
request
  .get('/api/ping', { q: 'hello' })
  .then((res) => console.log('GET res:', res))
  .catch((err) => console.error('GET err:', err))

// POST 示例
request
  .post('/api/user/register', {
    sid: 'session-xxx',
    timeZone: '480',
    country: 'CN',
    lang: 'CN',
    showLoading: true, // 影响内部 loading 行为标记
  })
  .then((res) => console.log('POST res:', res))
  .catch((err) => console.error('POST err:', err))

在浏览器中直接引入（UMD）

<script src="./dist/BtRequest.min.js"></script>
<script>
  const HttpRequest = window['bt-request']
  const client = new HttpRequest({ baseURL: '/api', toast: alert })
  client.setBaseInfo({ uid: 'u1' })
  client.get('/hello', { a: 1 }).then(console.log)
</script>

API 文档

new HttpRequest(config)

• config.baseURL：字符串，请求根路径，传入给 Axios.create({ baseURL })。
• config.toast：函数，错误或后端 message 提示回调（如 alert 或 UI Toast）。

setBaseInfo(baseInfo)

• 用途：设置/覆盖基础信息与行为开关。
• 行为：
  • fullResponseData（布尔）：为 true 时，Promise 解析为后端完整响应体；为 false 时解析为 response.data.data。
  • 其余 baseInfo 字段会被合并到请求头中（与签名一起发送）。

get(path, params, config?)

• 说明：发起 GET 请求，params 作为查询参数。
• 返回：Promise；解析规则见 setBaseInfo 的 fullResponseData。

post(path, params)

• 说明：发起 POST 请求，params 会参与签名并序列化为 JSON 字符串发送，同时签名通过请求头 s 传递。
• 特性：从 params 读取 showLoading 切换内部 Loading 标记。
• 返回：Promise；解析规则同上。

拦截器与返回约定

• 请求拦截：
  • 自动补齐 header['content-type']，默认 application/x-www-form-urlencoded。
  • 可根据 showLoading 控制 Loading 队列（当前占位，未实际触发 UI）。
• 响应拦截：
  • status 在 200..299 且 data.code === 0 视为成功；否则触发 toast(message) 或通用错误提示。
  • 网络错误统一提示 Network Error。
• 解析策略：
  • fullResponseData = true 时，返回 response.data。
  • 否则仅返回 response.data.data。

参数签名机制

• 时间戳：向请求体添加 t = 当前秒级时间戳。
• 排序：对所有键名按首字母 Unicode 递归比较排序（稳定且可复现）。
• 拼接：将 key=value 按排序结果拼接成字符串或使用 JSON 字符串。
• 签名：
  • 随机选取一个键空间：apple、grape、mango。
  • 使用各自的密钥对待签名字符串计算 HMAC-SHA256，并以大写十六进制形式返回：<key>|<HMAC>。
• 传输：签名通过请求头字段 s 发送；POST 请求体为 JSON 字符串。

提示：当前实现中 GET 请求未计算签名（头部 s 可能为空），如后端要求，可在 GET 分支补充签名逻辑。

打包与产物

• Webpack 配置关键点：
  • library: 'bt-request'、libraryExport: 'default'、libraryTarget: 'umd'。
  • 仅对 *.min.js 进行 Terser 压缩（include: /\.min\.js$/）。
• 产物：
  • dist/BtRequest.js（未压缩，便于调试）
  • dist/BtRequest.min.js（压缩版，适合生产）

常见问题

• 为什么返回的数据有时是完整响应，有时只有 data？
  • 由 baseInfo.fullResponseData 控制；设为 true 返回完整响应体。
• 我需要在浏览器里直接使用，应如何获取类？
  • UMD 通过全局变量 window['bt-request'] 暴露默认导出。
• GET 请求需要签名怎么办？
  • 目前 GET 分支未签名；可在 src/index.js 的 _formatAndSignData('GET', ...) 中接入 sign.js 逻辑。

许可证

• License：ISC（见 package.json）