@lark-apaas/client-toolkit 1.2.73 → 1.2.74-alpha.20261010220931

package/README.md

@@ -73,4 +73,177 @@ function Nav() {
     </nav>
   );
 } 
-```
+```
+
+## Axios 403 合同与 1.x → 2.x 迁移
+
+`axiosForBackend` / `getAxiosForBackend()` 在 **1.x** 有一项历史兼容行为：当
+Axios 按默认 `validateStatus` 收到带响应的真实 HTTP 403 时，SDK 的响应拦截器
+会返回 `error.response`，因此 Promise 是 fulfilled，返回值仍可读取
+`status`、`data`、`headers` 和 `config`。
+
+这不是推荐给新代码的安全默认。公开类型仍是普通 `AxiosInstance`：例如
+`get<SuccessDto>()` 的 TypeScript 类型会把 `response.data` 表示成
+`SuccessDto`，但 1.x 的 403 在运行时可能携带权限错误体。类型系统不会自动把
+两种 body 表示成联合类型，调用方必须先检查 status，再把 data 当成功 DTO。
+
+边界如下：
+
+- 1.x 默认配置下，2xx fulfilled；带响应的 403 也因兼容逻辑 fulfilled。
+- 400、401、404、500 等其它 HTTP 错误 rejected；网络错误同样 rejected，且
+  `error.response` 通常为 `undefined`。
+- 调用方若用 `validateStatus` 显式接受 403，Axios 会在进入 SDK 的 rejection
+  interceptor 之前正常 fulfilled；这在 1.x 和目标 2.x 合同中都不变。
+- 采用新合同的 2.x 目标是恢复 Axios 默认语义：默认真实 403 rejected，并保留
+  原始 `AxiosError` 的 `response`、`config` 等字段。**本文描述迁移目标，不表示
+  2.x 已经发布或可通过 `latest` 获取；升级前应另行确认可用的精确 2.x 版本。**
+
+以下示例中的错误判断使用 Axios 官方类型守卫。只有
+`axios.isAxiosError(error)` 为真时，才把错误当作 `AxiosError`；HTTP 错误可从
+`error.response?.status` / `error.response?.data` 读取响应，而网络错误通常没有
+`response`。
+
+```ts
+import axios from 'axios';
+import { axiosForBackend } from '@lark-apaas/client-toolkit';
+
+type ItemList = { items: Array<{ id: string }> };
+type ApiErrorBody = { code?: string; message?: string };
+```
+
+### 直接读取 `response.data` 的调用方
+
+1.x 不要直接返回 data；先在统一 API 层检查 fulfilled response 的 status：
+
+```ts
+async function listItems1x(): Promise<ItemList> {
+  const response = await axiosForBackend.get<ItemList>('/api/items');
+
+  if (response.status < 200 || response.status >= 300) {
+    // 1.x 默认配置下，此分支主要承接历史 fulfilled 403。
+    throw new Error(`Request failed with status ${response.status}`);
+  }
+
+  return response.data;
+}
+```
+
+迁移到采用新合同的 2.x 后，成功路径可以继续读取 data，但默认 403 在 catch 中
+处理：
+
+```ts
+async function listItems2x(): Promise<ItemList> {
+  try {
+    const response = await axiosForBackend.get<ItemList>('/api/items');
+    return response.data;
+  } catch (error) {
+    if (axios.isAxiosError<ApiErrorBody>(error)) {
+      const status = error.response?.status;
+      const body = error.response?.data;
+      throw new Error(`Request failed with status ${status}: ${body?.message ?? ''}`);
+    }
+    throw error;
+  }
+}
+```
+
+### 已按 fulfilled status 分支处理的调用方
+
+1.x 保留 status 分支，并确保成功 DTO 只在 2xx 后交给业务组件：
+
+```ts
+async function listItemsByStatus1x() {
+  const response = await axiosForBackend.get<ItemList>('/api/items');
+
+  if (response.status === 403) {
+    return { ok: false as const, reason: 'forbidden' as const };
+  }
+  if (response.status < 200 || response.status >= 300) {
+    return { ok: false as const, reason: 'http-error' as const };
+  }
+  return { ok: true as const, data: response.data };
+}
+```
+
+迁移到采用新合同的 2.x 后，把 403 分支移到结构化 `AxiosError` 的 catch 中：
+
+```ts
+async function listItemsByStatus2x() {
+  try {
+    const response = await axiosForBackend.get<ItemList>('/api/items');
+    return { ok: true as const, data: response.data };
+  } catch (error) {
+    if (axios.isAxiosError<ApiErrorBody>(error) && error.response?.status === 403) {
+      return {
+        ok: false as const,
+        reason: 'forbidden' as const,
+        detail: error.response.data,
+      };
+    }
+    throw error;
+  }
+}
+```
+
+### 已有 catch 的调用方
+
+1.x 的 catch 仍负责 400、401、404、500 和网络错误，但默认真实 403 必须在
+fulfilled 分支检查：
+
+```ts
+async function loadItems1x() {
+  try {
+    const response = await axiosForBackend.get<ItemList>('/api/items');
+    if (response.status === 403) {
+      return { ok: false as const, reason: 'forbidden' as const };
+    }
+    return { ok: true as const, data: response.data };
+  } catch (error) {
+    if (axios.isAxiosError<ApiErrorBody>(error)) {
+      return {
+        ok: false as const,
+        reason: error.response ? 'http-error' : 'network-error',
+        status: error.response?.status,
+      };
+    }
+    throw error;
+  }
+}
+```
+
+采用新合同的 2.x 中，catch 可以统一处理默认 403 和其它 rejected 错误：
+
+```ts
+async function loadItems2x() {
+  try {
+    const response = await axiosForBackend.get<ItemList>('/api/items');
+    return { ok: true as const, data: response.data };
+  } catch (error) {
+    if (axios.isAxiosError<ApiErrorBody>(error)) {
+      return {
+        ok: false as const,
+        reason: error.response?.status === 403 ? 'forbidden' : 'request-error',
+        status: error.response?.status,
+        detail: error.response?.data,
+      };
+    }
+    throw error;
+  }
+}
+```
+
+### 显式接受 403
+
+如果业务有意把 403 当普通响应，必须显式声明并继续检查 status；1.x 与目标
+2.x 都会 fulfilled：
+
+```ts
+const response = await axiosForBackend.get<ItemList | ApiErrorBody>('/api/items', {
+  validateStatus: status => (status >= 200 && status < 300) || status === 403,
+});
+
+if (response.status === 403) {
+  const errorBody = response.data as ApiErrorBody;
+  // 显式处理权限错误体，不把它当 ItemList。
+}
+```

