axios API Reference 全解公开 API、TypeScript 泛型与源码实现剖析【免费下载链接】axiosPromise based HTTP client for the browser and node.js项目地址: https://gitcode.com/GitHub_Trending/ax/axios本文基于 axios 官方文档的 API Reference参见 docs/fr/pages/advanced/api-reference.md英文同源版本见 docs/pages/advanced/api-reference.md系统梳理 axios 对外暴露的全部函数、类与常量默认实例axios、Axios/AxiosHeaders/AxiosError/CanceledError等核心类、isCancel/isAxiosError/toFormData/getAdapter/mergeConfig等实用函数、HttpStatusCode常量表以及 TypeScript 请求类型泛型体系。读完本篇后你能准确使用 axios 的每一项公开 API并借助仓库源码理解这些 API 背后的真实实现与版本 1.19.0 中的最新行为如参数解析器parseParameters、错误脱敏redact等。axios 遵循语义化版本管理SemVer文档明确承诺除非主版本号变更上述公开 API 将保持稳定。当前仓库 package.json 中的版本为1.19.0。一、总览axios 导出了什么axios 的公共 API 全部挂载在默认导出对象上。查看入口文件 lib/axios.js 可以看到完整的导出清单// lib/axios.js节选 const axios createInstance(defaults); // 默认实例 axios.Axios Axios; // Axios 类 axios.CanceledError CanceledError; // 取消错误 axios.CancelToken CancelToken; // 已废弃的取消令牌 axios.isCancel isCancel; axios.VERSION VERSION; axios.toFormData toFormData; axios.AxiosError AxiosError; axios.Cancel axios.CanceledError; // 向后兼容别名 axios.all (promises) Promise.all(promises); // 已废弃 axios.spread spread; axios.isAxiosError isAxiosError; axios.mergeConfig mergeConfig; axios.AxiosHeaders AxiosHeaders; axios.formToJSON (thing) formDataToJSON(utils.isHTMLForm(thing) ? new FormData(thing) : thing); axios.getAdapter adapters.getAdapter; axios.HttpStatusCode HttpStatusCode; axios.default axios;除以上挂到默认导出上的成员外axios 同时提供具名导出如import { toFormData, mergeConfig, AxiosError } from axios类型声明见 index.d.ts。下表按文档分类整理全部公开 API 及其源码位置分类API说明源码位置Instanceaxios默认实例发起请求的主入口lib/axios.js类Axios可继承的请求类lib/core/Axios.js类CancelToken已废弃推荐AbortControllerlib/cancel/CancelToken.js类/函数AxiosErrorHTTP 失败时抛出的错误类lib/core/AxiosError.js类AxiosHeadersHTTP 头部管理工具lib/core/AxiosHeaders.js类CanceledError请求被取消时抛出的错误lib/cancel/CanceledError.js类CancelCanceledError的兼容别名lib/axios.js函数isCancel/isAxiosError错误类型判别lib/cancel/isCancel.js、lib/helpers/isAxiosError.js函数all已废弃/spreadPromise 工具lib/helpers/spread.js函数toFormData/formToJSON表单数据互转lib/helpers/toFormData.js、lib/helpers/formDataToJSON.js函数getAdapter/mergeConfig适配器解析 / 配置合并lib/adapters/adapters.js、lib/core/mergeConfig.js常量HttpStatusCodeHTTP 状态码常量表lib/helpers/HttpStatusCode.js其他VERSION当前包版本字符串package.json二、Instance默认实例 axiosaxios实例是你发起 HTTP 请求时使用的主要对象。它本质上是一个工厂函数创建的Axios类实例同时自身也是一个可调用对象。这一点在 lib/axios.js 的createInstance中体现得非常清楚function createInstance(defaultConfig) { const context new Axios(defaultConfig); const instance bind(Axios.prototype.request, context); // 实例本身 绑定了 request 的函数 // 把 Axios.prototype 上的方法全部拷贝到 instanceget/post/put/... utils.extend(instance, Axios.prototype, context, { allOwnKeys: true }); // 把 context 实例defaults、interceptors也拷贝过去 utils.extend(instance, context, null, { allOwnKeys: true }); instance.create function create(instanceConfig) { return createInstance(mergeConfig(defaultConfig, instanceConfig)); }; return instance; } // 创建导出的默认实例 const axios createInstance(defaults);由此可以得到三个实用结论axios(url[, config])可以直接当request调用——因为instance就是Axios.prototype.request绑定后的函数instance.create()会基于当前默认配置派生新实例且派生时通过mergeConfig合并默认值这正是mergeConfig公开 API 的另一个应用场景方法别名get/post/put/patch/delete/head/options/query以及对应的postForm/putForm/patchForm都在Axios类上通过utils.forEach批量生成详见 请求方法别名 文档。三、TypeScript 请求类型D, P双泛型体系这是本次 API 文档中新增的重点。公开的请求类型使用独立泛型分别描述请求体与查询参数AxiosRequestConfigD any, P any RawAxiosRequestConfigD any, P any InternalAxiosRequestConfigD any, P any AxiosDefaultsD any, P any CreateAxiosDefaultsD any, P any AxiosResponseT any, D any, H {}, P any AxiosPromiseT any, D any, P any AxiosErrorT unknown, D any, P any CanceledErrorT, D any, P any其中D是请求体data的类型P是查询参数params的类型。以下 API 会在配置中同时保留D和PAxiosResponse/AxiosPromise错误类型AxiosError、CanceledError默认值类型AxiosDefaults、CreateAxiosDefaults可调用实例与各请求别名方法各适配器adaptermergeConfig()自定义参数序列化器paramsSerializer也能拿到同一个P请求方法的泛型顺序为T, R, D, P其中P被追加在最后以保证已有的显式泛型调用例如axios.getT(url)保持兼容。行为约定未显式指定响应类型R时默认的AxiosResponse会在response.config中保留D和P显式指定R时R继续控制 Promise 的 resolve 值数据与参数泛型默认值均为any以维持向后兼容。这些类型声明均可在 index.d.ts 中逐一定义核对例如AxiosRequestConfig上data?: D、params?: P的声明以及AxiosHeaders.parseParameters的静态方法签名。四、核心类4.1AxiosAxios是发起 HTTP 请求的主类。构造函数接受一个可选的默认配置对象constructor(instanceConfig?: AxiosRequestConfig);对应源码 lib/core/Axios.jsclass Axios { constructor(instanceConfig) { this.defaults instanceConfig || {}; this.interceptors { request: new InterceptorManager(), response: new InterceptorManager(), }; } // ... }可见每个实例持有两样东西默认配置defaults与请求/响应拦截器管理器。request方法request是发起请求的主方法接受配置对象并返回 PromiserequestT, R, D, P(config: AxiosRequestConfigD, P): PromiseR;从源码结构看lib/core/Axios.jsrequest内部委托给_request其执行链路为URL 快捷形式axios(example/url, config)支持类 fetch 的调用方式字符串参数会被移入config.url配置合并config mergeConfig(this.defaults, config)——每次请求都会把实例默认配置与本次配置深度合并配置校验transitional、paramsSerializer等字段会经validator.assertOptions校验写错的baseUrl/withXsrfToken会收到拼写纠正提示方法归一化config.method依次取请求配置、实例默认值兜底为get并转为小写请求头扁平化合并headers.common与headers[method]后删除方法占位键最终通过AxiosHeaders.concat归一为AxiosHeaders实例拦截器链组装请求拦截器按注册顺序压入dispatchRequest之前响应拦截器追加在其后最终形成一个 Promise 链同步请求拦截器则走同步执行分支减少微任务开销。request外层还包了一层 try/catch若错误没有stack部分环境/自定义 Error 可能缺失会用Error.captureStackTrace构造一份兜底调用栈附加到错误对象上——这是当前版本对可观测性的一个增强。此外Axios还提供getUri(config)将默认配置与传入配置合并后经buildFullPath与buildURL拼接查询参数计算出最终完整 URL适合调试链接。4.2CancelToken已废弃推荐AbortControllerCancelToken基于早期的tc39/proposal-cancelable-promises提案自0.22.0起已被标记为废弃将在后续版本中移除。官方强烈建议新项目使用标准AbortControllerAPI该类当前导出主要是为了向后兼容// 遗留方法仍然有完整类型仅供存量代码使用 subscribe(listener: (cancel: Cancel | any) void): void; unsubscribe(listener: (cancel: Cancel | any) void): void; toAbortSignal(): AbortSignal;其中 lib/cancel/CancelToken.js 的toAbortSignal()提供了向新 API 迁移的桥梁把旧式 CancelToken 的信号转换成AbortSignal方便在过渡期与signal配置共存。五、实用函数5.1AxiosErrorAxiosError是请求失败时抛出的错误类继承Error并附加 axios 专属属性constructor(message?: string, code?: string, config?: InternalAxiosRequestConfigD, P, request?: any, response?: AxiosResponseT, D, {}, P);实例属性如下// 请求配置实例 config?: InternalAxiosRequestConfigD, P; // 错误码如 ETIMEDOUT、ECONNABORTED code?: string; // 请求对象 request?: any; // 响应对象 response?: AxiosResponseT, D, {}, P; // 布尔标识该错误是否为 AxiosError isAxiosError: boolean; // HTTP 状态码 status?: number; // 将错误序列化为 JSON 对象的工具方法 toJSON: () object; // 错误原因cause cause?: Error;源码 lib/core/AxiosError.js 中有几个值得注意的实现细节构造函数中isAxiosError true是自身标记配合 lib/helpers/isAxiosError.js 的鸭子类型判断payload.isAxiosError true意味着即使错误对象跨 realm如 iframe、浏览器隔离环境传递判别依然可靠不依赖instanceofstatus在存在response时自动取response.status静态from(error, code, config, request, response)工厂方法用于包装外部错误会把原错误挂到非可枚举的cause上对齐原生Error.cause语义避免结构化日志库序列化cause内部循环引用时报错并能聚合 Node 双栈连接失败产生的AggregateError空消息toJSON()支持可选脱敏当请求配置中包含redact数组时序列化快照中任意深度、大小写匹配的键值会被替换为[REDACTED ****]适合在日志中隐藏 token 等敏感字段类上还挂载了一组标准错误码常量ERR_BAD_OPTION、ERR_BAD_OPTION_VALUE、ECONNABORTED、ETIMEDOUT、ECONNREFUSED、ERR_NETWORK、ERR_FR_TOO_MANY_REDIRECTS、ERR_BAD_RESPONSE、ERR_BAD_REQUEST、ERR_CANCELED、ERR_NOT_SUPPORT、ERR_INVALID_URL等可用于精确比对error.code。5.2AxiosHeadersAxiosHeaders是管理 HTTP 头部的工具类提供增删查与序列化能力。文档只列出主要方法完整签名请以 index.d.ts 为准。constructor(headers?: RawAxiosHeaders | AxiosHeaders | string);set添加或覆写头部。空或纯空格的头部名会被直接忽略set(headerName?: string, value?: AxiosHeaderValue, rewrite?: boolean | AxiosHeaderMatcher): AxiosHeaders; set(headers?: RawAxiosHeaders | AxiosHeaders | string, rewrite?: boolean): AxiosHeaders; set(headers?: Iterable[string, AxiosHeaderValue], rewrite?: boolean): AxiosHeaders;从 lib/core/AxiosHeaders.js 的set实现可以看到三种输入都被覆盖普通对象逐键写入、字符串先经parseHeaders解析为多行头部再写入、可迭代键值对重复键会被自动聚合为数组。写入时值会经过normalizeValue清洗——底层调用 lib/helpers/sanitizeHeaderValue.js 的sanitizeHeaderValue剥离 C0 控制字符、DEL0x7F以及首尾空格/制表符保证头部值符合 HTTP 规范。rewrite参数控制是否无条件覆盖已存在的键。get读取头部支持三种解析器形态get(headerName: string, parser: typeof AxiosHeaders.parseParameters): AxiosHeaderParameters; get(headerName: string, parser: RegExp): RegExpExecArray | null; get(headerName: string, matcher?: true | AxiosHeaderParser): AxiosHeaderValue;parser传true时使用内置的parseTokens以与,/;切分的轻量 tokenizer传RegExp返回exec结果传函数则以(value, key)调用都不传则返回原始值。新版增加了静态解析器AxiosHeaders.parseParameters用于把规范化 HTTP 参数解析为空原型null-prototype的强化 mapconst headers new AxiosHeaders({ Content-Type: multipart/form-data; boundarya,b, }); console.log({ ...headers.get(Content-Type, AxiosHeaders.parseParameters), }); // { boundary: a,b }其解析规则对应 lib/core/AxiosHeaders.js 的parseParameters状态机参数名大小写不敏感统一转小写存储引号包裹的字符串值会剥离两侧引号并解码\、\\转义引号内的逗号、分号作为值的一部分保留因此boundarya,b不会被错误切分仅剔除无引号值两侧 RFC 定义的可选空白OWS空格与制表符结果 map 为Object.create(null)并显式跳过__proto__、constructor、prototype三个名字防止原型链污染参数名需匹配^[!#$%*\-.^_|~0-9A-Za-z]$ 白名单非法名字直接丢弃。get(name, true)仍是旧版轻量 tokenizer两者定位不同迁移时按需选择。has/delete/clearhas(header: string, matcher?: AxiosHeaderMatcher): boolean; delete(header: string | string[], matcher?: AxiosHeaderMatcher): boolean; clear(matcher?: AxiosHeaderMatcher): boolean;matcher支持三种形态函数(value, header) boolean、字符串子串包含、正则test。delete接受单键或数组clear可清空全部头部两者返回值均表示是否确实删除了内容。normalizenormalize(format: boolean): AxiosHeaders;归一化头部对象合并重复键值聚为数组并把键名转为trim后的小写形式format为true时进一步格式化为 Pascal-Case 首字母大写形式如content-type→Content-Type。concatconcat(...targets: ArrayAxiosHeaders | RawAxiosHeaders | string | undefined | null): AxiosHeaders;按参数顺序合并多组头部返回新实例底层是static concat以第一个对象新建实例后依次set其余目标。axios 内部合并headers.common与headers[method]时用的就是它。toJSON/toStringtoJSON(asStrings: true): Recordstring, string; toJSON(asStrings?: false): Recordstring, string | string[]; toString(): string;toJSON(true)会把数组值用, 连接为字符串toString()输出无 CRLF 分隔的 HTTP 头部块——每个name: value对一行换行分隔见 lib/core/AxiosHeaders.js。另外源码中还有几个未在文档正文展开但确实存在的能力类实例可用Symbol.iterator迭代等价于遍历toJSON()的 entriesstatic accessor(headers)会为指定头部动态生成getContentType()/setContentType(v)/hasContentType()访问器内置已为Content-Type、Content-Length、Accept、Accept-Encoding、User-Agent、Authorization六个常用头部注册见 lib/core/AxiosHeaders.jsgetSetCookie()保证Set-Cookie多值以数组形式返回。5.3CanceledError与Cancel别名请求被取消时抛出CanceledError它继承自AxiosErrorconstructor(message?: string, config?: InternalAxiosRequestConfigD, P, request?: any); __CANCEL__?: boolean;源码 lib/cancel/CanceledError.js 显示其固定行为code取AxiosError.ERR_CANCELEDERR_CANCELEDname为CanceledError并打上__CANCEL__ true标记。Cancel仅是CanceledError的兼容别名lib/axios.js 中axios.Cancel axios.CanceledError未来版本会移除。5.4isCancel判断错误是否为取消错误用于区分用户主动取消和真实故障isCancelT any, D any, P any(value: any): value is CanceledErrorT, D, P;import axios from axios; const controller new AbortController(); axios.get(/api/data, { signal: controller.signal }).catch((error) { if (axios.isCancel(error)) { console.log(Request was cancelled:, error.message); } else { console.error(Unexpected error:, error); } }); controller.abort(User navigated away);5.5isAxiosError判断错误是否为AxiosError用于在catch块中安全访问error.response、error.config等 axios 专属属性isAxiosError(value: any): value is AxiosError;import axios from axios; try { await axios.get(/api/resource); } catch (error) { if (axios.isAxiosError(error)) { // error.response、error.config、error.code 均可安全访问 console.error(HTTP error, error.response?.status, error.message); } else { // 非 axios 错误例如编程错误原样抛出 throw error; } }5.6all已废弃与spreadall自 0.22.0 起废弃请直接使用Promise.all。源码层面它现在就是透传lib/axios.jsaxios.all function all(promises) { return Promise.all(promises); };spread把数组解包为函数参数适合在Promise.all之后把多个响应按位置传给回调spreadT, R(callback: (...args: T[]) R): (array: T[]) R;import axios, { spread } from axios; axios.all([axios.get(/user/123), axios.get(/posts/123)]) .then(axios.spread((user, posts) { // user 与 posts 为两个响应 }));5.7toFormData将普通 JS 对象可嵌套转换为FormData实例适合以对象形态组织 multipart 表单数据toFormData(sourceObj: object, formData?: FormData, options?: FormSerializerOptions): FormData;import { toFormData } from axios; const data { name: Jay, avatar: fileBlob }; const form toFormData(data); // form 已是可直接发送的 FormData 实例 await axios.post(/api/users, form);实现位于 lib/helpers/toFormData.js支持indexes是否生成数组下标键、visitor自定义序列化钩子、dots点号嵌套表示法等FormSerializerOptions同时 axios 的postForm/putForm/patchForm方法别名在内部也依赖这套序列化逻辑自动把对象转为multipart/form-data请求体。5.8formToJSONFormData反转为普通 JS 对象。结构性记法只有点号与方括号.、[、]作为路径分隔符foo.bar与foo[bar]生成嵌套对象foo[]生成数组而-、空格、、*、均保留为键名字面字符。formToJSON(form: FormData): object;import { formToJSON } from axios; const form new FormData(); form.append(user-name, johndoe); form.append(user.name, john); const obj formToJSON(form); console.log(obj); // { user-name: johndoe, user: { name: john } }注意 lib/axios.js 中的包装传入formHTML 元素时会自动先new FormData(thing)再转换因此axios.formToJSON(formElement)直接可用。5.9getAdapter按名称或候选名称数组解析并返回适配器函数。axios 内部正是用它为当前环境挑选可用适配器getAdapter(adapters: string | string[]): AxiosAdapter;import { getAdapter } from axios; // 显式获取 fetch 适配器 const fetchAdapter getAdapter(fetch); // 从优先级列表中获取当前环境可用的最优适配器 const adapter getAdapter([fetch, xhr, http]);实现见 lib/adapters/adapters.js内置knownAdapters只注册三个适配器httpNode.js、xhr浏览器 XHR、fetchfetch API按列表顺序逐个尝试第一个被当前环境支持的适配器胜出fetch在构建裁剪环境下经adapter.get(config)判定可用性全部不可用时抛出AxiosErrorcode: ERR_NOT_SUPPORT错误消息会逐条列出每个候选的失败原因is not supported by the environment 或 is not available in the build未知的适配器名直接抛Unknown adapter xxx。这解释了配置中adapter: [xhr, http]这类写法的行为它是一份降级优先级列表而非固定选择。5.10mergeConfig深度合并两个 axios 配置对象策略与 axios 内部默认值 请求选项合并完全一致后者优先mergeConfigD any, P any( config1: AxiosRequestConfigD, P, config2: AxiosRequestConfigD, P ): AxiosRequestConfigD, P;import { mergeConfig } from axios; const base { baseURL: https://api.example.com, timeout: 5000 }; const override { timeout: 10000, headers: { X-Custom: value } }; const merged mergeConfig(base, override); // { baseURL: https://api.example.com, timeout: 10000, headers: { X-Custom: value } }lib/core/mergeConfig.js 中维护了一张mergeMap按字段类别采用不同策略——这正是理解为什么timeout会覆盖而url必须来自请求方的关键valueFromConfig2后者优先没有则无值url、method、data——这三项属于请求本身defaultToConfig2后者优先缺省回退前者baseURL、timeout、transformRequest、transformResponse、paramsSerializer、withCredentials、adapter、responseType、xsrfCookieName、xsrfHeaderName、onUploadProgress、onDownloadProgress、maxContentLength、maxBodyLength、httpAgent/httpsAgent、socketPath、beforeRedirect等mergeDirectKeysvalidateStatus单独处理以兼容validateStatus: undefined的语义变化受transitional.validateStatusUndefinedResolves控制headers两边先各自转为普通对象再做不区分大小写的深度合并caseless: true其余未知字段走通用的mergeDeepProperties两侧都是普通对象时递归合并数组则浅拷贝。另外合并结果对象采用空原型Object.create(null)构造避免被污染的Object.prototype注入配置值__proto__/constructor/prototype键在遍历时被显式跳过。六、常量HttpStatusCodeHttpStatusCode是一个把 HTTP 状态码映射为命名常量的对象用于以可读方式书写状态判断而非魔法数字import axios, { HttpStatusCode } from axios; try { const response await axios.get(/api/resource); } catch (error) { if (axios.isAxiosError(error)) { if (error.response?.status HttpStatusCode.NotFound) { console.error(Resource not found); } else if (error.response?.status HttpStatusCode.Unauthorized) { console.error(Authentication required); } } }查看 lib/helpers/HttpStatusCode.js 可以确认其覆盖范围与两个特性双向映射对象末尾会遍历自身把码 → 名的反向映射也补全不覆盖已存在项因此HttpStatusCode[404] NotFound成立命名沿革PayloadTooLarge413、UnprocessableEntity422被标记deprecated建议改用更贴近 RFC 9110 用语的ContentTooLarge、UnprocessableContent旧名保留以兼容。常用成员示例Ok: 200、Created: 201、NoContent: 204、PartialContent: 206、NotFound: 404、TooManyRequests: 429、InternalServerError: 500、BadGateway: 502、ServiceUnavailable: 503以及RequestTimeout: 408/GatewayTimeout: 504等。七、其他VERSIONVERSION是字符串形式的当前包版本号随每次发版更新当前为1.19.0见 package.json。可用于日志上报或特性开关判断import axios from axios; console.log(axios.VERSION); // 1.19.0八、API 稳定性与迁移提示汇总结合文档与源码可归纳出几条使用准则取消请求新代码一律使用AbortControllersignal配合axios.isCancel(error)判别CancelToken含subscribe/unsubscribe/toAbortSignal与Cancel别名仅为存量代码保留并发请求用Promise.all替代axios.allspread可保留用于位置传参场景错误判别统一通过isAxiosError/isCancel做鸭子类型判别避免instanceof跨 realm 场景下不可靠状态码判断优先使用HttpStatusCode常量并注意 413/422 的推荐新名公开类型在 TS 项目里为D/P提供显式泛型可以让paramsSerializer、错误处理与response.config获得完整的参数类型推断。以上每一项 API 的行为均可在对应源码文件中复核实例组装在 lib/axios.js请求管线在 lib/core/Axios.js头部/错误/合并逻辑分别在 lib/core/AxiosHeaders.js、lib/core/AxiosError.js、lib/core/mergeConfig.js取消语义在 lib/cancel/CanceledError.js 与 lib/cancel/CancelToken.js适配器选择在 lib/adapters/adapters.js类型契约在 index.d.ts。【免费下载链接】axiosPromise based HTTP client for the browser and node.js项目地址: https://gitcode.com/GitHub_Trending/ax/axios创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考