@dune2/cli 是一个功能丰富的命令行工具集，主要用于处理 API 生成等任务。

CLI

@dune2/cli 是一个功能丰富的命令行工具集，主要用于从 Swagger/OpenAPI 文档生成类型安全的 API 客户端代码。

安装

npm install @dune2/cli
# 或者
yarn add @dune2/cli
# 或者
pnpm add @dune2/cli

典型使用场景

前端项目接入：从 Swagger/OpenAPI 生成 API SDK

你有：后端提供 Swagger/OpenAPI JSON（本地文件或远程 URL）
你想要：在前端项目里生成按 URL 目录组织的请求文件，并自带 TS 类型
搭配推荐：使用 @dune2/tools/rq 的 RequestBuilder（CLI 默认就是按这个导入路径生成）

核心功能

API 代码生成

CLI 的主要功能是根据 Swagger/OpenAPI 文档自动生成类型安全的 API 请求代码，包括：

自动生成 TypeScript 类型定义
生成基于 RequestBuilder 的请求代码
支持路径参数、查询参数、请求体等
支持分页接口的特殊处理
自动格式化生成的代码

配置管理

通过配置文件管理多个 API 源和生成选项，支持：

多个 API 配置
自定义输出路径
响应数据转换
URL 路径转换
代码格式化选项

命令列表

`dune generateApi`

从 Swagger/OpenAPI 文档生成 API 请求代码。

dune generateApi

这个命令会：

读取配置文件中的 API 配置
解析 Swagger/OpenAPI 文档
为每个 API 端点生成对应的请求代码
生成 TypeScript 类型定义
自动格式化代码（如果启用）

`dune init`

初始化配置文件。

dune init

会在项目根目录创建 dune.config.ts 配置文件模板：

import { defineConfig } from '@dune2/cli';

export default defineConfig({
  api: [],
});

`dune interactive` 或 `dune i`

进入交互式操作模式。

dune interactive
# 或者简写
dune i

信息

直接运行 dune 命令（不带参数）也会进入交互式操作模式。

交互式模式会显示所有可用命令的列表，你可以通过上下箭头键选择要执行的命令。

配置文件

基本配置

运行 dune init 创建配置文件后，需要根据项目需求进行配置：

import { defineConfig } from '@dune2/cli';

export default defineConfig({
  api: [
    {
      // Swagger/OpenAPI 文档路径（支持本地文件或远程 URL）
      swaggerJSONPath: 'http://localhost:3000/api-docs',

      // 生成代码的输出目录
      output: './src/apis',

      // RequestBuilder 导入路径（导入变量名必须是 RequestBuilder）
      // 默认值：import { RequestBuilder } from '@dune2/tools/rq';
      RequestBuilderImportPath:
        "import { RequestBuilder } from '@dune2/tools/rq';",

      // QueryClient 导入路径（可选）
      queryClientImportPath: "import { queryClient } from '@/utils/request'",

      // Swagger UI 地址（用于生成文档链接）
      swaggerUiUrl: 'http://localhost:3000/swagger',

      // 响应数据转换器
      responseSchemaTransformer: (schema) => schema.properties?.data ?? schema,

      // URL 转换器（可选）
      urlTransformer: '/api/v1',

      // 是否启用 TypeScript（生成 .ts 文件）
      enableTs: true,

      // 生成代码完毕后执行的格式化命令（可自定义）
      // 默认值：oxfmt（推荐）
      // 如果你更想沿用 prettier：prettier --write
      codeFormatterCmd: 'oxfmt',
    },
  ],
});

API 配置选项

`swaggerJSONPath`

类型: string
必填: 是
描述: Swagger/OpenAPI 文档的路径，可以是本地文件路径或远程 URL

`output`

类型: string
默认值: "./src/apis"
描述: 生成代码的输出目录

`enableTs`

类型: boolean
默认值: true
描述: 是否启用 TypeScript，true 生成 .ts 文件，false 生成 .js 文件

`RequestBuilderImportPath`

类型: string
默认值: "import { RequestBuilder } from '@dune2/tools/rq';"
描述: RequestBuilder 的导入路径（导入的变量名必须是 RequestBuilder）

`queryClientImportPath`

类型: string
可选: 是
描述: QueryClient 的导入路径（导入的变量名必须是 queryClient），用于接入你项目内的 QueryClient 实例

`responseSchemaTransformer`

类型: (schema: OpenAPI.SchemaObject) => any
默认值: (schema) => schema.properties?.data ?? schema
描述: 响应数据模式转换器，用于提取响应数据的实际结构

