Translators

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

什么是 Translator

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

interface Translator {
  apply(): Plugin[]
}

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

内置 Translators

MicroFunctionTranslator

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

生成的代码示例：

import { KeqRequest } from 'keq'

export const request = new KeqRequest()

import { request } from './request'

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

  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)

IsolatedTranslator

IsolatedTranslator 生成独立的操作文件，每个文件包含完整的类型声明和请求函数，无需依赖共享的 schema 文件。适合增量生成接口的场景，文件间完全隔离，不受共享 schema 变更或重名冲突影响。

生成的代码特点：

• 每个 operation 文件包含内联的 schema 类型声明
• 每个模块拥有独立的 KeqRequest 实例
• 无跨文件的 schema 依赖，可独立使用

生成的目录结构：

outdir/
├── cat-service/
│   ├── request.ts              # 模块独立的 KeqRequest 实例
│   └── operations/
│       ├── get-cats.ts         # 完整的操作文件（类型 + 函数）
│       └── create-cat.ts

生成的代码示例：

// cat-service/request.ts
import { KeqRequest } from "keq"

export const request = new KeqRequest()

// cat-service/operations/get-cats.ts
import { Keq } from "keq"
import type { KeqOperation, KeqPathParameterInit, KeqQueryInit } from "keq"
import { request } from "../request"

// 内联的类型声明（无需外部 schema 文件）
export interface GetCatsResponseBodies {
  200: { id: string; name: string; breed: string }[]
}

export interface GetCatsRequestBodies {}

export type GetCatsRequestQuery = {
  breed?: string
}

// ...其他类型声明

export function getCats<STATUS extends keyof GetCatsResponseBodies>(
  args?: GetCatsRequestParameters
): Keq<GetCatsOperation<STATUS>> {
  const req = request.get<GetCatsResponseBodies[STATUS]>("/api/cats")

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

  return req
}

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

配置示例：

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

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

使用生成的代码：

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

const response = await getCats({ breed: 'persian' })

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 等前端框架	函数式调用，简洁易用，默认选项
IsolatedTranslator	增量生成接口，文件间完全隔离	每个操作文件自包含类型，无共享 schema 依赖
NestjsTranslator	NestJS 后端项目	生成 NestJS 模块，支持依赖注入
自定义 Translator	特殊框架或定制需求	完全自定义生成逻辑

总结

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