# @dudousxd/nestjs-codegen 中文文档

规范地址：https://npmcn.com/package/%40dudousxd/nestjs-codegen/

版本：0\.30\.0
npm 元数据更新时间：2026-11-12T05:53:08.103Z
中文译文更新时间：2026-11-12T23:52:35.036Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40dudousxd/nestjs-codegen
原文对照：https://npmcn.com/package/%40dudousxd/nestjs-codegen/?lang=original
项目主页：https://davidecarvalho.github.io/aviary/docs/codegen
源码仓库：https://github.com/DavideCarvalho/nestjs-codegen

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：5.8 MB，39 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：4 个
- peer 依赖：tsx \>=4\.0\.0，typescript \>=5\.0\.0，@nestjs/common \>=9\.0\.0，@dudousxd/nestjs-agent-core \>=0\.53\.0
- 首次发布：2026-06-10T22:09:55.085Z
- 最新版本发布：2026-11-12T05:53:07.754Z
- 近 30 天下载量：4339（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：48（近 12 个月 48 个）

## 中文简介

NestJS的可扩展编码核:类验证器/合同发现器 → 中性schema IR → 可插式验证适配器.

## 安装

```sh
npm install @dudousxd/nestjs-codegen
```

也可以使用：`pnpm add @dudousxd/nestjs-codegen`、`yarn add @dudousxd/nestjs-codegen`、`bun add @dudousxd/nestjs-codegen`

## README

# @dudousxd/nestjs-codegen (英语)

> NestJS——路线,API客户端的可广泛打入客户端代码和验证计划.