package/lib/utils/__test__/axiosConfig.test.d.ts

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

package/lib/utils/__test__/axiosConfig.test.js

@@ -0,0 +1,159 @@
+import { createServer } from "node:http";
+import axios from "axios";
+import { afterAll, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { initAxiosConfig } from "../axiosConfig.js";
+const { loggerLogMock, sendEventMock, captureExceptionMock } = vi.hoisted(()=>({
+        loggerLogMock: vi.fn(),
+        sendEventMock: vi.fn(),
+        captureExceptionMock: vi.fn()
+    }));
+vi.mock('@lark-apaas/observable-web', ()=>({
+        observable: {
+            startSpan: vi.fn(()=>void 0),
+            log: vi.fn()
+        }
+    }));
+vi.mock('@lark-apaas/internal-slardar', ()=>({
+        slardar: {
+            sendEvent: sendEventMock,
+            captureException: captureExceptionMock
+        }
+    }));
+vi.mock('../../apis/logger', ()=>({
+        logger: {
+            log: loggerLogMock
+        }
+    }));
+vi.mock('../../logger/selected-logs', ()=>({
+        getStacktrace: vi.fn(async ()=>[])
+    }));
+vi.mock('../../locales', ()=>({
+        t: vi.fn((key)=>key)
+    }));
+const responseBody = {
+    code: 'FORBIDDEN',
+    message: 'permission denied'
+};
+let server;
+let baseURL;
+const originalWindowDescriptor = Object.getOwnPropertyDescriptor(globalThis, 'window');
+beforeAll(async ()=>{
+    Object.defineProperty(globalThis, 'window', {
+        configurable: true,
+        value: {
+            csrfToken: void 0,
+            location: {
+                pathname: '/contract-test'
+            }
+        }
+    });
+    server = createServer((request, response)=>{
+        if ('/network-error' === request.url) return void request.socket.destroy();
+        const status = Number(request.url?.split('/').pop());
+        const body = 403 === status ? responseBody : {
+            status
+        };
+        response.writeHead(status, {
+            'content-type': 'application/json',
+            'x-test-status': String(status)
+        });
+        response.end(204 === status ? void 0 : JSON.stringify(body));
+    });
+    await new Promise((resolve)=>{
+        server.listen(0, '127.0.0.1', resolve);
+    });
+    const address = server.address();
+    baseURL = `http://127.0.0.1:${address.port}`;
+});
+afterAll(async ()=>{
+    await new Promise((resolve, reject)=>{
+        server.close((error)=>error ? reject(error) : resolve());
+    });
+    if (originalWindowDescriptor) Object.defineProperty(globalThis, 'window', originalWindowDescriptor);
+    else Reflect.deleteProperty(globalThis, 'window');
+});
+beforeEach(()=>{
+    vi.clearAllMocks();
+});
+function client() {
+    const instance = axios.create({
+        baseURL,
+        adapter: 'http'
+    });
+    initAxiosConfig(instance);
+    return instance;
+}
+describe('initAxiosConfig 1.x legacy response contract', ()=>{
+    it('fulfills a default real HTTP 403 with its readable response structure', async ()=>{
+        const response = await client().get('/status/403');
+        expect(response).toMatchObject({
+            status: 403,
+            data: responseBody,
+            config: {
+                method: 'get',
+                url: '/status/403'
+            }
+        });
+        expect(response.headers['x-test-status']).toBe('403');
+        expect(sendEventMock).toHaveBeenCalledWith(expect.objectContaining({
+            name: 'toolkit_axios_403_downgrade'
+        }));
+    });
+    it.each([
+        200,
+        201,
+        204
+    ])('keeps real HTTP %s responses fulfilled', async (status)=>{
+        const response = await client().get(`/status/${status}`);
+        expect(response.status).toBe(status);
+        expect(response.data).toEqual(204 === status ? '' : {
+            status
+        });
+    });
+    it.each([
+        400,
+        401,
+        404,
+        500
+    ])('keeps real HTTP %s errors rejected as AxiosError', async (status)=>{
+        const error = await client().get(`/status/${status}`).catch((reason)=>reason);
+        expect(axios.isAxiosError(error)).toBe(true);
+        expect(error).toMatchObject({
+            config: {
+                method: 'get',
+                url: `/status/${status}`
+            },
+            response: {
+                status,
+                data: {
+                    status
+                }
+            }
+        });
+    });
+    it('keeps a real network failure rejected without a response', async ()=>{
+        const error = await client().get('/network-error').catch((reason)=>reason);
+        expect(axios.isAxiosError(error)).toBe(true);
+        expect(error).toMatchObject({
+            config: {
+                method: 'get',
+                url: '/network-error'
+            }
+        });
+        expect(error.response).toBeUndefined();
+    });
+    it('keeps a real HTTP 403 fulfilled when validateStatus explicitly accepts it', async ()=>{
+        const validateStatus = vi.fn((status)=>403 === status);
+        const response = await client().get('/status/403', {
+            validateStatus
+        });
+        expect(validateStatus).toHaveBeenCalledWith(403);
+        expect(response).toMatchObject({
+            status: 403,
+            data: responseBody
+        });
+        expect(sendEventMock).not.toHaveBeenCalledWith(expect.objectContaining({
+            name: 'toolkit_axios_403_downgrade'
+        }));
+    });
+});

package/lib/utils/axiosConfig.d.ts

@@ -9,4 +9,20 @@ declare module 'axios' {
         _requestUUID?: string;
     }
 }
