axios-annotations 2.2.0 → 3.0.0

package/README.md

@@ -1,944 +1,977 @@
-# Axios Annotations
-
-Quick Configuration Framework without Typescript using axios.<br/>
-
-声明式`API`配置工具。
-
-## Quick Overview
-
-+ Step 1：继承服务类`Service`
-+ Step 2：注解路径和参数
-+ Step 3：构建服务实例，调用接口
-
-### Basic Usage
-
-备胎，如果开发环境不支持装饰器。
-
-```javascript
-import {config, Service} from "axios-annotations"
-
-config.protocol = "http";
-config.host = "localhost";
-config.port = 8080;
-config.prefix = "/api";
-
-export default class TestService extends Service {
-    /**
-     * new TestService().get("a","b",null);
-     * <br>
-     * http://localhost:8080/api/path?p1=a&p2=b
-     * @param data1
-     * @param data2
-     * @returns {AxiosPromise<any>}
-     */
-    get(required1, required2, optional1) {
-        return this.requestWith("GET", "/path")
-            .param("p1", true)
-            .param("p2", true)
-            .param("p3", false)
-            .send({
-                p1: required1,
-                p2: required2,
-                p3: optional1
-            });
-    }
-
-    post(data1, data2) {
-        return this.requestWith("POST", "/path2")
-            .param("p1", true)
-            .body("p2")
-            .send({
-                p1: data1,
-                p2: data2
-            });
-    }
-
-    path(id) {
-        return this.requestWith("GET", "/path3/{id}")
-            .send({
-                id
-            });
-    }
-
-    basic() {
-        return this.request("POST", "/path3?p1=a&p2=b", {field1: 'c', field: 'd'},
-            {
-                headers: {
-                    'Content-Type': 'application/json'
-                }
-            }
-        );
-    }
-}
-```
-
-剩下自由发挥，自行管理服务实例。
-
-```javascript
-const ApiCommon = {
-    test: new TestService()
-};
-
-// 调用接口
-ApiCommon.test.get("a","b",null);
-```
-
-
-
-### Basic Usage With Decorators
-
-使用装饰器
-<br>
-可能需要插件支持：
-<br>
-`@babel/plugin-proposal-decorators`
-<br>
-`@babel/plugin-proposal-class-properties`
-<br>
-添加配置:
-
-```json
-{
-  "plugins": [
-    [
-      "@babel/plugin-proposal-decorators",
-      {
-        "legacy": true
-      }
-    ],
-    [
-      "@babel/plugin-proposal-class-properties",
-      {
-        "loose": true
-      }
-    ]
-  ]
-}
-```
-tsconfig.json / jsconfig.json
-```json
-{
-  "compilerOptions": {
-    "experimentalDecorators": true,
-    "emitDecoratorMetadata": true
-  }
-}
-```
-
-`vue-cli`等脚手架已默认支持装饰器，微信小程序说明请拉到末尾。
-<br>接口方法只需要处理和返回参数，并注解参数类型，框架根据注解分拆参数并注入`HTTP`请求。
-
-```javascript
-import {
-  Service,
-  RequestConfig,
-  RequestParam,
-  RequestMapping,
-  RequestBody,
-  RequestHeader,
-  IgnoreResidualParams
-} from "axios-annotations";
-
-@RequestMapping("/api")
-export default class TestService extends Service {
-    @RequestMapping("/path", "GET")
-    @RequestParam("p1", true)
-    @RequestParam("p2", true)
-    @RequestParam("p3", false)
-    get(p1, p2, p3) {
-        return {p1, p2, p3};
-    }
-
-    @RequestMapping("/path2", "POST")
-    @RequestParam("p1", true)
-    @RequestBody("p2")
-    @RequestHeader("Content-Type", "text/plain")
-    post(p1, str2) {
-        const defaultValue = {p1: "0x123456"};
-        return Object.assign(defaultValue, {p1, p2: str2});
-    }
-
-    @RequestMapping("/path", "GET")
-    @IgnoreResidualParams(false)
-    getDefault() {
-        return {
-            p1: "p1",
-            p2: "p2",
-            p3: "p3"
-        }
-    }
-}
-```
-
-调用接口：
-
-```javascript
-const ApiCommon = {
-    test: new TestService()
-};
-
-// 调用API
-ApiCommon.test.get("a","b",null);
-```
-
-
-
-如果不爽部分IDE的`non-promise inspection info`下划线，也可以给方法加上`async`。
-
-### 代码提示
-
-> Expect<ResponseType, PromiseType = AxiosPromise<ResponseType>>
-
-`Typescript`不支持装饰器修改方法返回值，但是可以绕开检查。<br/>
-
-Using a method decorator can not change the function return type.<br/>
-
-使用`Expect`绕过类型检查，获得代码提示功能。<br/>
-
-Using `Expect` to bypass type-checking and get code intelligence.
-
-```typescript
-import {Expect} from "axios-annotations";
-
-// ...
-
-export default class TestService extends Service {
-    @RequestBody()
-    @RequestMapping("/message", "POST")
-    @RequestHeader("Content-Type", "text/plain")
-    postMessage(message: string) {
-        return Expect<{
-            data: string;
-            success: boolean;
-        }>({
-            body: message
-        });
-    }
-}
-
-// call method, the return value can be deconstructed by IDE
-
-const res: AxiosResponse<{
-    data:string;
-    success:boolean;
-}> = await new TestService().postMessage("foo");
-
-console.log(res.data.data);
-```
-
-
-
-### QueryString Encoding
-
-`key-values pair`转查询串算法，运行环境不支持`URLSearchParams`时使用默认算法，也可以自定义。
-<br>
-使用第三方库,`qs`,`querystring`,`url-search-params-polyfill`等，不同运行环境下可能有差异。
-
-```javascript
-import qs from "qs";
-import {URLSearchParamsParser} from "axios-annotations";
-
-if (typeof URLSearchParams === "undefined") {
-    URLSearchParamsParser.encode = function (encoder) {
-        return qs.stringify(encoder);
-    }
-}
-```
-
-## Configuration
-
-### Custom Config
-
-配置服务链接，框架自带默认配置对象`config`，建议自行创建，使用`@RequestConfig`注入`Service`。
-
-```javascript
-import {
-    Config,
-    RequestConfig,
-    RequestMapping
-} from "axios-annotations";
-
-const config = new Config({
-    host: "localhost",
-    port: 8086,
-    protocol: "http",
-    prefix: "/api",
-    plugins: []
-});
-
-@RequestConfig(config)
-@RequestMapping("/test")
-export default class TestService extends Service {
-    @RequestMapping("/{id}", "GET") 
-    foo(id) {
-        return {id};
-    }
-}
-```
-
-### Default Config
-
-All Services inject this by default.
-
-```javascript
-import {config} from "axios-annotations";
-
-config.host = "192.168.137.1";
-config.port = 8080;
-// ...
-```
-
-### Register Config
-
-注册配置，用途：<br>
-
-+ 不需要 `export` 导出，使用 `Config.forName(name:string)` 获取。
-+ 部分特殊请求可能需要绕开自身配置，使用`@RequestWith(configName: string)`注解方法，请求将使用指定配置进行构建。
-
-```javascript
-new Config({
-    protocol: "http",
-    host: "localhost", 
-    port: 9999, 
-    prefix: "/auth"
-}).register("withoutAuth");
-```
-
-```javascript
-@RequestConfig(new Config({
-    protocol: "http",
-    host: "localhost", 
-    port: 8888,
-    prefix: "/prefix"
-}))
-@RequestMapping("/oauth") 
-class AuthService extends Service {
-    @PostMapping("/login")
-    @RequestWith("withoutAuth") 
-    login() {
-        // http://localhost:9999/auth/oauth/login
-        return {usename: "0x123456", password: "123456"};
-    }
-    
-    @GetMapping("/foo")
-    bar() {
-        // http://localhost:8888/prefix/oauth/foo
-        return {};
-    }
-}
-```
-
-## Abort
-小程序端第三方库可能没有实现请求取消接口。
-### 静态注入
-
-静态注入的`AbortController`取消请求为一次性，仅调试用途。
-
-```javascript
-const controller = new AbortController();
-// ...
-class AuthService extends Service {
-    // ...
-    @RequestConfig({
-      signal: controller.signal
-    })
-    bar() {
-        // ....
-        return {};
-    }
-}
-
-// 取消请求
-controller.abort()
-```
-
-或者：
-
-```javascript
-const controller = new AbortController();
-
-// ...
-class AuthService extends Service {
-  // ...
-  @AbortSource(controller) 
-  bar() {
-    // ....
-    return {};
-  }
-}
-
-new AuthService().bar().then(() => {
-
-}).catch(e => {
-  console.log(axios.isCancel(e));
-});
-
-// 取消请求
-controller.abort()
-```
-
-兼容旧版 `CancelToken` `(deprecated)`:
-```javascript
-const CancelToken = axios.CancelToken;
-
-const controller = new AbortControllerAdapter(CancelToken);
-
-// ...
-class AuthService extends Service {
-  // ...
-  @AbortSource(controller) 
-  bar() {
-    // ....
-    return {};
-  }
-}
-
-
-new AuthService().bar().then(() => {
-    // ...
-}).catch(e => {
-  console.log(axios.isCancel(e));
-});
-
-// 取消请求
-controller.signal.onabort = () => {
-    console.log("aborted");  
-};
-controller.abort("cancel test")
-```
-
-### 动态创建中断源
-不确定中断时机，自由发挥。
-```javascript
-// 自定义中断逻辑
-class AbortSourceManager {
-    // ...
-    
-    create () {
-        return AbortController();
-    }
-    
-    abortAll () {
-        // ...
-    }
-}
-
-const manager = new AbortSourceManager();
-
-// ...
-class AuthService extends Service {
-    // ...
-    @RequestConfig((...args)=>{
-        console.log(args);
-        const controller = manager.create();
-        return {
-          // ...
-          signal: controller.signal
-        };
-    })
-    bar() {
-        // ....
-        return {};
-    }
-}
-```
-
-
-## Plugin
-
-### Custom Plugin
-
-插件函数接收配置对象为参数，出于扩展性考虑，通常由高阶函数返回。
-
-插件在`Config`对象的`axios`实例创建时注入，建议在`Config`构造函数配置。
-
-```typescript
-import {Config} from "axios-annotations"
-import type {AxiosInstance} from "axios";
-
-export function ToastPlugin(fnToast) {
-    return function (config: Config, axios: AxiosInstance) {
-        axios.interceptors.response.use(function (e) {
-            return Promise.resolve(e);
-        }, function (e) {
-            fnToast(e);
-            return Promise.reject(e);
-        });
-
-        axios.interceptors.request.use(function (e) {
-            return Promise.resolve(e);
-        });
-    }
-}
-```
-
-配置插件：
-
-```javascript
-new Config({
-    plugins: [
-        ToastPlugin(function (e) {
-        	if (typeof wx !== "undefined") {
-                wx.showToast({
-                    icon: "none",
-                    title: `[${e.response.status}]` + ' ' + e.config.url
-                });
-            }
-        })
-    ]
-})
-```
-
-
-
-### <text style="color:red;">Auth Plugin</text>
-
-可选的内置插件，适配需要身份认证的服务，以`Spring Security`作为后端实现为例。
-<br>
-Basic Usage for Auth Plugin.
-<br>
-Take the case of `Spring Security OAtuh2.0`。
-
-```javascript
-// DevServer Proxy Config
-const authCfg = new Config({
-    host: "localhost",
-    port: 8080,
-    protocol: "http",
-    prefix: "/api"
-});
-
-@RequestConfig(authCfg)
-@RequestMapping("/oauth")
-export default class OAuth2Service extends Service {
-    @GetMapping("/token")
-    @RequestParam("grant_type", true)
-    @RequestParam("scope", false)
-    @RequestParam("client_id", false)
-    @RequestParam("client_secret", false)
-    @RequestParam("username", false)
-    @RequestParam("password", false)
-    @RequestBody() 
-    token() {
-        return {
-            grant_type: "password",
-            scope: "all",
-            client_id: "client_1",
-            client_secret: "123456",
-            username: "admin",
-            password: "123456"
-        };
-    }
-
-    @GetMapping("/token")
-    @RequestParam("grant_type", true)
-    @RequestParam("refresh_token", true)
-    @RequestParam("scope", false)
-    @RequestParam("client_id", true)
-    @RequestParam("client_secret", true) 
-    refreshToken(session) {
-        return {
-            grant_type: "refresh_token",
-            refresh_token: session.refresh_token,
-            scope: "all",
-            client_id: "client_1",
-            client_secret: "123456"
-        };
-    }
-}
-```
-
-Implement Authorizer.
-<br/>
-实现`Authorizer`类。至少需要实现方法`refreshSession`、`onAuthorizedDenied`。如果需要调用`invalidateSession`，还需要重载`onSessionInvalidated`。
-
-```javascript
-import {Authorizer} from "axios-annotations/plugins/auth";
-
-export default class OAuth2Authorizer extends Authorizer {
-    async refreshSession(session) {
-        // access_token invalid, could refresh access_token with refresh_token through 'password' grant type
-        // access_token 过期，如果使用 password 方式认证， 可使用 refresh_token 进行刷新
-        const oauthService = new OAuth2Service();
-        let res;
-        try {
-            res = await oauthService.refreshToken(session);
-        } catch (e) {
-            throw e;
-        }
-        if (!res || !res.data) {
-            throw new Error("Seession Unknow Error");
-        }
-        const nextSession = res.data;
-        return nextSession;
-    }
-
-    async onAuthorizedDenied(error) {
-        // refresh_token invalid (HTTP 401 default)，you should re-loign or logout here.
-        // refresh_token 过期触发该回调，在此进行重新登录或注销操作
-
-        // try logout, clean session.
-        // await this.invalidateSession();
-        // return;
-
-        const res = await new OAuth2Service().token();
-        if (res && res.data) {
-            const nextSession = res.data;
-
-            // save session manually if try re-login
-            await this.storageSession(nextSession);
-            return nextSession;
-        }
-
-        throw error;
-    }
-
-    // 调用 invalidateSession() 清除持久化的认证信息后触发该回调
-    onSessionInvalidated() {
-        // session cleaned, redirect to login page.
-        router.redirect("/login");
-    }
-}
-```
-
-如果是浏览器环境，持久化的认证信息默认存储在`sessionStorage`，默认键值`$_SESSION`，可以通过`window.sessionStorage.getItem("$_SESSION")`验证。
-<br>
-
-假如是`React Native`环境则需要自行实现持久化方案：
-
-```javascript
-import AsyncStorage from '@react-native-async-storage/async-storage';
-import {SessionStorage} from "axios-annotations/plugins/auth";
-
-export default class RNSessionStorage extends SessionStorage {
-    async set(key, value) {
-        const jsonValue = JSON.stringify(value);
-        // key: default "$_SESSION"
-        await AsyncStorage.setItem(key, jsonValue);
-    }
-
-    async get(key) {
-        // key: default "$_SESSION"
-    }
-
-    async remove(key) {
-        // key: default "$_SESSION"
-    }
-}
-```
-
-然后替换掉`Authorizer`存储器，如果通过重载`getSession`和`storageSession`实现验证信息存取，可以忽略掉`sessionStorage`和`sessionKey`，此时`sessionStorage`和`sessionKey`不会被调用。
-
-```javascript
-export default class OAuth2Authorizer extends Authorizer {
-    constructor() {
-        super();
-        this.sessionStorage = new RNSessionStorage();
-    }
-}
-```
-
-在需要鉴权的服务配置上设置插件：
-
-```javascript
-// config.js
-import {Config} from "axios-annotations";
-import {AuthorizationPlugin} from "axios-annotations/plugins/auth";
-
-const _authorizer = new OAuth2Authorizer();
-
-const config = new Config({
-    host: "localhost",
-    port: 8080,
-    protocol: "http",
-    prefix: "/api",
-    plugins: [
-        AuthorizationPlugin(_authorizer)
-    ]
-});
-
-// export it in order to save or read the grant result
-// 导出authorizer对象，方便读取或保存认证信息
-export const authorizer = _authorizer;
-
-// service.js
-@RequestConfig(config)
-@RequestMapping("/test")
-export default class TestService extends Service {
-    // ...
-}
-```
-
-首次登录，需要手动保存认证信息。
-<br>
-but you may store grant information yourself when the first time login succeed.
-
-```javascript
-import {authorizer} from "/path/config.js";
-
-// ... Login Page
-{
-    methods: {
-        registerApi().then(async session => {
-            await authorizer.sessionStorage.storageSession(session.data);
-            // redirect to other page ...
-        });
-    }
-}
-```
-
-## API
-
-### Service
-
-#### request(method, path, data?, config?): AxiosPromise
-
-+ method : string  `GET / POST / DELETE...`
-+ path : string `相对路径`
-+ data : Object `请求体`
-+ config : Object `AxiosRequestConfig`
-
-#### requestWith(method, path): RequestController
-
-+ method : string `GET /POST / DELETE...`
-+ path : string `相对路径`
-
-> #### RequestController
-> + param: (key, required?) : RequestController
->   + key : string  `标记查询串参数`
->   + required : boolean  `默认false，空字符串，null，undefined 将忽略`
-> + header: (header, header) : RequestController
->   + header : string `url 附加参数键值`
->   + header : string | function `字符串，或者接收 send 方法参数的函数，该函数应返回合法值。`
-> + body: (key) : RequestController
->   + key : string `标记参数中请求体`
-> + config: (cfg) : RequestController
->   + cfg : `AxiosRequestConfig`
->
-> + send: (data) : AxiosPromise<any>
->   + data : object `参数键值对`
-> + with: (name) : RequestController
->   + name : string `config name : 已注册配置名称`
-
-### Decorators
-
-#### RequestMapping(path, method?)
-
-+ path : string `相对路径`
-+ method : string  `默认GET，注解服务类时忽略该参数`
-
-> 注解方法时，可以使用简化形式：
-> <br>
-> GetMapping(path)
-> <br>
-> PostMapping(path)
-> <br>
-> PatchMapping(path)
-> <br>
-> PutMapping(path)
-> <br>
-> DeleteMapping(path)
-
-#### RequestParam(name, required?)
-
-+ name : string `方法返回值属性`
-+ required : boolean  `是否必要参数`
-
-#### RequestHeader(header, value)
-
-+ header : string `请求头`
-+ value : string  `字符串或函数`
-
-> 使用函数。
-> ```javascript
->    class TestService extends Service {
->        @RequestHeader("Authorization", (token) => {
->            return `Basic ${token}`;
->        })
->        @RequestMapping("/login", "GET")
->        foo(token) {
->            return {};
->        }
->    }
->  ```
-
-#### RequestBody(name)
-
-+ name : string `方法返回值属性，默认为 body，不能与 RequestParam name 参数重复，如果重复 RequestBody 请使用别名`,
-```javascript
-class TestService extends Service {
-  @RequestMapping("/foo", "POST")
-  @RequestHeader("Content-Type", "text/plain")
-  @RequestParam("str", true)
-  @RequestParam("strRepeat", true)
-  foo(str) {
-    return {
-      p2: str,
-      strRepeat: str // 如果请求体与查询串冲突
-    };
-  }
-}
-```
-
-#### IgnoreResidualParams(ignore?)
-+ ignore : boolean `拼接 QueryString 时是否忽略没有声明的参数`
-
-#### RequestConfig(config)
-+ axiosConfig: Config - class decorator，注解类，传入框架配置对象，注意不是 AxiosConfig。
-+ axiosConfig: AxiosConfig | (...args:any[]) => AxiosConfig - method decorator，注解方法，注解方法时可根据请求参数构造配置对象。
-
-```javascript
-// GET /foo?p1=p1&p2=p2&p3=p3
-class TestService extends Service {
-    @RequestMapping("/foo", "GET")
-    @RequestParam("p1", true)
-    foo(token) {
-        return {
-            p1: "p1",
-            p2: "p2", 
-            p3: "p3"
-        };
-    }
-}
-```
-该注解对请求体没有影响。
-```javascript
-// GET /foo?p1=p1
-class TestService extends Service {
-    @RequestMapping("/foo", "GET")
-    @RequestParam("p1", true)
-    @IgnoreResidualParams()
-    foo(token) {
-        return {
-            p1: "p1",
-            p2: "p2", 
-            p3: "p3"
-        };
-    }
-}
-```
-
-### Authorizer (Optional Plugin)
-
-鉴权插件。
-
-+ sessionKey : string `键值名称`
-    ```javascript
-    authorizer.sessionKey = "$_SESSION"; // default value
-    ```
-+ getSession : Promise<Session> `获取授权信息`
-  ```javascript
-  function onLogin(){
-    authorizer.getSession().then(session => {
-        // fetch other info / redirect to other page
-        store.dispatch('SAVE_USER_INFO' , info);
-    });
-  }  
-  ```
-+ storageSession(session: Session): Promise<void> `存储授权信息`
-+ checkResponse(response:AxiosResponse) : boolean `检查授权是否过期`
-  ```javascript
-  class OAuth2Authorizer extends Authorizer {
-    checkResponse(response){
-        return response.stauts === 401; // default implement
-    } 
-  }
-  ```
-
-+ withAuthentication(request: AxiosRequestConfig, session: Session) : void `请求附加认证信息，默认附加请求头`
-  ```javascript
-  class OAuth2Authorizer extends Authorizer {
-    withAuthentication(request, session){
-        request.headers.Authorization = 'Bearer 0x123456';
-    } 
-  }
-  ```
-
-## 运行环境
-
-### 微信小程序配置
-
-更新开发工具以支持装饰器语法。
-
-小程序`Typescript`环境不支持装饰器编译，但是`Javascript`环境可以。把涉及到`API`配置的`*.ts`文件扩展名改为`*.js`，绕过蹩脚的`TS`编译，本地配置勾选上`将JS编译成ES5`，正常引入即可。<br/>
-
-> 开发工具BUG：`TS`环境`npm`构建失败
->
-> 找到`project.config.json`文件，`setting`下面添加如下配置：
->
-> ```json
-> {
->     "packNpmManually": true,
->     "packNpmRelationList": [
->       {
->         "packageJsonPath": "./package.json",
->         "miniprogramNpmDistDir": "./miniprogram/"
->       }
->     ]
-> }
-> ```
->
-> 开发工具`项目`→`重新打开此项目`，然后构建`npm`。
-
-**安装第三方`axios`实现：**
-
-+ 备胎1，使用适配器，`axios-miniprogram-adapter`
-
-  `axios`需要降级，版本再高就得报错：
-
-  ```shell
-  npm install axios@0.26.1
-  npm install axios-miniprogram-adapter
-  ```
-  
-  开发工具如果编译报错 `module is not defined`， 在`app.js`头部补充缺失组件的声明：
-  
-  ```javascript
-  import {
-      Config,
-      URLSearchParamsParser,
-      AbortControllerAdapter,
-      Service,
-      AbortSource,
-      DeleteMapping,
-      GetMapping,
-      IgnoreResidualParams,
-      PatchMapping,
-      PostMapping,
-      PutMapping,
-      RequestBody,
-      RequestConfig,
-      RequestHeader,
-      RequestMapping,
-      RequestParam,
-      RequestWith
-  } from "axios-annotations";
-  ```
-+ 备胎2，使用第三方实现，不限于`axios-miniprogram`
-
-  ```shell
-  npm install axios-miniprogram
-  ```
-  
-  实现`AxiosStaticInstanceProvider`并配置，如果`IDE`警告`provide`返回类型，可忽略掉：
-  
-  ```javascript
-  import mpAxios from 'axios-miniprogram';
-  
-  class ThirdAxiosStaticInstanceProvider extends AxiosStaticInstanceProvider {
-      provide() {
-          return mpAxios;
-      }
-  }
-  
-  const config = new Config({
-      plugins: [],
-      protocol: "http",
-      host: "localhost",
-      port: 8888,
-      prefix: "/test",
-      axiosProvider: new ThirdAxiosStaticInstanceProvider(),
-  });
-  ```
-  
-  
+# axios-annotations
+
+<p align="left">
+  <a href="./README_EN.md">English</a> | <b>简体中文</b>
+</p>
+
+[![npm version](https://img.shields.io/npm/v/axios-annotations.svg?style=flat-square)](https://www.npmjs.com/package/axios-annotations)
+[![license](https://img.shields.io/badge/license-MIT-green.svg?style=flat-square)](https://github.com/sitorhy/axios-annotations/blob/master/LICENSE)
+
+---
+Quick Configuration Framework for Axios with TypeScript support.
+
+> 声明式`API`配置工具。将 **请求的构建声明** 与 **业务数据的提供** 完全分离。不再手动拼装 `URL`
+、请求头和请求体，而是通过装饰器来“声明”一个请求应该如何被构建。
+
+# 装饰器可用范围
+
+| 装饰器               | 可用范围   | 描述                        |
+|:------------------|:-------|:--------------------------|
+| `@RequestConfig`  | 类 / 方法 | 设置请求配置（例如 `signal`）。      |
+| `@RequestMapping` | 类 / 方法 | 定义 `URL` 路径和 `HTTP` 请求方法。 |
+| `@RequestWith`    | 方法     | 重定向请求方法使用的配置。             |
+| `@RequestBody`    | 方法     | 标记一个参数作为请求体。              |
+| `@RequestHeader`  | 方法     | 标记一个参数作为请求头。              |
+| `@RequestParam`   | 方法     | 标记一个参数作为 `URL` 查询参数。      |
+| `@PathVariables`  | 方法     | 标记一个参数作为 `URL` 路径变量。      |
+
+---
+
+# Usage
+
+## 流程简述
+
++ **声明式构建**：使用 `@RequestMapping`, `@RequestParam` 等装饰器来描述一个请求的静态结构。
++ **提供数据源**：业务方法接收参数，并 `return` 一个由这些参数组装成的普通 `JavaScript`
+  对象。这个对象将作为所有装饰器的数据源 (`Data Source`)。
++ **自动执行**：框架会拦截方法调用，使用装饰器定义的规则，从返回的数据源对象中提取数据，自动构建并执行请求。
+
+## 创建配置
+
+框架内置默认的全局配置，默认指向本地的`8080`端口，但建议自行创建和管理配置。
+例：
+
+```ts
+// config.ts
+import {Config} from "axios-annotations";
+
+export const localConfig = new Config({
+    protocol: 'http',
+    host: 'localhost',
+    prefix: '', // 请求前缀，可选
+    port: 5173
+});
+```
+
+通过 `@RequestConfig` 注入服务类，注意服务类需要继承 `Service`。
+
+```ts
+import {localConfig} from "./config.ts";
+import {Service, RequestConfig} from "axios-annotations";
+
+@RequestConfig(localConfig)
+export class DemoService extends Service {
+    // ...
+}
+```
+
+请求前缀可以在 `Config` 的 `prefix` 中指定，或者使用 `@RequestMapping` 指定前缀。
+
+## @RequestMapping
+
++ 声明服务使用的统一请求前缀。
++ 声明业务方法的请求方法和请求路径，注解方法的时候第二参数必填。
+
+```ts
+import {localConfig} from "./config.ts";
+import {Expect, Service, RequestConfig, RequestMapping} from "axios-annotations";
+
+@RequestConfig(localConfig)
+@RequestMapping("/api")
+export class DemoService extends Service {
+    // [GET] http://localhost:5173/api/foo
+    @RequestMapping("/foo", "GET")
+    foo() {
+        return Expect<Record<any>>({});
+    }
+
+    // [POST] http://localhost:5173/api/bar
+    @RequestMapping("/bar", "POST")
+    bar() {
+        return Expect<Record<any>>({});
+    }
+}
+```
+
+## @RequestWith
+
++ 重定向方法使用的配置，服务类的业务划分需要用到不同的服务器地址。
+  例子，请求不同服务器的文件：
+
+```ts
+import {Config, Expect, Service, RequestConfig, RequestMapping, RequestWith} from "axios-annotations";
+
+const config = new Config({
+    protocol: "http",
+    host: "localhost",
+    prefix: "/resources",
+    port: 5173
+});
+
+const config2 = new Config({
+    protocol: "http",
+    host: "localhost",
+    prefix: "/data",
+    port: 5173
+});
+
+@RequestConfig(config)
+export class FileService extends Service {
+    @RequestMapping("/test1.json", "GET")
+    getFile() {
+        // [GET] http://localhost:5173/resources/test1.json
+        return Expect<any>({
+            params: {}
+        });
+    }
+
+    @RequestWith(config2)
+    @RequestMapping("/test2.json", "GET")
+    getFile2() {
+        // [GET] http://localhost:5173/data/test2.json
+        return Expect<any>({
+            params: {}
+        });
+    }
+}
+```
+
+注意，如果服务类使用 `@RequestMapping` 声明了统一前缀，那么使用 `@RequestWith` 重定向仍然会拼接服务类的统一前缀。
+如果需要服务类方法使用不同的请求前缀，你可能需要将服务的统一前缀提升到 `Config` 的 `prefix` 字段或者取消前缀相关配置。
+
+```ts
+// ...config
+
+const config2 = new Config({
+    protocol: "http",
+    host: "localhost",
+    prefix: "/data",
+    port: 5173
+});
+
+@RequestConfig(config)
+@RequestMapping("/api")
+export class FileService extends Service {
+    // ...
+
+    @RequestWith(config2)
+    @RequestMapping("/test2.json", "GET")
+    getFile2() {
+        // [GET] http://localhost:5173/data/api/test2.json
+        return Expect<any>({
+            params: {}
+        });
+    }
+}
+```
+
+## @RequestBody
+
++ 仅用于声明请求体的取值字段，默认不传则为 `"body"` 字段, `@RequestBody()` 跟 `@RequestBody("body")` 等价：
+  注意请求体因类型问题无法合并，多次声明请求体取值以最后执行的为准。
+
+```ts
+
+@RequestConfig(config)
+@RequestMapping("/api")
+export class FileService extends Service {
+    // ...
+    @RequestMapping("/files/package_graph.json", "POST")
+    @RequestBody()
+    getPackageGraph() {
+        return Expect<Record<string, any>>({
+            body: {
+                version: '3.x',
+                description: '示例数据'
+            }
+        });
+    }
+}
+```
+
+`@RequestBody` 的扩展写法，用于指定静态值或自定义取值逻辑。
+指定静态值：
+
+```ts
+
+@RequestConfig(config)
+export class FileService extends Service {
+    // ...
+    @RequestMapping("/files/package_graph.json", "POST")
+    @RequestBody({
+        value: {
+            version: '3.x',
+            description: '示例数据'
+        }
+    })
+    getPackageGraph() {
+        return Expect<Record<string, any>>({});
+    }
+}
+```
+
+自定义取值逻辑:
+
+```ts
+
+@RequestConfig(config)
+export class FileService extends Service {
+    // ...
+    @RequestMapping("/files/package_graph.json", "POST")
+    @RequestBody({
+        value: function () {
+            return {
+                version: '3.x',
+                description: '示例数据2'
+            };
+        }
+    })
+    getPackageGraph() {
+        return Expect<Record<string, any>>({});
+    }
+}
+```
+
+## @RequestHeader
+
+声明请求头的取值，有以下的取值方式：
+
++ 声明数据源字段，`@RequestHeader(key: string, required?: boolean = true)` 第二参数`required`默认必填，`value`为空值时（`null` / `undefined` /`''`）默认转为空字符串。
++ 声明静态值，`key`必填。
++ 声明自定义取值逻辑，`key`必填。
+  请求头取值可合并，所以这里一次性给出取值示例：
+
+```ts
+
+@RequestConfig(config)
+export class FileService extends Service {
+    // ...
+    // 声明数据源字段，且必填
+    @RequestHeader("Custom-Header", true)
+    // 声明静态值
+    @RequestHeader({
+        key: "Custom-Header-2",
+        value: "static-header-value",
+        required: true,
+    })
+    // 声明自定义取值逻辑
+    @RequestHeader({
+        key: "Custom-Header-3",
+        value: function (source: Record<string, any>) {
+            return source.num1 + source.num2;
+        }
+    })
+    getPackageGraph() {
+        return Expect<Record<string, any>>({
+            "Custom-Header": "header-value-from-source",
+            num1: 100,
+            num2: 200
+        });
+    }
+}
+```
+
+生成的请求头为：
+
+```
+Custom-Header:       header-value-from-source
+Custom-Header-2:     static-header-value
+Custom-Header-3:     300
+```
+
+## @RequestParam
+
+声明查询参数的取值，取值方式用法跟请求头的声明类似：
+
++ 声明数据源字段，`@RequestParam(key: string, required?: boolean = false)` 第二参数默认选填，空值不会拼接到请求地址。
++ 声明静态值， `key` 必填。
++ 声明自定义取值逻辑，  `key` 必填。
+
+```ts
+const config = new Config({
+    protocol: "http",
+    host: "localhost",
+    prefix: "/resources",
+    port: 5173
+});
+
+@RequestConfig(config)
+export class FileService extends Service {
+    @RequestMapping("/demo.json", "POST")
+    @RequestParam("param1") // 基本形式
+    @RequestParam("param2") // 基本形式
+    // 扩展写法（函数）
+    @RequestParam({
+        key: "sum",
+        value: function (source: Record<string, any>) {
+            return Number(source['param1']) + Number(source['param2']);
+        }
+    })
+    // 扩展写法（静态值）
+    @RequestParam({
+        key: 'static',
+        value: 'foo'
+    })
+    @RequestBody()
+    getJson() {
+        return Expect<Record<string, any>>({
+            param1: '114',
+            param2: '514',
+            body: {
+                employees: [
+                    {
+                        firstName: "John",
+                        lastName: "Doe"
+                    }
+                ]
+            }
+        });
+    }
+}
+```
+
+调用 `getJson` 生成的地址：
+
+```text
+http://localhost:5173/resources/demo.json?static=foo&sum=628&param2=514&param1=114
+```
+
+## @PathVariables
+
+启用路径参数，从数据源或数据源字段中取值，取值必须为 `PlainObject`，替换 `url` 中的占位符。
+启用路径参数请至少确保有一个 `@PathVariables` 声明，不指定路径参数数据源字段时，直接从数据源本体取值。
+由于路径参数取值（`PlainObject`）可合并，此处给出所有取值示例：
+
+```ts
+export const localConfig = new Config({
+    protocol: 'http',
+    host: 'localhost',
+    port: 5173
+});
+
+@RequestConfig(config)
+export class FileService extends Service {
+    @RequestMapping("/files/{fileName}?a={a}&c={c}&e={e}", "GET")
+    @PathVariables() // 不指定字段，从数据源本体取值，此处会查询出 "fileName"
+    @PathVariables({
+        // 自定义数据源生成逻辑
+        value: function (source: Record<string, any>) {
+            return {
+                a: 100,
+                c: 300,
+                d: source.d
+            }
+        }
+    })
+    // 此处 pathVariablesKey 的值会跟数据源本体合并为一个新的对象，所以会查询出 "e"
+    @PathVariables('pathVariablesKey') // => "e"
+    // 注意这个是查询参数，生成逻辑跟路径参数不一样
+    @RequestParam({
+        key: 'b',
+        value: 200
+    })
+    getFileInfo(fileName: string) {
+        return Expect<Record<string, any>>({
+            fileName,
+            d: 400,
+            pathVariablesKey: {
+                e: 500
+            }
+        });
+    }
+}
+```
+
+路径参数可用于查询参数的填充，但跟 `@RequestParam` 有区别：
+
++ `@RequestParam` 合并值直接传给 `axios` 的 `params` 参数，对于数组等复合类型，使用 `axios` 的生成逻辑，路径参数则直接转为
+  `JSON` 字符串，所以不要传非基本类型。
++ 占位符是固定的字符序列，路径参数没有选填逻辑。
++ 转换非基本类型失败一律转为 `"undefined"`。
+
+## @RequestConfig
+
++ 注解类时，用于设置服务类使用的配置。
++ 注解方法时，合并 `AxiosRequestConfig` 配置，例如有 `N` 个查询参数/请求头不想一个个配置，可以使用 `@RequestConfig` 统一返回。
+
+```ts
+const config = new Config({
+    protocol: "http",
+    host: "localhost",
+    prefix: "/data",
+    port: 5173
+});
+
+@RequestConfig(config)
+export class FileService extends Service {
+    @RequestMapping("/test1.json", "GET")
+    @RequestConfig({
+        headers: {
+            'X-Source': 'class',
+            'Authorization': 'Bearer token'
+        }
+    })
+    @RequestConfig(function (source: Record<string, any>) {
+        return {
+            headers: {
+                'Token1': '1'
+            },
+            params: source.params
+        };
+    })
+    getData() {
+        // http://localhost:5173/data/test1.json?a=1&b=2
+        // ----
+        // Headers:
+        // 
+        // X-Source:         class
+        // Token1:           1
+        // Authorization:    Bearer token
+        return Expect<Record<string, any>>({
+            params: {
+                'a': 1,
+                'b': 2
+            }
+        });
+    }
+}
+```
+`@RequestConfig` 可用于注入 `AbortController` 或 `CancelToken` 中断源。
+众所周知，`React 18+`组件在开发环境下会重复挂载和卸载（`<React.StrictMode>`），导致 `useEffect(() => {}, [])` 中的请求会发送两次。
+此处举例如何限制发送一次请求，即组件卸载时候自动取消请求：
+
+```ts
+@RequestConfig(config)
+export class FileService extends Service {
+  @RequestMapping("/test1.json", "GET")
+  @RequestConfig(function (source: Record<string, any>) {
+    return {
+      signal: source.signal
+    };
+  })
+  getData(signal: AbortSignal) {
+    return Expect<Record<string, any>>({
+      signal
+    });
+  }
+}
+
+// 管理你的服务实例
+export const ApiManager = {
+  fileService: new FileService()
+}
+```
+`React`组件部分逻辑如下：
+```tsx
+import {ApiManager} from './api-manager'
+import {useEffect} from "react";
+
+export function ReactFunctionComponent() {
+  useEffect(function () {
+    const controller: AbortController = new AbortController();
+    ApiManager.fileService.getData(controller.signal);
+
+    return function () {
+      controller.abort();
+    };
+  }, []);
+
+  return (
+          <div>
+            <p>AbortController Demo</p>
+            <p>开发环境下只有第二次挂载的请求会被接收</p>
+          </div>
+  );
+}
+```
+
+## Expect
+
+函数原型参考：
+
+```typescript
+export default function Expect<T, D = AxiosPromise<T>>(params: any): D;
+```
+
+由于 `TypeScript` 的限制，装饰器无法在编译时改变一个方法的返回类型。方法在代码层面返回的是一个普通对象（数据源），但框架在运行时实际返回的是一个`AxiosPromise`。
+`Expect<T>` 的作用就是解决这个“类型不匹配”的问题。它是一个类型桥梁，通过类型断言绕过静态检查，从而让你在调用代码时能够获得完整的类型安全和`IDE` 代码提示。
+`Expect<T>` 的泛型 `T` 至关重要，它 **定义了你期望服务器响应体 `data` 的类型**。
+
+- 如果接口返回一个具体的 `JSON` 对象，你应该为其定义一个接口 `MyData` 并使用 `Expect<MyData>(...)`。
+
+- 如果接口返回纯文本，你应该使用 `Expect<string>(...)`。
+
+
+## 不支持装饰器的环境
+```ts
+import {RequestBuilder} from "axios-annotations";
+import {config} from './config';
+
+async function foo() {
+  const response = await new RequestBuilder().param({
+    key: 'param',
+    value: function (source: Record<string, any>) {
+      return source.param;
+    }
+  }).buildWith(config, "/demo.json", "GET", {
+    param: 666
+  });
+
+  console.log(response.data);
+}
+```
+
+## 运行环境
+
+### 微信小程序配置
+
+更新开发工具以支持装饰器语法。
+
+小程序`Typescript`环境不支持装饰器编译，但是`Javascript`环境可以。把涉及到`API`配置的`*.ts`文件扩展名改为`*.js`，绕过部分环境对装饰器支持限制，本地配置勾选上`将JS编译成ES5`，正常引入即可。<br/>
+
+> 开发工具BUG：`TS`环境`npm`构建失败
+>
+> 找到`project.config.json`文件，`setting`下面添加如下配置：
+>
+> ```json
+> {
+>     "packNpmManually": true,
+>     "packNpmRelationList": [
+>       {
+>         "packageJsonPath": "./package.json",
+>         "miniprogramNpmDistDir": "./miniprogram/"
+>       }
+>     ]
+> }
+> ```
+>
+> 开发工具`项目`→`重新打开此项目`，然后构建`npm`。
+
+**安装第三方`axios`实现：**
+
++ 方案 1，使用适配器，`axios-miniprogram-adapter`
+
+  `axios`需要降级，版本再高就得报错：
+
+  ```shell
+  npm install axios@0.26.1
+  npm install axios-miniprogram-adapter
+  ```
+
+  开发工具如果编译报错 `module is not defined`， 在`app.js`头部补充缺失组件的声明：
+
+  ```javascript
+  import {
+      Config,
+      Service,
+      Expect,
+      AxiosStaticInstanceProvider,
+      RequestBody,
+      RequestConfig,
+      RequestHeader,
+      RequestMapping,
+      RequestParam,
+      PathVariables,
+      RequestWith,
+      RequestBuilder
+  } from "axios-annotations";
+  ```
++ 方案 2，使用第三方实现，不限于`axios-miniprogram`
+
+  ```shell
+  npm install axios-miniprogram
+  ```
+  如果`npm`构建失败直接将`node_modules`下的目录复制出来。
+  实现`AxiosStaticInstanceProvider`并配置，如果`IDE`警告`provide`返回类型，可忽略掉：
+
+  ```javascript
+  import mpAxios from 'axios-miniprogram';
+  
+  class ThirdAxiosStaticInstanceProvider extends AxiosStaticInstanceProvider {
+      provide() {
+          return mpAxios;
+      }
+  }
+  
+  const config = new Config({
+      plugins: [],
+      protocol: "http",
+      host: "localhost",
+      port: 8888,
+      prefix: "/test",
+      axiosProvider: new ThirdAxiosStaticInstanceProvider(),
+  });
+  ```
+
+
+# 插件
+
+## 自定义插件
+插件函数接收配置对象为参数，出于扩展性考虑，通常由高阶函数返回。
+插件在`Config`对象的`axios`实例创建时注入，建议在`Config`构造函数配置。
+```typescript
+import {Config} from "axios-annotations"
+import type {AxiosInstance} from "axios";
+
+export function ToastPlugin(fnToast) {
+    return function (config: Config, axios: AxiosInstance) {
+        axios.interceptors.response.use(function (e) {
+            return Promise.resolve(e);
+        }, function (e) {
+            fnToast(e);
+            return Promise.reject(e);
+        });
+
+        axios.interceptors.request.use(function (e) {
+            return Promise.resolve(e);
+        });
+    }
+}
+```
+配置插件：
+```javascript
+new Config({
+    plugins: [
+        ToastPlugin(function (e) {
+        	if (typeof wx !== "undefined") {
+                wx.showToast({
+                    icon: "none",
+                    title: `[${e.response.status}]` + ' ' + e.config.url
+                });
+            }
+        })
+    ]
+})
+```
+## 授权插件 (可选)
+使用该插件用于自动为请求写入授权信息（自动携带`Bearer Token`请求头等），默认适配`OAuth2`标准，直接给出示例：
++ 定义会话存储器
+```ts
+import {SessionStorage} from "axios-annotations/plugins/auth";
+
+class WebSessionStorage extends SessionStorage {
+  async set(key: string, value: any): Promise<void> {
+    return sessionStorage.setItem(key, JSON.stringify(value));
+  }
+
+  async get(key: string): Promise<any> {
+    const str = sessionStorage.getItem(key);
+    if (str) {
+      return JSON.parse(str);
+    } else {
+      return null;
+    }
+  }
+
+  async remove(key: string): Promise<void> {
+    return sessionStorage.removeItem(key);
+  }
+}
+```
++ 实例化并导出`Authorizer`对象，并注入`SessionStorage`
+> 这里导出的`Authorizer`对象将用于首次登录后会话信息写入（调用`storageSession`）和获取会话（`getSession`）。
+```ts
+import {Authorizer, type BasicSession} from "axios-annotations/plugins/auth";
+
+class LocalAuthorizer extends Authorizer {
+  constructor() {
+    super();
+    this.sessionStorage = new WebSessionStorage();
+  }
+
+  // 刷新 access_token，这里直接返回修改后的 session 对象即可
+  async refreshSession(session: BasicSession): Promise<any> {
+    const response = await new OAuthService().refreshToken({
+      refresh_token: session.refresh_token
+    });
+    console.log(`刷新 ${JSON.stringify(response.data)}`);
+    // 此处组装新的 session 对象并返回, onAuthorizedDenied 会捕获该方法运行时异常
+    return {
+      ...response.data
+    };
+  }
+
+  // 附加 session 字段到请求头
+  withAuthentication(request: InternalAxiosRequestConfig, session: BasicSession) {
+    // 这里使用默认实现，如果 refreshSession 返回 null, withAuthentication 的逻辑不会执行
+    super.withAuthentication(request, session);
+    console.log(request.headers);
+  }
+
+  // 会话刷新过程抛出异常
+  // refresh_token 失效，约等于 refreshSession 返回 null
+  async onAuthorizedDenied(error: unknown): Promise<void> {
+    console.error(error); // 这个是 refreshSession 抛出的异常
+
+    // 删除会话信息
+    // 调用 invalidateSession 触发 onSessionInvalidated
+    await this.invalidateSession();
+  }
+
+  onSessionInvalidated() {
+    // 跳转回登录页/首页
+    window.history.replaceState({}, document.title, window.location.pathname);
+  }
+}
+
+export const authorizer = new LocalAuthorizer();
+```
++ 定义授权链服务配置和业务链服务配置
+授权链的接口应该跟业务链的接口分别独立`Service`，防止请求头冲突。
+`OAuthService`示例代码适配`spring-boot-starter-oauth2-authorization-server 4.0.x`，仅供参考，看不懂可直接跳到`Authorizer`说明。
+```ts
+import AuthorizationPlugin, {type BasicSession} from "axios-annotations/plugins/auth";
+
+const oauthConfig = new Config({
+  protocol: 'http',
+  host: 'localhost',
+  port: 8080
+});
+
+// 这里业务接口跟授权接口使用同一服务器
+const businessConfig = new Config({
+  protocol: 'http',
+  host: 'localhost',
+  port: 8080,
+  plugins: [
+    AuthorizationPlugin(authorizer)
+  ]
+});
+
+@RequestConfig(oauthConfig)
+export class OAuthService extends Service {
+  // 随机字符串
+  generateVerifier() {
+    const array = new Uint32Array(56);
+    window.crypto.getRandomValues(array);
+    return Array.from(array, dec => ('0' + dec.toString(16)).slice(-2)).join('');
+  }
+
+  async getCodeChallenge(verifier: string) {
+    const encoder = new TextEncoder();
+    const data = encoder.encode(verifier);
+    // 使用浏览器原生 Web Crypto API 进行 SHA-256 加密
+    const digest = await window.crypto.subtle.digest('SHA-256', data);
+
+    // Base64Url 编码 (注意：不是普通的 Base64)
+    return btoa(String.fromCharCode(...new Uint8Array(digest)))
+            .replace(/\+/g, '-')
+            .replace(/\//g, '_')
+            .replace(/=+$/, '');
+  }
+
+  // 根据 code 换取 accessToken 和 refreshToken
+  @RequestMapping('/oauth2/token', 'POST')
+  @RequestConfig(function (source) {
+    const {signal, ...data} = source;
+    return {
+      headers: {
+        'Authorization': 'Basic ' + btoa('test-client:test-secret'),
+        'Content-Type': 'application/x-www-form-urlencoded'
+      },
+      signal: signal,
+      data,
+    }
+  })
+  getToken(params: {
+    code_verifier: string;
+    code: string;
+    redirect_uri: string;
+    signal?: AbortSignal
+  }) {
+    return Expect<{
+      access_token: string;
+      refresh_token: string;
+    }>({
+      signal: params.signal,
+      grant_type: 'authorization_code',
+      code: params.code,
+      client_id: 'test-client',
+      redirect_uri: params.redirect_uri,
+      code_verifier: params.code_verifier
+    });
+  }
+
+  // 刷新 accessToken
+  @RequestMapping('/oauth2/token', 'POST')
+  @RequestConfig(function (source) {
+    const {signal, ...data} = source;
+    return {
+      headers: {
+        'Authorization': 'Basic ' + btoa('test-client:test-secret'),
+        'Content-Type': 'application/x-www-form-urlencoded'
+      },
+      signal: signal,
+      data,
+    }
+  })
+  refreshToken(params: {
+    refresh_token: string;
+    signal?: AbortSignal
+  }) {
+    return Expect<{
+      "access_token": string;
+      "refresh_token": string;
+      "scope": string;
+      "token_type": string;
+      "expires_in": number;
+    }>({
+      signal: params.signal,
+      grant_type: 'refresh_token',
+      refresh_token: params.refresh_token,
+      client_id: 'test-client'
+    });
+  }
+}
+
+// 业务接口
+@RequestConfig(businessConfig)
+export class BusinessService extends Service {
+  // ... 全部省略
+}
+```
++ 登录并写入授权信息
+```ts
+const oauthService = new OAuthService();
+
+async function handleLoginButtonClick() {
+  const verifier = oauthService.generateVerifier();
+  sessionStorage.setItem('code_verifier', verifier);
+  const challenge = await oauthService.getCodeChallenge(verifier);
+  const params = new URLSearchParams({
+    response_type: 'code',
+    client_id: 'test-client',
+    scope: 'read',
+    redirect_uri: 'http://localhost:5173',
+    code_challenge: challenge,
+    code_challenge_method: 'S256'
+  });
+  window.location.href = `http://localhost:8080/oauth2/authorize?${params.toString()}`
+}
+
+// 服务器回调的路由页面，这里直接用首页
+useEffect(() => {
+  const urlParams = new URLSearchParams(window.location.search);
+  const code = urlParams.get('code');
+  const controller = new AbortController();
+  const verifier = sessionStorage.getItem('code_verifier');
+
+  if (code && verifier) {
+    oauthService.getToken({
+      code: code,
+      redirect_uri: 'http://localhost:5173',
+      code_verifier: verifier,
+      signal: controller.signal,
+    }).then((response) => {
+      const {access_token, refresh_token} = response.data;
+      authorizer.storageSession({access_token, refresh_token}).then(() => {
+        console.log({access_token, refresh_token});
+      });
+      // 消除地址栏的 code
+      window.history.replaceState({}, document.title, window.location.pathname);
+    }).catch(error => {
+      if (error.name !== 'AbortError') console.error("Failed to get token:", error);
+    });
+  } else {
+    authorizer.getSession().then(session => {
+      // ...
+    });
+  }
+  return () => controller.abort();
+}, []);
+```
+
+## Authorizer
+会话对象结构：
+```ts
+export type BasicSession = {
+  access_token?: string;
+  accessToken?: string;
+  token?: string;
+
+  refreshToken?: string;
+  refresh_token?: string;
+} & Record<string, any>;
+```
+非标准授权凭证需要映射到`access_token`/`accessToken`/`token`中的一个或多个字段。
+
+非标准授权流程不支持`refreshToken`，可设置为不重复的随机值。
+
+必须重载的方法只有`onAuthorizedDenied`、`refreshSession`。
+
+**方法说明**：
+
++ invalidateSession(): Promise<void>
+> 删除会话信息，并触发 `onSessionInvalidated` 回调。
++ onSessionInvalidated(): void
+> 可重载该方法返回登录页或首页。
++ onAuthorizedDenied(error: unknown): Promise<void>
+> 处理 `refreshSession` 运行时异常（HTTP 401/500/RuntimeError），通常就是`refreshToken`过期需要重新登录。
+> 重载该方法执行清理工作，默认实现直接 `rethrow` 异常，你的控制台会始终报错误信息。
+> 该方法应始终重载，务必调用 `invalidateSession` 删除会话信息。
++ refreshSession(session: BasicSession): Promise<BasicSession | null>
+> 该方法应始终重载，参数是当前会话信息，根据`session.refreshToken`换取新的`accessToken`，返回新会话对象（`PlainObject`），插件会自动持久化。
+> 如果是非标准的授权流程（不支持续期，无`refreshToken`等）直接返回`null`即可，并调用`invalidateSession`移除会话信息。或者直接抛出自定义异常走`onAuthorizedDenied`清理流程。
+> 如果支持无感知的`refreshToken`重新获取，也在该方法进行。
++ checkResponse(response: AxiosResponse): boolean
+> 检查请求是否触发了授权过期错误，默认**只检查状态码**是否为`401`，返回`false`表示授权过期。
+> 授权过期触发续期流程，插件会先调用`getSession`获取会话对象，会话对象将用于：
+>
+> 1. 传给`checkSession`进行会话信息和请求的匹配，因为当前会话信息已过期，应当返回`false`表示校验不通过，返回 `true` 直接抛出原始异常，跳过续期流程。
+> 2. `checkSession`返回`false`将调用`refreshSession`，并传入当前带有`refreshToken`的会话对象作为参数。
++ checkSession(request: InternalAxiosRequestConfig, session: BasicSession): boolean
+> 默认实现为提取 `authorizer.withAuthentication` 写入请求头的`accessToken`与当前过期会话信息的`accessToken`匹配，相等返回`false`。
++ withAuthentication(request: InternalAxiosRequestConfig, session: BasicSession): void
+> 拦截请求注入会话信息，默认实现为将`accessToken`写入请求头`Authorization: Bearer ${accessToken}`。
+> 如果`refreshSession`返回`null`，那么插件正常重载的情况下`getSession`会返回`null`，会话对象为空`withAuthentication`不会执行请求头写入。
++ getSession(): Promise<BasicSession>
+> 获取会话信息对象，其实就是调用`sessionStorage.get`。
++ storageSession(session: BasicSession | null)
+> 调用`sessionStorage.set`。
+
+---
+
+```mermaid
+graph TD
+    %% 请求拦截器部分
+    Start((开始请求)) --> ReqInterceptor[<b>请求拦截器</b>]
+    ReqInterceptor --> GetSession[authorizer.getSession 获取会话]
+    GetSession --> InjectHeader[authorizer.withAuthentication<br/>注入 Authorization 响应头]
+    InjectHeader --> SendRequest[发送 Axios 请求]
+
+    %% 响应拦截器部分
+    SendRequest --> RespInterceptor{<b>响应拦截器</b><br/>状态码判断}
+    RespInterceptor -- "2xx (成功)" --> Success((返回数据))
+    
+    RespInterceptor -- "401 (授权失效)" --> CheckUnauthorized{当前是否正在<br/>处理刷新流程?}
+    
+    %% 队列逻辑
+    CheckUnauthorized -- "是 (unauthorized=true)" --> QueueRequest[将请求放入 PendingQueue 队列等待]
+    QueueRequest --> WaitRefresh[等待刷新成功后自动重发]
+    
+    %% 核心刷新逻辑
+    CheckUnauthorized -- "否 (unauthorized=false)" --> SetLock[设置锁 unauthorized=true]
+    SetLock --> CheckHistory{refreshToken<br/>是否已作废?}
+    
+    CheckHistory -- "是 (已作废)" --> Denied[authorizer.onAuthorizedDenied<br/>跳转登录页/清理会话]
+    
+    CheckHistory -- "否" --> CheckSessionMatch{checkSession 当前 Session 与<br/>请求 Session 是否一致?}
+    
+    %% 避免重复刷新
+    CheckSessionMatch -- "不一致 (已被他人刷新)" --> PopQueue[直接开始消耗队列重发]
+    
+    CheckSessionMatch -- "一致 (需执行刷新)" --> RefreshAction[<b>authorizer.refreshSession</b><br/>调用刷新接口]
+    
+    RefreshAction -- "刷新失败 (Token过期)" --> Deprecate[标记当前 Session 作废]
+    Deprecate --> Denied
+    
+    RefreshAction -- "刷新成功" --> UpdateSession[authorizer.storageSession<br/>更新持久化存储]
+    UpdateSession --> ReleaseLock[释放锁 unauthorized=false]
+    ReleaseLock --> PopQueue
+    
+    PopQueue --> ResendAll[依次重发队列中的所有请求]
+    ResendAll --> Success
+
+    %% 其他错误
+    RespInterceptor -- "5xx/其他错误" --> Error((抛出异常))
+```