@complex-suite/request 1.1.3

package/README.md

@@ -0,0 +1,198 @@
+# Complex Request
+
+这是一个功能强大且高度可扩展的 TypeScript 请求库，旨在通过分层、可组合的规则引擎，优雅地处理复杂的 Web 请求场景。
+
+## 核心特性
+
+- **分层架构**:
+  - **`BaseRequest`**: 抽象请求基类，负责驱动整个请求生命周期，包括 Token 处理、请求重试、错误捕获等。
+  - **`Rule`**: 可定制的规则引擎，将所有与具体业务相关的逻辑（如响应解析、登录/刷新流程）集中管理。
+  - **`Token`**: 封装单个 Token 的所有行为，包括值的获取、存储、附加到请求和生命周期管理。
+- **强大的 Token 管理**:
+  - 支持多个具名 `Token` 和一个 `refreshToken`。
+  - 支持从内存、`localStorage` 和 `sessionStorage` 中自动获取和缓存 Token。
+  - 可配置 Token 的有效期、存储位置（`header`, `body`, `params`）和附加键名。
+  - 自动化的登录和刷新流程，当 Token 失效时，可自动触发 `login` 或 `refresh` 操作，并无缝地重试原始请求。
+- **高度可定制**:
+  - **响应解析**: 可通过 `parse` 函数，将任何格式的服务器响应，适配为统一的 `{ status, data, ... }` 格式。
+  - **请求格式化**: 可通过 `format` 函数，在请求发送前，对请求参数进行最后一次修改。
+  - **底层实现无关**: `BaseRequest` 是一个抽象类，您可以继承它，并使用任何底层的请求库（如 `axios`, `fetch`）来实现 `$request` 方法。
+- **数据格式转换**:
+  - 支持在 `json` 和 `form-data` 之间自动转换请求数据。
+
+## 安装
+
+```bash
+npm install complex-request
+```
+
+## 快速开始
+
+下面是一个使用 `fetch` 作为底层实现的简单示例：
+
+```typescript
+import { BaseRequest, Rule, Token } from 'complex-request';
+
+// 1. 创建一个继承自 BaseRequest 的具体请求类
+//    我们在这里为泛型 R (原始响应) 和 L (本地配置) 提供了具体的类型
+class MyRequest extends BaseRequest<any, { signal?: AbortSignal }> {
+  $request(requestConfig) {
+    // 使用 fetch 实现底层的请求逻辑
+    const { url, method, headers, data, params, local } = requestConfig;
+    const finalUrl = new URL(url);
+    Object.keys(params).forEach(key => finalUrl.searchParams.append(key, params[key]));
+
+    return fetch(finalUrl.toString(), {
+      method,
+      headers,
+      body: data,
+      signal: local?.signal // 传递 AbortSignal 以便取消请求
+    }).then(res => res.json());
+  }
+
+  $parseError(error) {
+    // 解析 fetch 抛出的错误
+    return { type: 'internal', msg: error.message, data: error };
+  }
+}
+
+// 2. 定义一套规则
+const myRule = new Rule({
+  prop: 'api',
+  token: {
+    data: {
+      // 定义一个名为 'accessToken' 的 Token
+      accessToken: {
+        location: 'header', // 存储在 Header 中
+        require: true // 这是一个必需的 Token
+      }
+    }
+  },
+  parse: (response) => {
+    // 解析服务器响应
+    if (response.code === 200) {
+      return { status: 'success', data: response.data };
+    } else if (response.code === 401) {
+      return { status: 'login', data: null, msg: '请先登录' };
+    } else {
+      return { status: 'fail', data: null, msg: response.message };
+    }
+  },
+  login: () => {
+    // 定义登录逻辑
+    return new Promise(resolve => {
+      // ... 执行登录操作，例如弹出一个登录框
+      // ... 登录成功后，使用 setToken 设置新的 Token
+      myRequest.setToken('accessToken', 'new-token-from-server');
+      resolve();
+    });
+  }
+});
+
+// 3. 实例化请求对象
+const myRequest = new MyRequest({
+  baseUrl: 'https://api.example.com',
+  rule: myRule
+});
+
+// 4. 发送请求
+// 4. 发送请求，并传递一个本地配置
+const controller = new AbortController();
+myRequest.get({
+  url: '/user/profile',
+  local: { signal: controller.signal } 
+})
+  .then(response => {
+    console.log('用户信息:', response.data);
+  })
+  .catch(error => {
+    console.error('请求失败:', error);
+  });
+
+// 可以在需要时取消请求
+// controller.abort();
+```
+
+## 高级用法：泛型类型
+
+`complex-request` 大量使用泛型来提供强大的类型安全。理解 `R` 和 `L` 这两个核心泛型，能帮助您更好地利用这个库。
+
+### `R` - 原始响应 (`Raw Response`)
+
+`R` 代表的是底层请求工具（如 `fetch`, `axios`）直接返回的、**未经 `rule.parse` 解析**的原始响应数据的类型。
+
+在 `Rule` 的 `parse` 函数中，`response` 参数的类型就是 `R`。
+
+```typescript
+// 假设服务器返回的数据结构是 { code: number, data: T, message: string }
+type ServerResponse<T> = {
+  code: number;
+  data: T;
+  message: string;
+}
+
+// 在定义 Rule 时，我们可以将 R 指定为 ServerResponse<any>
+const myRule = new Rule<ServerResponse<any>>({
+  // ...
+  parse: (response) => { // 在这里，`response` 的类型就是 ServerResponse<any>
+    if (response.code === 200) {
+      return { status: 'success', data: response.data };
+    }
+    // ...
+  }
+});
+```
+
+### `L` - 本地配置 (`Local Config`)
+
+`L` 代表的是一个可选的、用于传递给底层请求工具的、**特定于实现的**配置对象的类型。
+
+这非常有用，因为不同的底层请求库（`fetch`, `axios`）有它们自己独特的配置选项（例如，`axios` 的 `cancelToken`，`fetch` 的 `signal`）。`L` 允许您以类型安全的方式，将这些特定于实现的配置，一路传递到您自己实现的 `$request` 方法中。
+
+在上面的“快速开始”示例中，我们通过 `L` 泛型，为 `fetch` 实现了一个请求取消的功能。
+
+### `parse` 函数：请求的“交通警察”
+
+`parse` 函数是 `complex-request` 库的**核心**。它就像一个交通警察，负责检查每一个从服务器返回的原始响应 (`R`)，并根据您定义的业务逻辑，告诉 `BaseRequest` 下一步应该做什么。
+
+`parse` 函数必须返回一个 `responseType` 对象，其 `status` 字段决定了整个请求的走向：
+
+```typescript
+interface responseType<D = any> {
+  status: 'success' | 'fail' | 'login' | 'refresh'
+  data: D
+  code?: number | string
+  msg?: string
+}
+```
+
+下面是 `BaseRequest` 对每种 `status` 的处理方式：
+
+-   **`'success'`**: **请求成功**
+    -   **含义**: 服务器成功处理了请求，且响应数据是有效的。
+    -   **`BaseRequest` 的行为**: `request` 方法返回的 Promise 将被 **resolve**，并将 `data` 字段作为结果传递下去。
+
+-   **`'fail'`**: **请求失败**
+    -   **含义**: 服务器返回了一个业务逻辑上的错误（例如，表单验证失败、权限不足等）。
+    -   **`BaseRequest` 的行为**: `request` 方法返回的 Promise 将被 **reject**，并将整个 `responseType` 对象作为错误信息传递下去。
+
+-   **`'login'`**: **需要登录**
+    -   **含义**: 用户的会话已完全失效，必须重新登录。
+    -   **`BaseRequest` 的行为**:
+        1.  自动触发您在 `Rule` 中定义的 `login` 函数。
+        2.  在 `login` 函数成功执行后（即其返回的 Promise 被 resolve），`BaseRequest` 会**自动重新发送**之前失败的那个请求。
+        3.  整个过程对最终的调用者是**完全透明的**。
+
+-   **`'refresh'`**: **需要刷新 Token**
+    -   **含义**: 用户的访问令牌（Access Token）已过期，但刷新令牌（Refresh Token）仍然有效。
+    -   **`BaseRequest` 的行为**:
+        1.  自动触发您在 `Rule` 中定义的 `refresh` 函数。
+        2.  在 `refresh` 函数成功执行后，`BaseRequest` 会**自动重新发送**之前失败的那个请求。
+        3.  如果 `refresh` 本身也失败了，或者刷新后重试的请求依然返回 `'refresh'`，`BaseRequest` 会自动将流程降级为 `'login'`。
+
+通过精心设计您的 `parse` 函数，您可以以一种非常优雅和集中的方式，实现极其复杂的认证和重试逻辑。
+
+## 依赖
+
+- [complex-utils](https://github.com/MarAngle/complex-utils): 提供核心的工具函数和基类。
+- [complex-plugin](https://github.com/MarAngle/complex-plugin): 提供 `notice` 通知插件。

package/history.md

@@ -0,0 +1,88 @@
+### 1.1.2 - 1.1.3
+- refactor: 将TypeScript类型导入语法升级为type关键字形式
+
+### 1.1.1
+- refactor(build): 移除项目的所有构建配置，回归到纯源码模式。
+- feat(test): 集成 `Vitest` 单元测试框架。
+- docs(readme): 创建详细的 `README.md` 文件。
+- chore(history): 全面优化和重构 `history.md` 的格式。
+
+### 1.0.1
+- feat(module): 修改模块加载逻辑为 ES2020。
+
+### 0.6.2
+- refactor(code): 基于 AI 进行全局代码优化。
+
+### 0.6.1
+- chore: 稳定版升级。
+
+### 0.5.10
+- chore(deps): 升级 `complex-plugin` 依赖并优化逻辑。
+
+### 0.5.7
+- refactor(request)!: **[非兼容性更新]** `failNotice` 重命名为 `fail`，`failNotice.local` 重命名为 `fail.intercept`。
+- refactor(request): 优化 `$parseError` 返回的 `type` 类型。
+- refactor(request): 将 `config` 配置项迁移到类的静态数据中。
+
+### 0.5.5
+- refactor(types): 优化泛型类型传递。
+
+### 0.5.4
+- feat(token): 实现 `refreshToken` 的数据持久化保存。
+
+### 0.5.3
+- feat(request): 实现完整的 `login` -> `refresh` -> `retry` 流程。
+  - `rule.login` 添加 `trigger` 参数，用于判断登录的触发来源。
+  - `responseType.status` 添加 `refresh` 状态，用于触发 `rule.refresh`。
+  - 当 `refresh` 失败或再次触发 `refresh` 时，自动降级为 `login`。
+
+### 0.5.1
+- chore(deps): 升级 `complex-plugin` 依赖。
+
+### 0.4.7
+- chore(deps): 升级 `complex-plugin` 依赖。
+
+### 0.4.3
+- refactor(rule)!: **[非兼容性更新]** `BaseRequest` 的 `rule` 简化为单选，以简化逻辑。
+
+### 0.3.6
+- refactor(code): 优化全局的 `undefined` 校验逻辑。
+
+### 0.3.5
+- refactor(rule)!: **[非兼容性更新]** `responseFormat` 重命名为 `responseParse`。
+- refactor(rule)!: **[非兼容性更新]** `Rule` 的 `format` 函数重命名为 `parse`，并新增 `format` 函数用于请求前的格式化。
+
+### 0.3.4
+- chore(deps): 依赖大版本升级。
+
+### 0.2.1
+- refactor(types): 为 `local` 参数实现泛型类型。
+
+### 0.2.0
+- refactor(code): 统一函数命名规则 (外部函数、内部函数、私有函数)。
+
+### 0.1.10
+- chore(deps): 升级依赖，适配 `formatConfig`。
+
+### 0.1.9
+- fix(request): 修正 `requestConfig.data` 被重置为空对象的 BUG。
+- feat(types): 扩展 `BaseRequest` 为泛型类，允许定义最终的响应类型。
+
+### 0.1.8
+- refactor(request)!: **[非兼容性更新]** `Request` 类重命名为 `BaseRequest`。
+- fix(request): 修正 `post/get/form/json` 未正确设置 `method` 的 BUG。
+- chore(deps): 升级依赖。
+
+### 0.1.7
+- fix(deps): 修正错误的依赖项。
+
+### 0.1.6
+- refactor(request): 优化请求参数和失败错误处理。
+- feat(request): 扩展失败信息提示。
+
+### 0.1.2
+- feat(request): 扩展支持的 HTTP 状态码错误信息。
+- refactor(code): 优化函数和类型定义。
+
+### 0.1.1
+- feat: 项目初始化，实现基础的请求功能。

package/index.ts

@@ -0,0 +1,12 @@
+import BaseRequest, { type RequestConfig, type RequestInitOption, type requestTrigger } from './src/BaseRequest'
+import Rule from './src/Rule'
+import Token from './src/Token'
+
+export {
+  BaseRequest,
+  type RequestConfig,
+  type RequestInitOption,
+  type requestTrigger,
+  Rule,
+  Token
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@complex-suite/request",
+  "version": "1.1.3",
+  "description": "a complex request",
+  "type": "module",
+  "main": "index.ts",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MarAngle/complex-request.git"
+  },
+  "dependencies": {
+    "@complex-suite/utils": "2.10.5",
+    "@complex-suite/plugin": "4.10.2"
+  },
+  "devDependencies": {
+    "jsdom": "^27.1.0",
+    "typescript": "^5.2.2",
+    "vitest": "^4.0.7"
+  },
+  "keywords": [
+    "complex",
+    "ajax",
+    "fetch",
+    "require",
+    "request"
+  ],
+  "author": "MarAngle",
+  "license": "ISC",
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "vitest",
+    "coverage": "vitest run --coverage",
+    "release": "npm publish --registry=https://registry.npmjs.org"
+  }
+}