![npm](https://img.shields.io/npm/v/@dudousxd/nestjs-codegen)

`nestjs-codegen` 读你的NestJS控制器, `defineContract` 合同,DTO,以及 (可选) Inertia 页面通过 [ts-形态](https://ts-morph.com/),建立中性计划 红外线,并发出a **全类型客户端**: 路由图,图约风格的API客户端,以及 客户端验证计划。 有用吗 **不论有无**,每个移动 部分是可插件的 — 验证库、 HTTP 客户端、 序列器和查询 层.

## 安装

```bash
pnpm add -D @dudousxd/nestjs-codegen
# a validation adapter (no adapter is bundled in core) — zod shown; or -valibot / -arktype:
pnpm add -D @dudousxd/nestjs-codegen-zod
# the runtime the generated client imports its Fetcher type from:
pnpm add @dudousxd/nestjs-client
```

生成的 `api.ts` 进口 `Fetcher` 类型从 `@dudousxd/nestjs-client`,所以这是一个 实时依赖. `@nestjs/common`, (中文(简体) ), `tsx`,以及 `typescript` 是同伴的依赖关系 (单位:千美元)`@nestjs/common` 财务报告和审定财务报表 `tsx` 是可选的, 您的 Nest 应用程序已经拥有了 .

## 快开始

导入 `NestjsCodegenModule` 输入您的根模块。 代码源始于您的 Dev 服务器 在您编辑控制器时重生客户端 — 没有配置文件, 没有额外进程. 监视器是一个 dev/CI 关切,所以模块在 `NODE_ENV === 'production'`。 。 。 .

```ts
import { Module } from '@nestjs/common';
import { NestjsCodegenModule } from '@dudousxd/nestjs-codegen/nest';
import { zodAdapter } from '@dudousxd/nestjs-codegen-zod';

@Module({
  imports: [
    NestjsCodegenModule.forRoot({
      // controllers to scan for routes + contracts
      contracts: { glob: 'src/**/*.controller.ts' },
      // output directory for the generated files
      codegen: { outDir: 'src/generated' },

      validation: zodAdapter, // zodAdapter | valibotAdapter | arktypeAdapter
    }),
  ],
})
export class AppModule {}
```

生成的 `api.ts` 出口a `createApi(fetcher)` 工厂 - 创建客户端一次, 注射你的取水器。 每个终点都是 **统一可等待的手柄**: 一个懒惰的,被纪念的 `Promise` —— 说 `await` 它(或从一株取回) `mutationFn`运行请求.

```ts
import { createApi } from '../generated/api';
import { createFetcher } from '@dudousxd/nestjs-client';

export const api = createApi(createFetcher({ baseUrl: '/api' }));

const users = await api.users.list();              // typed User[]
const created = await api.users.create({ body });  // typed body + response
```

## 它会产生什么

代码将这些文件写入您的输出目录 :

-   **`routes.ts`** a 包括: `ROUTES` 地图, a `RouteName` 结合,并输入 `route()` 帮手.
-   **`api.ts`** -图约式的 `createApi(fetcher)` 工厂,以路由名称为巢,完全打字.
-   **`forms.ts`** ——每个验证的终点的验证计划,在您选择的 lib 中.
-   **`pages.d.ts` 编号 : `components.json`** ——当Inertia集成启用时.

## 扩展和生态系统

核心之外的一切都是可插接的. 扩展通过 `extensions: [...]`· ; 验证适配器通过 `validation: ...`。 。 。 .

```ts
import { NestjsCodegenModule } from '@dudousxd/nestjs-codegen/nest';
import { tanstackQuery } from '@dudousxd/nestjs-codegen-tanstack';
import { nestjsFilterCodegen } from '@dudousxd/nestjs-filter-codegen';
import { nestjsInertiaCodegen } from '@dudousxd/nestjs-inertia-codegen-extension';
import { arktypeAdapter } from '@dudousxd/nestjs-codegen-arktype';

NestjsCodegenModule.forRoot({
  contracts: { glob: 'src/**/*.controller.ts' },
  codegen: { outDir: 'src/generated' },
  validation: arktypeAdapter, // render the IR as arktype instead of zod
  extensions: [tanstackQuery(), nestjsFilterCodegen(), nestjsInertiaCodegen()],
});
```

TanStack扩展注册后,每个生成的叶子都成为了统一的柄: `await api.users.show({ params })` 执行请求,以及 _不变_ 手柄载具 `.queryOptions()` 编号 : `.mutationOptions()` 编号 : `.infiniteQueryOptions()` 编号 : `.queryKey()`。 。 。 .

```tsx
import { useQuery, useMutation } from '@tanstack/react-query';
import { api } from '../lib/api';

const users = useQuery(api.users.list().queryOptions());
const create = useMutation(api.users.create().mutationOptions());
```

| 软件包 | 上面写的 |
| --- | --- |
| [`@dudousxd/nestjs-client`](https://www.npmjs.com/package/@dudousxd/nestjs-client) | 运行时间取取器—— `createFetcher` 带有可插件的运输工具(内部) `fetch` 或者说 `axiosTransport()`)并出出一超杰生钩. 传过来 `createApi(fetcher)`。 。 。 . |
| [`@dudousxd/nestjs-codegen-tanstack`](https://www.npmjs.com/package/@dudousxd/nestjs-codegen-tanstack) | TanStack 查询帮助者 (`queryOptions` 编号 : `mutationOptions` 编号 : `infiniteQueryOptions` 编号 : `queryKey`每个生成的叶子上。 注册为扩展. |
| [`@dudousxd/nestjs-codegen-arktype`](https://www.npmjs.com/package/@dudousxd/nestjs-codegen-arktype) | 验证适配器-渲染 `forms.ts` 作为 [方舟类型](https://arktype.io/)。通过 `validation: arktypeAdapter`。 。 。 . |
| [`@dudousxd/nestjs-codegen-valibot`](https://www.npmjs.com/package/@dudousxd/nestjs-codegen-valibot) | 验证适配器-渲染 `forms.ts` 作为 [华丽机器人](https://valibot.dev/)。通过 `validation: valibotAdapter`。 。 。 . |
| [`@dudousxd/nestjs-filter-codegen`](https://www.npmjs.com/package/@dudousxd/nestjs-filter-codegen) | 分机 - 键入 `filterQuery` 来自 [过滤器](https://github.com/DavideCarvalho/nestjs-filter) 复发. |
| [`@dudousxd/nestjs-inertia-codegen-extension`](https://www.npmjs.com/package/@dudousxd/nestjs-inertia-codegen-extension) | 扩展-Inertia `router` /从"巢"-"巢"-"巢""巢""巢""巢""巢"""巢""""巢"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""". |

### Generative-UI 沙盒套件(装入)

`genuiSandboxKit()` 写沙盒- kit 文档 [`@dudousxd/nestjs-agent`](https://github.com/DavideCarvalho/nestjs-agent) 用于制造 你设计系统中的基因UI 组件的名称和道具(从它们读取) TypeScript 类型, 以及您的样式, 转到 `.genui/sandbox-kit.json`这发生在 每个生成和监视模式。 它需要可选的对等点 `@dudousxd/nestjs-agent-core` (>=0.53.

```ts
import { defineConfig, genuiSandboxKit } from '@dudousxd/nestjs-codegen';

export default defineConfig({
  contracts: { glob: 'src/**/*.controller.ts' },
  codegen: { outDir: 'src/generated' },
  extensions: [genuiSandboxKit({ components: 'web/components/ui', styles: 'web/styles/globals.css' })],
});
```

选项( 与代理的 Vite 插件相同 ) :

-   `components` (默认: 第一个阴影) `components/ui` 找到目录 , `styles`, (中文(简体) ), `wrapper`, (中文(简体) ), `stylesDocs`, (中文(简体) ), `tsconfig`· ;
-   `output` (默认) `.genui/sandbox-kit.json`,相对于应用程序 cwd;
-   `generate`,以注入文件撰写器.

写你自己对 `@dudousxd/nestjs-codegen/extension` 合同:

```ts
import { defineExtension, type CodegenExtension } from '@dudousxd/nestjs-codegen/extension';
```

## 国 际

对于 CI( 在部署前) 您想要一个一发, 无监视运行, 如果 忠实的客户已经漂移。 包裹运送 `nestjs-codegen` CLI: 爱丽丝

```bash
npx nestjs-codegen codegen   # one-shot generate (CI); pair with `git diff --exit-code`
npx nestjs-codegen init      # scaffold nestjs-codegen.config.ts
npx nestjs-codegen doctor    # diagnose your setup
```

CLI读取 `nestjs-codegen.config.ts` (遗产) `nestjs-inertia.config.ts` 名称是 从您的工程根。 通过撰写选项保留一个单一的真相来源 与 `defineConfig` 输入到 `forRoot()`数字 :

```ts
import { defineConfig } from '@dudousxd/nestjs-codegen';
import { zodAdapter } from '@dudousxd/nestjs-codegen-zod';

export default defineConfig({
  contracts: { glob: 'src/**/*.controller.ts' },
  codegen: { outDir: 'src/generated' },
  validation: zodAdapter,
});
```

```bash
npx nestjs-codegen codegen
git diff --exit-code src/generated   # non-zero if the client is stale
```

## 文档

完整文件——启动、配置、验证适配器、取取取器和 展期合同——居住在repo:

-   仓库和文件 : [https://github.com/Davide Carvalho/nestjs-codegen 互联网档案馆的存檔,存档日期2013-12-22](https://github.com/DavideCarvalho/nestjs-codegen)

## 许可证

麻省理工学院

## 常见问题

### @dudousxd/nestjs-codegen 是什么？

NestJS的可扩展编码核:类验证器/合同发现器 → 中性schema IR → 可插式验证适配器\.

### 如何安装 @dudousxd/nestjs-codegen？

在项目目录运行 npm install @dudousxd/nestjs-codegen，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：typescript（\>=5\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。它还提供命令行工具 nestjs-codegen，可以用 npx nestjs-codegen 直接运行。

### @dudousxd/nestjs-codegen 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @dudousxd/nestjs-codegen 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @dudousxd/nestjs-codegen 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @dudousxd/nestjs-codegen 可以商用吗？

@dudousxd/nestjs-codegen 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @dudousxd/nestjs-codegen 的下载量有多少？

根据 npm 官方下载统计，@dudousxd/nestjs-codegen 在 2026/10/13 – 2026/11/11 这 30 天内被下载 4,339 次，日均约 145 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @dudousxd/nestjs-codegen 还在维护吗？

最新版本 0\.30\.0 发布于 2026/11/12（1 天前）；至今共发布 48 个版本，其中过去 12 个月发布了 48 个；首次发布于 2026/06/11。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。