@polyv/request-plugin-status-code 2.0.0

package/README.md

@@ -0,0 +1,104 @@
+# StatusCodeRequestPlugin
+
+用途：对后端返回的 code 进行处理，并返回 Response 中的 data
+
+## 实例化参数
+
+| 参数名 | 用途 | 类型 | 默认值 |
+| - | - | - | - |
+| `successCode` | 请求成功状态码 | `number \| number[]` | `200` |
+| `fields` | 状态码字段配置 | `StatusCodeFields` | 见下文 |
+| `errorCallback` | 请求失败回调函数 | `function` | - |
+
+## 请求选项
+
+| 参数名 | 用途 | 类型 | 默认值 |
+| - | - | - | - |
+| `useStatusCode` | 是否使用状态码判断 | `boolean` | `true` |
+| `successCode` | 成功状态码 | `number \| number[]` | - |
+
+## 状态码字段配置
+
+`StatusCodeFields` 类型如下：
+
+| 参数名 | 用途 | 类型 | 默认值 |
+| - | - | - | - |
+| `codeField` | 状态码字段名 | `string` | `'code'` |
+| `statusField` | 状态字段名 | `string` | `'status'` |
+| `messageField` | 消息字段名 | `string` | `'message'` |
+| `dataField` | 数据字段名 | `string` | `'data'` |
+| `errorField` | 错误对象字段名 | `string` | `'error'` |
+| `errorCodeField` | 错误对象中的错误码字段名 | `string` | `'code'` |
+| `errorDescField` | 错误对象中的错误描述字段名 | `string` | `'desc'` |
+
+## 使用方式
+
+```js
+import { PolyvRequest } from '@polyv/request-core';
+import { StatusCodeRequestPlugin } from '@polyv/request-plugin-status-code';
+
+// 基础用法
+const requester = new PolyvRequest({
+  requestPlugins: [
+    new StatusCodeRequestPlugin(),
+  ]
+});
+
+// 自定义成功状态码
+const requester = new PolyvRequest({
+  requestPlugins: [
+    new StatusCodeRequestPlugin({
+      successCode: [200, 0],
+    }),
+  ]
+});
+
+// 自定义字段名
+const requester = new PolyvRequest({
+  requestPlugins: [
+    new StatusCodeRequestPlugin({
+      fields: {
+        codeField: 'errorCode',
+        dataField: 'result',
+        messageField: 'msg',
+      },
+    }),
+  ]
+});
+
+// 添加错误处理回调
+const requester = new PolyvRequest({
+  requestPlugins: [
+    new StatusCodeRequestPlugin({
+      errorCallback: (code, message) => {
+        console.error(`请求失败: ${code} - ${message}`);
+      },
+    }),
+  ]
+});
+
+interface PeopleInfo {
+  name: string;
+}
+// 如果后端接口返回的 Response：{ code: 200, data: { name: string } }
+const data = await requester.get<PeopleInfo>('/api/data', {});
+// 此时无需做 code 判断，直接得到 data 的内容
+console.log('名称', data.name);
+
+// 如果你想在某个请求中不使用状态码判断
+requester.get('/api/data', {}, {
+  useStatusCode: false,
+});
+```
+
+## 响应处理逻辑
+
+1. 插件会解析接口返回的数据，提取 `code`、`status`、`message`、`data` 等字段
+2. 当满足以下条件之一时，请求被视为成功：
+   - 返回的 `code` 值在成功状态码列表中
+   - 返回的 `status` 值为 `'success'`
+3. 成功时直接返回 `data` 字段的内容
+4. 失败时抛出错误，错误信息包含：
+   - `code`: 优先使用 `error.code` 字段，其次使用顶层 `code` 字段
+   - `message`: 优先使用 `error.desc` 字段，其次使用顶层 `message` 字段，都不存在则为 `'未知错误'`
+

package/index.d.ts

@@ -0,0 +1,3 @@
+export * from './status-code-plugin';
+export * from './types';
+export * from './request-options';

package/index.js

@@ -0,0 +1,3 @@
+export * from './status-code-plugin';
+export * from './types';
+export * from './request-options';

package/package.json

@@ -0,0 +1,9 @@
+{
+  "name": "@polyv/request-plugin-status-code",
+  "version": "2.0.0",
+  "main": "./index.js",
+  "dependencies": {
+    "@polyv/request-core": "2.0.0"
+  },
+  "types": "./index.d.ts"
+}

package/request-options.d.ts

@@ -0,0 +1,21 @@
+export interface StatusCodeRequestOptions {
+    /**
+     * 是否使用 status-code 判断返回
+     * @default true
+     * @plugin `StatusCodeRequestPlugin`
+     */
+    useStatusCode?: boolean;
+    /**
+     * 成功状态码
+     * @plugin `StatusCodeRequestPlugin`
+     */
+    successCode?: number | number[];
+}
+declare module '@polyv/request-core' {
+    interface RequestCustomOptions extends StatusCodeRequestOptions {
+    }
+}
+declare module 'axios' {
+    interface AxiosRequestConfig extends StatusCodeRequestOptions {
+    }
+}

