# NestJS 模块生成指南

## 快速生成完整模块

### 方法一：使用 `resource` 命令（推荐）

一次性生成包含 module、controller、service、entity 的完整 CRUD 资源：

```bash
# 生成 user 模块（会在 src/modules/user 目录下创建所有文件）
pnpm nest g resource modules/user

# 或者使用别名
pnpm nest g res modules/user
```

**交互式选项：**

- `What transport layer do you use?` → 选择 `REST API`
- `Would you like to generate CRUD entry points?` → 选择 `Yes`

**生成的文件结构：**

```
src/modules/user/
├── user.controller.ts      # 控制器
├── user.controller.spec.ts # 控制器测试
├── user.service.ts         # 服务
├── user.service.spec.ts    # 服务测试
├── user.module.ts          # 模块
└── entities/
    └── user.entity.ts      # 实体（TypeORM）
```

### 方法二：分别生成各个文件

```bash
# 生成模块
pnpm nest g module modules/user

# 生成控制器
pnpm nest g controller modules/user

# 生成服务
pnpm nest g service modules/user

# 生成实体（需要手动创建，或使用 TypeORM CLI）
```

### 方法三：使用 TypeORM 生成实体

```bash
# 安装 TypeORM CLI（如果还没有）
pnpm add -D typeorm

# 生成实体（需要先配置 TypeORM）
pnpm typeorm entity:create -n User
```

## 文件组织模式

### 模式一：按功能模块组织（推荐）⭐

```
src/
├── modules/
│   ├── user/
│   │   ├── user.module.ts
│   │   ├── user.controller.ts
│   │   ├── user.service.ts
│   │   ├── user.entity.ts
│   │   ├── user.dto.ts          # DTO 文件
│   │   ├── user.controller.spec.ts
│   │   └── user.service.spec.ts
│   ├── order/
│   │   ├── order.module.ts
│   │   ├── order.controller.ts
│   │   ├── order.service.ts
│   │   ├── order.entity.ts
│   │   └── ...
│   └── product/
│       └── ...
├── database/
│   ├── database.module.ts
│   └── database.config.ts
└── app.module.ts
```

**优点：**

- 模块化清晰，每个功能独立
- 易于维护和扩展
- 符合 NestJS 最佳实践

**适用场景：**

- 大型企业级应用
- 需要复杂业务逻辑
- 需要清晰的架构分层

## 推荐的文件组织（当前项目）

基于你的项目结构，推荐使用**模式一**：

```
src/
├── modules/              # 业务模块
│   ├── user/
│   │   ├── user.module.ts
│   │   ├── user.controller.ts
│   │   ├── user.service.ts
│   │   ├── user.entity.ts
│   │   ├── dto/          # DTO 文件（可选）
│   │   │   ├── create-user.dto.ts
│   │   │   └── update-user.dto.ts
│   │   └── interfaces/   # 接口定义（可选）
│   │       └── user.interface.ts
│   ├── order/
│   └── product/
├── database/             # 数据库配置
│   ├── database.module.ts
│   └── database.config.ts
├── common/               # 公共模块（可选）
│   ├── filters/
│   ├── guards/
│   ├── interceptors/
│   └── pipes/
└── app.module.ts
```

## 实际生成示例

### 生成 user 模块

```bash
# 1. 生成完整资源
cd /Users/joey-xd/sites/vest-mind/vest-mind-backend/apps/api
pnpm nest g resource modules/user

# 2. 选择选项：
# - REST API
# - Yes (生成 CRUD)
```

### 生成后的文件内容示例

**user.entity.ts:**

```typescript
import { Entity, Column, PrimaryGeneratedColumn } from 'typeorm';

@Entity()
export class User {
    @PrimaryGeneratedColumn()
    id: number;

    @Column()
    name: string;
}
```

**user.service.ts:**

```typescript
import { Injectable } from '@nestjs/common';
import { CreateUserDto } from './dto/create-user.dto';
import { UpdateUserDto } from './dto/update-user.dto';

@Injectable()
export class UserService {
    create(createUserDto: CreateUserDto) {
        return 'This action adds a new user';
    }

    findAll() {
        return `This action returns all user`;
    }

    findOne(id: number) {
        return `This action returns a #${id} user`;
    }

    update(id: number, updateUserDto: UpdateUserDto) {
        return `This action updates a #${id} user`;
    }

    remove(id: number) {
        return `This action removes a #${id} user`;
    }
}
```

**user.controller.ts:**

```typescript
import {
    Controller,
    Get,
    Post,
    Body,
    Patch,
    Param,
    Delete,
} from '@nestjs/common';
import { UserService } from './user.service';
import { CreateUserDto } from './dto/create-user.dto';
import { UpdateUserDto } from './dto/update-user.dto';

