企业官网建设流程全解析

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 及其源码位置：

二、Instance：默认实例 axios

axios实例是你发起 HTTP 请求时使用的主要对象。它本质上是一个工厂函数创建的Axios类实例，同时自身也是一个可调用对象。这一点在 lib/axios.js 的createInstance中体现得非常清楚：

function createInstance(defaultConfig) { const context = new Axios(defaultConfig); const instance = bind(Axios.prototype.request, context); // 实例本身 = 绑定了 request 的函数 // 把 Axios.prototype 上的方法全部拷贝到 instance（get/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);

由此可以得到三个实用结论：

1. axios(url[, config])可以直接当request调用——因为instance就是Axios.prototype.request绑定后的函数；
2. instance.create()会基于当前默认配置派生新实例，且派生时通过mergeConfig合并默认值，这正是mergeConfig公开 API 的另一个应用场景；
3. 方法别名get/post/put/patch/delete/head/options/query以及对应的postForm/putForm/patchForm都在Axios类上通过utils.forEach批量生成，详见 请求方法别名 文档。

三、TypeScript 请求类型：<D, P>双泛型体系

这是本次 API 文档中新增的重点。公开的请求类型使用独立泛型分别描述请求体与查询参数：

AxiosRequestConfig<D = any, P = any> RawAxiosRequestConfig<D = any, P = any> InternalAxiosRequestConfig<D = any, P = any> AxiosDefaults<D = any, P = any> CreateAxiosDefaults<D = any, P = any> AxiosResponse<T = any, D = any, H = {}, P = any> AxiosPromise<T = any, D = any, P = any> AxiosError<T = unknown, D = any, P = any> CanceledError<T, D = any, P = any>

其中D是请求体（data）的类型，P是查询参数（params）的类型。以下 API 会在配置中同时保留D和P：

• AxiosResponse/AxiosPromise
• 错误类型（AxiosError、CanceledError）
• 默认值类型（AxiosDefaults、CreateAxiosDefaults）
• 可调用实例与各请求别名方法
• 各适配器（adapter）
• mergeConfig()
• 自定义参数序列化器（paramsSerializer也能拿到同一个P）

请求方法的泛型顺序为<T, R, D, P>，其中P被追加在最后，以保证已有的显式泛型调用（例如axios.get<T>(url)）保持兼容。行为约定：

• 未显式指定响应类型R时，默认的AxiosResponse会在response.config中保留D和P；
• 显式指定R时，R继续控制 Promise 的 resolve 值；
• 数据与参数泛型默认值均为any，以维持向后兼容。

这些类型声明均可在 index.d.ts 中逐一定义核对，例如AxiosRequestConfig上data?: D、params?: P的声明，以及AxiosHeaders.parseParameters的静态方法签名。

四、核心类

4.1Axios

Axios是发起 HTTP 请求的主类。构造函数接受一个可选的默认配置对象：

constructor(instanceConfig?: AxiosRequestConfig);

对应源码 lib/core/Axios.js：

class Axios { constructor(instanceConfig) { this.defaults = instanceConfig || {}; this.interceptors = { request: new InterceptorManager(), response: new InterceptorManager(), }; } // ... }

可见每个实例持有两样东西：默认配置defaults与请求/响应拦截器管理器。

request方法

request是发起请求的主方法，接受配置对象并返回 Promise：

request<T, R, D, P>(config: AxiosRequestConfig<D, P>): Promise<R>;

从源码结构看（lib/core/Axios.js），request内部委托给_request，其执行链路为：

1. URL 快捷形式：axios('example/url', config)支持类 fetch 的调用方式，字符串参数会被移入config.url；
2. 配置合并：config = mergeConfig(this.defaults, config)——每次请求都会把实例默认配置与本次配置深度合并；
3. 配置校验：transitional、paramsSerializer等字段会经validator.assertOptions校验，写错的baseUrl/withXsrfToken会收到拼写纠正提示；
4. 方法归一化：config.method依次取请求配置、实例默认值，兜底为'get'，并转为小写；
5. 请求头扁平化：合并headers.common与headers[method]后删除方法占位键，最终通过AxiosHeaders.concat归一为AxiosHeaders实例；
6. 拦截器链组装：请求拦截器按注册顺序压入dispatchRequest之前，响应拦截器追加在其后，最终形成一个 Promise 链；同步请求拦截器则走同步执行分支，减少微任务开销。

request外层还包了一层 try/catch：若错误没有stack（部分环境/自定义 Error 可能缺失），会用Error.captureStackTrace构造一份兜底调用栈附加到错误对象上——这是当前版本对可观测性的一个增强。

此外，Axios还提供getUri(config)：将默认配置与传入配置合并后，经buildFullPath与buildURL（拼接查询参数）计算出最终完整 URL，适合调试链接。

4.2CancelToken（已废弃，推荐AbortController）

CancelToken基于早期的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.1AxiosError

AxiosError是请求失败时抛出的错误类，继承Error并附加 axios 专属属性：

constructor(message?: string, code?: string, config?: InternalAxiosRequestConfig<D, P>, request?: any, response?: AxiosResponse<T, D, {}, P>);

实例属性如下：

// 请求配置实例 config?: InternalAxiosRequestConfig<D, P>; // 错误码（如 'ETIMEDOUT'、'ECONNABORTED'） code?: string; // 请求对象 request?: any; // 响应对象 response?: AxiosResponse<T, 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、浏览器隔离环境）传递，判别依然可靠，不依赖instanceof；
• status在存在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.2AxiosHeaders

AxiosHeaders是管理 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 控制字符、DEL（0x7F）以及首尾空格/制表符，保证头部值符合 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）的强化 map：

const headers = new AxiosHeaders({ 'Content-Type': 'multipart/form-data; boundary="a,b"', }); console.log({ ...headers.get('Content-Type', AxiosHeaders.parseParameters), }); // { boundary: "a,b" }

其解析规则（对应 lib/core/AxiosHeaders.js 的parseParameters状态机）：

• 参数名大小写不敏感（统一转小写存储）；
• 引号包裹的字符串值会剥离两侧引号并解码\"、\\转义；
• 引号内的逗号、分号作为值的一部分保留（因此boundary="a,b"不会被错误切分）；
• 仅剔除无引号值两侧 RFC 定义的可选空白（OWS：空格与制表符）；
• 结果 map 为Object.create(null)，并显式跳过__proto__、constructor、prototype三个名字，防止原型链污染；
• 参数名需匹配^[!#$%&'*+\-.^_|~0-9A-Za-z]+$` 白名单，非法名字直接丢弃。

get(name, true)仍是旧版轻量 tokenizer，两者定位不同，迁移时按需选择。

has/delete/clear

has(header: string, matcher?: AxiosHeaderMatcher): boolean; delete(header: string | string[], matcher?: AxiosHeaderMatcher): boolean; clear(matcher?: AxiosHeaderMatcher): boolean;

matcher支持三种形态：函数（(value, header) => boolean）、字符串（子串包含）、正则（test）。delete接受单键或数组，clear可清空全部头部；两者返回值均表示"是否确实删除了内容"。

normalize

normalize(format: boolean): AxiosHeaders;

归一化头部对象：合并重复键（值聚为数组），并把键名转为trim后的小写形式；format为true时进一步格式化为 Pascal-Case 首字母大写形式（如content-type→Content-Type）。

concat

concat(...targets: Array<AxiosHeaders | RawAxiosHeaders | string | undefined | null>): AxiosHeaders;

按参数顺序合并多组头部，返回新实例（底层是static concat：以第一个对象新建实例后依次set其余目标）。axios 内部合并headers.common与headers[method]时用的就是它。

toJSON/toString

toJSON(asStrings: true): Record<string, string>; toJSON(asStrings?: false): Record<string, string | string[]>; toString(): string;

toJSON(true)会把数组值用', '连接为字符串；toString()输出"无 CRLF 分隔的 HTTP 头部块"——每个name: value对一行，换行分隔（见 lib/core/AxiosHeaders.js）。

另外源码中还有几个未在文档正文展开但确实存在的能力：类实例可用Symbol.iterator迭代（等价于遍历toJSON()的 entries）；static accessor(headers)会为指定头部动态生成getContentType()/setContentType(v)/hasContentType()访问器，内置已为Content-Type、Content-Length、Accept、Accept-Encoding、User-Agent、Authorization六个常用头部注册（见 lib/core/AxiosHeaders.js）；getSetCookie()保证Set-Cookie多值以数组形式返回。

5.3CanceledError与Cancel别名

请求被取消时抛出CanceledError，它继承自AxiosError：

constructor(message?: string, config?: InternalAxiosRequestConfig<D, P>, request?: any); __CANCEL__?: boolean;

源码 lib/cancel/CanceledError.js 显示其固定行为：code取AxiosError.ERR_CANCELED（'ERR_CANCELED'），name为'CanceledError'，并打上__CANCEL__ = true标记。Cancel仅是CanceledError的兼容别名（lib/axios.js 中axios.Cancel = axios.CanceledError），未来版本会移除。

5.4isCancel

判断错误是否为取消错误，用于区分"用户主动取消"和"真实故障"：

isCancel<T = any, D = any, P = any>(value: any): value is CanceledError<T, 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（已废弃）与spread

all自 0.22.0 起废弃，请直接使用Promise.all。源码层面它现在就是透传（lib/axios.js）：

axios.all = function all(promises) { return Promise.all(promises); };

spread把数组解包为函数参数，适合在Promise.all之后把多个响应按位置传给回调：

spread<T, 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.8formToJSON

FormData反转为普通 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 中的包装：传入<form>HTML 元素时会自动先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只注册三个适配器：http（Node.js）、xhr（浏览器 XHR）、fetch（fetch API）；
• 按列表顺序逐个尝试，第一个被当前环境支持的适配器胜出（fetch在构建裁剪环境下经adapter.get(config)判定可用性）；
• 全部不可用时抛出AxiosError（code: 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 内部"默认值 + 请求选项"合并完全一致，后者优先：

mergeConfig<D = any, P = any>( config1: AxiosRequestConfig<D, P>, config2: AxiosRequestConfig<D, P> ): AxiosRequestConfig<D, 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等；
• mergeDirectKeys：validateStatus单独处理以兼容validateStatus: undefined的语义变化（受transitional.validateStatusUndefinedResolves控制）；
• headers：两边先各自转为普通对象再做不区分大小写的深度合并（caseless: true）；
• 其余未知字段走通用的mergeDeepProperties（两侧都是普通对象时递归合并，数组则浅拷贝）。

另外合并结果对象采用空原型（Object.create(null)）构造，避免被污染的Object.prototype注入配置值；__proto__/constructor/prototype键在遍历时被显式跳过。

六、常量：HttpStatusCode

HttpStatusCode是一个把 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 可以确认其覆盖范围与两个特性：

1. 双向映射：对象末尾会遍历自身，把"码 → 名"的反向映射也补全（不覆盖已存在项），因此HttpStatusCode[404] === 'NotFound'成立；
2. 命名沿革：PayloadTooLarge（413）、UnprocessableEntity（422）被标记@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等。

七、其他：VERSION

VERSION是字符串形式的当前包版本号，随每次发版更新（当前为1.19.0，见 package.json）。可用于日志上报或特性开关判断：

import axios from 'axios'; console.log(axios.VERSION); // "1.19.0"

八、API 稳定性与迁移提示汇总

结合文档与源码，可归纳出几条使用准则：

1. 取消请求：新代码一律使用AbortController+signal，配合axios.isCancel(error)判别；CancelToken（含subscribe/unsubscribe/toAbortSignal）与Cancel别名仅为存量代码保留；
2. 并发请求：用Promise.all替代axios.all；spread可保留用于位置传参场景；
3. 错误判别：统一通过isAxiosError/isCancel做鸭子类型判别，避免instanceof（跨 realm 场景下不可靠）；
4. 状态码判断：优先使用HttpStatusCode常量，并注意 413/422 的推荐新名；
5. 公开类型：在 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