feat: fileName 替换为 name

docs/config/download.md

@@ -11,8 +11,6 @@ axios
     {
       // 指定文件下载后存储的路径 (本地路径)，选填
       filePath: '',
-      // 指定文件下载后存储的名称，选填
-      fileName: '',
     },
     {
       download: true,

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,

src/adapter.ts

@@ -25,15 +25,36 @@ export type AxiosAdapterRequestMethod =
   | 'CONNECT';
 
 export interface AxiosAdapterResponse<TData = unknown> 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 {
+export interface AxiosAdapterUploadOptions
-  filePath: string;
+  extends AxiosAdapterBaseOptions,
-  name: string;
+    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,
+      name,
-      fileName: fileName,
+      /**
+       * [钉钉小程序用 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);

src/axios.ts

@@ -12,23 +12,63 @@ import { AxiosAdapter, createAdapter, AxiosPlatform } from './adapter';
 import defaults from './defaults';
 
 export interface AxiosInstanceDefaults extends AxiosRequestConfig {
+  /**
+   * 请求头
+   */
   headers: Required<AxiosRequestHeaders>;
 }
 
 export interface AxiosInstance extends Axios {
+  /**
+   * 默认请求配置
+   */
   defaults: AxiosInstanceDefaults;
-  <TData = unknown>(config: AxiosRequestConfig): Promise<AxiosResponse<TData>>;
+  <TData = unknown>(
-  <TData = unknown>(url: string, config?: AxiosRequestConfig): Promise<
+    /**
-    AxiosResponse<TData>
+     * 请求配置
-  >;
+     */
+    config: AxiosRequestConfig,
+  ): Promise<AxiosResponse<TData>>;
+  <TData = unknown>(
+    /**
+     * 请求地址
+     */
+    url: string,
+    /**
+     * 请求配置
+     */
+    config?: AxiosRequestConfig,
+  ): Promise<AxiosResponse<TData>>;
 }
 
 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;
 }
 

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<TData = unknown>
   extends AxiosAdapterResponse<TData> {
+  /**
+   * 请求配置
+   */
   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 {
+  <TData = unknown>(
+    /**
+     * 请求地址
+     */
+    url: string,
+    /**
+     * 请求配置
+     */
+    config?: AxiosRequestConfig,
+  ): Promise<AxiosResponse<TData>>;
+}
+
+export interface AxiosWithParamsAliasMethod {
+  <TData = unknown>(
+    /**
+     * 请求地址
+     */
+    url: string,
+    /**
+     * 请求参数
+     */
+    params?: AnyObject,
+    /**
+     * 请求配置
+     */
+    config?: AxiosRequestConfig,
+  ): Promise<AxiosResponse<TData>>;
+}
+
+export interface AxiosWithDataAliasMethod {
+  <TData = unknown>(
+    /**
+     * 请求地址
+     */
+    url: string,
+    /**
+     * 请求数据
+     */
+    data?: AnyObject,
+    /**
+     * 请求配置
+     */
+    config?: AxiosRequestConfig,
+  ): Promise<AxiosResponse<TData>>;
+}
+
 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<AxiosRequestConfig>(),
+    /**
+     * 响应拦截器
+     */
     response: new InterceptorManager<AxiosResponse>(),
   };
 
-  public options!: <TData = unknown>(
+  /**
-    url: string,
+   * 发送 options 请求
-    config?: AxiosRequestConfig,
+   */
-  ) => Promise<AxiosResponse<TData>>;
+  public options!: AxiosAliasMethod;
 
-  public get!: <TData = unknown>(
+  /**
-    url: string,
+   * 发送 get 请求
-    params?: AnyObject,
+   */
-    config?: AxiosRequestConfig,
+  public get!: AxiosWithParamsAliasMethod;
-  ) => Promise<AxiosResponse<TData>>;
 
-  public head!: <TData = unknown>(
+  /**
-    url: string,
+   * 发送 head 请求
-    params?: AnyObject,
+   */
-    config?: AxiosRequestConfig,
+  public head!: AxiosWithParamsAliasMethod;
-  ) => Promise<AxiosResponse<TData>>;
 
-  public post!: <TData = unknown>(
+  /**
-    url: string,
+   * 发送 post 请求
-    data?: AnyObject | AxiosRequestFormData,
+   */
-    config?: AxiosRequestConfig,
+  public post!: AxiosWithDataAliasMethod;
-  ) => Promise<AxiosResponse<TData>>;
 
-  public put!: <TData = unknown>(
+  /**
-    url: string,
+   * 发送 put 请求
-    data?: AnyObject | AxiosRequestFormData,
+   */
-    config?: AxiosRequestConfig,
+  public put!: AxiosWithDataAliasMethod;
-  ) => Promise<AxiosResponse<TData>>;
 
-  public delete!: <TData = unknown>(
+  /**
-    url: string,
+   * 发送 delete 请求
-    params?: AnyObject,
+   */
-    config?: AxiosRequestConfig,
+  public delete!: AxiosWithParamsAliasMethod;
-  ) => Promise<AxiosResponse<TData>>;
 
-  public trace!: <TData = unknown>(
+  /**
-    url: string,
+   * 发送 trace 请求
-    config?: AxiosRequestConfig,
+   */
-  ) => Promise<AxiosResponse<TData>>;
+  public trace!: AxiosAliasMethod;
 
-  public connect!: <TData = unknown>(
+  /**
-    url: string,
+   * 发送 connect 请求
-    config?: AxiosRequestConfig,
+   */
-  ) => Promise<AxiosResponse<TData>>;
+  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<TData = unknown>(
     config: AxiosRequestConfig,
   ): Promise<AxiosResponse<TData>> {

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;
 }
 

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(

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;
   }

src/index.ts

@@ -2,6 +2,7 @@ import axios from './axios';
 
 export type {
   AxiosRequestConfig,
+  AxiosRequestData,
   AxiosRequestFormData,
   AxiosResponse,
   AxiosResponseError,

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,
     };