Token认证拦截器

信息

策略类型：拦截器

版本要求：v1.3.0+

在使用扩展 hooks 前，确保你已熟悉了 alova 的基本使用。

Token 认证拦截器，对基于 token 的登录、登出、token 附带、token 刷新进行统一管理，并支持无感刷新 token。

特性

✨ 统一维护 Token 身份认证的所有代码，包括登录、登出、token 附带、token 刷新等；
✨ 支持在客户端和服务端验证 token 过期，并无感刷新 token；
✨ 依赖 token 的请求自动等待 token 刷新完成再请求；
✨ 使用元数据设置请求身份；
✨ 自动放行不依赖 token 的访客请求；

安装

vue composition
react
svelte

# npm
npm install @alova/scene-vue --save
# yarn
yarn add @alova/scene-vue

# npm
npm install @alova/scene-react --save
# yarn
yarn add @alova/scene-react

# npm
npm install @alova/scene-svelte --save
# yarn
yarn add @alova/scene-svelte

信息

以下所有拦截器都是可选的，只需要选择需要使用的即可。

绑定 Token 认证拦截器

Token 身份认证是通过全局的拦截器完成的，分别提供了createClientTokenAuthentication和createServerTokenAuthentication 用于基于客户端和服务端的身份认证。

基于客户端的身份认证：表示从客户端判断 token 是否过期，例如在登录时获取到的 token 过期时间；
基于服务端的身份认证：表示从服务端返回的状态判断 token 是否过期，例如status为 401 时表示过期；

绑定基于客户端的身份认证的拦截器

import { createClientTokenAuthentication } from '@alova/scene-*';
import { createAlova } from 'alova';

const { onAuthRequired, onResponseRefreshToken } = createClientTokenAuthentication({
  // ...
});

const alovaInstance = createAlova({
  // ...
  beforeRequest: onAuthRequired(method => {
    // ...原请求前拦截器
  }),
  responded: onResponseRefreshToken((response, method) => {
    //...原响应成功拦截器
    return response.json();
  })
});

在onResponseRefreshToken中也可以绑定响应错误和完成的拦截器，也和原来的用法相同。

createAlova({
  // ...
  responded: onResponseRefreshToken({
    onSuccess: (response, method) => {
      //...原响应成功拦截器
    },
    onError: (error, method) => {
      //...原响应错误拦截器
    },
    onComplete: method => {
      //...原响应完成拦截器
    }
  })
});

如果不需要设置拦截器，也可以不传入拦截器函数。

createAlova({
  //...
  beforeRequest: onAuthRequired(),
  responded: onResponseRefreshToken()
});

绑定基于服务端的身份认证拦截器

与基于客户端的用法相同

import { createServerTokenAuthentication } from '@alova/scene-*';
import { createAlova } from 'alova';

const { onAuthRequired, onResponseRefreshToken } = createServerTokenAuthentication({
  // ...
});

const alovaInstance = createAlova({
  // ...
  beforeRequest: onAuthRequired(method => {
    // ...原请求前拦截器
  }),
  responded: onResponseRefreshToken((response, method) => {
    //...原响应成功拦截器
    return response.json();
  })
});

注意

当你使用GlobalFetch适配器时，你可能会遇到TypeError: Failed to execute 'json' on 'Response': body stream already read这个问题，这是因为Response的body stream只能访问一次，你可以response.clone().json()来解决它。

在客户端无感刷新 Token

设置refreshToken并指定 token 是否过期，以及调用刷新 token 的函数就可以了。当 token 刷新完成前，所有依赖 token 的请求都将会等待 token 刷新完成。

createClientTokenAuthentication({
  refreshToken: {
    // 在请求前触发，将接收到method参数，并返回boolean表示token是否过期
    isExpired: method => {
      return tokenExpireTime < Date.now();
    },

    // 当token过期时触发，在此函数中触发刷新token
    handler: async method => {
      const { token, refresh_token } = await refreshToken();
      localStorage.setItem('token', token);
      localStorage.setItem('refresh_token', refresh_token);
    }
  }
});

为了让refreshToken请求顺利通过，需要通过元数据标识authRole为refreshToken。

了解更多元数据的信息，请前往method 元数据。

export const refreshToken = () => {
  const method = alovaInstance.Get('/refresh_token');
  method.meta = {
    authRole: 'refreshToken'
  };
  return method;
};