@Controller('user')
export class UserController {
    constructor(private readonly userService: UserService) {}

    @Post()
    create(@Body() createUserDto: CreateUserDto) {
        return this.userService.create(createUserDto);
    }

    @Get()
    findAll() {
        return this.userService.findAll();
    }

    @Get(':id')
    findOne(@Param('id') id: string) {
        return this.userService.findOne(+id);
    }

    @Patch(':id')
    update(@Param('id') id: string, @Body() updateUserDto: UpdateUserDto) {
        return this.userService.update(+id, updateUserDto);
    }

    @Delete(':id')
    remove(@Param('id') id: string) {
        return this.userService.remove(+id);
    }
}
```

## 常用生成命令速查

```bash
# 生成资源（完整 CRUD）
pnpm nest g resource modules/user

# 生成模块
pnpm nest g module modules/user

# 生成控制器
pnpm nest g controller modules/user

# 生成服务
pnpm nest g service modules/user

# 生成守卫
pnpm nest g guard modules/user/guards/auth

# 生成拦截器
pnpm nest g interceptor modules/user/interceptors/logging

# 生成过滤器
pnpm nest g filter modules/user/filters/http-exception

# 生成管道
pnpm nest g pipe modules/user/pipes/validation

# 生成装饰器
pnpm nest g decorator modules/user/decorators/roles
```

## 注意事项

1. **路径规范：**
    - 使用 `modules/模块名` 作为路径
    - 会自动创建目录结构

2. **自动导入：**
    - 生成的文件会自动导入到相应的模块中
    - 如果不想自动导入，使用 `--skip-import` 选项

3. **测试文件：**
    - 默认会生成 `.spec.ts` 测试文件
    - 使用 `--no-spec` 可以跳过测试文件生成

4. **扁平结构：**
    - 使用 `--flat` 可以生成扁平结构（所有文件在同一目录）
    - 不推荐使用，会破坏模块化结构

## DTO（Data Transfer Object）详解

### 什么是 DTO？

DTO（Data Transfer Object）是数据传输对象，用于在不同层之间传输数据。在 NestJS 中，DTO 主要用于：

1. **定义 API 请求和响应的数据结构**
2. **数据验证**（结合 `class-validator`）
3. **类型安全**
4. **API 文档生成**（结合 Swagger）

### 为什么需要 DTO？

#### 1. 数据验证

```typescript
// 没有 DTO - 不安全
@Post()
create(@Body() body: any) {
    // body 可能是任何数据，没有验证
    return this.userService.create(body);
}

// 使用 DTO - 安全
@Post()
create(@Body() createUserDto: CreateUserDto) {
    // 数据已经验证，类型安全
    return this.userService.create(createUserDto);
}
```

#### 2. 类型安全

```typescript
// DTO 定义了明确的数据结构
export class CreateUserDto {
    username: string;
    email: string;
    age: number;
}

// TypeScript 会检查类型
const user = new CreateUserDto();
user.username = 'john'; // ✅ 正确
user.age = '25'; // ❌ TypeScript 错误
```

#### 3. API 文档

使用 Swagger 时，DTO 会自动生成 API 文档：

```typescript
import { ApiProperty } from '@nestjs/swagger';

export class CreateUserDto {
    @ApiProperty({ description: '用户名', example: 'john' })
    username: string;

    @ApiProperty({ description: '邮箱', example: 'john@example.com' })
    email: string;
}
```

### DTO 的类型

#### 1. Create DTO（创建数据）

用于创建新资源时的数据验证：

```typescript
// dto/create-user.dto.ts
import {
    IsString,
    IsEmail,
    IsOptional,
    MinLength,
    MaxLength,
} from 'class-validator';
import { ApiProperty } from '@nestjs/swagger';

export class CreateUserDto {
    @ApiProperty({ description: '用户名', example: 'john' })
    @IsString()
    @MinLength(3)
    @MaxLength(20)
    username: string;

    @ApiProperty({ description: '邮箱', example: 'john@example.com' })
    @IsEmail()
    email: string;

