Translators

Translators 是 @keq-request/cli 的代码生成策略系统，用于定义从 OpenAPI 文档生成 TypeScript 代码的风格和模式。通过不同的 Translator，你可以生成适配不同框架的 API 客户端代码。

什么是 Translator

Translator 是一个接口，用于组织和应用一组插件（Plugins），从而控制代码生成的方式：

interface Translator {
  apply(): Plugin[]
}

每个 Translator 通过 apply() 方法返回一组插件，这些插件会在编译流程中被执行，最终生成符合特定风格的代码。

内置 Translators

MicroFunctionTranslator

MicroFunctionTranslator 是默认的 translator，生成函数式的 API 调用代码。这种风格的代码简洁、易用，适合大多数场景。

生成的代码示例：

import { request } from 'keq'

// 生成的函数式 API
export function getCats<STATUS extends keyof GetCatsResponseBodies>(
  args?: GetCatsRequestParameters
): Keq<GetCatsOperation<STATUS>> {
  const req = request.get<GetCatsResponseBodies[STATUS]>("/api/cats")
    .option('module', { name: 'catService', pathname: '/api/cats', method: 'get' })

  if (args && "breed" in args) {
    req.query("breed", args["breed"], { arrayFormat: "repeat" })
  }

  return req
}

getCats.pathname = '/api/cats'
getCats.method = 'get'

使用生成的代码：

import { getCats } from './apis/cat-service'

// 直接调用函数发起请求
const response = await getCats({ breed: 'persian' })
console.log(response.data)

NestjsTranslator

NestjsTranslator 生成与 NestJS 框架深度集成的模块代码，适合在 NestJS 项目中使用。

生成的代码特点：

• NestJS 服务模块定义
• 依赖注入支持
• 与 NestJS 生态系统无缝集成

配置示例：

// .keqrc.ts
import { defineKeqConfig, NestjsTranslator } from "@keq-request/cli"

export default defineKeqConfig({
  outdir: "./src/apis",
  modules: {
    catService: "./cat-service-swagger.json",
  },
  translators: [new NestjsTranslator()],
})

使用生成的代码：

import { Module } from '@nestjs/common'
import { CatServiceModule } from './apis/cat-service'

@Module({
  imports: [CatServiceModule],
})
export class AppModule {}

配置 Translators

基本配置

在配置文件中通过 translators 字段指定使用的 translator：

// .keqrc.ts
import { defineKeqConfig, MicroFunctionTranslator } from "@keq-request/cli"

export default defineKeqConfig({
  outdir: "./src/apis",
  modules: {
    catService: "./cat-service-swagger.json",
  },
  // 指定使用 MicroFunctionTranslator
  translators: [new MicroFunctionTranslator()],
})

默认值

如果不配置 translators 字段，CLI 会默认使用 MicroFunctionTranslator：

// 以下两种配置等效
export default defineKeqConfig({
  // ...
})

export default defineKeqConfig({
  // ...
  translators: [new MicroFunctionTranslator()],
})

使用多个 Translators

你可以同时配置多个 translators（虽然这种情况比较少见）：

import { defineKeqConfig, MicroFunctionTranslator, NestjsTranslator } from "@keq-request/cli"

export default defineKeqConfig({
  outdir: "./src/apis",
  modules: {
    catService: "./cat-service-swagger.json",
  },
  // 同时使用多个 translators
  translators: [
    new MicroFunctionTranslator(),
    new NestjsTranslator(),
  ],
})

工作原理

Translator 在编译流程中的工作方式如下：

配置文件 (.keqrc.ts)
    ↓
解析配置，读取 translators
    ↓
对每个 translator 调用 apply() 方法
    ↓
获取 Plugin[] 数组并展平
    ↓
应用所有插件到编译器
    ↓
执行编译流程
    ↓
生成代码

Translator 与 Plugin 的关系

Translator 本质上是一个 Plugin 的组织器：

• Translator: 定义代码生成策略，返回一组相关的 Plugins
• Plugin: 执行具体的代码生成逻辑

例如，MicroFunctionTranslator 内部使用了两个插件：

class MicroFunctionTranslator implements Translator {
  apply(): Plugin[] {
    return [
      new GenerateDeclarationPlugin(),    // 生成类型声明
      new GenerateMicroFunctionPlugin(),  // 生成函数代码
    ]
  }
}

自定义 Translator

如果内置的 translators 不满足需求，你可以实现自定义 translator：

// custom-translator.ts
import type { Translator, Plugin } from '@keq-request/cli'
import { GenerateDeclarationPlugin } from '@keq-request/cli'

export class CustomTranslator implements Translator {
  apply(): Plugin[] {
    return [
      new GenerateDeclarationPlugin(),
      new MyCustomPlugin(),
    ]
  }
}

class MyCustomPlugin implements Plugin {
  apply(compiler: Compiler): void {
    // 注册到编译器的各个钩子
    compiler.hooks.compile.tap('MyCustomPlugin', (context) => {
      // 自定义代码生成逻辑
    })
  }
}

然后在配置中使用：

// .keqrc.ts
import { defineKeqConfig } from "@keq-request/cli"
import { CustomTranslator } from "./custom-translator"

export default defineKeqConfig({
  outdir: "./src/apis",
  modules: {
    catService: "./cat-service-swagger.json",
  },
  translators: [new CustomTranslator()],
})

选择合适的 Translator

Translator	适用场景	特点
MicroFunctionTranslator	通用项目、React、Vue 等前端框架	函数式调用，简洁易用，默认选项
NestjsTranslator	NestJS 后端项目	生成 NestJS 模块，支持依赖注入
自定义 Translator	特殊框架或定制需求	完全自定义生成逻辑

总结

• Translators 定义了从 OpenAPI 文档生成代码的策略
• 内置的 MicroFunctionTranslator（默认）和 NestjsTranslator 满足大多数需求
• 通过配置文件的 translators 字段指定要使用的 translator
• 可以实现自定义 translator 来生成特定框架的代码
• Translator 通过组织和应用一组 Plugins 来完成代码生成工作