package/src/BaseRequest.ts

@@ -0,0 +1,333 @@
+import { _Data, jsonToForm } from "@complex-suite/utils"
+import { notice } from "@complex-suite/plugin"
+import type { messageType } from "@complex-suite/plugin"
+import Rule from "./Rule"
+import type { RuleInitOption, responseType } from "./Rule"
+
+type statusType = {
+  [prop: number]: string
+}
+
+export type formatUrlType = (url: string) => string
+
+export interface RequestInitOption<R = Record<PropertyKey, unknown>, L = Record<PropertyKey, unknown>> {
+  baseUrl?: string
+  status?: statusType
+  formatUrl?: formatUrlType
+  rule: RuleInitOption<R, L>
+}
+
+export type methodType = 'get' | 'post' | 'delete' | 'put' | 'patch' | 'head' | 'options'
+
+export type failType = 'internal' | 'server'
+
+export type totalFailType = 'token' | failType
+
+export type failOption = {
+  intercept?: totalFailType[] // 内部报错判断值
+  content?: string
+  duration?: number
+  type?: messageType
+  title?: string
+}
+
+const defaultFormatUrlWithBaseUrl = function(this: BaseRequest, url: string) {
+  if (!url.startsWith('https://') && !url.startsWith('http://')) {
+    // 当前URL不以http/https开始，则认为此URL需要添加默认前缀
+    url = this.baseUrl + url
+  }
+  return url
+}
+
+const defaultFormatUrl = function(url: string) {
+  return url
+}
+
+export type requestTrigger = 'login' | 'refresh'
+
+export interface RequestConfig<_R = Record<PropertyKey, unknown>, L = Record<PropertyKey, unknown>> {
+  url: string // 请求地址
+  method: methodType // 请求方式
+  headers: Record<string, undefined | null | string | number | boolean> // Header头
+  data: Record<PropertyKey, unknown> | FormData // Body体
+  params: Record<PropertyKey, unknown> // query数据
+  token: boolean | string[] // Token
+  format?: (finalConfig: L, trigger?: requestTrigger) => unknown // 对最终的数据做格式化处理，此数据为对应请求插件的参数而非Request的参数
+  currentType: 'json' | 'form' // 当前数据类型
+  targetType?: 'json' | 'form' // 目标数据类型=>初始化参数，后期无效
+  responseType: 'json' | 'text' | 'blob' // 返回值类型，仅json进行格式化
+  responseParse: boolean // 返回值解析判断，为否不解析
+  fail: false | failOption
+  local?: L // 请求插件的单独参数
+}
+
+abstract class BaseRequest<R = Record<PropertyKey, unknown>, L = Record<PropertyKey, unknown>> extends _Data {
+  static $name = 'BaseRequest'
+  static $formatConfig = { name: 'Request:BaseRequest', level: 5, recommend: false }
+  static $status = {
+    400: '错误请求！',
+    403: '拒绝访问！',
+    404: '很抱歉，资源未找到！',
+    405: '请求方法不支持！',
+    408: '请求超时！',
+    410: '请求资源已删除！',
+    500: '服务器内部错误！',
+    502: '错误网关！',
+    503: '服务不可用！',
+    504: '网关超时！',
+    505: 'HTTP版本不受支持！'
+  }
+  static $contentType = {
+    json: undefined,
+    form: 'multipart/form-data'
+  }
+  static $fail = {
+    message: {
+      internal: '请求终止，请求发送失败！',
+      server: '服务器请求失败，请刷新重试或联系管理员！'
+    } as Record<totalFailType, undefined | string>,
+    option: {
+      token: {
+        type: 'error',
+        title: 'Token错误'
+      },
+      internal: {
+        type: 'error',
+        title: '请求错误'
+      },
+      server: {
+        type: 'error',
+        title: '请求失败'
+      },
+    } as Record<totalFailType, failOption>
+  }
+  baseUrl?: string
+  isLogining?: Promise<any>
+  isRefreshing?: Promise<any>
+  status: statusType
+  formatUrl: formatUrlType
+  rule: Rule<R, L>
+  constructor(initOption: RequestInitOption<R, L>) {
+    super()
+    this.baseUrl = initOption.baseUrl
+    this.status = {
+      ...(this.constructor as typeof BaseRequest).$status,
+      ...initOption.status
+    }
+    this.formatUrl = this._getFormatUrl(initOption.formatUrl)
+    this.rule = new Rule(initOption.rule)
+  }
+  protected _getFormatUrl(formatUrl?: formatUrlType) {
+    if (formatUrl) {
+      return formatUrl
+    } else if (this.baseUrl) {
+      return defaultFormatUrlWithBaseUrl
+    } else {
+      return defaultFormatUrl
+    }
+  }
+  protected _syncFormatUrl() {
+    // 当前格式化URL函数为默认函数时则进行重新获取操作
+    if (this.formatUrl === defaultFormatUrlWithBaseUrl || this.formatUrl === defaultFormatUrl) {
+      this.formatUrl = this._getFormatUrl()
+    }
+  }
+  changeBaseUrl(baseUrl: string) {
+    this.baseUrl = baseUrl || ''
+    this._syncFormatUrl()
+  }
+  protected _parseRequestConfig(requestConfig: Partial<RequestConfig<R, L>>): RequestConfig<R, L> {
+    requestConfig.url = this.formatUrl(requestConfig.url!)
+    if (!requestConfig.method) {
+      requestConfig.method = 'get'
+    }
+    const targetType = requestConfig.targetType || 'json'
+    if (requestConfig.currentType == undefined) {
+      requestConfig.currentType = 'json'
+    }
+    const $contentType = (this.constructor as typeof BaseRequest).$contentType
+    const defaultContentType = targetType === 'json' ? $contentType.json : $contentType.form
+    if (!requestConfig.headers) {
+      requestConfig.headers = defaultContentType != undefined ? {
+        'Content-Type': defaultContentType
+      } : {}
+    } else if (requestConfig.headers['Content-Type'] == undefined && defaultContentType != undefined) {
+      requestConfig.headers['Content-Type'] = defaultContentType
+    }
+    if (!requestConfig.data) {
+      requestConfig.data = targetType === 'form' ? new FormData() : {}
+    } else if (requestConfig.currentType !== targetType) {
+      if (requestConfig.currentType === 'json') {
+        requestConfig.data = jsonToForm(requestConfig.data)
+      } else {
+        const data: Record<PropertyKey, unknown> = {};
+        (requestConfig.data as FormData).forEach((value, key) => {
+          (data as Record<PropertyKey, unknown>)[key] = value
+        })
+        requestConfig.data = data
+      }
+    }
+    requestConfig.currentType = targetType
+    if (requestConfig.token == undefined) {
+      requestConfig.token = true
+    }
+    if (!requestConfig.params) {
+      requestConfig.params = {}
+    }
+    if (requestConfig.responseType == undefined) {
+      requestConfig.responseType = 'json'
+    }
+    if (requestConfig.responseParse == undefined) {
+      requestConfig.responseParse = true
+    }
+    if (requestConfig.fail == undefined) {
+      requestConfig.fail = {}
+    }
+    return requestConfig as RequestConfig<R, L>
+  }
+  request(requestConfig: Partial<RequestConfig<R, L>>) {
+    return this._request(this._parseRequestConfig(requestConfig))
+  }
+  protected _showFail(fail: false | failOption, from: totalFailType, msg?: string) {
+    if (fail !== false) {
+      if (fail.intercept && fail.intercept.indexOf(from) > -1) {
+        // 存在拦截时判断类型在拦截范围内直接返回不输出错误信息
+        return
+      }
+      const content = fail.content || msg
+      if (content) {
+        const $failOption = (this.constructor as typeof BaseRequest).$fail.option[from]
+        notice.message(content, fail.type || $failOption.type, fail.title || $failOption.title, fail.duration || $failOption.duration)
+      }
+    }
+  }
+  protected _request(requestConfig: RequestConfig<R, L>, trigger?: requestTrigger): Promise<responseType> {
+    const res = this.rule.$appendToken(requestConfig)
+    if (res) {
+      if (res.token) {
+        // 存在Token规则但是不存在值，需要调用login接口
+        // 此处不应判断是否为重复操作
+        return this._handleTokenLogin(requestConfig)
+      } else {
+        const msg = `${res.prop}对应的Token规则不存在！`
+        this.$exportMsg(msg)
+        this._showFail(requestConfig.fail, 'token', msg)
+        return Promise.reject({ status: 'fail', code: 'token absent' })
+      }
+    }
+    return this._handleRequest(requestConfig, trigger)
+  }
+  private _handleTokenLogin(requestConfig: RequestConfig<R, L>): Promise<responseType> {
+    return new Promise((resolve, reject) => {
+      this.rule.login('token').then(() => {
+        this._request(requestConfig, 'login').then(resolve).catch(reject)
+      }).catch(reject)
+    })
+  }
+  private _handleRequest(requestConfig: RequestConfig<R, L>, trigger?: requestTrigger): Promise<responseType> {
+    return new Promise((resolve, reject) => {
+      this.$request(requestConfig, trigger).then(response => {
+        if (requestConfig.responseParse && requestConfig.responseType === 'json') {
+          const finalResponse = this.rule.parse(response, requestConfig)
+          if (finalResponse.status === 'success') {
+            resolve(finalResponse)
+          } else if (finalResponse.status === 'refresh') {
+            if (this.rule.refresh && trigger !== 'refresh') {
+              // 当前请求提示login说明请求前的token验证通过
+              // 此时在第一次需要登陆时进行this.rule.refresh的操作，进行可能的刷新Token机制
+              // 此刷新机制失败则触发登录
+              // 如登录后依然需要登录则按照失败处理(此处的登录可能是由本地token验证失败触发的登录)
+              if (!this.isRefreshing) {
+                this.isRefreshing = this.rule.refresh()
+              }
+              this.isRefreshing.then(() => {
+                this._request(requestConfig, 'refresh').then(resolve).catch(reject).finally(() => {
+                  this.isRefreshing = undefined
+                })
+              }).catch(reject)
+            } else if (trigger !== 'login') {
+              if (!this.isLogining) {
+                this.isLogining = this.rule.login('refresh')
+              }
+              this.isLogining.then(() => {
+                this._request(requestConfig, 'login').then(resolve).catch(reject).finally(() => {
+                  this.isLogining = undefined
+                })
+              }).catch(reject)
+            } else {
+              reject(finalResponse)
+            }
+          } else if (finalResponse.status === 'login') {
+            if (!this.isLogining) {
+              this.isLogining = this.rule.login('login')
+            }
+            this.isLogining.then(() => {
+              this._request(requestConfig, 'login').then(resolve).catch(reject).finally(() => {
+                this.isLogining = undefined
+              })
+            }).catch(reject)
+          } else if (finalResponse.status === 'fail') {
+            this._showFail(requestConfig.fail, 'server', finalResponse.msg)
+            reject(finalResponse)
+          }
+        } else {
+          resolve({ status: 'success', code: 'origin', data: response })
+        }
+      }).catch(error => {
+        const err = this.$parseError(error)
+        const $failOption = (this.constructor as typeof BaseRequest).$fail
+        this._showFail(requestConfig.fail, err.type, err.msg || $failOption.message[err.type])
+        reject({ status: 'fail', code: err.type + ' error', err: error })
+      })
+    })
+  }
+  // 重要: requestConfig需要深拷贝到具体实例中而非直接引用，此处保证在login/refresh时的requestConfig保持一致
+  abstract $request(requestConfig: RequestConfig<R, L>, from?: requestTrigger): Promise<R>
+  abstract $parseError(responseError: unknown): { msg?: string, type: failType, data: unknown }
+  get(requestConfig: Partial<RequestConfig<R, L>>) {
+    requestConfig.method = 'get'
+    return this.request(requestConfig)
+  }
+  post(requestConfig: Partial<RequestConfig<R, L>>) {
+    requestConfig.method = 'post'
+    return this.request(requestConfig)
+  }
+  form(requestConfig: Partial<RequestConfig<R, L>>) {
+    requestConfig.method = 'post'
+    requestConfig.currentType = 'form'
+    requestConfig.targetType = 'form'
+    return this.request(requestConfig)
+  }
+  json(requestConfig: Partial<RequestConfig<R, L>>) {
+    requestConfig.method = 'post'
+    requestConfig.currentType = 'json'
+    requestConfig.targetType = 'form'
+    return this.request(requestConfig)
+  }
+  setToken(tokenName: string, value: unknown, unSave?: boolean) {
+    this.rule.setToken(tokenName, value, unSave)
+  }
+  getToken(tokenName: string) {
+    return this.rule.getToken(tokenName)
+  }
+  clearToken(tokenName: string | true) {
+    return this.rule.clearToken(tokenName)
+  }
+  destroyToken(tokenName: string | true) {
+    return this.rule.destroyToken(tokenName)
+  }
+  setRefreshToken(value: unknown, unSave?: boolean) {
+    this.rule.setRefreshToken(value, unSave)
+  }
+  getRefreshToken() {
+    return this.rule.getRefreshToken()
+  }
+  clearRefreshToken() {
+    return this.rule.clearRefreshToken()
+  }
+  destroyRefreshToken() {
+    return this.rule.destroyRefreshToken()
+  }
+}
+
+export default BaseRequest

