FastAxios 容器
createFastAxios(options?, newInstance?) 创建
创建或更新 FastAxios 配置容器。
const fastAxios = createFastAxios({
baseUrl: "https://api.example.com",
timeout: 30_000,
headers: { Authorization: "Bearer <token>" },
requestCipher: false,
});| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
options.baseUrl | string | "" | 创建 Axios 请求实例时使用的 baseURL。 |
options.timeout | number | 60000 | 请求超时,单位毫秒。 |
options.headers | RawAxiosHeaders | {} | 跨请求共享的公共请求头;重复设置时按字段合并。 |
options.requestCipher | boolean | true | 单次请求未覆盖时使用的加解密开关。 |
newInstance | boolean | false | 为 true 时返回独立容器,不写入全局单例。 |
axiosUtil.request() 始终读取全局单例。独立容器不会自动参与请求流程。
重复调用单例模式的 createFastAxios() 会保留现有处理器,并通过 setOptions() 合并本次基础配置。
useFastAxios() 实例
返回已经初始化的全局容器。尚未调用 createFastAxios() 时抛出 Error。
setOptions(options?) 配置
更新基础配置并返回当前容器;链式调用时 TypeScript 会保留容器的具体子类型。headers 按字段合并;其他显式传入的值直接覆盖。空字符串、0 和 false 都是有效值。
addErrorCode() 错误码
添加或覆盖错误提示:
fastAxios.addErrorCode(40101, "登录状态已失效");
fastAxios.addErrorCode({
40102: "账号已停用",
CUSTOM_ERROR: "自定义错误",
});支持 HTTP 状态码、Axios error code 和 Fast 业务 code。单值重载缺少 message 时抛出 TypeError。
createFastAxios 创建
创建或更新全局 FastAxios 容器,也可以返回不写入单例的独立容器。
签名
createFastAxios(options?: InitializeOptions, newInstance?: boolean): FastAxios;示例
import { createFastAxios } from "@fast-china/axios";
const result = createFastAxios({ baseUrl: "/api", timeout: 30_000, requestCipher: false });输入
| 输入值 | 输入值类型 | 必填/默认值 | 输入值说明 |
|---|---|---|---|
options | InitializeOptions | 否 | 基础地址、超时、公共请求头和全局加解密开关。 |
newInstance | boolean | 否,默认 false | 为 true 时创建不影响全局单例的独立容器。 |
返回
| 返回值 | 返回值类型 | 返回值说明 |
|---|---|---|
result | FastAxios | 全局单例或新建的独立配置容器。 |
useFastAxios 实例
取得已经初始化的 FastAxios 全局单例。
签名
useFastAxios(): FastAxios;示例
import { createFastAxios, useFastAxios } from "@fast-china/axios";
createFastAxios({ baseUrl: "/api" });
const result = useFastAxios();输入
该方法没有输入参数。
返回
| 返回值 | 返回值类型 | 返回值说明 |
|---|---|---|
result | FastAxios | 已初始化的全局容器;尚未初始化时抛出 Error。 |
fastAxios.setOptions 配置
合并基础配置;Headers 按字段合并,其他显式值直接覆盖。
签名
setOptions(options?: InitializeOptions): this;示例
import { createFastAxios } from "@fast-china/axios";
const fastAxios = createFastAxios({ baseUrl: "/api" }, true);
const result = fastAxios.setOptions({ timeout: 15_000, headers: { Authorization: "Bearer token" } });输入
| 输入值 | 输入值类型 | 必填/默认值 | 输入值说明 |
|---|---|---|---|
options | InitializeOptions | 否,默认 {} | 需要更新的基础配置。 |
返回
| 返回值 | 返回值类型 | 返回值说明 |
|---|---|---|
result | this | 当前容器,支持链式调用。 |
fastAxios.addErrorCode 错误码
添加或覆盖单个错误提示;也支持一次传入错误码映射。
签名
addErrorCode(key: string | number, message: string): FastAxios;
addErrorCode(codes: Record<string | number, string>): FastAxios;示例
import { createFastAxios } from "@fast-china/axios";
const fastAxios = createFastAxios({ baseUrl: "/api" }, true);
fastAxios.addErrorCode(40101, "登录状态已失效");
const result = fastAxios.addErrorCode({ 40102: "账号已停用", CUSTOM_ERROR: "自定义错误" });输入
| 输入值 | 输入值类型 | 必填/默认值 | 输入值说明 |
|---|---|---|---|
key | string | number | 单值重载必填 | HTTP、Axios 或 Fast 业务错误码。 |
message | string | 单值重载必填 | 展示给用户的提示。 |
codes | Record<string | number, string> | 映射重载必填 | 批量错误码与提示映射。 |
返回
| 返回值 | 返回值类型 | 返回值说明 |
|---|---|---|
result | FastAxios | 当前容器,支持链式调用。 |
国际化与应用词条接入
从 2.0.7 起,SDK 内建简体中文、繁体中文和英文,默认仍为简体中文,不依赖 UI 或国际化框架。
import { createFastAxios } from "@fast-china/axios";
import type { FastAxiosLocale, FastAxiosLocaleSource, FastAxiosMessageKey, FastAxiosTranslate } from "@fast-china/axios";
let language: FastAxiosLocale = "zh-CN";
const locale: FastAxiosLocaleSource = () => language;
const appMessages: Partial<Record<FastAxiosMessageKey, string>> = { loading: "Please wait..." };
const translate: FastAxiosTranslate = (key, currentLocale, fallback) => (currentLocale === "en-US" ? (appMessages[key] ?? fallback) : fallback);
const fastAxios = createFastAxios({ locale, translate });
language = "en-US";
fastAxios.setOptions({ locale: "zh-TW", translate: null });实际项目中,locale 函数读取应用当前语言,translate 调用自己的同步翻译方法;仅在应用有对应词条时返回译文,缺失时返回 undefined、null 或 fallback。
FastAxiosLocale:"zh-CN" | "zh-TW" | "en-US"。FastAxiosLocaleSource也允许返回任意字符串的同步函数;不支持的值回退到zh-CN,不自动转换语言别名。FastAxiosTranslate:(key: FastAxiosMessageKey, locale: FastAxiosLocale, fallback: string) => string | null | undefined。FastAxiosMessageKey包括字符串 HTTP 状态码(如"400")、Axios 原始错误码(如"ERR_NETWORK")、default、offLine、fileDownloadError、loading和确认框等 SDK 文案键。- 语言和译文在使用文案时读取,不为在途请求固定语言。空字符串有效;翻译抛错时回退到当前语言内建文案,语言读取抛错时回退到简体中文,均不替换请求错误。
setOptions({ translate: null })清除回调;省略或undefined保留原配置。 - 内建
errorCode项跟随语言切换;addErrorCode()和直接赋值的覆盖继续优先。服务端消息、显式loadingText和确认框按钮文本不送入翻译。 - 默认 Loading 文案、错误提示、RESTful 校验错误、uni 确认框标题和按钮会本地化。浏览器原生确认框按钮由浏览器控制。服务端消息、Axios/uni 原生诊断、原始取消原因及未初始化等开发配置诊断保持原样。
- HTTP/网络错误仍以同一个 AxiosError 拒绝,保留
code、message、config、request、response;取消仍能通过axios.isCancel()判断并继续拒绝,不额外弹错。SDK 自建业务错误仅改变文案,错误码仍为ERR_BAD_RESPONSE。 - 不自动修改请求头或缓存命名空间;服务端响应依赖语言时,应用须设置语言请求头并清理缓存,或在 URL 查询参数中区分语言。独立容器的语言及翻译配置相互隔离;请求仍只读取全局单例。
fastAxios.t(key)
t(key: FastAxiosMessageKey): string;返回当前语言的 SDK 文案,经 translate 处理并按上述规则回退。此方法不读取 addErrorCode() 的业务覆盖;需要最终错误码提示时读取 fastAxios.errorCode[code]。
App 与小程序边界
国际化实现使用普通对象、Object.keys、Object.defineProperty 和同步回调,不依赖 Intl、DOM 或浏览器存储。参考 uni-app JavaScript 运行环境。
按 uni.showModal 官方限制,小程序的确认/取消按钮文字最多 4 个字符。内建英文采用 OK / Back;自定义翻译和显式按钮文字也应满足目标平台限制,SDK 不自动截断调用方文本。
SDK 当前产物目标为 ES2022,旧系统/基础库仍需由消费项目完成兼容转译和必要的运行时补充。已有 uni adapter 的 Basic Auth 编码依赖 btoa;缺少该 API 时使用 auth 会以 ERR_BAD_OPTION_VALUE 拒绝,不能将 H5 成功等同于 App/小程序已支持。
已用受控 uni 请求验证:缺少 window、document、navigator、Intl、crypto、TextEncoder、URL、URLSearchParams、Blob、FormData 和 AbortController 时,普通请求、动态语言和网络错误提示仍工作。这不代替目标 App/小程序构建及真机验证,也不覆盖所有第三方依赖的初始化路径。
