method实例

一个 method 实例对应一个请求信息描述，它拥有一次请求的 url、请求头、请求参数，以及响应数据处理、缓存数据处理等请求行为参数。通过 method 实例，你可以在任意的 js 环境下感受到统一的使用体验，只需要非常少的改动就可以正常运行起来，此外，method 实例将请求参数和请求行为参数放在了一起，更便于 api 的管理，而不是分散在多个代码文件中。

PromiseLike 特性

在[v2.16.0]之后，method 实例是一个 PromiseLike 实例，它拥有then/catch/finally函数，因此你可以按如下方式使用：

// 调用method的then函数
method.then(res => {
  console.log(res);
});

// 捕获异常
method.catch(e => {
  console.log(e);
});

// 请求完成调用
method.finally(() => {
  console.log('请求完成');
});

此外，也可以通过await method来发送请求。

new Method()

自定义创建 method 实例。

• 类型

interface MethodConstructor {
  new (
    type: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'PATCH',
    context: Alova,
    url: string,
    config?: AlovaMethodCreateConfig,
    data?: Arg | string | FormData | Blob | ArrayBuffer | URLSearchParams | ReadableStream
  ): Method;
  readonly prototype: Method;
}

• 参数

1. type：请求类型
2. context：alova 实例
3. url：请求 url
4. config：配置参数, 类型与alova.Get的 config 参数类型一致
5. data：请求体数据

• 示例

import { Method } from 'alova';
import { alovaInstance } from './api';

const method = new Method('GET', alovaInstance, '/api/users', {
  params: {
    id: 1
  }
});

getMethodKey()

获取 method 的 key 值，此 key 值作为 alova 内部缓存 key 使用。

• 类型

function getMethodKey(method: Method): string;

• 参数

1. method：method 实例

• 返回

传入的 method 实例的 key 值。

• 示例

import { getMethodKey } from 'alova';

const method = alova.Get('/api/users');
const methodKey = getMethodKey(method);

matchSnapshotMethod()

以method 匹配器的匹配方式获取已经请求过的 method 实例快照，并返回匹配的结果。

• 类型

type MethodFilter =
  | string
  | RegExp
  | {
      name?: string | RegExp;
      filter?: MethodFilterHandler;
      alova?: Alova;
    };
function matchSnapshotMethod(
  matcher: MethodFilter,
  matchAll?: boolean
): Method[] | Method | undefined;

• 参数

1. matcher：method 匹配器
2. matchAll：是否匹配全部，默认为 true

• 返回

matchAll 为 true 时返回 method 实例数组，否则返回 method 实例或 undefined

• 示例

import { matchSnapshotMethod } from 'alova';

await alova.Get('/api/users');
const snapshotMethod = matchSnapshotMethod({
  name: 'user',
  filter(method, i, methodArray) {
    return method.url.includes('users');
  },
  alova: alova
});

method.headers

请求头。

• 类型

interface Method {
  headers?: any;
}

method.baseURL

请求的基础路径，继承于alova 实例。

• 类型

interface Method {
  baseURL: string;
}

method.url

创建 method 实例的 url。

• 类型

interface Method {
  url: string;
}

method.type

请求类型。

• 类型:

interface Method {
  type: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'PATCH';
}

method.data

请求 body。

• 类型

interface Method {
  data?: any;
}

method.context

创建当前 method 的 alova 实例。

• 类型

interface Method {
  context: Alova;
}

method.hitSource

打击源方法实例，当源方法实例请求成功时，当前方法实例的缓存将被失效。作为自动失效功能，只需设置打击源即可，而不需要手动调用invalidateCache失效缓存。此外，此功能在错综复杂的失效关系中比invalidateCache方法更简洁有效，该字段值可设置为 method 实例、其他 method 实例的 name、name 正则匹配，或者它们的数组。

• 类型

interface Method {
  hitSource?: Method | string | RegExp | (Method | string | RegExp)[];
}

method.meta

method 的 元数据，用于记录请求特性信息，详情查看。

• 类型

interface Method {
  meta?: any;
}

method.config

通过alova.Get/alova.Post等方法创建 method 时的配置信息，详情查看。

• 类型

interface Method {
  config: AlovaMethodCreateConfig;
}

method.fromCache

当前请求的数据是否来自缓存。

• 类型

interface Method {
  fromCache: boolean;
}

method.send()

使用此 method 实例直接发送请求，在[v2.16.0]之后发送请求可省略调用此方法。

• 类型

interface Method {
  send(forceRequest?: boolean): Promise<Response>;
}

• 参数

1. forceRequest：是否强制请求，默认为 false

• 返回

附带响应数据的 Promise 实例。

• 示例

const method = alova.Get('/api/users');
const response = await method.send();

method.abort()

中止当前请求。

• 类型

interface Method {
  abort(): void;
}

• 示例

const method = alova.Get('/api/users');
method.abort();

method.then()

在[v2.16.0]之后，method 实例是一个 PromiseLike 实例，可直接调用此方法或await method发送请求，获得响应数据。

• 类型

interface Method {
  then(
    onFulfilled?: (value: Response) => any,
    onRejected?: (reason: any) => any
  ): Promise<Response>;
}

• 参数

1. onFulfilled：请求成功时的回调函数
2. onRejected：请求失败时的回调函数

• 返回

附带响应数据的 Promise 实例。

• 示例

const method = alova.Get('/api/users');
const response = await method;

method.catch()

在[v2.16.0]之后，method 实例是一个 PromiseLike 实例，可直接调用此方法发送请求，并捕获错误。

• 类型

interface Method {
  catch<TResult = never>(
    onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | undefined | null
  ): Promise<Response | TResult>;
}

• 参数

1. onrejected：请求错误时的回调函数

• 返回

Promise 实例。

• 示例

const method = alova.Get('/api/users');
const response = await method.catch(error => {
  console.error('请求错误');
});

method.finally()

在[v2.16.0]之后，method 实例是一个 PromiseLike 实例，可直接调用此方法发送请求，并处理响应完成。

• 类型

interface Method {
  finally(onfinally?: (() => void) | undefined | null): Promise<Response>;
}

• 返回

Promise 实例。

• 示例

const method = alova.Get('/api/users');
const response = await method.finally(() => {
  console.log('请求完成');
});

method.onDownload()

绑定下载事件，可获得下载进度信息。

• 类型

interface Method {
  onDownload(handler: ProgressHandler): () => void;
}

• 参数

1. handler下载事件回调函数

• 返回

解绑函数

• 示例

const method = alova.Get('/api/download_file');
const offEvent = method.onDownload(event => {
  console.log('文件大小：', event.total);
  console.log('已下载：', event.loaded);
});

offEvent();

method.onUpload()

绑定上传事件，可获得上传进度信息。

• 类型

interface Method {
  onUpload(handler: ProgressHandler): () => void;
}

• 参数

1. handler上传事件回调函数

• 返回

解绑函数

• 示例

const method = alova.Get('/api/upload_file', formData);
const offEvent = method.onUpload(event => {
  console.log('文件大小：', event.total);
  console.log('已上传：', event.loaded);
});

offEvent();

method.setName()

设置 method 实例的 name。

• 类型

interface Method {
  setName(name: string | number): void;
}

• 参数

1. name：method 实例的 name

• 返回

无

• 示例

const method = alova.Get('/api/users', {
  name: 'user'
});
method.setName('newUser');