@minson1994/ms-utils 1.0.0

package/README.md

@@ -0,0 +1,696 @@
+# @minson/ms-utils
+
+一个实用型 TypeScript 工具库，封装 HTTP 请求、时间处理、加密/随机、数据验证、任务队列、并发去重、Promise Hook、Cookie 等常用能力。
+
+- TypeScript 编写，自带 `.d.ts` 类型提示
+- 同时支持 ESM / CommonJS
+- 核心能力不绑定浏览器、Node、微信小程序、uniapp
+- 浏览器、微信小程序、uniapp、axios 能力通过子路径按需导入
+
+## 安装
+
+```bash
+npm install @minson/ms-utils
+```
+
+如果要使用 axios 适配器，请在项目里自行安装：
+
+```bash
+npm install axios qs
+```
+
+## 导入方式
+
+```js
+import {
+  $Use,
+  ApiConfig,
+  ApiRequest,
+  ApiStatusInterceptor,
+  Concurrency,
+  AlgorithmUtils,
+  Hook,
+  TaskQueue,
+  TimeUtils,
+  ValidateUtils,
+} from "@minson/ms-utils";
+
+import { AxiosHttpAdapter } from "@minson/ms-utils/axios";
+import { CookieUtils } from "@minson/ms-utils/browser";
+import { WxHttpAdapter } from "@minson/ms-utils/wx";
+```
+
+CommonJS：
+
+```js
+const { TimeUtils, AlgorithmUtils } = require("@minson/ms-utils");
+```
+
+## 功能总览
+
+| 能力         | 导入                       | 说明                                              |
+| ------------ | -------------------------- | ------------------------------------------------- |
+| HTTP 请求    | `@minson/ms-utils`         | 请求配置、拦截器、适配器编排                      |
+| axios 适配器 | `@minson/ms-utils/axios`   | 用 axios 作为底层请求实现                         |
+| Cookie       | `@minson/ms-utils/browser` | 浏览器 `document.cookie` 工具                     |
+| 小程序/uni 请求 | `@minson/ms-utils/wx`      | 微信小程序 `wx.request` / uniapp `uni.request` 适配器 |
+| 时间         | `TimeUtils`                | 格式化、加减、差值、多久前、延迟                  |
+| 加密/随机    | `AlgorithmUtils`           | Base64、MD5、AES、SHA256、HMAC、RSA、UUID、随机数 |
+| 数据验证     | `ValidateUtils`            | 空值、类型、邮箱、手机号、身份证、银行卡等        |
+| 任务队列     | `TaskQueue`                | 异步任务并发控制、超时、暂停恢复                  |
+| 并发去重     | `Concurrency`              | 同 key 并发只执行一次                             |
+| Hook         | `Hook`                     | 外部回调唤醒 Promise                              |
+
+## HTTP 请求
+
+### 基础请求
+
+```js
+import axios from "axios";
+import qs from "qs";
+import { $Use, ApiRequest } from "@minson/ms-utils";
+import { AxiosHttpAdapter } from "@minson/ms-utils/axios";
+
+const request = new ApiRequest({
+  url: ["https://api.example.com"],
+  adapter: new AxiosHttpAdapter(axios, qs),
+});
+
+const result = await $Use({
+  url: "/user/info",
+  method: "GET",
+  data: { id: 1 },
+})
+  .useJsonBody()
+  .useBackFailResult()
+  .request(request);
+```
+
+### 绑定请求后执行
+
+```js
+const result = await request
+  .use({
+    url: "/",
+    method: "GET",
+  })
+  .useJsonBody()
+  .useBackFailResult()
+  .emit();
+```
+
+### 链式配置
+
+```js
+const config = ApiConfig.use({ url: "/upload" })
+  .useAuth()
+  .useTimeout(10)
+  .useHeaders({ token: "xxx" })
+  .useWithCredentials()
+  .useUpload()
+  .useJsonBody()
+  .useSign()
+  .useLoading()
+  .useShowErrorMessage()
+  .useCheckHttpStatus()
+  .useBackFailResult()
+  .useBackOnlyData()
+  .useCache();
+```
+
+### 状态拦截器
+
+`ApiStatusInterceptor` 默认读取：
+
+```js
+{
+    code: 200,
+    message: 'ok',
+    data: {}
+}
+```
+
+可以按你的后端字段改：
+
+```js
+const statusInterceptor = new ApiStatusInterceptor({
+  status: "code",
+  message: "message",
+  data: "data",
+  success: 200,
+  onUnauthorized(message) {
+    console.log("登录失效：", message);
+  },
+});
+```
+
+### HTTP API
+
+| API                     | 说明                                    |
+| ----------------------- | --------------------------------------- |
+| `ApiRequest`           | 请求编排器，串起 adapter 和 interceptor |
+| `ApiConfig`            | 单次请求配置，支持链式 `useXxx`         |
+| `$Use(options)`         | `ApiConfig.use(options)` 的快捷入口    |
+| `ApiGlobalConfig`      | 全局默认配置                            |
+| `ApiResponse`          | 统一响应对象                            |
+| `ApiAdapter`           | 抽象适配器基类                          |
+| `ApiInterceptor`       | 抽象拦截器基类                          |
+| `ApiStatusInterceptor` | HTTP/业务状态码处理                     |
+| `ApiCacheInterceptor`  | 缓存拦截器                              |
+| `ApiUIInterceptor`     | loading / error message UI 钩子         |
+
+## TimeUtils 时间工具
+
+```js
+TimeUtils.now();
+TimeUtils.timestamp();
+TimeUtils.timestamp(new Date(), "second");
+TimeUtils.toDate("2026-06-08");
+TimeUtils.isValid("2026-06-08");
+TimeUtils.format(new Date(), "yyyy-MM-dd HH:mm:ss");
+TimeUtils.add(new Date(), 1, "day");
+TimeUtils.subtract(new Date(), 1, "hour");
+TimeUtils.diff("2026-06-08", "2026-06-10", "day");
+TimeUtils.fromNow(Date.now() - 60 * 1000); // 1 分钟前
+TimeUtils.startOfDay(new Date());
+TimeUtils.endOfDay(new Date());
+await TimeUtils.wait(1000);
+```
+
+| 方法                           | 说明                             |
+| ------------------------------ | -------------------------------- |
+| `now()`                        | 当前时间 `Date`                  |
+| `timestamp(date?, unit?)`      | 毫秒/秒时间戳                    |
+| `toDate(value)`                | 转成 `Date`                      |
+| `isValid(value)`               | 是否是有效时间                   |
+| `format(date?, pattern?)`      | 格式化时间                       |
+| `add(date, amount, unit)`      | 增加时间                         |
+| `subtract(date, amount, unit)` | 减少时间                         |
+| `diff(start, end, unit?)`      | 计算差值                         |
+| `fromNow(date, base?)`         | 输出“刚刚 / x 分钟前 / x 小时后” |
+| `startOfDay(date?)`            | 当天开始时间                     |
+| `endOfDay(date?)`              | 当天结束时间                     |
+| `wait(ms)`                     | 延迟等待                         |
+
+## AlgorithmUtils 加密和随机工具
+
+> Base64、MD5、AES、SHA256、HMAC、UUID、随机数基于 `crypto-js` 和运行时随机源；RSA 使用 WebCrypto。老环境没有 `crypto.subtle` 时，RSA 不可用。
+
+```js
+AlgorithmUtils.base64Encode("hello");
+AlgorithmUtils.base64Decode("aGVsbG8=");
+
+AlgorithmUtils.md5("hello");
+AlgorithmUtils.md5("hello", 16, true);
+AlgorithmUtils.md5_16("hello");
+AlgorithmUtils.md5_32("hello");
+
+const encrypted = AlgorithmUtils.aesEncrypt("content", "password");
+const decrypted = AlgorithmUtils.aesDecrypt(encrypted, "password");
+
+AlgorithmUtils.sha256("hello");
+AlgorithmUtils.hmac("hello", "secret", "SHA256");
+AlgorithmUtils.hmacSha256("hello", "secret");
+
+AlgorithmUtils.uuid();
+AlgorithmUtils.randomInt(1, 100);
+AlgorithmUtils.randomFloat();
+AlgorithmUtils.randomString(16);
+```
+
+### AES 指定 iv
+
+```js
+const ciphertext = AlgorithmUtils.aesEncrypt("content", {
+  key: "1234567890123456",
+  iv: "1234567890123456",
+});
+
+AlgorithmUtils.aesDecrypt(ciphertext, {
+  key: "1234567890123456",
+  iv: "1234567890123456",
+});
+```
+
+### RSA
+
+```js
+const keys = await AlgorithmUtils.rsaGeneratePemKeyPair();
+const ciphertext = await AlgorithmUtils.rsaEncrypt("secret", keys.publicKey);
+const plaintext = await AlgorithmUtils.rsaDecrypt(ciphertext, keys.privateKey);
+```
+
+| 方法                                                                 | 说明                       |
+| -------------------------------------------------------------------- | -------------------------- |
+| `base64Encode(text)` / `base64Decode(text)`                          | Base64 编解码              |
+| `md5(text, length?, upper?)`                                         | MD5，支持 16/32 位和大小写 |
+| `md5_16(text, upper?)` / `md5_32(text, upper?)`                      | 快捷 MD5                   |
+| `aesEncrypt(text, options)` / `aesDecrypt(text, options)`            | AES 加解密                 |
+| `sha256(text, upper?)`                                               | SHA256                     |
+| `hmac(text, key, algorithm?, upper?)`                                | HMAC，支持 SHA256/SHA1/MD5 |
+| `hmacSha256(text, key, upper?)`                                      | HMAC-SHA256                |
+| `uuid()`                                                             | UUID v4                    |
+| `randomInt(min, max)`                                                | 指定范围整数               |
+| `randomFloat()`                                                      | 0 到 1 的随机小数          |
+| `randomString(length?, chars?)`                                      | 随机字符串                 |
+| `rsaGenerateKeyPair()` / `rsaGeneratePemKeyPair()`                   | 生成 RSA 密钥对            |
+| `rsaEncrypt(text, publicKey)` / `rsaDecrypt(ciphertext, privateKey)` | RSA-OAEP 加解密            |
+
+## ValidateUtils 数据验证工具
+
+```js
+ValidateUtils.isEmpty("");
+ValidateUtils.isNotEmpty("abc");
+ValidateUtils.isString("abc");
+ValidateUtils.isNumber(123);
+ValidateUtils.isInteger(1);
+ValidateUtils.isBoolean(false);
+ValidateUtils.isArray([]);
+ValidateUtils.isPlainObject({});
+
+ValidateUtils.lengthBetween("abc", 1, 10);
+ValidateUtils.numberBetween(5, 1, 10);
+ValidateUtils.match("abc", /^[a-z]+$/);
+
+ValidateUtils.isEmail("a@b.com");
+ValidateUtils.isMobileCN("13800138000");
+ValidateUtils.isUrl("https://example.com");
+ValidateUtils.isIPv4("127.0.0.1");
+ValidateUtils.isIPv6("::1");
+ValidateUtils.isJSON('{"a":1}');
+ValidateUtils.isPostalCodeCN("528000");
+ValidateUtils.isPlateNumberCN("粤A12345");
+ValidateUtils.isBankCard("4111111111111111");
+ValidateUtils.isIdCardCN("11010519491231002X");
+ValidateUtils.validateIdCardCN("11010519491231002X");
+ValidateUtils.passwordStrength("Abcdef12!@");
+ValidateUtils.isStrongPassword("Abcdef12!@");
+```
+
+| 方法                                                | 说明                           |
+| --------------------------------------------------- | ------------------------------ |
+| `isNil` / `isEmpty` / `isNotEmpty`                  | 空值判断                       |
+| `isString` / `isNumber` / `isInteger` / `isBoolean` | 基础类型判断                   |
+| `isArray` / `isPlainObject`                         | 数组和普通对象判断             |
+| `lengthBetween` / `numberBetween` / `match`         | 通用规则判断                   |
+| `isEmail` / `isMobileCN` / `isUrl`                  | 常用格式判断                   |
+| `isIPv4` / `isIPv6` / `isJSON`                      | 网络和 JSON 判断               |
+| `isPostalCodeCN` / `isPlateNumberCN`                | 国内邮编、车牌判断             |
+| `isBankCard`                                        | 银行卡 Luhn 校验               |
+| `isIdCardCN` / `validateIdCardCN`                   | 身份证校验，支持生日和性别返回 |
+| `passwordStrength` / `isStrongPassword`             | 密码强度判断                   |
+
+## TaskQueue 任务队列
+
+用于限制异步任务并发，支持超时、任务间隔、暂停、恢复、停止和等待空闲。
+
+```js
+const queue = new TaskQueue({
+  concurrency: 1,
+  taskDelayMs: 100,
+  timeout: 0,
+});
+
+queue.add(async () => {
+  await TimeUtils.wait(1000);
+  return "done";
+});
+
+const results = await queue.addMany([() => 1, async () => 2]);
+
+queue.pause();
+queue.resume();
+await queue.waitForIdle();
+```
+
+| 方法/属性                     | 说明                 |
+| ----------------------------- | -------------------- |
+| `add(task, timeout?)`         | 添加单个任务         |
+| `addMany(tasks)`              | 批量添加任务         |
+| `pause()` / `resume()`        | 暂停/恢复队列        |
+| `clear(reason?)`              | 清空等待队列         |
+| `stop(reason?)`               | 停止队列并拒绝新任务 |
+| `reset()`                     | 重置队列状态         |
+| `waitForIdle()`               | 等待队列空闲         |
+| `setConcurrency(n)`           | 修改并发数           |
+| `setTimeout(ms)`              | 修改默认超时         |
+| `setTaskDelay(ms)`            | 修改任务间隔         |
+| `size` / `activeCount`        | 等待数 / 运行数      |
+| `TaskQueue.delay(ms, value?)` | 静态延迟工具         |
+
+## Concurrency 并发去重
+
+同名同参数的并发调用只执行一次，后续调用复用同一个 Promise。
+
+```js
+const loadUserOnce = Concurrency.createConcurrentCall(
+  async (id) => fetchUser(id),
+  "load-user",
+);
+
+await Promise.all([loadUserOnce(1), loadUserOnce(1)]);
+```
+
+| 方法                                      | 说明                   |
+| ----------------------------------------- | ---------------------- |
+| `createConcurrentCall(fn, name, getKey?)` | 创建并发去重函数       |
+| `pendingRequests`                         | 当前正在执行的请求 Map |
+
+## Hook 回调工具
+
+适合“先发起动作，后由外部回调唤醒”的场景，比如扫码、第三方 SDK 回调、`postMessage`。
+
+```js
+const hook = new Hook();
+const promise = Hook.on(hook);
+
+setTimeout(() => {
+  hook.call("ok");
+}, 1000);
+
+const result = await promise;
+```
+
+自动生成编号：
+
+```js
+const result = await Hook.no(async (no) => {
+  window.postMessage({ no });
+});
+```
+
+| 方法/属性                                   | 说明                      |
+| ------------------------------------------- | ------------------------- |
+| `new Hook(no?, timeout?)`                   | 创建 Hook，timeout 单位秒 |
+| `Hook.on(hook)`                             | 注册等待                  |
+| `Hook.call(hook, data)` / `hook.call(data)` | 唤醒等待                  |
+| `Hook.clear(hook)`                          | 清理 Hook                 |
+| `Hook.no(fn, timeout?)`                     | 自动生成编号并等待回调    |
+| `hook.no` / `hook.timeout`                  | 编号 / 超时时间           |
+
+## CookieUtils 浏览器 Cookie 工具
+
+`CookieUtils` 依赖浏览器 `document.cookie`，请从 browser 子路径导入，避免 Node 环境误加载浏览器对象。
+
+```js
+import { CookieUtils } from "@minson/ms-utils/browser";
+
+CookieUtils.write("token", "xxx");
+CookieUtils.read("token");
+CookieUtils.has("token");
+CookieUtils.delete("token");
+CookieUtils.writeJSON("user", { id: 1 });
+CookieUtils.readJSON("user");
+CookieUtils.readAll();
+```
+
+## WxHttpAdapter 微信小程序 / uniapp 适配器
+
+```js
+import { ApiRequest } from "@minson/ms-utils";
+import { WxHttpAdapter } from "@minson/ms-utils/wx";
+
+const request = new ApiRequest({
+  url: "https://api.example.com",
+  adapter: new WxHttpAdapter(wx), // uniapp 项目传 uni
+});
+```
+
+## 本地编译并安装到 test 项目
+
+项目内已经提供脚本，用来验证真实 npm 包安装效果：
+
+```bash
+cd main
+npm run build:test
+```
+
+该命令会自动：
+
+1. 编译 `main/dist`
+2. 打包 `minson-ms-utils-*.tgz`
+3. 安装到 `../test`
+
+然后可以运行：
+
+```bash
+cd ../test
+node test.js
+```
+
+## 发布前检查
+
+```bash
+cd main
+npm run typecheck
+npm run test
+npm run build
+npm pack --dry-run
+```
+
+`npm pack --dry-run` 应只看到 `dist/`、`README.md`、`LICENSE` 和 package metadata。
+
+## API 工具设计说明
+
+这个模块不是为了替代 axios、ky、ofetch 这类底层 HTTP client。
+它解决的是另一个痛点：在 Web、Node、微信小程序、uniapp 等环境里，尽量复用同一份业务 API 接口代码。
+
+核心请求模块只暴露 `ApiRequest`、`ApiConfig`、`ApiResponse`、`ApiAdapter`、`ApiInterceptor` 等 `Api*` 命名；底层适配器仍保留 `FetchHttpAdapter`、`XhrHttpAdapter`、`AxiosHttpAdapter` 这类名称，表示它们负责对接具体 HTTP 实现。
+
+### 整体分层
+
+| 层级 | 类型 | 职责 |
+| --- | --- | --- |
+| API 编排器 | `ApiRequest` | 串起配置、适配器、拦截器、缓存、错误处理和多 base url 重试 |
+| 单次配置 | `ApiConfig` | 描述一次请求，并提供链式 `useXxx()` 能力 |
+| 响应对象 | `ApiResponse` | 统一包装 status、data、headers、原始响应 |
+| 适配器 | `ApiAdapter` | 抽象底层请求能力，不绑定 axios、fetch、xhr、wx |
+| 拦截器 | `ApiInterceptor` | 抽象请求前后处理，业务可继承扩展 |
+
+### 适配器
+
+适配器负责把同一份 `ApiConfig` 转成不同运行时的请求调用。
+
+| 适配器 | 入口 | 适用环境 | 说明 |
+| --- | --- | --- | --- |
+| `XhrHttpAdapter` | `@minson/ms-utils` | 浏览器 | 支持上传进度、下载进度、取消请求 |
+| `FetchHttpAdapter` | `@minson/ms-utils` | Node / 浏览器 / Worker | 通用 fetch 实现，支持取消；下载进度依赖 ReadableStream |
+| `AxiosHttpAdapter` | `@minson/ms-utils/axios` | 使用 axios 的项目 | axios 构造注入，不内置打包 axios |
+| `WxHttpAdapter` | `@minson/ms-utils/wx` | 微信小程序 / uniapp | 适配 `wx.request`、`wx.uploadFile` 或 `uni.request`、`uni.uploadFile` |
+| `AjaxHttpAdapter` | 源码路径按需引用 | jQuery/uni 风格 ajax | 适合已有 ajax runtime 的老项目 |
+
+默认适配器策略：
+
+```js
+// 浏览器优先 XHR，方便拿上传/下载进度；其它环境走 fetch。
+const api = new ApiRequest({
+    url: "https://api.example.com",
+});
+```
+
+等价于：
+
+```js
+const adapter = typeof XMLHttpRequest !== "undefined"
+    ? new XhrHttpAdapter()
+    : new FetchHttpAdapter();
+```
+
+### 容灾与故障切换
+
+`ApiRequest` 的 `url` 支持数组。底层请求失败时，会按数组顺序切换到下一个 base url 重试。
+
+```js
+const api = new ApiRequest({
+    url: [
+        "https://api-a.example.com",
+        "https://api-b.example.com",
+        "https://api-c.example.com",
+    ],
+    retryDelay: 1000,
+});
+
+const user = await api
+    .use({
+        url: "/user/info",
+        method: "GET",
+        data: { id: 1 },
+    })
+    .emit();
+```
+
+适用场景：
+
+- 主备域名切换。
+- 多网关容灾。
+- 灰度网关失败回退。
+- 小程序 / uniapp 不同环境域名兜底。
+
+边界说明：
+
+- `retryDelay` 单位是毫秒，默认 `1000`。
+- 只在 adapter 层请求失败时切换，例如网络错误、超时、取消外的 reject。
+- 业务状态失败不会自动切换域名，例如 `{ code: 500 }` 这种由 `ApiStatusInterceptor` 处理。
+- 所有 base url 都失败后，抛出最后一次错误。
+
+### 默认拦截器
+
+`ApiRequest` 内置了几类默认拦截器，常规业务不用每个接口重复写。
+
+| 拦截器 | 默认类型 | 职责 |
+| --- | --- | --- |
+| UI 拦截器 | `ApiUIInterceptor` | 根据 `loading`、`showErrorMessage` 统一处理 loading 和错误提示钩子 |
+| 状态拦截器 | `ApiStatusInterceptor` | 统一处理 HTTP 状态、业务 code、message、data 拆包、未授权回调 |
+| 缓存拦截器 | `ApiCacheInterceptor` | 根据 `cache` 配置拦截重复请求结果 |
+| 业务拦截器 | `ApiInterceptor[]` | 项目自定义鉴权、签名、埋点、灰度、错误结构处理 |
+
+如果后端响应结构简单，例如：
+
+```js
+{
+    code: 200,
+    message: "ok",
+    data: {}
+}
+```
+
+可以直接配置 `ApiStatusInterceptor`：
+
+```js
+import { ApiRequest, ApiStatusInterceptor } from "@minson/ms-utils";
+
+const api = new ApiRequest({
+    url: "https://api.example.com",
+    statusInterceptor: new ApiStatusInterceptor({
+        status: "code",
+        message: "message",
+        data: "data",
+        success: 200,
+        onUnauthorized: (message) => {
+            console.log("登录失效", message);
+        },
+    }),
+});
+```
+
+### 单次请求功能封装
+
+`ApiConfig` 把常见请求能力封成链式方法，接口文件只描述业务参数，不散落环境判断。
+
+| 方法 | 说明 |
+| --- | --- |
+| `useAuth()` | 标记需要登录态，给自定义拦截器使用 |
+| `useTimeout(seconds)` | 设置超时时间 |
+| `useHeaders(headers)` | 设置请求头 |
+| `useWithCredentials()` | 携带 cookie / credentials |
+| `useUpload()` | 标记上传请求，适配器会转 `FormData` 或平台上传 API |
+| `useJsonBody()` | 按 JSON body 发送 |
+| `useSign()` | 标记需要签名，给自定义签名拦截器使用 |
+| `useLoading()` | 触发 UI loading 钩子 |
+| `useShowErrorMessage()` | 控制是否展示错误消息 |
+| `useCheckHttpStatus()` | 检查 HTTP status |
+| `useBackFailResult()` | 业务失败时返回原始失败结果 |
+| `useBackOnlyData()` | 成功时只返回业务 data |
+| `useCache()` | 开启缓存拦截 |
+| `useCancel(callback)` | 获取取消函数，外部可主动取消请求 |
+| `useUploadProgress(callback)` | 上传进度回调，适配器支持多少给多少 |
+| `useDownloadProgress(callback)` | 下载进度回调，适配器支持多少给多少 |
+| `useProgress(callback)` | 同时绑定上传和下载进度 |
+| `request(api)` | 使用指定 `ApiRequest` 执行当前配置 |
+| `emit()` / `exec()` | 使用绑定的 `ApiRequest` 执行当前配置 |
+
+示例：
+
+```js
+const result = await api
+    .use({
+        url: "/user/create",
+        method: "POST",
+        data: { name: "minson" },
+    })
+    .useAuth()
+    .useJsonBody()
+    .useLoading()
+    .useCancel((cancel) => {
+        // 需要取消时调用 cancel("用户取消")
+    })
+    .useProgress((progress) => {
+        console.log(progress.percent);
+    })
+    .emit();
+```
+
+### 推荐的业务 API 写法
+
+把运行时选择放在初始化处，把业务接口写成纯函数。
+
+```js
+import { ApiRequest } from "@minson/ms-utils";
+
+// 返回示例：{ id: 1, name: "minson" }
+const api = new ApiRequest({
+    url: "https://api.example.com",
+});
+
+export function getUser(id) {
+    return api
+        .use({
+            url: "/user/info",
+            method: "GET",
+            data: { id },
+        })
+        .useAuth()
+        .emit();
+}
+```
+
+### 复杂业务结构
+
+复杂业务不需要把各种协议都塞进核心库里，直接继承 `ApiInterceptor`，重写 `before()` 或 `after()` 即可。
+
+例如后端返回：
+
+```js
+{
+    meta: {
+        code: 0,
+        traceId: "trace-id",
+    },
+    payload: {},
+    error: {
+        message: "请求失败",
+    },
+}
+```
+
+可以这样写业务状态拦截器：
+
+```js
+import {
+    ApiInterceptor,
+    ApiRequest,
+} from "@minson/ms-utils";
+
+class CustomStatusInterceptor extends ApiInterceptor {
+    async before(_config) {
+        return undefined;
+    }
+
+    async after(_config, response) {
+        const body = response.data;
+
+        if (body.meta.code !== 0) {
+            throw new Error(body.error?.message || "请求失败");
+        }
+
+        response.data = body.payload;
+    }
+}
+
+const api = new ApiRequest({
+    url: "https://api.example.com",
+    statusInterceptor: new CustomStatusInterceptor(),
+});
+```
+
+这样业务 API 文件仍然只关心：路径、参数、返回类型；不同运行时只替换 adapter，不需要复制接口代码。