@dayu-sec/bizlib-request

浏览器端主应用和微应用可复用的请求初始化工具包。它基于 @seed-fe/request 做一层很薄的封装，把常见的请求实例注册、Token 会话恢复、鉴权请求头注入、可选语言请求头注入、卸载清理和消费者自定义错误管道入口收敛到一个包里。

这个包只处理请求基础设施，不包含业务服务方法、接口路径、代理地址、真实 Token、业务载荷或特定应用上下文。业务自定义请求头、埋点、接口级错误提示等逻辑应放在消费方自己的请求配置或业务服务中。

安装

pnpm add @dayu-sec/bizlib-request axios

axios 是 peer dependency。当前包与底层请求包都按 Axios 1.x 验证，因此 peer 范围固定为 ^1.0.0；扩大主版本范围前需要由两个包共同完成兼容性验证。

消费方只从 @dayu-sec/bizlib-request 的公开根入口导入请求能力。@seed-fe/request 是本包的普通运行时依赖，消费方不需要重复安装，也不要从它或本包的内部路径深层导入。只有绕过本包公开 API 的代码才需要直接声明底层包，而团队项目默认不保留这种例外。

建议开发环境使用 pnpm 11 及以上，实际 Node.js 版本要求以 package.json 的 engines 为准。

快速开始

在业务服务执行前初始化请求层：

import { getRequestInstance, initializeRequest, setAuthToken } from '@dayu-sec/bizlib-request';

initializeRequest({
  instances: [{ instanceName: 'default', baseURL: '/api/v1', timeout: 10_000 }],
  getLocale: () => 'zh-CN',
});

setAuthToken('Bearer demo-token');

const request = getRequestInstance('default');
const result = await request.get('/demo/resources');

如果不传 getLocale，包不会注入 Accept-Language。

Token 会话

import {
  buildAuthHeader,
  clearAuthSession,
  getAuthToken,
  initAuthSession,
  setAuthToken,
} from '@dayu-sec/bizlib-request';

initAuthSession();
setAuthToken('Bearer demo-token');
getAuthToken();
buildAuthHeader(getAuthToken());
clearAuthSession();

空字符串和只有空白字符的值会被规范化为 null。浏览器存储不可用时，读写会降级为内存态，不会中断应用启动。

初始化时可以指定自定义 Token 存储 key：

initializeRequest({
  authStorageKey: 'demo_access_token',
  instances: [{ instanceName: 'default', baseURL: '/api/v1' }],
});

buildAuthHeader 是纯函数，只根据入参构造 { Authorization: string } 或 {}。它不会修改全局状态，也不会直接修改请求配置；因此命名为 build 比 set 更准确。

如果消费方存的是裸 Token，可以让它补上 Bearer 前缀：

buildAuthHeader('demo-token', { bearer: true });

错误归属

默认初始化不会注册全局错误管道，也不会清理消费方在本包之外注册的全局错误策略。请求失败仍然沿原始请求 Promise 传播，包内不会额外 Promise.reject 制造第二条异常链，业务层和宿主层可以按自己的职责处理。

需要统一错误副作用的消费方可以显式注册：

import { setGlobalErrorPipeline } from '@dayu-sec/bizlib-request';

setGlobalErrorPipeline([
  async (_ctx, next) => {
    await next();
  },
]);

如果只是为了关闭 loading 或 submitting 状态，业务代码优先使用 finally，不要为了回收状态额外 catch 并制造重复提示。

卸载清理

微应用卸载或等价生命周期结束时调用：

import { resetRequest } from '@dayu-sec/bizlib-request';

resetRequest();

resetRequest 会清理包内初始化状态、包拥有的请求实例、Token 会话状态，以及通过本包 setGlobalErrorPipeline 注册的错误策略。它不会清理其他应用自己注册的请求实例，也不会清理绕过本包直接注册的全局错误策略。

公开 API

import type {
  BuildAuthHeaderOptions,
  CustomRequestConfig,
  HttpRequest,
  RequestSetupOptions,
} from '@dayu-sec/bizlib-request';
import {
  buildAuthHeader,
  clearAuthSession,
  clearGlobalErrorPipeline,
  getAuthToken,
  getRequestInstance,
  initAuthSession,
  initializeRequest,
  normalizeError,
  resetRequest,
  setAuthToken,
  setGlobalErrorPipeline,
} from '@dayu-sec/bizlib-request';

示例项目

当前包内提供一个 React + Vite 8 示例。React 只属于示例项目依赖，不是库源码依赖。

cd packages/dayu-sec-bizlib-request
pnpm install
pnpm example-dev

示例从包的公开根入口和 dist 产物导入请求能力，并使用本地 mock 接口演示初始化、Token 设置与清理、语言请求头、请求调用、自定义错误策略和重置流程。pnpm example-dev 会先构建库产物再启动示例。后续如果团队需要 Vue 或 Angular 最佳实践，可以在 examples/ 下继续增加独立示例项目。

发布内容

源码仓库保留 src/、test/、examples/ 和配置文件，方便维护、测试和示例验证。发布到 NPM 时以 package.json 的 files 字段为准，只包含：

• dist
• README.md
• CHANGELOG.md
• LICENSE
• package.json

发布包不包含 src/、test/、examples/、source maps、本地构建缓存或示例产物。构建配置不会生成 sourcemap，因此发布包不会携带源码映射文件。prepack 会在打包和发布前自动生成最新 dist，发布前可用下面命令检查实际 tarball 内容：

pnpm pack --dry-run

本地验证

pnpm check
pnpm test
pnpm build
pnpm --dir examples/react-vite8-demo build
pnpm test-package
pnpm pack --dry-run

pnpm test-package 会创建临时消费者，用 npm 安装当前 tarball，并验证 ESM、CommonJS 和 TypeScript 声明入口。