terminaldesktop-http

基于 Axios 的 HTTP 请求封装库，提供统一的 requestApi 方法，支持三层三阶段配置合并、生命周期钩子和内置 Token 认证。

安装

npm install terminaldesktop-http

快速开始

const { requestApi, setLocalConfig, setAuthConfig } = require('terminaldesktop-http')

// 设置 Token 认证（内置机制，不受配置覆盖影响）
setAuthConfig({
  token: {
    getToken: () => localStorage.getItem('token'),
    setToken: (token) => localStorage.setItem('token', token)
  },
  refresh: {
    enabled: true,
    refreshToken: () => axios.post('/auth/refresh').then(r => r.data.token),
    isTokenExpired: (result) => result.responseData?.code === 401
  }
})

// 设置全局配置
setLocalConfig({
  request: {
    baseURL: 'https://api.example.com',
    timeout: 10000
  },
  response: {
    props: { codeName: 'code', dataName: 'data', messageName: 'message' }
  }
})

// 发送请求
requestApi({
  api: '/user/list',
  method: 'GET',
  success: (res) => console.log(res.data),
  fail: (err) => console.error(err.message)
})

API

requestApi(options)

核心请求方法，返回 Promise<requestResult>。

options 参数：

| 参数 | 类型 | 说明 | |------|------|------| | api | string | 请求地址（与 url 二选一） | | url | string | 请求地址（与 api 二选一） | | method | string | 请求方法，默认 'GET' | | data | object | 请求体数据 | | params | object | URL 查询参数 | | requestConfig | object | 覆盖/补充 request 层配置 | | responseConfig | object | 覆盖/补充 response 层配置 | | runtimeConfig | object | 覆盖/补充 runtime 层配置 | | success | function | 成功回调 | | fail | function | 失败回调 | | complete | function | 完成回调 | | exception | function | 异常回调 | | finally | function | 最终回调 |

返回 result：

{
  data: any,            // 业务数据
  message: string,      // 业务消息
  responseData: any,    // 原始响应数据
  response: any         // axios 响应对象
}

配置管理

| 方法 | 说明 | |------|------| | setLocalConfig(config) | 设置静态配置 | | getBaseConfig() | 获取内置默认配置 | | getLocalConfig() | 获取当前静态配置 | | getFinalConfig() | 获取合并后的最终配置 | | resetConfig() | 重置静态配置 |

Token 认证

| 方法 | 说明 | |------|------| | setAuthConfig(config) | 设置 Token 认证与自动刷新配置 |

setAuthConfig({
  token: {
    getToken: () => string | null,      // 获取当前 token
    setToken: (token) => void,           // 持久化新 token
    headerName: 'Authorization',         // 请求头字段名，默认 'Authorization'（仅在未提供 tokenInjector 时生效）
    headerType: 'Bearer',                // 前缀，默认 'Bearer'（仅在未提供 tokenInjector 时生效）
    tokenInjector: (token, requestConfig) => void  // 自定义注入函数，覆盖默认 header 方式
  },
  refresh: {
    enabled: false,                       // 是否启用自动刷新，默认 false
    refreshToken: () => Promise<string>,  // 刷新 token 的方法
    isTokenExpired: (result) => boolean,  // 判断响应是否表示 token 过期
    maxRetries: 1                         // 最大重试次数，默认 1
  }
})

// 示例：自定义注入到 URL 参数
setAuthConfig({
  token: {
    getToken: () => localStorage.getItem('token'),
    tokenInjector: (token, requestConfig) => {
      requestConfig.params = { ...requestConfig.params, token }
    }
  }
})

// 示例：自定义注入到 cookie
setAuthConfig({
  token: {
    getToken: () => localStorage.getItem('token'),
    tokenInjector: (token) => {
      document.cookie = `session=${token}; path=/`
    }
  }
})

配置合并规则

配置分为三种类型（requestConfig / responseConfig / runtimeConfig）和三个阶段（base < local < user），合并规则：

final = defaultsDeep(userConfig, localConfig, baseConfig)

每次调用 requestApi 时，通过 defaultsDeep 将三层配置按 user > local > base 优先级合并。

生命周期

before → axios 请求 → 响应解析 → success/fail → complete → finally
                                     ↓
                                  exception（请求异常时）

Token 认证在生命周期中的位置：

内置 Token 注入 → before 钩子 → axios 请求 → 响应解析 → 判断 Token 过期
                                                              ├─ 未过期 → success/fail
                                                              └─ 过期 → 刷新 Token → 重试请求

依赖

• axios ^1.x
• lodash ^4.x