package/src/Rule.ts

@@ -0,0 +1,186 @@
+import { _Data } from "@complex-suite/utils"
+import Token from "./Token"
+import type { TokenInitOption } from "./Token"
+import type { RequestConfig } from "./BaseRequest"
+
+export type tokenType = {
+  time?: number
+  session?: boolean
+  data?: Record<string, TokenInitOption>
+  refreshToken?: TokenInitOption
+}
+
+export interface responseType<D = any> {
+  status: 'success' | 'fail' | 'login' | 'refresh'
+  data: D
+  code?: number | string
+  msg?: string
+  err?: string | Error | Record<PropertyKey, unknown>
+}
+
+type formatType<R = Record<PropertyKey, unknown>, L = Record<PropertyKey, unknown>> = (requestConfig: RequestConfig<R, L>) => void
+type parseType<R = Record<PropertyKey, unknown>, L = Record<PropertyKey, unknown>> = (response: R, requestConfig: RequestConfig<R, L>) => responseType
+type formatUrlType = (url: string) => string
+type loginType = (trigger: 'token' | 'refresh' | 'login') => Promise<unknown>
+type refreshType = () => Promise<unknown>
+
+export interface RuleInitOption<R = Record<PropertyKey, unknown>, L = Record<PropertyKey, unknown>> {
+  prop: string
+  token?: tokenType
+  format?: formatType<R, L> // 跟登录无关的参数在这里进行赋值，避免token过多导致的token失效后的连锁反应，注意此时的requestConfig已经经过了token的判断，data可能为formdata
+  parse: parseType<R, L> // 格式化返回参数
+  login: loginType // 登录操作，触发于token本地验证失败时\接口login\接口refresh成功后重新调用依然需要refresh时
+  refresh: refreshType // 刷新操作，触发于请求提示refresh时
+  formatUrl?: formatUrlType // 格式化对应URL
+}
+
+function defaultFormatUrl(url: string) {
+  return url
+}
+
+class Rule<R = Record<PropertyKey, unknown>, L = Record<PropertyKey, unknown>> extends _Data{
+  static $name = 'Rule'
+  static $formatConfig = { name: 'Request:Rule', level: 5, recommend: false }
+  prop: string
+  token: Record<string, Token>
+  refreshToken?: Token
+  format?: formatType<R, L>
+  parse: parseType<R, L>
+  login: loginType
+  refresh: refreshType
+  formatUrl: formatUrlType
+  constructor(initOption: RuleInitOption<R, L>) {
+    super()
+    this.prop = initOption.prop
+    this.token = {}
+    if (initOption.token) {
+      if (initOption.token.data) {
+        for (const tokenName in initOption.token.data) {
+          this.token[tokenName] = new Token(initOption.token.data[tokenName], tokenName, this.prop, initOption.token.time, initOption.token.session)
+        }
+      }
+      if (initOption.token.refreshToken) {
+        this.refreshToken = new Token(initOption.token.refreshToken, 'refreshToken', this.prop, initOption.token.time, initOption.token.session)
+      }
+    }
+    this.format = initOption.format
+    this.parse = initOption.parse
+    this.login = initOption.login
+    this.refresh = initOption.refresh
+    this.formatUrl = initOption.formatUrl || defaultFormatUrl
+  }
+  $appendToken(requestConfig: RequestConfig<R, L>) {
+    const tokenList = requestConfig.token === true ? Object.keys(this.token) : requestConfig.token
+    if (tokenList) {
+      for (const tokenName of tokenList) {
+        const token = this.token[tokenName]
+        if (token) {
+          if (!token.$appendValue(requestConfig, tokenName)) {
+            return { prop: tokenName, token: true, value: false }
+          }
+        } else {
+          return { prop: tokenName, token: false }
+        }
+      }
+    }
+    if (this.format) {
+      this.format(requestConfig)
+    }
+    return
+  }
+  setToken(tokenName: string, value: unknown, unSave?: boolean) {
+    if (this.token[tokenName]) {
+      this.token[tokenName].setValue(value, unSave)
+    } else {
+      this.$exportMsg(`未找到${tokenName}对应的Token规则,setToken失败！`, 'error')
+    }
+  }
+  getToken (tokenName: string) {
+    if (this.token[tokenName]) {
+      return this.token[tokenName].getValue()
+    } else {
+      this.$exportMsg(`未找到${tokenName}对应的Token规则,getToken失败！`, 'error')
+    }
+  }
+  setRefreshToken(value: unknown, unSave?: boolean) {
+    if (this.refreshToken) {
+      this.refreshToken.setValue(value, unSave)
+    } else {
+      this.$exportMsg(`未找到refreshToken对应的Token规则,setRefreshToken失败！`, 'error')
+    }
+  }
+  getRefreshToken() {
+    if (this.refreshToken) {
+      return this.refreshToken.getValue()
+    } else {
+      this.$exportMsg(`未找到refreshToken对应的Token规则,getRefreshToken失败！`, 'error')
+    }
+  }
+  clearRefreshToken() {
+    if (this.refreshToken) {
+      this.refreshToken.clear()
+    }
+  }
+  destroyRefreshToken() {
+    if (this.refreshToken) {
+      this.refreshToken.destroy()
+      delete this.refreshToken
+    }
+  }
+  protected _clearToken(tokenName: string) {
+    if (this.token[tokenName]) {
+      this.token[tokenName].clear()
+      return true
+    } else {
+      this.$exportMsg(`未找到${tokenName}对应的token规则,clearToken失败！`, 'warn')
+      return false
+    }
+  }
+  protected _destroyToken(tokenName: string) {
+    if (this.token[tokenName]) {
+      this.token[tokenName].destroy()
+      delete this.token[tokenName]
+      return true
+    } else {
+      this.$exportMsg(`未找到${tokenName}对应的token规则,destroyToken失败！`, 'warn')
+      return false
+    }
+  }
+  clearToken(tokenName: true | string) {
+    if (tokenName) {
+      if (tokenName === true) {
+        for (const n in this.token) {
+          this._clearToken(n)
+        }
+        this.clearRefreshToken()
+        return true
+      } else {
+        return this._clearToken(tokenName)
+      }
+    } else {
+      this.$exportMsg(`未指定需要清除的token！`)
+      return false
+    }
+  }
+  destroyToken(tokenName: true | string) {
+    if (tokenName) {
+      if (tokenName === true) {
+        for (const n in this.token) {
+          this._destroyToken(n)
+        }
+        this.destroyRefreshToken()
+        return true
+      } else {
+        return this._destroyToken(tokenName)
+      }
+    } else {
+      this.$exportMsg(`未指定需要销毁的token！`)
+      return false
+    }
+  }
+  _getName() {
+    return `${this._getConstructorName()}:${this.prop}`
+  }
+}
+
+export default Rule

