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

CLI

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

安装

npm install @dune2/cli
# 或者
yarn add @dune2/cli
# 或者
pnpm add @dune2/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({
  i18n: [],
  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",

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

      // 是否在生成后格式化代码
      format: true,

      // RequestBuilder 导入路径
      RequestBuilderImportPath: "import { RequestBuilder } from '@dune2/tools'",

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

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

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

      // URL 转换器（可选）
      urlTransformer: "/api/v1",
    },
  ],
});

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'"
描述: RequestBuilder 的导入路径

`queryClientImportPath`

类型: string
可选: 是
描述: QueryClient 的导入路径，用于集成 react-query 等查询库

`responseSchemaTransformer`

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

`urlTransformer`

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

`format`

类型: boolean
默认值: true
描述: 是否在生成代码后自动格式化（需要安装 prettier）

`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";
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]; // 分页数据项类型
}

表单字段映射

对于 POST 和 PUT 请求，CLI 会生成字段映射对象：

export const apiV1UsersPostApiFieldsMap = {
  name: "name",
  email: "email",
  age: "age",
} as const;

使用示例

故障排除

常见问题

类型生成失败
- 检查 Swagger 文档是否符合 OpenAPI 3.0 规范
- 确认响应数据结构是否正确
导入路径错误
- 检查 RequestBuilderImportPath 配置
- 确认 @dune2/tools 包已正确安装
代码格式化失败
- 确认项目已安装 prettier
- 检查 prettier 配置是否正确

调试模式

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

DEBUG=dune:* dune generateApi

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

CLI

CLI

安装

核心功能

API 代码生成

配置管理

命令列表

dune generateApi

dune init

dune interactive 或 dune i