package/request-options.js

@@ -0,0 +1 @@
+export {};

package/status-code-plugin.d.ts

@@ -0,0 +1,20 @@
+import type { RequestOptions, RequestPlugin, RequestResult } from '@polyv/request-core';
+import { StatusCodeRequestPluginConfig } from './types';
+/**
+ * 状态码处理插件
+ */
+export declare class StatusCodeRequestPlugin implements RequestPlugin {
+    private __fields;
+    private __successCodes;
+    private __errorCallback?;
+    constructor(config?: StatusCodeRequestPluginConfig);
+    usePlugin(options: RequestOptions): boolean;
+    interceptResponse(result: RequestResult, options: RequestOptions): Promise<RequestResult>;
+    private __formatRes;
+    /**
+     * 格式化 successCode，返回数组类型的状态码
+     * @param target
+     */
+    private __formateSuccessCode;
+    private __getSuccessCodes;
+}

package/status-code-plugin.js

@@ -0,0 +1,91 @@
+import { createRequestError } from '@polyv/request-core';
+/**
+ * 状态码处理插件
+ */
+export class StatusCodeRequestPlugin {
+    __fields;
+    __successCodes;
+    __errorCallback;
+    constructor(config = {}) {
+        this.__successCodes = this.__formateSuccessCode(config.successCode ?? 200);
+        this.__errorCallback = config.errorCallback;
+        this.__fields = {
+            codeField: 'code',
+            statusField: 'status',
+            messageField: 'message',
+            dataField: 'data',
+            errorField: 'error',
+            errorCodeField: 'code',
+            errorDescField: 'desc',
+            ...config.fields,
+        };
+    }
+    usePlugin(options) {
+        const { useStatusCode = true } = options;
+        return useStatusCode;
+    }
+    interceptResponse(result, options) {
+        if (!result.data) {
+            throw new Error(`status-code-plugin error: result.data is undefined, url: ${options.requestUrl}`);
+        }
+        const data = this.__formatRes(result.data);
+        const apiCode = data.code;
+        const apiStatus = data.status;
+        const successCodes = this.__getSuccessCodes(options);
+        if (successCodes.includes(apiCode) || apiStatus === 'success') {
+            return Promise.resolve({
+                ...result,
+                data: data.data,
+            });
+        }
+        const code = data.error?.code || apiCode;
+        const message = data.error?.desc || data.message || '未知错误';
+        const error = createRequestError({
+            code,
+            message,
+        });
+        if (this.__errorCallback) {
+            this.__errorCallback(code, message);
+        }
+        return Promise.reject(error);
+    }
+    __formatRes(target) {
+        const code = target[this.__fields.codeField];
+        const status = target[this.__fields.statusField];
+        const message = target[this.__fields.messageField];
+        const data = target[this.__fields.dataField];
+        const result = {
+            code,
+            data,
+            status,
+            message,
+        };
+        const error = target[this.__fields.errorField];
+        if (error) {
+            const errorCode = error[this.__fields.errorCodeField];
+            const errorDesc = error[this.__fields.errorDescField];
+            result.error = {
+                code: errorCode,
+                desc: errorDesc,
+            };
+        }
+        return result;
+    }
+    /**
+     * 格式化 successCode，返回数组类型的状态码
+     * @param target
+     */
+    __formateSuccessCode(target) {
+        if (typeof target === 'number') {
+            return [target];
+        }
+        else if (Array.isArray(target)) {
+            return target;
+        }
+        return [];
+    }
+    __getSuccessCodes(options) {
+        const optionsSuccessCodes = this.__formateSuccessCode(options.successCode);
+        return [...this.__successCodes, ...optionsSuccessCodes];
+    }
+}

package/types.d.ts

@@ -0,0 +1,35 @@
+export interface StatusCodeRequestPluginConfig {
+    /**
+     * 请求成功状态码
+     * @default 200
+     */
+    successCode?: number | number[];
+    /**
+     * 状态码字段
+     */
+    fields?: StatusCodeFields;
+    /**
+     * 请求失败回调
+     */
+    errorCallback?: StatusCodeErrorCallback;
+}
+export interface StatusCodeFields {
+    codeField?: string;
+    statusField?: string;
+    messageField?: string;
+    dataField?: string;
+    errorField?: string;
+    errorCodeField?: string;
+    errorDescField?: string;
+}
+export type StatusCodeErrorCallback = (code: number | undefined, message: string) => unknown;
+export interface PolyvResponseType {
+    code: number;
+    data: unknown;
+    status?: string;
+    message?: string;
+    error?: {
+        code?: number;
+        desc?: string;
+    };
+}

package/types.js

@@ -0,0 +1 @@
+export {};