package/src/Token.test.ts

@@ -0,0 +1,47 @@
+import { describe, it, expect } from 'vitest';
+import Token from './Token';
+
+describe('Token', () => {
+  it('should be instantiated correctly with default values', () => {
+    const token = new Token({}, 'testToken', 'testRule');
+    expect(token).toBeInstanceOf(Token);
+    expect(token.location).toBe('body');
+    expect(token.require).toBeUndefined();
+  });
+
+  it('should store and retrieve a value from memory', () => {
+    const token = new Token({ value: 'my-secret-token' }, 'testToken', 'testRule');
+    expect(token.getValue()).toBe('my-secret-token');
+  });
+
+  it('should respect the require flag', () => {
+    const requiredToken = new Token({ require: true }, 'requiredToken', 'testRule');
+    const optionalToken = new Token({ require: false }, 'optionalToken', 'testRule');
+
+    expect(requiredToken.$checkValue(undefined)).toBe(false);
+    expect(requiredToken.$checkValue(null)).toBe(false);
+    expect(requiredToken.$checkValue('some-value')).toBe(true);
+    
+    expect(optionalToken.$checkValue(undefined)).toBe(true);
+  });
+
+  it('should append value to the correct location', () => {
+    const headerToken = new Token({ value: 'header-val', location: 'header' }, 'hToken', 'testRule');
+    const bodyToken = new Token({ value: 'body-val', location: 'body' }, 'bToken', 'testRule');
+    const paramsToken = new Token({ value: 'params-val', location: 'params' }, 'pToken', 'testRule');
+
+    const config = {
+      headers: {},
+      data: {},
+      params: {}
+    };
+
+    headerToken.$appendValue(config as any, 'Authorization');
+    bodyToken.$appendValue(config as any, 'token');
+    paramsToken.$appendValue(config as any, 'api_key');
+
+    expect(config.headers).toEqual({ 'Authorization': 'header-val' });
+    expect(config.data).toEqual({ 'token': 'body-val' });
+    expect(config.params).toEqual({ 'api_key': 'params-val' });
+  });
+});