+/**
+ * 为 Axios 实例安装 client-toolkit 的请求与响应拦截器。
+ *
+ * @remarks
+ * 1.x 为兼容存量调用，会把带 `error.response` 的真实 403 从 rejected 恢复为
+ * fulfilled `AxiosResponse`。`AxiosInstance` 的泛型仍只描述调用方声明的成功
+ * DTO，无法表达 403 错误体，因此直接读取 `response.data` 前必须先检查
+ * `response.status`。fulfilled-status 调用方应在统一 API 层处理 403；仅依赖
+ * `catch` 的调用方在 1.x 默认配置下不会在 catch 中收到真实 403。
+ *
+ * 其它 4xx/5xx 和网络错误仍以 `AxiosError` rejected；调用方显式通过
+ * `validateStatus` 接受 403 时，Axios 也会正常 fulfilled。上述 403 recovery
+ * 是 1.x 历史兼容合同，不是推荐给新代码的安全默认。迁移到采用新合同的
+ * 2.x 时，默认 403 将在 catch 中以原始 `AxiosError` 提供
+ * `error.response?.status` 和 `error.response?.data`。完整迁移示例见包 README。
+ */
 export declare function initAxiosConfig(axiosInstance?: AxiosInstance): void;

package/lib/utils/getAxiosForBackend.d.ts

@@ -6,6 +6,20 @@ declare module 'axios' {
         };
     }
 }
-/** 获取axios实例 */
+/**
+ * 获取供前端调用后端 API 的共享 Axios 实例。
+ *
+ * @remarks
+ * 1.x 保留历史兼容语义：默认真实 403 会 fulfilled。直接读取
+ * `response.data` 的调用方必须先检查 status；已有 fulfilled-status 调用方应
+ * 继续在统一 API 层归一化 403；只在 catch 中判断 403 的调用方不能假设
+ * 1.x 默认请求会进入 catch。其它 HTTP 错误和网络错误仍 rejected，通常可用
+ * `axios.isAxiosError(error)` 后读取 `error.response`。
+ *
+ * 迁移到采用新合同的 2.x 后，默认真实 403 会 rejected 为原始
+ * `AxiosError`，fulfilled-status 分支应迁到 catch；显式 `validateStatus`
+ * 接受 403 时仍会 fulfilled。该 1.x 行为仅用于兼容，不是推荐的新合同。
+ * 完整的 direct-data、fulfilled-status 和 catch 迁移示例见包 README。
+ */
 export declare function getAxiosForBackend(): AxiosInstance;
 export declare const axiosForBackend: AxiosInstance;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/client-toolkit",
-  "version": "1.2.73",
+  "version": "1.2.74-alpha.20261010220931",
   "types": "./lib/index.d.ts",
   "main": "./lib/index.js",
   "files": [