alova-wormhole-usage

Alova OpenAPI 集成

客户端用法请参阅 alova-client skill。 服务端（Node/Bun/Deno）用法请参阅 alova-server skill。

Alova 通过 @alova/wormhole 集成 OpenAPI/Swagger 规范，自动生成 API 请求函数和 TypeScript 类型。

工作流

Install → Create alova.config → Run alova gen → Customize alova instance → Use generated APIs

Alova 配置

配置文件

支持的格式：

• alova.config.cjs：CommonJS 配置文件
• alova.config.js：ESModule 配置文件
• alova.config.ts：TypeScript 配置文件

使用 alova init 命令快速创建配置模板。

import { defineConfig } from '@alova/wormhole';

export default defineConfig({
  // API generation settings array
  generator: [
    {
      // OpenAPI file URL or local path
      input: 'http://localhost:3000/openapi.json',

      // Output path
      output: 'src/api',

      // Platform type (swagger)
      platform: 'swagger',

      // Plugin configuration
      plugins: [],

      // Response data media type (default: application/json)
      responseMediaType: 'application/json',

      // Request body media type (default: application/json)
      bodyMediaType: 'application/json',

      // API version (default: auto)
      version: 'auto',

      // Code type: auto/ts/typescript/module/commonjs
      type: 'auto',

      // Global API export name (default: Apis)
      global: 'Apis',

      // Global mount object (default: globalThis)
      globalHost: 'globalThis',

      // Filter/transform API interface functions
      handleApi: (apiDescriptor) => apiDescriptor,
    },
  ],

  // Auto-update configuration
  autoUpdate: true, // or { launchEditor: true, interval: 5 * 60 * 1000 }
});

defineConfig 也可以接受同步或异步函数，以支持更灵活的配置。

预设 Wormhole 插件

插件	描述	文档
rename	重命名 API 函数和参数名称，支持 camelCase/snake_case	文档
tagModifier	修改 API 标签名称	文档
payloadModifier	添加、移除或修改 API 参数类型	文档
filterApi	根据 URL 和标签匹配结果筛选 API	文档
apifox	自动导入 Apifox 项目	文档
importType	排除需要自定义的类型	文档

用法示例：

import { rename, tagModifier } from '@alova/wormhole/plugin';

export default defineConfig({
  generator: [
    {
      plugins: [
        rename({ style: 'camelCase' }),
        tagModifier({ ... })
      ]
    }
  ]
});

handleApi 钩子

用于自定义 API 配置。在生成每个 API 之前调用。可以修改参数名称、类型或返回类型。

注意：apiDescriptor 参数包含 OpenAPI 文件中每个 API 的信息。详情请参阅 OpenAPI Spec Operation Object。

重命名函数（snake_case → camelCase）：

handleApi: (apiDescriptor) => {
  apiDescriptor.operationId = apiDescriptor.operationId.replace(/_([a-z])/g, (match, group) =>
    group.toUpperCase()
  );
  return apiDescriptor;
};

修改标签：

handleApi: (apiDescriptor) => {
  if (apiDescriptor.url.includes('/user')) {
    apiDescriptor.tags = ['userTag'];
  }
  return apiDescriptor;
};

筛选 API：

handleApi: (apiDescriptor) => {
  // Return falsy value to filter this API
  if (!apiDescriptor.path.startsWith('/user')) {
    return;
  }
  return apiDescriptor;
};

修改响应数据类型的生成方式：

handleApi: (apiDescriptor) => {
  apiDescriptor.responses = apiDescriptor.responses?.properties?.data;
  return apiDescriptor;
};

修改生成的数据时，优先使用 Wormhole 插件，而不是 handleApi。插件可以简化逻辑，并按配置顺序执行。

功能与参考文档

功能	参考文档
安装与设置	references/INSTALLATION
CLI 用法（alova gen、alova init）	references/CLI
编程式 API（generate、readConfig）	references/PROGRAMMATIC-API
自定义 alova 实例（index.ts）	references/ALOVA-INSTANCE
故障排查	references/TROUBLESHOOTING