跳到正文

FastAxios 容器 ​

createFastAxios(options?, newInstance?) 创建 ​

创建或更新 FastAxios 配置容器。

ts
const fastAxios = createFastAxios({
	baseUrl: "https://api.example.com",
	timeout: 30_000,
	headers: { Authorization: "Bearer <token>" },
	requestCipher: false,
});
参数类型默认值说明
options.baseUrlstring""创建 Axios 请求实例时使用的 baseURL。
options.timeoutnumber60000请求超时,单位毫秒。
options.headersRawAxiosHeaders{}跨请求共享的公共请求头;重复设置时按字段合并。
options.requestCipherbooleantrue单次请求未覆盖时使用的加解密开关。
newInstancebooleanfalse为 true 时返回独立容器,不写入全局单例。

axiosUtil.request() 始终读取全局单例。独立容器不会自动参与请求流程。

重复调用单例模式的 createFastAxios() 会保留现有处理器,并通过 setOptions() 合并本次基础配置。

useFastAxios() 实例 ​

返回已经初始化的全局容器。尚未调用 createFastAxios() 时抛出 Error。

setOptions(options?) 配置 ​

更新基础配置并返回当前容器;链式调用时 TypeScript 会保留容器的具体子类型。headers 按字段合并;其他显式传入的值直接覆盖。空字符串、0 和 false 都是有效值。

addErrorCode() 错误码 ​

添加或覆盖错误提示:

ts
fastAxios.addErrorCode(40101, "登录状态已失效");

fastAxios.addErrorCode({
	40102: "账号已停用",
	CUSTOM_ERROR: "自定义错误",
});

支持 HTTP 状态码、Axios error code 和 Fast 业务 code。单值重载缺少 message 时抛出 TypeError。

createFastAxios 创建 ​

创建或更新全局 FastAxios 容器,也可以返回不写入单例的独立容器。

签名 ​

ts
createFastAxios(options?: InitializeOptions, newInstance?: boolean): FastAxios;

示例 ​

ts
import { createFastAxios } from "@fast-china/axios";

const result = createFastAxios({ baseUrl: "/api", timeout: 30_000, requestCipher: false });

输入 ​

输入值输入值类型必填/默认值输入值说明
optionsInitializeOptions否基础地址、超时、公共请求头和全局加解密开关。
newInstanceboolean否,默认 false为 true 时创建不影响全局单例的独立容器。

返回 ​

返回值返回值类型返回值说明
resultFastAxios全局单例或新建的独立配置容器。

useFastAxios 实例 ​

取得已经初始化的 FastAxios 全局单例。

签名 ​

ts
useFastAxios(): FastAxios;

示例 ​

ts
import { createFastAxios, useFastAxios } from "@fast-china/axios";

createFastAxios({ baseUrl: "/api" });
const result = useFastAxios();

输入 ​

该方法没有输入参数。

返回 ​

返回值返回值类型返回值说明
resultFastAxios已初始化的全局容器;尚未初始化时抛出 Error。

fastAxios.setOptions 配置 ​

合并基础配置;Headers 按字段合并,其他显式值直接覆盖。

签名 ​

ts
setOptions(options?: InitializeOptions): this;

示例 ​

ts
import { createFastAxios } from "@fast-china/axios";

const fastAxios = createFastAxios({ baseUrl: "/api" }, true);

const result = fastAxios.setOptions({ timeout: 15_000, headers: { Authorization: "Bearer token" } });

输入 ​

输入值输入值类型必填/默认值输入值说明
optionsInitializeOptions否,默认 {}需要更新的基础配置。

返回 ​

返回值返回值类型返回值说明
resultthis当前容器,支持链式调用。

fastAxios.addErrorCode 错误码 ​

添加或覆盖单个错误提示;也支持一次传入错误码映射。

签名 ​

ts
addErrorCode(key: string | number, message: string): FastAxios;
addErrorCode(codes: Record<string | number, string>): FastAxios;

示例 ​

ts
import { createFastAxios } from "@fast-china/axios";

const fastAxios = createFastAxios({ baseUrl: "/api" }, true);

fastAxios.addErrorCode(40101, "登录状态已失效");
const result = fastAxios.addErrorCode({ 40102: "账号已停用", CUSTOM_ERROR: "自定义错误" });

输入 ​

输入值输入值类型必填/默认值输入值说明
keystring | number单值重载必填HTTP、Axios 或 Fast 业务错误码。
messagestring单值重载必填展示给用户的提示。
codesRecord<string | number, string>映射重载必填批量错误码与提示映射。

返回 ​

返回值返回值类型返回值说明
resultFastAxios当前容器,支持链式调用。

国际化与应用词条接入 ​

从 2.0.7 起,SDK 内建简体中文、繁体中文和英文,默认仍为简体中文,不依赖 UI 或国际化框架。

ts
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) ​

ts
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/小程序构建及真机验证,也不覆盖所有第三方依赖的初始化路径。