@micl/net 请求工具库

基于 Axios / 微信小程序 request 封装的通用请求工具，提供统一的 API 接口和类型支持

统一请求工具，简化多端开发 🚀

✨ 特性

• ✅ Axios REST 请求统一封装
• ✅ 微信小程序（WX）请求封装
• ✅ 请求别名（Alias）机制
• ✅ 自动注入 TransId / Header
• ✅ 可中断（Abort）的 Promise
• ✅ 统一后端返回结构 ServerResult<T>
• ✅ 强类型支持（TypeScript 泛型）
• ✅ 请求缓存与去重

适用于 Web / Node / 微信小程序 项目。

📦 安装

npm install @micl/net
# or
pnpm add @micl/net
# or
yarn add @micl/net

📚 模块导出

export { AxiosRest } from './rest';
export { WXRest } from './rest.wx';
export type { ServerResult };

🧱 后端通用返回结构

export interface ServerResult<T> {
  code?: number;
  success?: boolean;
  message?: string;
  msgId?: string;
  data?: T;
  status?: {
    code?: number;
    desc?: string;
  };
  timestamp?: number;
  [key: string]: any;
}

推荐后端统一使用该结构，便于前端泛型约束。

⛔ PromiseWithAbort

一个可中断的 Promise，基于 Axios CancelToken 实现。

class PromiseWithAbort<T> extends Promise<T> {
  source?: CancelTokenSource;
  abort(message?: string): void;
}

使用示例

const req = AxiosRest.get<User>('/api/user');

setTimeout(() => {
  req.abort('用户取消请求');
}, 1000);

🌐 AxiosRest（Web / Node）

获取实例

import { AxiosRest } from '@micl/net';

AxiosRest 为单例对象。

基础配置

AxiosRest.config({
  logger: console,
  axios: {
    baseURL: '/api',
    timeout: 10000
  },
  useAlias: true,
  useTransId: true,
  onRequest: (config) => {
    console.log('request', config);
  },
  onResponse: (res) => {
    console.log('response', res);
  },
  bodyConfig: {
    appId: 'your-app-id'
  }
});

注意：调用 AxiosRest 之前必须先调用 config 方法进行配置。

配置项说明

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | logger | any | console | 日志对象 | | axios | AxiosRequestConfig | - | Axios 原生配置 | | useAlias | boolean | true | 是否启用别名 | | useTransId | boolean | true | 是否自动注入 TransId | | onRequest | Function | - | 请求拦截回调 | | onResponse | Function | - | 响应拦截回调 | | bodyConfig | Object | Function | - | body 处理配置或函数 |

Alias 别名配置

AxiosRest.alias({
  '@user': {
    url: '/user/info',
    headers: {
      token: 'xxx'
    }
  }
});

使用：

AxiosRest.get<User>('@user');

发起请求

request

AxiosRest.request<User>({
  url: '/user',
  method: 'GET'
});

get

AxiosRest.get<User>('/user', { id: 1 });

post

AxiosRest.post<User>('/user', {
  name: 'Tom'
});

终止请求

abortAll

AxiosRest.abortAll();

适用于路由切换、页面销毁等场景，终止所有正在进行的请求。

获取 Axios 实例

const axiosInstance = AxiosRest.getAxiosInstance();

📱 WXRest（微信小程序）

引入

import { WXRest } from '@micl/net';

基础配置

WXRest.config({
  context: wx,
  appId: 'your-app-id',
  headers: {
    token: 'xxx'
  },
  noHttpCache: true,
  logger: console,
  onRequest: (config) => {
    console.log('request', config);
  },
  onResponse: (res) => {
    console.log('response', res);
  }
});

配置项说明

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | context | any | wx | 小程序上下文 | | logger | any | console | 日志对象 | | appId | string | - | 小程序 AppID | | headers | Object | - | 请求头 | | noHttpCache | boolean | false | 是否禁用 HTTP 缓存 | | onRequest | Function | - | 请求拦截回调 | | onResponse | Function | - | 响应拦截回调 |

Alias 配置

WXRest.alias({
  login: {
    url: '/login'
  }
});

发起请求

GET

WXRest.get<User>('/user', { id: 1 });

POST

WXRest.post<User>('/user', {
  name: 'Tom'
});

返回值统一为：

Promise<ServerResult<T>>

请求去重 & 缓存

WXRest 内部维护请求缓存：

• 相同 URL + 参数的请求可自动复用
• 避免短时间内重复请求
• 缓存列表最多保留 5 条记录

适合小程序页面频繁触发请求的场景。

🔧 工具函数

generateUUID()

生成唯一 UUID。

import { generateUUID } from '@micl/net';

const id = generateUUID();

✅ 设计目标

• 强类型（TypeScript 泛型）
• 可中断请求
• 多端统一 API（Web / WX）
• 统一后端返回结构
• 易于扩展与维护

🤝 贡献

欢迎提交 Issue 和 Pull Request 来完善这个模块。

📄 许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

Copyright (c) alexgogoing [email protected]

📞 支持

如有问题或建议，请提交 Issue 或联系维护者。