    @ApiProperty({ description: '密码', example: 'password123' })
    @IsString()
    @MinLength(6)
    password: string;

    @ApiProperty({ description: '年龄', example: 25, required: false })
    @IsOptional()
    @IsNumber()
    age?: number;
}
```

#### 2. Update DTO（更新数据）

用于更新资源时的数据验证：

```typescript
// dto/update-user.dto.ts
import { PartialType } from '@nestjs/mapped-types';
import { CreateUserDto } from './create-user.dto';

// 方式一：使用 PartialType（推荐）
export class UpdateUserDto extends PartialType(CreateUserDto) {}

// 方式二：手动定义（更灵活）
// export class UpdateUserDto {
//     @IsOptional()
//     @IsString()
//     username?: string;
//
//     @IsOptional()
//     @IsEmail()
//     email?: string;
// }
```

#### 3. Query DTO（查询参数）

用于查询列表时的参数验证：

```typescript
// dto/query-user.dto.ts
import { IsOptional, IsNumber, Min, Max } from 'class-validator';
import { Type } from 'class-transformer';

export class QueryUserDto {
    @IsOptional()
    @Type(() => Number)
    @IsNumber()
    @Min(1)
    page?: number = 1;

    @IsOptional()
    @Type(() => Number)
    @IsNumber()
    @Min(1)
    @Max(100)
    limit?: number = 10;

    @IsOptional()
    @IsString()
    search?: string;

    @IsOptional()
    @IsString()
    sortBy?: string = 'createdAt';

    @IsOptional()
    @IsString()
    sortOrder?: 'ASC' | 'DESC' = 'DESC';
}
```

#### 4. Response DTO（响应数据）

用于定义 API 响应的数据结构：

```typescript
// dto/user-response.dto.ts
import { ApiProperty } from '@nestjs/swagger';

export class UserResponseDto {
    @ApiProperty({ description: '用户ID', example: 1 })
    id: number;

    @ApiProperty({ description: '用户名', example: 'john' })
    username: string;

    @ApiProperty({ description: '邮箱', example: 'john@example.com' })
    email: string;

    @ApiProperty({ description: '创建时间', example: '2024-01-01T00:00:00Z' })
    createdAt: Date;

    @ApiProperty({ description: '更新时间', example: '2024-01-01T00:00:00Z' })
    updatedAt: Date;
}
```

### 在 Controller 中使用 DTO

```typescript
import {
    Controller,
    Get,
    Post,
    Body,
    Patch,
    Param,
    Query,
} from '@nestjs/common';
import { UserService } from './user.service';
import { CreateUserDto } from './dto/create-user.dto';
import { UpdateUserDto } from './dto/update-user.dto';
import { QueryUserDto } from './dto/query-user.dto';

@Controller('users')
export class UserController {
    constructor(private readonly userService: UserService) {}

    @Post()
    create(@Body() createUserDto: CreateUserDto) {
        return this.userService.create(createUserDto);
    }

    @Get()
    findAll(@Query() queryUserDto: QueryUserDto) {
        return this.userService.findAll(queryUserDto);
    }

    @Get(':id')
    findOne(@Param('id') id: string) {
        return this.userService.findOne(+id);
    }

    @Patch(':id')
    update(@Param('id') id: string, @Body() updateUserDto: UpdateUserDto) {
        return this.userService.update(+id, updateUserDto);
    }
}
```

### 启用全局验证管道

在 `main.ts` 中启用全局验证：

```typescript
import { ValidationPipe } from '@nestjs/common';

async function bootstrap() {
    const app = await NestFactory.create(AppModule);

    // 启用全局验证管道
    app.useGlobalPipes(
        new ValidationPipe({
            whitelist: true, // 自动删除不在 DTO 中的属性
            forbidNonWhitelisted: true, // 如果请求包含未定义的属性，抛出错误
            transform: true, // 自动转换类型（如字符串转数字）
            transformOptions: {
                enableImplicitConversion: true,
            },
        }),
    );

    await app.listen(3000);
}
```

### 常用验证装饰器

```typescript
import {
    IsString, // 字符串
    IsNumber, // 数字
    IsBoolean, // 布尔值
    IsEmail, // 邮箱
    IsUrl, // URL
    IsDate, // 日期
    IsOptional, // 可选字段
    IsNotEmpty, // 非空
    MinLength, // 最小长度
    MaxLength, // 最大长度
    Min, // 最小值
    Max, // 最大值
    IsEnum, // 枚举
    IsArray, // 数组
    IsObject, // 对象
    ValidateNested, // 嵌套对象验证
    IsUUID, // UUID
    Matches, // 正则匹配
} from 'class-validator';
```

### DTO 示例：完整的用户模块

```typescript
// dto/create-user.dto.ts
import {
    IsString,
    IsEmail,
    IsOptional,
    MinLength,
    IsNumber,
    Min,
    Max,
} from 'class-validator';
import { ApiProperty } from '@nestjs/swagger';