`urlTransformer`

类型: string | ((url: string) => string)
可选: 是
描述: URL 转换器，可以是字符串前缀或转换函数

`codeFormatterCmd`

类型: string
默认值: "oxfmt"
描述: 生成代码完毕后执行的格式化命令（可自定义工具及参数）

格式化工具指南（同时支持 Prettier 与 Oxfmt）

codeFormatterCmd 本质上就是一段会被执行的命令。你可以选择 Oxfmt（推荐） 或继续使用 Prettier（兼容）。

方案 A：Oxfmt（推荐）

安装：

pnpm add -D oxfmt

配置（示例：.oxfmtrc.jsonc）：

{
  "$schema": "./node_modules/oxfmt/configuration_schema.json",
  "printWidth": 80,
  "singleQuote": true,
  "jsxSingleQuote": true,
}

配置 dune.config.ts：

export default defineConfig({
  api: [
    {
      codeFormatterCmd: 'oxfmt',
    },
  ],
});

方案 B：Prettier（兼容）

安装：

pnpm add -D prettier

配置（示例：.prettierrc）：

{
  "singleQuote": true,
  "jsxSingleQuote": true
}

配置 dune.config.ts：

export default defineConfig({
  api: [
    {
      codeFormatterCmd: 'prettier --write',
    },
  ],
});

`swaggerUiUrl`

类型: string
可选: 是
描述: Swagger UI 地址，用于在生成的代码中添加文档链接

`dereferenceSwaggerConfig`

类型: SwaggerParser.Options
可选: 是
描述: Swagger 解析器的配置选项

生成的代码结构

基本结构

生成的代码会按照以下结构组织：

src/apis/
├── /api/v1/users/
│   ├── get.ts      # GET /api/v1/users
│   ├── post.ts     # POST /api/v1/users
│   └── ...
├── /api/v1/users/{userId}/
│   ├── get.ts      # GET /api/v1/users/{userId}
│   ├── put.ts      # PUT /api/v1/users/{userId}
│   └── ...

生成的代码示例

// do not edit this file manually, it will be overwritten by @dune2/cli
import { RequestBuilder } from '@dune2/tools/rq';
import { queryClient } from '@/utils/request';

/**
 * 获取用户列表
 * @tags 用户管理
 * @see http://localhost:3000/swagger#/用户管理/getUserList
 */
export const apiV1UsersGetApi = new RequestBuilder<
  apiV1UsersGetApi.Req,
  apiV1UsersGetApi.Res
>({
  url: '/api/v1/users',
  method: 'get',
  queryClient,
});

export namespace apiV1UsersGetApi {
  export interface Req {
    pageNum: number;
    pageSize: number;
    keyword?: string;
  }

  export interface Res {
    code: number;
    data: {
      list: User[];
      total: number;
    };
    message: string;
  }

  export type ResultItem = Res['data']['list'][0];
}

特殊功能

路径参数处理

对于包含路径参数的 API（如 /api/v1/users/{userId}），CLI 会自动生成 urlPathParams 配置：

export const apiV1UsersUserIdGetApi = new RequestBuilder({
  url: '/api/v1/users/{userId}',
  method: 'get',
  urlPathParams: ['userId'],
});

分页接口支持

CLI 会自动识别分页接口并生成额外的类型定义：

export namespace apiV1UsersGetApi {
  // ... 其他类型定义
  export type ResultItem = Res['data']['list'][0]; // 分页数据项类型
}

使用示例

一套推荐工作流（前端项目）

安装依赖：

pnpm add @dune2/cli @dune2/tools

初始化配置：

pnpm dune init

编辑 dune.config.ts，至少配置 swaggerJSONPath 与 output（可按项目接入 queryClientImportPath）。
生成 API：

pnpm dune generateApi

故障排除

常见问题

类型生成失败
- 检查 Swagger 文档是否符合 OpenAPI 3.0 规范
- 确认响应数据结构是否正确
导入路径错误
- 检查 RequestBuilderImportPath 配置
- 确认 @dune2/tools 包已正确安装
代码格式化失败
- 确认项目已安装 codeFormatterCmd 指定的工具（oxfmt 或 prettier）
- 检查对应配置是否正确（例如 .oxfmtrc.jsonc / .prettierrc）

调试模式

设置环境变量启用调试输出：

DEBUG=dune:* dune generateApi

这将显示详细的执行日志，帮助诊断问题。

CLI

CLI

安装