在服务端无感刷新 Token

与在客户端无感刷新 Token 相同，指定 token 是否过期，以及调用刷新 token 的函数就可以了。当 token 刷新完成前，所有依赖 token 的请求都将会等待 token 刷新完成。

在请求成功拦截器中处理

当使用GlobalFetch时，只要服务端返回了响应数据，就会触发响应成功拦截器，此时我们需要在响应成功拦截器中处理 token 的刷新。

createServerTokenAuthentication({
  refreshTokenOnSuccess: {
    // 响应时触发，可获取到response和method，并返回boolean表示token是否过期
    // 当服务端返回401时，表示token过期
    isExpired: (response, method) => {
      return response.status === 401;
    },

    // 当token过期时触发，在此函数中触发刷新token
    handler: async (response, method) => {
      const { token, refresh_token } = await refreshToken();
      localStorage.setItem('token', token);
      localStorage.setItem('refresh_token', refresh_token);
    }
  }
});

在请求错误拦截器中处理

当使用axios拦截器时，服务端返回了非200/300的状态码就会触发响应错误拦截器，此时我们需要在响应错误拦截器中处理 token 的刷新。

createServerTokenAuthentication({
  refreshTokenOnError: {
    // 响应时触发，可获取到error和method，并返回boolean表示token是否过期
    // 当服务端返回401时，表示token过期
    isExpired: (error, method) => {
      return error.response.status === 401;
    },

    // 当token过期时触发，在此函数中触发刷新token
    handler: async (error, method) => {
      const { token, refresh_token } = await refreshToken();
      localStorage.setItem('token', token);
      localStorage.setItem('refresh_token', refresh_token);
    }
  }
});

为了让refreshToken请求顺利通过，需要通过元数据标识authRole为refreshToken。

了解更多元数据的信息，请前往method 元数据。

export const refreshToken = () => {
  const method = alovaInstance.Get('/refresh_token');
  method.meta = {
    authRole: 'refreshToken'
  };
  return method;
};

放行访客请求

有些接口不需要依赖 token 认证，我们称它们为“访客请求”，此时我们可以设置它们的元数据为authRole: null来绕过前端的拦截，让它们顺利发出请求和接收响应。

export const requestTokenNotRequired = () => {
  const method = alovaInstance.Get('/token_not_required');
  method.meta = {
    authRole: null
  };
  return method;
};

登录拦截

在身份认证拦截器中，你还可以拦截登录请求，在拦截器中保存登录信息，达到统一维护身份认证代码的目的。

首先标识登录请求的元数据为authRole: 'login'。

export const login = () => {
  const method = alovaInstance.Get('/login');
  method.meta = {
    authRole: 'login'
  };
  return method;
};

再在登录拦截器中保存登录信息。

createClientTokenAuthentication({
  login(response, method) {
    localStorage.setItem('token', response.token);
    localStorage.setItem('refresh_token', response.refresh_token);
  }
});

createServerTokenAuthentication的登录拦截器用法相同。

附加 token

通常，我们会在beforeRequest附加 token 到请求信息中。在 Token 认证拦截器中提供了assignToken回调函数用于附加 token，它会过滤访客请求和登录请求，并在请求前触发，也可以达到统一维护身份认证代码的目的。

createClientTokenAuthentication({
  assignToken: method => {
    method.config.headers.Authorization = localStorage.getItem('token')};
  }
});

createServerTokenAuthentication的 assignToken 回调函数用法相同。

登出拦截

当你的登出也需要调用接口时，也可以拦截登出请求，清除登录信息。

首先标识登出请求的元数据为authRole: 'logout'。

export const logout = () => {
  const method = alovaInstance.Get('/logout');
  method.meta = {
    authRole: 'logout'
  };
  return method;
};

再在登出拦截器中清除登录信息。

createClientTokenAuthentication({
  logout(response, method) {
    localStorage.removeItem('token');
    localStorage.removeItem('refresh_token');
  }
});

createServerTokenAuthentication的登录拦截器用法相同。

自定义标识身份

在上面的元数据身份标识中，实际上都默认的身份标识，如果需要自定义身份标识，你可以按下面这样设置。

token 刷新身份标识

createClientTokenAuthentication({
  refreshToken: {
    metaMatches: {
      refreshToken: true
    }
    // ...
  }
});