export class CreateUserDto {
    @ApiProperty({ description: '用户名', example: 'john' })
    @IsString()
    @MinLength(3)
    @MaxLength(20)
    username: string;

    @ApiProperty({ description: '邮箱', example: 'john@example.com' })
    @IsEmail()
    email: string;

    @ApiProperty({ description: '密码', example: 'password123' })
    @IsString()
    @MinLength(6)
    password: string;

    @ApiProperty({ description: '年龄', example: 25, required: false })
    @IsOptional()
    @IsNumber()
    @Min(18)
    @Max(100)
    age?: number;
}
```

```typescript
// dto/update-user.dto.ts
import { PartialType } from '@nestjs/mapped-types';
import { CreateUserDto } from './create-user.dto';

export class UpdateUserDto extends PartialType(CreateUserDto) {}
```

```typescript
// dto/query-user.dto.ts
import { IsOptional, IsNumber, IsString, Min, Max } from 'class-validator';
import { Type } from 'class-transformer';

export class QueryUserDto {
    @IsOptional()
    @Type(() => Number)
    @IsNumber()
    @Min(1)
    page?: number = 1;

    @IsOptional()
    @Type(() => Number)
    @IsNumber()
    @Min(1)
    @Max(100)
    limit?: number = 10;

    @IsOptional()
    @IsString()
    search?: string;
}
```

### 安装必要的依赖

```bash
# 安装验证库
pnpm add class-validator class-transformer

# 如果使用 Swagger（可选）
pnpm add @nestjs/swagger swagger-ui-express
```

### DTO vs Entity

| 特性     | DTO                    | Entity              |
| -------- | ---------------------- | ------------------- |
| **用途** | 数据传输和验证         | 数据库模型          |
| **位置** | `dto/` 目录            | `entities/` 目录    |
| **验证** | 使用 `class-validator` | 使用 TypeORM 装饰器 |
| **暴露** | 暴露给 API 客户端      | 不直接暴露          |
| **示例** | `CreateUserDto`        | `User` entity       |

**最佳实践：**

- ✅ Entity 包含数据库字段（如 `id`, `createdAt`）
- ✅ DTO 只包含客户端需要传递的字段
- ✅ 使用 DTO 转换 Entity，避免暴露敏感信息

### DTO 转换示例

```typescript
// service 中使用
@Injectable()
export class UserService {
    async create(createUserDto: CreateUserDto): Promise<User> {
        // DTO → Entity
        const user = this.userRepository.create({
            username: createUserDto.username,
            email: createUserDto.email,
            // 不直接传递 password，需要加密
            passwordHash: await this.hashPassword(createUserDto.password),
        });

        return this.userRepository.save(user);
    }

    async findAll(queryDto: QueryUserDto): Promise<User[]> {
        // 使用 DTO 中的查询参数
        return this.userRepository.find({
            skip: (queryDto.page - 1) * queryDto.limit,
            take: queryDto.limit,
        });
    }
}
```

## 最佳实践

1. ✅ **使用 `resource` 命令生成完整模块**
2. ✅ **按功能模块组织文件**
3. ✅ **每个模块包含：module、controller、service、entity**
4. ✅ **DTO 文件放在模块目录下的 `dto/` 子目录**
5. ✅ **为每个操作创建对应的 DTO（Create、Update、Query、Response）**
6. ✅ **使用 `class-validator` 进行数据验证**
7. ✅ **使用 `PartialType` 创建 Update DTO**
8. ✅ **启用全局验证管道**
9. ✅ **区分 DTO 和 Entity，不要混用**
10. ✅ **公共组件放在 `common/` 目录**
11. ❌ **避免使用扁平结构**
12. ❌ **避免按类型组织文件**
13. ❌ **避免在 Entity 中直接暴露给 API**