@origen-ui/http

@origen-ui/http 是基于 Axios 的请求传输边界，面向需要请求取消、幂等重试、追踪 ID、响应协议适配和可刷新鉴权的应用，同时不把业务规则塞进客户端。

import {
  ApiClient,
  createApiEnvelopeAdapter,
  createBearerAuthStrategy,
  responseDataAdapter,
  TokenManager,
} from '@origen-ui/http'

const tokens = new TokenManager({
  accessKey: 'admin-access-token',
  accessStorage: window.localStorage,
})

const api = new ApiClient({
  baseURL: '/api',
  responseAdapter: createApiEnvelopeAdapter(),
  auth: createBearerAuthStrategy({
    tokenManager: tokens,
    refresh: async ({ refreshToken, traceId }) => refreshSession({ refreshToken, traceId }),
    shouldRefresh: (error) => error.kind === 'business' && error.code === 40101,
    onExpired: () => navigateToLogin(),
  }),
  retry: 1,
})

成功请求解析为数据；失败请求 reject 为 ApiError。信封协议失败会具体 reject 为 ApiBusinessError，并保留后端 code、data、HTTP 状态码、追踪 ID 和请求上下文。

const users = await api.get<User[]>('/users', {
  params: { page: 1, pageSize: 20 },
})

const exportFile = await api.get<Blob>('/users/export', {
  responseType: 'blob',
  responseAdapter: responseDataAdapter,
})

TokenManager 默认使用内存存储。应用需要在刷新页面后保留令牌时，应显式传入存储适配器。DTO 归一化、分页参数映射和面向用户的业务错误翻译由业务仓库负责；本包只负责可靠的传输行为。如果注入的 onError 回调自身抛错，ApiClient 会记录回调错误，同时仍以原始 ApiError reject。

根入口 API 索引

| 分类 | 可见根入口 API | | ------------ | ---------------------------------------------------------------------------------------------------------------------------- | | 错误边界 | ApiBusinessError, ApiError, isApiError, ApiBusinessErrorOptions, ApiErrorKind, ApiErrorOptions, RequestContext | | 客户端与请求 | ApiClient, ApiClientOptions, RequestOptions | | 鉴权 | createBearerAuthStrategy, AuthStrategy, BearerAuthOptions, RefreshResult | | 响应适配 | createApiEnvelopeAdapter, rawResponseAdapter, responseDataAdapter, ResponseAdapter, ResponseContext | | 令牌管理 | TokenManager, TokenManagerOptions, TokenStorage |

上方示例说明这些入口在一次请求与刷新流程中的组合方式。

令牌与刷新边界

ApiClient 和 TokenManager 都由应用持有；本包不会安装单例客户端或存储策略。只有在分别传入对应存储选项时，访问令牌和刷新令牌才会独立持久化。刷新回调会收到当前刷新令牌、新的追踪 ID 和可选的 CSRF 令牌，并且必须返回新的访问令牌。刷新请求的传输方式和 Cookie 策略仍由应用负责。

resolveHeaders 会先解析每次请求的默认请求头，再应用显式请求头，因此调用方可以注入语言或租户请求头，而不必让客户端耦合应用状态。 HTTP 包不依赖 Element Plus，也不会把传输错误翻译为 UI 消息。