diff --git a/docs/config/download.md b/docs/config/download.md index a630cd3..38b050e 100644 --- a/docs/config/download.md +++ b/docs/config/download.md @@ -11,8 +11,6 @@ axios { // 指定文件下载后存储的路径 (本地路径),选填 filePath: '', - // 指定文件下载后存储的名称,选填 - fileName: '', }, { download: true, diff --git a/docs/config/upload.md b/docs/config/upload.md index 9df4d51..b9d7ce1 100644 --- a/docs/config/upload.md +++ b/docs/config/upload.md @@ -9,14 +9,12 @@ axios.post( '/file', { // 文件名称,必填 - fileName: 'image.png', + name: 'image.png', // 文件路径,必填 filePath: '/file/image.png', - // 文件类型,选填 - fileType: 'image' | 'video' | 'audio'; // 可以传入更多自定义字段,这些自定义字段最终会以 formData 的形式发送给服务端 (前提是平台支持) custom1: 'name', - custom2: 'id' + custom2: 'id', }, { upload: true, diff --git a/src/adapter.ts b/src/adapter.ts index 33324b2..f95a157 100644 --- a/src/adapter.ts +++ b/src/adapter.ts @@ -25,15 +25,36 @@ export type AxiosAdapterRequestMethod = | 'CONNECT'; export interface AxiosAdapterResponse extends AnyObject { + /** + * 状态码 + */ status: number; + /** + * 状态字符 + */ statusText: string; + /** + * 响应头 + */ headers: AnyObject; + /** + * 响应数据 + */ data: TData; } export interface AxiosAdapterResponseError extends AnyObject { + /** + * 状态码 + */ status: number; + /** + * 状态字符 + */ statusText: string; + /** + * 响应头 + */ headers: AnyObject; } @@ -90,17 +111,15 @@ export interface AxiosAdapterBaseOptions extends AxiosAdapterRequestConfig { fail(error: unknown): void; } -export interface AxiosAdapterUploadOptions extends AxiosAdapterBaseOptions { - filePath: string; - name: string; +export interface AxiosAdapterUploadOptions + extends AxiosAdapterBaseOptions, + AxiosRequestFormData { fileName: string; - fileType: 'image' | 'video' | 'audio'; formData?: AnyObject; } export interface AxiosAdapterDownloadOptions extends AxiosAdapterBaseOptions { filePath?: string; - fileName?: string; } export interface AxiosAdapterRequest { @@ -149,7 +168,6 @@ export function getAdapterDefault(): AxiosAdapter | undefined { while (!isEmptyArray(tryGetPlatforms) && !isPlatform(platform)) { try { const tryGetPlatform = tryGetPlatforms.shift(); - if (isPlainObject((platform = tryGetPlatform!()))) { platform = revisePlatformApiNames(platform); } @@ -176,49 +194,54 @@ export function createAdapter(platform: AxiosPlatform): AxiosAdapter { switch (config.type) { case 'request': - return callRequest(platform.request, baseOptions); + return processRequest(platform.request, baseOptions); case 'upload': - return callUpload(platform.upload, baseOptions); + return processUpload(platform.upload, baseOptions); case 'download': - return callDownload(platform.download, baseOptions); + return processDownload(platform.download, baseOptions); default: throwError(`无法识别的请求类型 ${config.type}`); } } - function callRequest( + function processRequest( request: AxiosAdapterRequest, baseOptions: AxiosAdapterBaseOptions, ): AxiosAdapterTask { return request(baseOptions); } - function callUpload( + function processUpload( upload: AxiosAdapterUpload, baseOptions: AxiosAdapterBaseOptions, ): AxiosAdapterTask { - const { fileName, filePath, fileType, ...formData } = + const { name, filePath, fileType, ...formData } = baseOptions.data as AxiosRequestFormData; const options = { ...baseOptions, - name: fileName, - fileName: fileName, + name, + /** + * [钉钉小程序用 fileName 代替 name](https://open.dingtalk.com/document/orgapp/dd-upload-objects#title-ngk-rr1-eow) + */ + fileName: name, filePath, - fileType: fileType ?? 'image', + /** + * 钉钉小程序|支付宝小程序特有参数 + */ + fileType, formData, }; return upload(options); } - function callDownload( + function processDownload( download: AxiosAdapterDownload, baseOptions: AxiosAdapterBaseOptions, ): AxiosAdapterTask { const options = { ...baseOptions, filePath: baseOptions.params?.filePath, - fileName: baseOptions.params?.fileName, success(response: AnyObject): void { injectDownloadData(response); baseOptions.success(response); diff --git a/src/axios.ts b/src/axios.ts index 7867542..7c48b9c 100644 --- a/src/axios.ts +++ b/src/axios.ts @@ -12,23 +12,63 @@ import { AxiosAdapter, createAdapter, AxiosPlatform } from './adapter'; import defaults from './defaults'; export interface AxiosInstanceDefaults extends AxiosRequestConfig { + /** + * 请求头 + */ headers: Required; } export interface AxiosInstance extends Axios { + /** + * 默认请求配置 + */ defaults: AxiosInstanceDefaults; - (config: AxiosRequestConfig): Promise>; - (url: string, config?: AxiosRequestConfig): Promise< - AxiosResponse - >; + ( + /** + * 请求配置 + */ + config: AxiosRequestConfig, + ): Promise>; + ( + /** + * 请求地址 + */ + url: string, + /** + * 请求配置 + */ + config?: AxiosRequestConfig, + ): Promise>; } export interface AxiosStatic extends AxiosInstance { + /** + * Axios 类 + */ Axios: AxiosConstructor; + /** + * 取消令牌 + */ CancelToken: CancelTokenConstructor; + /** + * 创建 axios 实例 + * + * @param defaults 默认配置 + */ create(defaults?: AxiosRequestConfig): AxiosInstance; + /** + * 创建适配器 + * + * @param platform 平台 + */ createAdapter(platform: AxiosPlatform): AxiosAdapter; + /** + * 判断 Cancel + */ isCancel: typeof isCancel; + /** + * 判断 AxiosError + */ isAxiosError: typeof isAxiosError; } diff --git a/src/core/Axios.ts b/src/core/Axios.ts index 59187ce..ae6fb21 100644 --- a/src/core/Axios.ts +++ b/src/core/Axios.ts @@ -25,23 +25,57 @@ export type AxiosRequestMethod = | 'connect'; export interface AxiosRequestHeaders extends AnyObject { + /** + * 通用请求头 + */ common?: AnyObject; + /** + * options 请求头 + */ options?: AnyObject; + /** + * get 请求头 + */ get?: AnyObject; + /** + * head 请求头 + */ head?: AnyObject; + /** + * post 请求头 + */ post?: AnyObject; + /** + * put 请求头 + */ put?: AnyObject; + /** + * delete 请求头 + */ delete?: AnyObject; + /** + * trace 请求头 + */ trace?: AnyObject; + /** + * connect 请求头 + */ connect?: AnyObject; } export interface AxiosRequestFormData extends AnyObject { - fileName: string; + /** + * 文件名 + */ + name: string; + /** + * 文件路径 + */ filePath: string; - fileType?: 'image' | 'video' | 'audio'; } +export type AxiosRequestData = AnyObject | AxiosRequestFormData; + export interface AxiosProgressEvent { progress: number; totalBytesSent: number; @@ -72,7 +106,7 @@ export interface AxiosRequestConfig /** * 请求数据 */ - data?: AnyObject | AxiosRequestFormData; + data?: AxiosRequestData; /** * 请求头 */ @@ -125,13 +159,28 @@ export interface AxiosRequestConfig export interface AxiosResponse extends AxiosAdapterResponse { + /** + * 请求配置 + */ config?: AxiosRequestConfig; + /** + * 请求任务 + */ request?: AxiosAdapterTask; } export interface AxiosResponseError extends AxiosAdapterResponseError { + /** + * 原生接口 fail 回调产生的响应错误 + */ isFail: true; + /** + * 请求配置 + */ config?: AxiosRequestConfig; + /** + * 请求任务 + */ request?: AxiosAdapterTask; } @@ -139,63 +188,131 @@ export interface AxiosConstructor { new (config: AxiosRequestConfig): Axios; } +export interface AxiosAliasMethod { + ( + /** + * 请求地址 + */ + url: string, + /** + * 请求配置 + */ + config?: AxiosRequestConfig, + ): Promise>; +} + +export interface AxiosWithParamsAliasMethod { + ( + /** + * 请求地址 + */ + url: string, + /** + * 请求参数 + */ + params?: AnyObject, + /** + * 请求配置 + */ + config?: AxiosRequestConfig, + ): Promise>; +} + +export interface AxiosWithDataAliasMethod { + ( + /** + * 请求地址 + */ + url: string, + /** + * 请求数据 + */ + data?: AnyObject, + /** + * 请求配置 + */ + config?: AxiosRequestConfig, + ): Promise>; +} + export default class Axios { + /** + * 普通请求别名 + */ public static as = ['options', 'trace', 'connect'] as const; + /** + * 带请求参数的请求别名 + */ public static pas = ['head', 'get', 'delete'] as const; + /** + * 带请求数据的请求别名 + */ public static das = ['post', 'put'] as const; + /** + * 默认请求配置 + */ public defaults: AxiosRequestConfig; + /** + * 拦截器 + */ public interceptors = { + /** + * 请求拦截器 + */ request: new InterceptorManager(), + /** + * 响应拦截器 + */ response: new InterceptorManager(), }; - public options!: ( - url: string, - config?: AxiosRequestConfig, - ) => Promise>; + /** + * 发送 options 请求 + */ + public options!: AxiosAliasMethod; - public get!: ( - url: string, - params?: AnyObject, - config?: AxiosRequestConfig, - ) => Promise>; + /** + * 发送 get 请求 + */ + public get!: AxiosWithParamsAliasMethod; - public head!: ( - url: string, - params?: AnyObject, - config?: AxiosRequestConfig, - ) => Promise>; + /** + * 发送 head 请求 + */ + public head!: AxiosWithParamsAliasMethod; - public post!: ( - url: string, - data?: AnyObject | AxiosRequestFormData, - config?: AxiosRequestConfig, - ) => Promise>; + /** + * 发送 post 请求 + */ + public post!: AxiosWithDataAliasMethod; - public put!: ( - url: string, - data?: AnyObject | AxiosRequestFormData, - config?: AxiosRequestConfig, - ) => Promise>; + /** + * 发送 put 请求 + */ + public put!: AxiosWithDataAliasMethod; - public delete!: ( - url: string, - params?: AnyObject, - config?: AxiosRequestConfig, - ) => Promise>; + /** + * 发送 delete 请求 + */ + public delete!: AxiosWithParamsAliasMethod; - public trace!: ( - url: string, - config?: AxiosRequestConfig, - ) => Promise>; + /** + * 发送 trace 请求 + */ + public trace!: AxiosAliasMethod; - public connect!: ( - url: string, - config?: AxiosRequestConfig, - ) => Promise>; + /** + * 发送 connect 请求 + */ + public connect!: AxiosAliasMethod; + /** + * 实例化 + * + * @param defaults 默认配置 + */ public constructor(defaults: AxiosRequestConfig = {}) { this.defaults = defaults; @@ -221,7 +338,7 @@ export default class Axios { } for (const alias of Axios.das) { - this[alias] = (url, data, config) => { + this[alias] = (url, data, config = {}) => { return this.request({ ...config, method: alias, @@ -241,6 +358,11 @@ export default class Axios { return buildURL(url, params, paramsSerializer).replace(/^\?/, ''); } + /** + * 发送请求 + * + * @param config 请求配置 + */ public request( config: AxiosRequestConfig, ): Promise> { diff --git a/src/core/cancel.ts b/src/core/cancel.ts index 317515c..452ea37 100644 --- a/src/core/cancel.ts +++ b/src/core/cancel.ts @@ -1,13 +1,29 @@ export interface CancelAction { - (message?: string): void; + ( + /** + * 取消信息 + */ + message?: string, + ): void; } export interface CancelExecutor { - (cancel: CancelAction): void; + ( + /** + * 取消函数 + */ + cancel: CancelAction, + ): void; } export interface CancelTokenSource { + /** + * 取消令牌 + */ token: CancelToken; + /** + * 取消函数 + */ cancel: CancelAction; } diff --git a/src/core/createError.ts b/src/core/createError.ts index 5bd67e6..72e508d 100644 --- a/src/core/createError.ts +++ b/src/core/createError.ts @@ -6,9 +6,7 @@ export type AxiosErrorResponse = AxiosResponse | AxiosResponseError; class AxiosError extends Error { public config: AxiosRequestConfig; - public request: AxiosAdapterTask; - public response: AxiosErrorResponse; public constructor( diff --git a/src/core/transformData.ts b/src/core/transformData.ts index 0091ddd..11dc13f 100644 --- a/src/core/transformData.ts +++ b/src/core/transformData.ts @@ -1,17 +1,24 @@ import { isArray, isUndefined } from '../helpers/isTypes'; -import { AxiosRequestFormData } from './Axios'; +import { AxiosRequestData } from './Axios'; export interface AxiosTransformer { - (data?: AnyObject | AxiosRequestFormData, headers?: AnyObject): - | AnyObject - | AxiosRequestFormData; + ( + /** + * 数据 + */ + data?: AxiosRequestData, + /** + * 头信息 + */ + headers?: AnyObject, + ): AxiosRequestData; } export function transformData( - data?: AnyObject | AxiosRequestFormData, + data?: AxiosRequestData, headers?: AnyObject, transforms?: AxiosTransformer | AxiosTransformer[], -): AnyObject | AxiosRequestFormData | undefined { +): AxiosRequestData | undefined { if (isUndefined(transforms)) { return data; } diff --git a/src/index.ts b/src/index.ts index 02f4027..c17f103 100644 --- a/src/index.ts +++ b/src/index.ts @@ -2,6 +2,7 @@ import axios from './axios'; export type { AxiosRequestConfig, + AxiosRequestData, AxiosRequestFormData, AxiosResponse, AxiosResponseError, diff --git a/test/adapter.test.ts b/test/adapter.test.ts index fa50ee7..dc961e8 100644 --- a/test/adapter.test.ts +++ b/test/adapter.test.ts @@ -50,7 +50,7 @@ describe('src/adapter.ts', () => { type: 'download' as const, url: 'test', method: 'GET' as const, - params: { fileName: '', filePath: '' }, + params: { filePath: '' }, success: noop, fail: noop, };