createServerTokenAuthentication({
  refreshTokenOnSuccess: {
    metaMatches: {
      refreshToken: true
    }
    // ...
  },
  refreshTokenOnError: {
    metaMatches: {
      refreshToken: true
    }
    // ...
  }
});

然后，元数据中具有refreshToken: true的请求，就会被认定为refreshToken身份。

export const refreshToken = () => {
  const method = alovaInstance.Get('/refresh_token');
  method.meta = {
    refreshToken: true
  };
  return method;
};

访客身份标识

createClientTokenAuthentication({
  visitorMeta: {
    isVisitor: true
  }
});

然后，元数据中具有isVisitor: true的请求，就会被认定为访客身份。

export const requestTokenNotRequired = () => {
  const method = alovaInstance.Get('/token_not_required');
  method.meta = {
    isVisitor: true
  };
  return method;
};

登录身份标识

createClientTokenAuthentication({
  login: {
    metaMatches: {
      login: true
    },
    handler(response, method) {
      // 登录拦截器
    }
  }
});

然后，元数据中具有login: true的请求，就会被认定为login身份。

export const login = () => {
  const method = alovaInstance.Get('/login');
  method.meta = {
    login: true
  };
  return method;
};

登出身份标识

createClientTokenAuthentication({
  logout: {
    metaMatches: {
      logout: true
    },
    handler(response, method) {
      // 登出拦截器
    }
  }
});

然后，元数据中具有logout: true的请求，就会被认定为logout身份。

export const logout = () => {
  const method = alovaInstance.Get('/logout');
  method.meta = {
    logout: true
  };
  return method;
};

createServerTokenAuthentication的登录拦截器用法相同。

Typescript

默认情况下，createClientServerTokenAuthentication和createServerTokenAuthentication适配了GlobalFetch请求适配器，你只需要指定statesHook的类型，如下：

const { onAuthRequired, onResponseRefreshToken } = createClientTokenAuthentication<typeof VueHook>({
  //...
});

const alovaInstance = createAlova({
  // ...
  statesHook: VueHook,
  beforeRequest: onAuthRequired(method => {
    // method的类型为 Method<any, any, any, any, RequestInit, Response, Headers>
  }),
  responded: onResponseRefreshToken((response, method) => {
    // response的类型为Response
    return response.json();
  })
});

如果你使用的不是GlobalFetch请求适配器，你还需要指定请求适配器的类型，这也很简单。

以下为 axios 请求适配器为例，在createClientTokenAuthentication中指定请求适配器类型。

import { axiosRequestAdapter } from '@alova/adapter-axios';

const { onAuthRequired, onResponseRefreshToken } = createClientTokenAuthentication<
  typeof VueHook,
  typeof axiosRequestAdapter
>({
  //...
});
const alovaInstance = createAlova({
  //...
  statesHook: VueHook,
  beforeRequest: onAuthRequired(method => {
    // method的类型为 Method<any, any, any, any, AlovaAxiosRequestConfig, AxiosResponse, AxiosResponseHeaders>
  }),
  responded: onResponseRefreshToken((response, method) => {
    // response的类型为AxiosResponse
    return response.data;
  })
});

基于服务端的 Token 认证拦截器的用法相同。

import { axiosRequestAdapter } from '@alova/adapter-axios';

createServerTokenAuthentication<typeof VueHook, typeof axiosRequestAdapter>({
  //...
});

特性​

安装​

绑定 Token 认证拦截器​

绑定基于客户端的身份认证的拦截器​

绑定基于服务端的身份认证拦截器​

在客户端无感刷新 Token​

在服务端无感刷新 Token​

在请求成功拦截器中处理​

在请求错误拦截器中处理​

放行访客请求​

登录拦截​

附加 token​

登出拦截​

自定义标识身份​

token 刷新身份标识​

访客身份标识​

登录身份标识​

登出身份标识​

Typescript​

特性

安装

绑定 Token 认证拦截器

绑定基于客户端的身份认证的拦截器

绑定基于服务端的身份认证拦截器

在客户端无感刷新 Token

在服务端无感刷新 Token

在请求成功拦截器中处理

在请求错误拦截器中处理

放行访客请求

登录拦截

附加 token

登出拦截

自定义标识身份

token 刷新身份标识

访客身份标识

登录身份标识

登出身份标识

Typescript