axios API 参考详解实例、请求类型、错误体系与工具函数的完整手册【免费下载链接】axiosPromise based HTTP client for the browser and node.js项目地址: https://gitcode.com/GitHub_Trending/ax/axios本文基于 axios 仓库的 API 参考文档系统梳理当前版本中所有可用的公共 APIaxios实例、Axios核心类、TypeScript 泛型请求类型、错误类体系AxiosError/CanceledError、请求头工具类AxiosHeaders以及toFormData、getAdapter、mergeConfig等函数与HttpStatusCode常量。每个 API 均给出类型签名、用法示例并结合仓库源码说明其底层实现位置与行为细节帮助你既能正确调用这些 API也能理解它们背后的设计。API 总览与导出入口axios 遵循语义化版本承诺在不发布主版本变更的情况下以下所有函数和类将保持稳定不变。所有 API 既可以从包入口以命名导入的方式获取也可以作为axios默认导出对象的静态属性访问。包入口 index.js 将默认导出解包为命名导出完整导出列表如下导出类型说明axios默认导出、create函数实例工厂函数Axios类发起 HTTP 请求的核心类AxiosError类请求失败时抛出的错误类AxiosHeaders类HTTP 请求头管理工具类CanceledError、Cancel类请求取消错误Cancel为向后兼容别名CancelToken类已废弃请改用AbortControllerisCancel、isAxiosError函数错误类型守卫all、spread函数Promise 辅助函数all已废弃toFormData、formToJSON函数对象与FormData互转getAdapter、mergeConfig函数适配器解析与配置合并HttpStatusCode常量对象HTTP 状态码命名常量VERSION字符串当前版本号这些静态属性的挂载逻辑集中在 lib/axios.js 中例如axios.AxiosError AxiosError、axios.AxiosHeaders AxiosHeaders、axios.getAdapter adapters.getAdapter因此import axios from axios后访问axios.xxx与命名导入是等价的。实例axios与createaxios实例是你发起 HTTP 请求的主要对象它是一个创建Axios类新实例的工厂函数。实例提供了get、post、put、delete、patch、query以及对应的xxxForm请求方法详见仓库文档中的请求别名章节。从源码看默认实例由 lib/axios.js 中的createInstance函数创建function createInstance(defaultConfig) { const context new Axios(defaultConfig); const instance bind(Axios.prototype.request, context); // Copy axios.prototype to instance utils.extend(instance, Axios.prototype, context, { allOwnKeys: true }); // Copy context to instance utils.extend(instance, context, null, { allOwnKeys: true }); // Factory for creating new instances instance.create function create(instanceConfig) { return createInstance(mergeConfig(defaultConfig, instanceConfig)); }; return instance; } // Create the default instance to be exported const axios createInstance(defaults);这段实现揭示了三个关键事实你直接调用的axios(config)、axios.get(url)最终都汇聚到Axios.prototype.request通过bind绑定到内部 context 上实例同时拷贝了Axios.prototype的方法与 context 的属性defaults、interceptors等所以拦截器、默认配置在实例上都是可访问的instance.create(instanceConfig)会以mergeConfig(defaultConfig, instanceConfig)为基础派生新实例——这是基于现有实例再定制的标准做法新实例的默认配置是父实例默认配置与增量配置的合并结果。默认实例的初始配置来自 lib/defaults/index.js。TypeScript 请求类型公共请求类型使用不同的泛型分别表示请求数据和查询参数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是请求体类型P是查询参数类型。AxiosResponse、AxiosPromise、错误、默认配置、可调用实例、请求别名、适配器和mergeConfig()都会在请求配置中保留这两种类型自定义参数序列化器会接收同一个P。请求方法使用T, R, D, P的泛型顺序将P添加在最后因此现有的显式泛型参数保持兼容。未提供自定义响应类型R时默认AxiosResponse会在response.config中保留D和P显式提供的R仍然控制最终返回值。为保持向后兼容请求数据和参数泛型均默认为any。类型声明本身位于仓库根目录的 index.d.ts需要严格类型校验时可对照该文件。类AxiosAxios类是发起 HTTP 请求的核心类实现位于 lib/core/Axios.js。constructor创建一个新的Axios实例构造函数接受一个可选的配置对象作为参数constructor(instanceConfig?: AxiosRequestConfig);源码实现非常简洁lib/core/Axios.js#L22-L29class Axios { constructor(instanceConfig) { this.defaults instanceConfig || {}; this.interceptors { request: new InterceptorManager(), response: new InterceptorManager(), }; } // ... }即每个实例只持有两样东西默认配置defaults和一对拦截器管理器。Axios类还被显式导出axios.Axios Axios目的是允许类继承——你可以class MyClient extends Axios扩展自定义客户端。request处理请求调用和响应解析是发起 HTTP 请求的核心方法requestT, R, D, P(config: AxiosRequestConfigD, P): PromiseR;_request内部流程lib/core/Axios.js#L82-L258可以概括为支持 fetch 风格的axios(url[, config])调用字符串参数会被包装为{ url }通过mergeConfig(this.defaults, config)合并实例默认配置与请求级配置请求级配置优先校验transitional选项与paramsSerializer允许直接传函数会自动包装为{ serialize }解析method缺省为get并压平按方法分组的请求头headers.common与headers[config.method]最终生成AxiosHeaders实例组装拦截器链请求拦截器按注册顺序串联runWhen返回false的拦截器会被跳过中间插入dispatchRequest再串联响应拦截器返回 Promise。Axios类还提供getUri(config)方法它只做mergeConfig→buildFullPath→buildURL的组合用于在不发送请求的情况下生成完整 URL含查询参数适合生成跳转链接或调试。方法别名get/post等在类文件底部统一生成lib/core/Axios.js#L267-L306无数据方法delete、get、head、options签名为method(url, config)有数据方法post、put、patch、query签名为method(url, data, config)并额外生成postForm、putForm、patchForm快捷方法自动设置Content-Type: multipart/form-data。错误体系AxiosError与CanceledErrorAxiosErrorAxiosError类是 HTTP 请求失败时抛出的错误类继承自Error并添加了额外属性实现位于 lib/core/AxiosError.js。constructorconstructor(message?: string, code?: string, config?: InternalAxiosRequestConfigD, P, request?: any, response?: AxiosResponseT, D, {}, P);构造函数会将response.status同步到error.status并把isAxiosError true标记写入实例——这正是isAxiosError类型守卫的判定依据。properties// 配置实例。 config?: InternalAxiosRequestConfigD, P; // 错误代码。 code?: string; // 请求实例。 request?: any; // 响应实例。 response?: AxiosResponseT, D, {}, P; // 表示该错误是否为 AxiosError 的布尔值。 isAxiosError: boolean; // 错误状态码。 status?: number; // 将错误转换为 JSON 对象的辅助方法。 toJSON: () object; // 错误原因。 cause?: Error;源码中还有两点值得注意的实现细节除构造函数外类上还有一个静态方法AxiosError.from(error, code, config, request, response, customProps)lib/core/AxiosError.js#L99-L131用于把任意原生错误如 Node 的连接错误包装成AxiosError并保留cause链toJSON()支持可选的敏感字段脱敏当请求配置中带有redact键值数组时序列化出的config快照中对应字段不区分大小写、任意深度会被替换为[REDACTED ****]。类上还定义了一组常见错误码常量供与error.code比较ECONNABORTED、ETIMEDOUT、ECONNREFUSED、ERR_NETWORK、ERR_CANCELED、ERR_BAD_RESPONSE、ERR_BAD_REQUEST、ERR_NOT_SUPPORT、ERR_FR_TOO_MANY_REDIRECTS、ERR_INVALID_URL等lib/core/AxiosError.js#L204-L217。isAxiosError检查某个错误是否为AxiosError的函数。在catch块中使用此函数可安全访问 axios 特有的错误属性如error.response和error.configisAxiosError(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; } }实现只有一行lib/helpers/isAxiosError.js判断对象上isAxiosError true对应单元测试见 tests/unit/helpers/isAxiosError.test.js。CanceledErrorCanceledError类是 HTTP 请求被取消时抛出的错误类继承自AxiosErrorconstructor(message?: string, config?: InternalAxiosRequestConfigD, P, request?: any); __CANCEL__?: boolean;源码lib/cancel/CanceledError.js中它固定使用错误码AxiosError.ERR_CANCELED并打上__CANCEL__ true标记class CanceledError extends AxiosError { constructor(message, config, request) { super(message null ? canceled : message, AxiosError.ERR_CANCELED, config, request); this.name CanceledError; this.__CANCEL__ true; } }CancelCancel是CanceledError的别名为向后兼容而保留导出将在未来版本中移除Cancel: typeof CanceledError;在 lib/axios.js#L63 中可见其定义axios.Cancel axios.CanceledError。isCancel检查某个错误是否为CanceledError的函数可用于区分主动取消和意外错误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);实现同样极简lib/cancel/isCancel.js检查value.__CANCEL__标记与上面CanceledError构造函数中的赋值相互印证。类CancelToken已废弃CancelToken类基于tc39/proposal-cancelable-promises提案用于创建可取消 HTTP 请求的令牌。该类现已废弃推荐使用AbortControllerAPI。从 0.22.0 版本起CancelToken类已废弃将在未来版本中移除。建议改用AbortControllerAPI。该类主要为了向后兼容而保留导出未来将被移除。我们强烈不建议在新项目中使用下面的旧版互操作辅助方法仅为已有代码列出。这些旧版方法仍为现有集成提供类型subscribe(listener: (cancel: Cancel | any) void): void; unsubscribe(listener: (cancel: Cancel | any) void): void; toAbortSignal(): AbortSignal;其中toAbortSignal()是把旧CancelToken桥接到新AbortController世界的关键方法它内部创建一个AbortController把abort回调订阅到 token 的取消信号上使两套取消机制可以互通实现见 lib/cancel/CancelToken.js#L105-L117。类AxiosHeadersAxiosHeaders类是用于管理 HTTP 请求头的工具类提供添加、删除和获取请求头等操作方法实现位于 lib/core/AxiosHeaders.js。请求管线中所有配置头实例默认头、方法头、请求头最终都会通过AxiosHeaders.concat归一化为该类的实例因此了解它对调试请求行为很有帮助。此处仅列出主要方法完整方法列表请参阅类型声明文件 index.d.ts。constructor创建一个新的AxiosHeaders实例构造函数接受一个可选的请求头对象作为参数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#L203-L257set支持三种输入形态单个name/value对、普通对象或AxiosHeaders实例、以及可迭代的键值对重复键会被合并为数组传入无法识别为合法头名的长字符串时会按原始头块文本解析parseHeaders。rewrite为true时强制覆盖已有同名头。get从请求头对象获取一个请求头get(headerName: string, parser: typeof AxiosHeaders.parseParameters): AxiosHeaderParameters; get(headerName: string, parser: RegExp): RegExpExecArray | null; get(headerName: string, matcher?: true | AxiosHeaderParser): AxiosHeaderValue;传入AxiosHeaders.parseParameters可将规范化的 HTTP 参数解析为安全的、原型为 null 的映射const headers new AxiosHeaders({ Content-Type: multipart/form-data; boundarya,b, }); console.log({ ...headers.get(Content-Type, AxiosHeaders.parseParameters), }); // { boundary: a,b }参数名称不区分大小写。解析器会移除带引号字符串的定界引号解码转义的引号和反斜杠保留带引号值中的逗号和分号并且只移除不带引号值两侧的 RFC 可选空白。它会忽略__proto__、constructor和prototype。get(name, true)仍是旧版分词器。这一行为在 lib/core/AxiosHeaders.js#L92-L149 的parseParameters函数中实现字符级状态机处理引号与转义parameterNameRE白名单校验参数名并在归一化后显式过滤原型污染键名。而get(name, true)走的是更早期的parseTokens正则分词。has检查请求头对象中是否存在某个请求头has(header: string, matcher?: AxiosHeaderMatcher): boolean;delete从请求头对象移除一个请求头delete(header: string | string[], matcher?: AxiosHeaderMatcher): boolean;clear从请求头对象移除所有请求头clear(matcher?: AxiosHeaderMatcher): boolean;matcher可以是字符串子串匹配、正则或函数delete/clear都会按该条件选择性移除返回值表示是否发生了删除。normalize规范化请求头对象normalize(format: boolean): AxiosHeaders;format为true时把头名格式化为首字母大写驼峰如content-type→Content-Type否则仅去除首尾空白同时合并大小写不同的重复键。concat合并多个请求头对象concat(...targets: ArrayAxiosHeaders | RawAxiosHeaders | string | undefined | null): AxiosHeaders;静态版本AxiosHeaders.concat(first, ...targets)会基于first构造新实例再依次set各目标因此原对象不被修改。toJSON将请求头对象转换为 JSON 对象toJSON(asStrings: true): Recordstring, string; toJSON(asStrings?: false): Recordstring, string | string[];asStrings为true时数组值会用, 连接成字符串返回对象使用 null 原型创建可避免原型污染风险。toString将请求头返回为不含 CRLF 的 HTTP 请求头块每行一个name: value键值对toString(): string;此外类通过AxiosHeaders.accessor为Content-Type、Content-Length、Accept、Accept-Encoding、User-Agent、Authorization六个常用头生成了getContentLength()/setContentLength()之类的驼峰访问器日常代码里可以直接headers.getContentType()。函数Promise 辅助与表单工具all已废弃all函数接受一组 Promise 并返回一个在所有 Promise 都完成后才完成的单一 Promise现已废弃推荐使用Promise.all方法。从 0.22.0 版本起all函数已废弃将在未来版本中移除。建议改用Promise.all方法。当前实现就是Promise.all的薄封装lib/axios.js#L66-L68axios.all function all(promises) { return Promise.all(promises); };spreadspread函数可将一个参数数组展开为函数调用的多个参数在你需要将数组参数传递给接收多个参数的函数时非常实用spreadT, R(callback: (...args: T[]) R): (array: T[]) R;实现见 lib/helpers/spread.jsexport default function spread(callback) { return function wrap(arr) { return callback.apply(null, arr); }; }典型用法axios.all([p1, p2]).then(axios.spread(([user, repos]) { /* ... */ }))all废弃后等价于Promise.allspread。toFormData将普通 JavaScript 对象包括嵌套对象转换为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);第二个参数允许把转换结果追加进已存在的FormData第三个参数FormSerializerOptions可控制可见性、深度限制depth、日期/数组/访客值格式化等行为完整选项见 index.d.ts。嵌套深度超过上限会抛出AxiosError.ERR_FORM_DATA_DEPTH_EXCEEDED。formToJSON将FormData实例转换回普通 JavaScript 对象在需要以结构化格式读取表单数据时非常实用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 } }只有点号和方括号表示法具有结构含义.、[和]会分隔路径而-、空格、、*和会保留在字面键中。foo.bar和foo[bar]会创建嵌套对象foo[]会创建数组。这一语义由 lib/helpers/formDataToJSON.js 中的parsePropPath正则/[^.[\]]|\[([^.[\]]*)]/g实现。另外通过axios.formToJSON调用时还支持直接传入 HTML 表单元素入口会自动执行new FormData(form)lib/axios.js#L80。函数适配器与配置合并getAdapter通过名称或名称数组解析并返回一个适配器函数。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。内置适配器只有三个knownAdaptershttpNode.js、xhr浏览器 XMLHttpRequest、fetchfetch API。函数按列表顺序逐个尝试第一个在当前环境可用的适配器胜出全部不可用时会抛出带ERR_NOT_SUPPORT错误码的AxiosError错误信息中会列出每个候选被拒绝的原因not supported by the environment 或 not available in the build。也可以直接传入适配器函数而非名称。各适配器的实现分别位于 lib/adapters/http.js、lib/adapters/xhr.js、lib/adapters/fetch.js其选择策略详见仓库文档的适配器章节。mergeConfig合并两个 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可以看出它并非简单深拷贝合并策略按属性类别分派——method、data、url等标量类属性直接取config2的值headers走AxiosHeaders归一化后合并区分大小写无关baseURL、transformRequest等走config2 优先、否则回退 config1的策略纯对象属性则递归深合并。合并结果使用 null 原型对象构造避免下游读取config.auth等属性时继承被污染的原型值。请求管线中Axios.prototype._request的第一步就是调用它lib/core/Axios.js#L92所以对外暴露的mergeConfig与内部行为完全一致可用于在自定义实例工厂中精确复现 axios 的合并规则。常量HttpStatusCode包含 HTTP 状态码命名常量的对象可用于编写更具可读性的条件判断避免直接使用数字字面量实现位于 lib/helpers/HttpStatusCode.jsimport 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); } } }该常量对象覆盖了 1xx 到 5xx 的常用状态码Ok: 200、NoContent: 204、NotFound: 404、TooManyRequests: 429、InternalServerError: 500等。值得注意的是源码在末尾还做了一次反向映射lib/helpers/HttpStatusCode.js#L82-L86数字键映射回名称字符串即HttpStatusCode[404]得到NotFound适合在日志中把状态码转成人类可读文案。此外PayloadTooLarge、UnprocessableEntity已被标注废弃分别应使用ContentTooLarge、UnprocessableContent。其他VERSIONaxios.VERSION是axios包的当前版本号字符串随每次发布更新。源码中它来自构建时生成的数据模块lib/axios.js#L12import { VERSION } from ./env/data.js因此打包产物中的版本号与发布的 npm 包版本保持一致可用于运行时日志或按版本做特性开关判断。小结axios 的公共 API 面可以归纳为三层请求层axios实例与Axios类通过request方法加拦截器链完成请求派发create支持派生实例错误层AxiosError含ERR_*错误码与toJSON脱敏、CanceledError与isCancel/isAxiosError两个类型守卫配合AbortController取代已废弃的CancelToken工具层AxiosHeaders管理请求头toFormData/formToJSON处理表单互转getAdapter/mergeConfig暴露了内部适配器解析与配置合并逻辑HttpStatusCode与VERSION提供可读性常量。所有 API 的语义以当前仓库的 index.d.ts 类型声明为准行为实现以lib/下对应源码为准测试用例集中在 tests/unit 目录可用于验证各 API 的边界行为。【免费下载链接】axiosPromise based HTTP client for the browser and node.js项目地址: https://gitcode.com/GitHub_Trending/ax/axios创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 axios API 参考详解：实例、请求类型、错误体系与工具函数的完整手册
axios API 参考详解实例、请求类型、错误体系与工具函数的完整手册【免费下载链接】axiosPromise based HTTP client for the browser and node.js项目地址: https://gitcode.com/GitHub_Trending/ax/axios本文基于 axios 仓库的 API 参考文档系统梳理当前版本中所有可用的公共 APIaxios实例、Axios核心类、TypeScript 泛型请求类型、错误类体系AxiosError/CanceledError、请求头工具类AxiosHeaders以及toFormData、getAdapter、mergeConfig等函数与HttpStatusCode常量。每个 API 均给出类型签名、用法示例并结合仓库源码说明其底层实现位置与行为细节帮助你既能正确调用这些 API也能理解它们背后的设计。API 总览与导出入口axios 遵循语义化版本承诺在不发布主版本变更的情况下以下所有函数和类将保持稳定不变。所有 API 既可以从包入口以命名导入的方式获取也可以作为axios默认导出对象的静态属性访问。包入口 index.js 将默认导出解包为命名导出完整导出列表如下导出类型说明axios默认导出、create函数实例工厂函数Axios类发起 HTTP 请求的核心类AxiosError类请求失败时抛出的错误类AxiosHeaders类HTTP 请求头管理工具类CanceledError、Cancel类请求取消错误Cancel为向后兼容别名CancelToken类已废弃请改用AbortControllerisCancel、isAxiosError函数错误类型守卫all、spread函数Promise 辅助函数all已废弃toFormData、formToJSON函数对象与FormData互转getAdapter、mergeConfig函数适配器解析与配置合并HttpStatusCode常量对象HTTP 状态码命名常量VERSION字符串当前版本号这些静态属性的挂载逻辑集中在 lib/axios.js 中例如axios.AxiosError AxiosError、axios.AxiosHeaders AxiosHeaders、axios.getAdapter adapters.getAdapter因此import axios from axios后访问axios.xxx与命名导入是等价的。实例axios与createaxios实例是你发起 HTTP 请求的主要对象它是一个创建Axios类新实例的工厂函数。实例提供了get、post、put、delete、patch、query以及对应的xxxForm请求方法详见仓库文档中的请求别名章节。从源码看默认实例由 lib/axios.js 中的createInstance函数创建function createInstance(defaultConfig) { const context new Axios(defaultConfig); const instance bind(Axios.prototype.request, context); // Copy axios.prototype to instance utils.extend(instance, Axios.prototype, context, { allOwnKeys: true }); // Copy context to instance utils.extend(instance, context, null, { allOwnKeys: true }); // Factory for creating new instances instance.create function create(instanceConfig) { return createInstance(mergeConfig(defaultConfig, instanceConfig)); }; return instance; } // Create the default instance to be exported const axios createInstance(defaults);这段实现揭示了三个关键事实你直接调用的axios(config)、axios.get(url)最终都汇聚到Axios.prototype.request通过bind绑定到内部 context 上实例同时拷贝了Axios.prototype的方法与 context 的属性defaults、interceptors等所以拦截器、默认配置在实例上都是可访问的instance.create(instanceConfig)会以mergeConfig(defaultConfig, instanceConfig)为基础派生新实例——这是基于现有实例再定制的标准做法新实例的默认配置是父实例默认配置与增量配置的合并结果。默认实例的初始配置来自 lib/defaults/index.js。TypeScript 请求类型公共请求类型使用不同的泛型分别表示请求数据和查询参数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是请求体类型P是查询参数类型。AxiosResponse、AxiosPromise、错误、默认配置、可调用实例、请求别名、适配器和mergeConfig()都会在请求配置中保留这两种类型自定义参数序列化器会接收同一个P。请求方法使用T, R, D, P的泛型顺序将P添加在最后因此现有的显式泛型参数保持兼容。未提供自定义响应类型R时默认AxiosResponse会在response.config中保留D和P显式提供的R仍然控制最终返回值。为保持向后兼容请求数据和参数泛型均默认为any。类型声明本身位于仓库根目录的 index.d.ts需要严格类型校验时可对照该文件。类AxiosAxios类是发起 HTTP 请求的核心类实现位于 lib/core/Axios.js。constructor创建一个新的Axios实例构造函数接受一个可选的配置对象作为参数constructor(instanceConfig?: AxiosRequestConfig);源码实现非常简洁lib/core/Axios.js#L22-L29class Axios { constructor(instanceConfig) { this.defaults instanceConfig || {}; this.interceptors { request: new InterceptorManager(), response: new InterceptorManager(), }; } // ... }即每个实例只持有两样东西默认配置defaults和一对拦截器管理器。Axios类还被显式导出axios.Axios Axios目的是允许类继承——你可以class MyClient extends Axios扩展自定义客户端。request处理请求调用和响应解析是发起 HTTP 请求的核心方法requestT, R, D, P(config: AxiosRequestConfigD, P): PromiseR;_request内部流程lib/core/Axios.js#L82-L258可以概括为支持 fetch 风格的axios(url[, config])调用字符串参数会被包装为{ url }通过mergeConfig(this.defaults, config)合并实例默认配置与请求级配置请求级配置优先校验transitional选项与paramsSerializer允许直接传函数会自动包装为{ serialize }解析method缺省为get并压平按方法分组的请求头headers.common与headers[config.method]最终生成AxiosHeaders实例组装拦截器链请求拦截器按注册顺序串联runWhen返回false的拦截器会被跳过中间插入dispatchRequest再串联响应拦截器返回 Promise。Axios类还提供getUri(config)方法它只做mergeConfig→buildFullPath→buildURL的组合用于在不发送请求的情况下生成完整 URL含查询参数适合生成跳转链接或调试。方法别名get/post等在类文件底部统一生成lib/core/Axios.js#L267-L306无数据方法delete、get、head、options签名为method(url, config)有数据方法post、put、patch、query签名为method(url, data, config)并额外生成postForm、putForm、patchForm快捷方法自动设置Content-Type: multipart/form-data。错误体系AxiosError与CanceledErrorAxiosErrorAxiosError类是 HTTP 请求失败时抛出的错误类继承自Error并添加了额外属性实现位于 lib/core/AxiosError.js。constructorconstructor(message?: string, code?: string, config?: InternalAxiosRequestConfigD, P, request?: any, response?: AxiosResponseT, D, {}, P);构造函数会将response.status同步到error.status并把isAxiosError true标记写入实例——这正是isAxiosError类型守卫的判定依据。properties// 配置实例。 config?: InternalAxiosRequestConfigD, P; // 错误代码。 code?: string; // 请求实例。 request?: any; // 响应实例。 response?: AxiosResponseT, D, {}, P; // 表示该错误是否为 AxiosError 的布尔值。 isAxiosError: boolean; // 错误状态码。 status?: number; // 将错误转换为 JSON 对象的辅助方法。 toJSON: () object; // 错误原因。 cause?: Error;源码中还有两点值得注意的实现细节除构造函数外类上还有一个静态方法AxiosError.from(error, code, config, request, response, customProps)lib/core/AxiosError.js#L99-L131用于把任意原生错误如 Node 的连接错误包装成AxiosError并保留cause链toJSON()支持可选的敏感字段脱敏当请求配置中带有redact键值数组时序列化出的config快照中对应字段不区分大小写、任意深度会被替换为[REDACTED ****]。类上还定义了一组常见错误码常量供与error.code比较ECONNABORTED、ETIMEDOUT、ECONNREFUSED、ERR_NETWORK、ERR_CANCELED、ERR_BAD_RESPONSE、ERR_BAD_REQUEST、ERR_NOT_SUPPORT、ERR_FR_TOO_MANY_REDIRECTS、ERR_INVALID_URL等lib/core/AxiosError.js#L204-L217。isAxiosError检查某个错误是否为AxiosError的函数。在catch块中使用此函数可安全访问 axios 特有的错误属性如error.response和error.configisAxiosError(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; } }实现只有一行lib/helpers/isAxiosError.js判断对象上isAxiosError true对应单元测试见 tests/unit/helpers/isAxiosError.test.js。CanceledErrorCanceledError类是 HTTP 请求被取消时抛出的错误类继承自AxiosErrorconstructor(message?: string, config?: InternalAxiosRequestConfigD, P, request?: any); __CANCEL__?: boolean;源码lib/cancel/CanceledError.js中它固定使用错误码AxiosError.ERR_CANCELED并打上__CANCEL__ true标记class CanceledError extends AxiosError { constructor(message, config, request) { super(message null ? canceled : message, AxiosError.ERR_CANCELED, config, request); this.name CanceledError; this.__CANCEL__ true; } }CancelCancel是CanceledError的别名为向后兼容而保留导出将在未来版本中移除Cancel: typeof CanceledError;在 lib/axios.js#L63 中可见其定义axios.Cancel axios.CanceledError。isCancel检查某个错误是否为CanceledError的函数可用于区分主动取消和意外错误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);实现同样极简lib/cancel/isCancel.js检查value.__CANCEL__标记与上面CanceledError构造函数中的赋值相互印证。类CancelToken已废弃CancelToken类基于tc39/proposal-cancelable-promises提案用于创建可取消 HTTP 请求的令牌。该类现已废弃推荐使用AbortControllerAPI。从 0.22.0 版本起CancelToken类已废弃将在未来版本中移除。建议改用AbortControllerAPI。该类主要为了向后兼容而保留导出未来将被移除。我们强烈不建议在新项目中使用下面的旧版互操作辅助方法仅为已有代码列出。这些旧版方法仍为现有集成提供类型subscribe(listener: (cancel: Cancel | any) void): void; unsubscribe(listener: (cancel: Cancel | any) void): void; toAbortSignal(): AbortSignal;其中toAbortSignal()是把旧CancelToken桥接到新AbortController世界的关键方法它内部创建一个AbortController把abort回调订阅到 token 的取消信号上使两套取消机制可以互通实现见 lib/cancel/CancelToken.js#L105-L117。类AxiosHeadersAxiosHeaders类是用于管理 HTTP 请求头的工具类提供添加、删除和获取请求头等操作方法实现位于 lib/core/AxiosHeaders.js。请求管线中所有配置头实例默认头、方法头、请求头最终都会通过AxiosHeaders.concat归一化为该类的实例因此了解它对调试请求行为很有帮助。此处仅列出主要方法完整方法列表请参阅类型声明文件 index.d.ts。constructor创建一个新的AxiosHeaders实例构造函数接受一个可选的请求头对象作为参数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#L203-L257set支持三种输入形态单个name/value对、普通对象或AxiosHeaders实例、以及可迭代的键值对重复键会被合并为数组传入无法识别为合法头名的长字符串时会按原始头块文本解析parseHeaders。rewrite为true时强制覆盖已有同名头。get从请求头对象获取一个请求头get(headerName: string, parser: typeof AxiosHeaders.parseParameters): AxiosHeaderParameters; get(headerName: string, parser: RegExp): RegExpExecArray | null; get(headerName: string, matcher?: true | AxiosHeaderParser): AxiosHeaderValue;传入AxiosHeaders.parseParameters可将规范化的 HTTP 参数解析为安全的、原型为 null 的映射const headers new AxiosHeaders({ Content-Type: multipart/form-data; boundarya,b, }); console.log({ ...headers.get(Content-Type, AxiosHeaders.parseParameters), }); // { boundary: a,b }参数名称不区分大小写。解析器会移除带引号字符串的定界引号解码转义的引号和反斜杠保留带引号值中的逗号和分号并且只移除不带引号值两侧的 RFC 可选空白。它会忽略__proto__、constructor和prototype。get(name, true)仍是旧版分词器。这一行为在 lib/core/AxiosHeaders.js#L92-L149 的parseParameters函数中实现字符级状态机处理引号与转义parameterNameRE白名单校验参数名并在归一化后显式过滤原型污染键名。而get(name, true)走的是更早期的parseTokens正则分词。has检查请求头对象中是否存在某个请求头has(header: string, matcher?: AxiosHeaderMatcher): boolean;delete从请求头对象移除一个请求头delete(header: string | string[], matcher?: AxiosHeaderMatcher): boolean;clear从请求头对象移除所有请求头clear(matcher?: AxiosHeaderMatcher): boolean;matcher可以是字符串子串匹配、正则或函数delete/clear都会按该条件选择性移除返回值表示是否发生了删除。normalize规范化请求头对象normalize(format: boolean): AxiosHeaders;format为true时把头名格式化为首字母大写驼峰如content-type→Content-Type否则仅去除首尾空白同时合并大小写不同的重复键。concat合并多个请求头对象concat(...targets: ArrayAxiosHeaders | RawAxiosHeaders | string | undefined | null): AxiosHeaders;静态版本AxiosHeaders.concat(first, ...targets)会基于first构造新实例再依次set各目标因此原对象不被修改。toJSON将请求头对象转换为 JSON 对象toJSON(asStrings: true): Recordstring, string; toJSON(asStrings?: false): Recordstring, string | string[];asStrings为true时数组值会用, 连接成字符串返回对象使用 null 原型创建可避免原型污染风险。toString将请求头返回为不含 CRLF 的 HTTP 请求头块每行一个name: value键值对toString(): string;此外类通过AxiosHeaders.accessor为Content-Type、Content-Length、Accept、Accept-Encoding、User-Agent、Authorization六个常用头生成了getContentLength()/setContentLength()之类的驼峰访问器日常代码里可以直接headers.getContentType()。函数Promise 辅助与表单工具all已废弃all函数接受一组 Promise 并返回一个在所有 Promise 都完成后才完成的单一 Promise现已废弃推荐使用Promise.all方法。从 0.22.0 版本起all函数已废弃将在未来版本中移除。建议改用Promise.all方法。当前实现就是Promise.all的薄封装lib/axios.js#L66-L68axios.all function all(promises) { return Promise.all(promises); };spreadspread函数可将一个参数数组展开为函数调用的多个参数在你需要将数组参数传递给接收多个参数的函数时非常实用spreadT, R(callback: (...args: T[]) R): (array: T[]) R;实现见 lib/helpers/spread.jsexport default function spread(callback) { return function wrap(arr) { return callback.apply(null, arr); }; }典型用法axios.all([p1, p2]).then(axios.spread(([user, repos]) { /* ... */ }))all废弃后等价于Promise.allspread。toFormData将普通 JavaScript 对象包括嵌套对象转换为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);第二个参数允许把转换结果追加进已存在的FormData第三个参数FormSerializerOptions可控制可见性、深度限制depth、日期/数组/访客值格式化等行为完整选项见 index.d.ts。嵌套深度超过上限会抛出AxiosError.ERR_FORM_DATA_DEPTH_EXCEEDED。formToJSON将FormData实例转换回普通 JavaScript 对象在需要以结构化格式读取表单数据时非常实用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 } }只有点号和方括号表示法具有结构含义.、[和]会分隔路径而-、空格、、*和会保留在字面键中。foo.bar和foo[bar]会创建嵌套对象foo[]会创建数组。这一语义由 lib/helpers/formDataToJSON.js 中的parsePropPath正则/[^.[\]]|\[([^.[\]]*)]/g实现。另外通过axios.formToJSON调用时还支持直接传入 HTML 表单元素入口会自动执行new FormData(form)lib/axios.js#L80。函数适配器与配置合并getAdapter通过名称或名称数组解析并返回一个适配器函数。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。内置适配器只有三个knownAdaptershttpNode.js、xhr浏览器 XMLHttpRequest、fetchfetch API。函数按列表顺序逐个尝试第一个在当前环境可用的适配器胜出全部不可用时会抛出带ERR_NOT_SUPPORT错误码的AxiosError错误信息中会列出每个候选被拒绝的原因not supported by the environment 或 not available in the build。也可以直接传入适配器函数而非名称。各适配器的实现分别位于 lib/adapters/http.js、lib/adapters/xhr.js、lib/adapters/fetch.js其选择策略详见仓库文档的适配器章节。mergeConfig合并两个 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可以看出它并非简单深拷贝合并策略按属性类别分派——method、data、url等标量类属性直接取config2的值headers走AxiosHeaders归一化后合并区分大小写无关baseURL、transformRequest等走config2 优先、否则回退 config1的策略纯对象属性则递归深合并。合并结果使用 null 原型对象构造避免下游读取config.auth等属性时继承被污染的原型值。请求管线中Axios.prototype._request的第一步就是调用它lib/core/Axios.js#L92所以对外暴露的mergeConfig与内部行为完全一致可用于在自定义实例工厂中精确复现 axios 的合并规则。常量HttpStatusCode包含 HTTP 状态码命名常量的对象可用于编写更具可读性的条件判断避免直接使用数字字面量实现位于 lib/helpers/HttpStatusCode.jsimport 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); } } }该常量对象覆盖了 1xx 到 5xx 的常用状态码Ok: 200、NoContent: 204、NotFound: 404、TooManyRequests: 429、InternalServerError: 500等。值得注意的是源码在末尾还做了一次反向映射lib/helpers/HttpStatusCode.js#L82-L86数字键映射回名称字符串即HttpStatusCode[404]得到NotFound适合在日志中把状态码转成人类可读文案。此外PayloadTooLarge、UnprocessableEntity已被标注废弃分别应使用ContentTooLarge、UnprocessableContent。其他VERSIONaxios.VERSION是axios包的当前版本号字符串随每次发布更新。源码中它来自构建时生成的数据模块lib/axios.js#L12import { VERSION } from ./env/data.js因此打包产物中的版本号与发布的 npm 包版本保持一致可用于运行时日志或按版本做特性开关判断。小结axios 的公共 API 面可以归纳为三层请求层axios实例与Axios类通过request方法加拦截器链完成请求派发create支持派生实例错误层AxiosError含ERR_*错误码与toJSON脱敏、CanceledError与isCancel/isAxiosError两个类型守卫配合AbortController取代已废弃的CancelToken工具层AxiosHeaders管理请求头toFormData/formToJSON处理表单互转getAdapter/mergeConfig暴露了内部适配器解析与配置合并逻辑HttpStatusCode与VERSION提供可读性常量。所有 API 的语义以当前仓库的 index.d.ts 类型声明为准行为实现以lib/下对应源码为准测试用例集中在 tests/unit 目录可用于验证各 API 的边界行为。【免费下载链接】axiosPromise based HTTP client for the browser and node.js项目地址: https://gitcode.com/GitHub_Trending/ax/axios创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考