package/src/Token.ts

@@ -0,0 +1,174 @@
+import { isExist, storage, appendProp } from '@complex-suite/utils'
+import type { RequestConfig } from './BaseRequest'
+
+type getValueType = () => unknown
+type removeValueType = getValueType
+type clearType = getValueType
+type isExistType = (data: unknown) => boolean
+type destroyType = clearType
+
+export type locationType = 'body' | 'header' | 'params'
+
+export interface TokenInitOption {
+  value?: unknown
+  require?: boolean // 是否必选，必选则会在isExist返回不存在时失败，可能触发rule.login
+  location?: locationType // 位置
+  time?: number // 本地缓存有效期
+  session?: boolean // 本地缓存是否为session
+  getValue?: getValueType // 获取value函数实现，如存在此函数则不会直接从value中取值
+  isExist?: isExistType // 判断数据是否存在，用户require判断和缓存获取判断
+  clear?: clearType // 清除数据
+  destroy?: destroyType // 销毁数据/会先触发清除数据
+}
+
+function setValue(this: Token, data: unknown, unSave?: boolean) {
+  this.value = data
+  if (!unSave) {
+    storage.setData(this.prop, data)
+  }
+}
+
+function setValueBySession(this: Token, data: unknown, unSave?: boolean) {
+  this.value = data
+  if (!unSave) {
+    storage.setSessionData(this.prop, data)
+  }
+}
+
+function getValue(this: Token) {
+  let data = this.$getValue!()
+  if (!this.isExist(data)) {
+    data = storage.getData(this.prop, this.time)
+    if (this.isExist(data)) {
+      this.setValue(data, true)
+    }
+  }
+  return data
+}
+
+function getValueBySession(this: Token) {
+  let data = this.$getValue!()
+  if (!this.isExist(data)) {
+    data = storage.getSessionData(this.prop, this.time)
+    if (this.isExist(data)) {
+      this.setValue(data, true)
+    }
+  }
+  return data
+}
+
+function getValueFromValue(this: Token) {
+  let data = this.value
+  if (!this.isExist(data)) {
+    data = storage.getData(this.prop, this.time)
+    if (this.isExist(data)) {
+      this.setValue(data, true)
+    }
+  }
+  return data
+}
+
+function getValueFromValueBySession(this: Token) {
+  let data = this.value
+  if (!this.isExist(data)) {
+    data = storage.getSessionData(this.prop, this.time)
+    if (this.isExist(data)) {
+      this.setValue(data, true)
+    }
+  }
+  return data
+}
+
+function removeValue(this: Token) {
+  storage.removeData(this.prop)
+  this.value = undefined
+}
+
+function removeValueBySession(this: Token) {
+  storage.removeSessionData(this.prop)
+  this.value = undefined
+}
+
+class Token {
+  static $name = 'Token'
+  prop: string
+  require?: boolean
+  value?: unknown
+  location: locationType
+  time?: number
+  isExist: isExistType
+  setValue: (data: unknown, unSave?: boolean) => void
+  $getValue?: getValueType
+  getValue: getValueType
+  removeValue: removeValueType
+  $destroy?: destroyType
+  $clear?: clearType
+  constructor(initOption: TokenInitOption, prop: string, ruleProp: string, time?: number, session?: boolean) {
+    this.prop = `require-${prop}-${ruleProp}`
+    if (initOption.require !== undefined) {
+      this.require = initOption.require
+    }
+    if (initOption.value !== undefined) {
+      this.value = initOption.value
+    }
+    this.location = initOption.location || 'body'
+    if (initOption.time === undefined) {
+      if (time !== undefined) {
+        this.time = time
+      }
+    } else {
+      this.time = initOption.time
+    }
+    if (initOption.session != undefined) {
+      session = initOption.session
+    }
+    this.isExist = initOption.isExist || isExist
+    this.setValue = !session ? setValue : setValueBySession
+    if (initOption.getValue) {
+      this.$getValue = initOption.getValue
+      this.getValue = !session ? getValue : getValueBySession
+    } else {
+      this.getValue = !session ? getValueFromValue : getValueFromValueBySession
+    }
+    this.removeValue = !session ? removeValue : removeValueBySession
+    this.$clear = initOption.clear
+    this.$destroy = initOption.destroy
+  }
+  $appendValue(requestConfig: RequestConfig<any, any>, tokenName: string) {
+    const value = this.getValue()
+    if (this.$checkValue(value)) {
+      const location = this.location
+      if (location === 'body') {
+        appendProp(requestConfig.data as Record<PropertyKey, unknown>, tokenName, value, requestConfig.currentType as 'json')
+      } else if (location === 'header') {
+        requestConfig.headers[tokenName] = value as string
+      } else if (location === 'params') {
+        requestConfig.params[tokenName] = value
+      }
+      return true
+    } else {
+      return false
+    }
+  }
+  $checkValue(data: unknown) {
+    if (this.require && !this.isExist(data)) {
+      // 数据必选且不存在时返回失败
+      return false
+    }
+    return true
+  }
+  clear() {
+    this.removeValue()
+    if (this.$clear) {
+      this.$clear()
+    }
+  }
+  destroy() {
+    this.clear()
+    if (this.$destroy) {
+      this.$destroy()
+    }
+  }
+}
+
+export default Token

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "exclude": ["node_modules", "**/*.test.ts", "vitest.config.ts"]
+}

package/vitest.config.ts

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'jsdom',
+    include: ['src/**/*.test.ts'],
+  },
+})