create-hest-app 0.1.0

package/templates/cqrs_scalar/src/modules/custom-validation/custom-validation.controller.ts

@@ -0,0 +1,146 @@
+import { Controller, Get, Post } from '@hestjs/core';
+import { Body } from '@hestjs/validation';
+import { CustomValidationDto, SearchQueryDto } from './dto/custom-validation.dto';
+import { CustomValidationService } from './custom-validation.service';
+
+/**
+ * 自定义验证控制器 - 展示 TypeBox 自定义验证功能
+ */
+@Controller('/api/custom')
+export class CustomValidationController {
+  constructor(
+    private readonly customValidationService: CustomValidationService,
+  ) {}
+
+  @Get('/')
+  async getInfo() {
+    return {
+      success: true,
+      message: 'HestJS 自定义验证功能示例',
+      features: [
+        '🔧 TypeBox 自定义 Schema 验证',
+        '🏗️ SchemaFactory 便捷构建器',
+        '📦 CommonValidators 常用验证',
+        '🔗 联合类型验证',
+        '📐 嵌套对象验证',
+        '📱 中国手机号验证',
+        '🔗 UUID 验证',
+        '📍 地理坐标验证',
+      ],
+      endpoints: {
+        'POST /api/custom/validate': '测试自定义验证',
+        'POST /api/custom/search': '测试搜索参数验证',
+        'GET /api/custom/examples': '获取验证示例',
+      },
+    };
+  }
+
+  @Post('/validate')
+  async validateCustomData(
+    @Body(CustomValidationDto) data: CustomValidationDto,
+  ) {
+    const result = this.customValidationService.processCustomData(data);
+    return {
+      success: true,
+      message: '自定义验证通过！',
+      result,
+      validationInfo: {
+        username: `用户名 "${data.username}" 通过正则验证`,
+        role: `角色 "${data.role}" 通过联合类型验证`,
+        userId: `UUID "${data.userId}" 格式验证通过`,
+        phoneNumber: data.phoneNumber
+          ? `手机号 "${data.phoneNumber}" 通过中国手机号验证`
+          : '未提供手机号',
+        location: data.location
+          ? `坐标 (${data.location.lat}, ${data.location.lng}) 验证通过`
+          : '未提供坐标',
+        emails: data.emails
+          ? `邮箱列表包含 ${data.emails.length} 个地址`
+          : '未提供邮箱',
+      },
+    };
+  }
+
+  @Post('/search')
+  async searchWithValidation(@Body(SearchQueryDto) query: SearchQueryDto) {
+    const result = this.customValidationService.processSearch(query);
+    return {
+      success: true,
+      message: '搜索参数验证通过！',
+      result,
+      validationInfo: {
+        query: query.q || '无搜索关键词',
+        pagination: query.pagination || '使用默认分页',
+      },
+    };
+  }
+
+  @Get('/examples')
+  async getValidationExamples() {
+    return {
+      success: true,
+      message: '自定义验证示例',
+      examples: {
+        customValidation: {
+          description: 'POST /api/custom/validate',
+          validExample: {
+            username: 'john_doe123',
+            role: 'user',
+            userId: '123e4567-e89b-12d3-a456-426614174000',
+            phoneNumber: '13812345678',
+            location: { lat: 39.9042, lng: 116.4074 },
+            emails: ['john@example.com', 'john.doe@company.com'],
+          },
+          invalidExample: {
+            username: 'a', // 太短
+            role: 'invalid_role', // 不在联合类型中
+            userId: 'not-a-uuid', // 无效 UUID
+            phoneNumber: '123456', // 无效手机号
+            location: { lat: 200, lng: 200 }, // 超出范围
+            emails: ['invalid-email', 'another@invalid'], // 无效邮箱
+          },
+        },
+        searchValidation: {
+          description: 'POST /api/custom/search',
+          validExample: {
+            q: 'TypeScript',
+            pagination: {
+              page: 1,
+              limit: 10,
+              sort: 'createdAt',
+              order: 'desc',
+            },
+          },
+          invalidExample: {
+            q: 123, // 应该是字符串
+            pagination: {
+              page: 0, // 应该 >= 1
+              limit: 1000, // 应该 <= 100
+              order: 'invalid', // 应该是 'asc' 或 'desc'
+            },
+          },
+        },
+      },
+      typeboxFeatures: {
+        basicTypes: [
+          'Type.String()',
+          'Type.Number()',
+          'Type.Boolean()',
+          'Type.Array()',
+        ],
+        advancedTypes: [
+          'Type.Union()',
+          'Type.Object()',
+          'Type.Intersect()',
+          'Type.Optional()',
+        ],
+        formats: ['email', 'date', 'date-time', 'uri', 'uuid'],
+        patterns: ['正则表达式验证', '长度限制', '数值范围', '枚举值'],
+        customValidators: [
+          'SchemaFactory 便捷方法',
+          'CommonValidators 常用验证',
+        ],
+      },
+    };
+  }
+}

package/templates/cqrs_scalar/src/modules/custom-validation/custom-validation.module.ts

@@ -0,0 +1,10 @@
+import { Module } from '@hestjs/core';
+import { CustomValidationController } from './custom-validation.controller';
+import { CustomValidationService } from './custom-validation.service';
+
+@Module({
+  controllers: [CustomValidationController],
+  providers: [CustomValidationService],
+  exports: [CustomValidationService],
+})
+export class CustomValidationModule {}

package/templates/cqrs_scalar/src/modules/custom-validation/custom-validation.service.ts

@@ -0,0 +1,33 @@
+import { Injectable } from '@hestjs/core';
+import type { CustomValidationDto, SearchQueryDto } from './dto/custom-validation.dto';
+
+/**
+ * 自定义验证服务
+ */
+@Injectable()
+export class CustomValidationService {
+  processCustomData(data: CustomValidationDto) {
+    // 模拟处理逻辑
+    return {
+      processed: true,
+      data: {
+        ...data,
+        processedAt: new Date().toISOString(),
+        validation: 'TypeBox 自定义验证通过',
+      },
+    };
+  }
+
+  processSearch(query: SearchQueryDto) {
+    // 模拟搜索逻辑
+    return {
+      results: [
+        { id: 1, title: '搜索结果 1', relevance: 0.95 },
+        { id: 2, title: '搜索结果 2', relevance: 0.87 },
+      ],
+      query,
+      total: 2,
+      searchedAt: new Date().toISOString(),
+    };
+  }
+}

package/templates/cqrs_scalar/src/modules/custom-validation/dto/custom-validation.dto.ts

@@ -0,0 +1,132 @@
+import {
+  CommonValidators,
+  Custom,
+  IsOptional,
+  IsString,
+  SchemaFactory,
+} from '@hestjs/validation';
+import { Type } from '@sinclair/typebox';
+
+/**
+ * 展示自定义验证功能的简化 DTO
+ */
+export class CustomValidationDto {
+  // 使用基础的 TypeBox API
+  @Custom(
+    Type.String({ minLength: 3, maxLength: 20, pattern: '^[a-zA-Z0-9_]+$' }),
+    {
+      message: '用户名必须是3-20位字母、数字或下划线',
+    },
+  )
+  username!: string;
+
+  // 使用联合类型
+  @Custom(
+    Type.Union([
+      Type.Literal('admin'),
+      Type.Literal('user'),
+      Type.Literal('guest'),
+    ]),
+    {
+      message: '角色必须是 admin、user 或 guest',
+    },
+  )
+  role!: 'admin' | 'user' | 'guest';
+
+  // 使用 CommonValidators 的便捷方法
+  @CommonValidators.UUID({ message: '必须是有效的 UUID' })
+  userId!: string;
+
+  // 使用 SchemaFactory 的便捷方法
+  @Custom(SchemaFactory.chinesePhoneNumber(), {
+    message: '必须是有效的中国手机号',
+    optional: true,
+  })
+  phoneNumber?: string;
+
+  // 自定义对象验证
+  @Custom(
+    Type.Object({
+      lat: Type.Number({ minimum: -90, maximum: 90 }),
+      lng: Type.Number({ minimum: -180, maximum: 180 }),
+    }),
+    { optional: true, message: '坐标必须在有效范围内' },
+  )
+  location?: {
+    lat: number;
+    lng: number;
+  };
+
+  // 数组验证
+  @Custom(Type.Array(Type.String({ format: 'email' })), {
+    optional: true,
+    message: '邮箱列表必须是有效的邮箱地址数组',
+  })
+  emails?: string[];
+}
+
+/**
+ * 搜索查询 DTO - 展示复杂对象验证
+ */
+export class SearchQueryDto {
+  @IsOptional()
+  @IsString({ message: '搜索关键词必须是字符串' })
+  q?: string;
+
+  // 使用 SchemaFactory 构建复杂的分页对象
+  @Custom(
+    Type.Object({
+      page: Type.Number({ minimum: 1 }),
+      limit: Type.Number({ minimum: 1, maximum: 100 }),
+      sort: Type.Optional(Type.String()),
+      order: Type.Optional(
+        Type.Union([Type.Literal('asc'), Type.Literal('desc')]),
+      ),
+    }),
+    {
+      optional: true,
+      message: '分页参数格式错误',
+    },
+  )
+  pagination?: {
+    page: number;
+    limit: number;
+    sort?: string;
+    order?: 'asc' | 'desc';
+  };
+
+  // 使用联合类型进行复杂验证
+  @Custom(
+    Type.Union([
+      Type.Array(Type.String()),
+      Type.String(),
+      Type.Null(),
+      Type.Undefined(),
+    ]),
+    {
+      optional: true,
+      message: '标签可以是字符串、字符串数组或空值',
+    },
+  )
+  tags?: string | string[] | null;
+
+  // 使用数值范围验证
+  @Custom(Type.Number({ minimum: 0, maximum: 100 }), {
+    optional: true,
+    message: '评分必须在 0-100 之间',
+  })
+  score?: number;
+
+  // 使用日期字符串验证
+  @Custom(Type.String({ format: 'date' }), {
+    optional: true,
+    message: '开始日期格式必须是 YYYY-MM-DD',
+  })
+  startDate?: string;
+
+  @Custom(Type.String({ format: 'date' }), {
+    optional: true,
+    message: '结束日期格式必须是 YYYY-MM-DD',
+  })
+  endDate?: string;
+}

package/templates/cqrs_scalar/src/modules/users/dto/user.dto.ts

@@ -0,0 +1,64 @@
+import {
+  IsEmail,
+  IsNumber,
+  IsOptional,
+  IsString,
+  Length,
+  Max,
+  Min,
+} from '@hestjs/validation';
+
+/**
+ * 创建用户 DTO
+ */
+export class CreateUserDto {
+  @IsString({
+    minLength: 2,
+    maxLength: 50,
+    message: '用户名长度必须在2-50字符之间',
+  })
+  name!: string;
+
+  @IsEmail({ message: '请输入有效的邮箱地址' })
+  email!: string;
+
+  @IsNumber({ message: '年龄必须是数字' })
+  @Min(0, { message: '年龄不能小于0' })
+  @Max(120, { message: '年龄不能大于120' })
+  age!: number;
+
+  @IsString({ message: '密码必须是字符串' })
+  @Length(8, 100, { message: '密码长度必须在8-100字符之间' })
+  password!: string;
+
+  @IsOptional()
+  @IsString({ message: '个人简介必须是字符串' })
+  bio?: string;
+}
+
+/**
+ * 更新用户 DTO
+ */
+export class UpdateUserDto {
+  @IsOptional()
+  @IsString({
+    minLength: 2,
+    maxLength: 50,
+    message: '用户名长度必须在2-50字符之间',
+  })
+  name?: string;
+
+  @IsOptional()
+  @IsEmail({ message: '请输入有效的邮箱地址' })
+  email?: string;
+
+  @IsOptional()
+  @IsNumber({ message: '年龄必须是数字' })
+  @Min(0, { message: '年龄不能小于0' })
+  @Max(120, { message: '年龄不能大于120' })
+  age?: number;
+
+  @IsOptional()
+  @IsString({ message: '个人简介必须是字符串' })
+  bio?: string;
+}

package/templates/cqrs_scalar/src/modules/users/entities/user.entity.ts

@@ -0,0 +1,9 @@
+// 定义用户类型
+export interface User {
+  id: number;
+  name: string;
+  email: string;
+  age: number;
+  password?: string;
+  bio?: string;
+}

package/templates/cqrs_scalar/src/modules/users/users.controller.ts

@@ -0,0 +1,68 @@
+import type { HestContext } from '@hestjs/core';
+import { Context, Controller, Get, Post } from '@hestjs/core';
+import { Body } from '@hestjs/validation';
+import { CreateUserDto, UpdateUserDto } from './dto/user.dto';
+import { UsersService } from './users.service';
+
+/**
+ * 用户控制器 - 展示验证功能
+ */
+@Controller('/users')
+export class UsersController {
+  constructor(private readonly usersService: UsersService) {}
+
+  @Get('/')
+  async getAllUsers() {
+    return {
+      success: true,
+      data: this.usersService.findAll(),
+      message: 'Users retrieved successfully',
+    };
+  }
+
+  @Get('/:id')
+  async getUser(@Context() c: HestContext) {
+    const id = parseInt(c.req.param('id'));
+    const user = this.usersService.findOne(id);
+
+    if (!user) {
+      return c.json(
+        {
+          success: false,
+          message: 'User not found',
+        },
+        404,
+      );
+    }
+
+    return {
+      success: true,
+      data: user,
+      message: 'User retrieved successfully',
+    };
+  }
+
+  @Post('/')
+  async createUser(@Body(CreateUserDto) createUserDto: CreateUserDto) {
+    const newUser = this.usersService.create(createUserDto);
+    return {
+      success: true,
+      data: newUser,
+      message: 'User created successfully',
+    };
+  }
+
+  @Post('/:id')
+  async updateUser(
+    @Context() c: HestContext,
+    @Body(UpdateUserDto) updateUserDto: UpdateUserDto,
+  ) {
+    const id = parseInt(c.req.param('id'));
+    const updatedUser = this.usersService.update(id, updateUserDto);
+    return {
+      success: true,
+      data: updatedUser,
+      message: 'User updated successfully',
+    };
+  }
+}

package/templates/cqrs_scalar/src/modules/users/users.module.ts

@@ -0,0 +1,10 @@
+import { Module } from '@hestjs/core';
+import { UsersController } from './users.controller';
+import { UsersService } from './users.service';
+
+@Module({
+  controllers: [UsersController],
+  providers: [UsersService],
+  exports: [UsersService],
+})
+export class UsersModule {}

package/templates/cqrs_scalar/src/modules/users/users.service.ts

@@ -0,0 +1,55 @@
+import { Injectable } from '@hestjs/core';
+import type { User } from './entities/user.entity';
+import type { CreateUserDto, UpdateUserDto } from './dto/user.dto';
+
+/**
+ * 用户服务
+ */
+@Injectable()
+export class UsersService {
+  private users: User[] = [
+    { id: 1, name: 'John Doe', email: 'john@example.com', age: 30 },
+    { id: 2, name: 'Jane Smith', email: 'jane@example.com', age: 25 },
+  ];
+
+  findAll(): User[] {
+    return this.users;
+  }
+
+  findOne(id: number): User | undefined {
+    return this.users.find(user => user.id === id);
+  }
+
+  create(createUserDto: CreateUserDto): Omit<User, 'password'> {
+    const newUser: User = {
+      id: this.users.length + 1,
+      ...createUserDto,
+    };
+    this.users.push(newUser);
+
+    // 不返回密码
+    const { password: _password, ...userWithoutPassword } = newUser;
+    return userWithoutPassword;
+  }
+
+  update(id: number, updateUserDto: UpdateUserDto): User {
+    const userIndex = this.users.findIndex(user => user.id === id);
+    if (userIndex === -1) {
+      throw new Error('User not found');
+    }
+
+    this.users[userIndex] = { ...this.users[userIndex], ...updateUserDto };
+    return this.users[userIndex];
+  }
+
+  remove(id: number): User {
+    const userIndex = this.users.findIndex(user => user.id === id);
+    if (userIndex === -1) {
+      throw new Error('User not found');
+    }
+
+    const deletedUser = this.users[userIndex];
+    this.users.splice(userIndex, 1);
+    return deletedUser;
+  }
+}

package/templates/cqrs_scalar/src/test-error-scenarios.ts

@@ -0,0 +1,54 @@
+import { logger } from '@hestjs/logger';
+
+// 模拟应用启动时的错误处理
+async function testErrorScenarios() {
+  console.log('=== Testing Real-world Error Scenarios ===\n');
+
+  // 场景 1: 数据库连接错误
+  try {
+    throw new Error('Database connection failed');
+  } catch (error) {
+    logger.error(
+      '❌ Failed to connect to database:',
+      error instanceof Error ? error : new Error(String(error)),
+    );
+  }
+
+  // 场景 2: API 调用失败
+  try {
+    const apiError = new Error('API request timeout');
+    (apiError as any).status = 504;
+    (apiError as any).endpoint = '/api/users';
+    throw apiError;
+  } catch (error) {
+    logger.error(
+      '❌ API call failed:',
+      error instanceof Error ? error : new Error(String(error)),
+      {
+        requestId: 'req-12345',
+        userId: 'user-67890',
+      },
+    );
+  }
+
+  // 场景 3: 验证错误
+  try {
+    const validationError = new Error('Validation failed');
+    (validationError as any).fields = ['email', 'password'];
+    (validationError as any).code = 'VALIDATION_ERROR';
+    throw validationError;
+  } catch (error) {
+    logger.error(
+      '❌ Validation failed:',
+      error instanceof Error ? error : new Error(String(error)),
+    );
+  }
+
+  // 场景 4: 使用简化的语法
+  const simpleError = new Error('Something went wrong');
+  logger.error('❌ Simple error logging:', simpleError);
+
+  console.log('\n=== Test Complete ===');
+}
+
+testErrorScenarios();

package/templates/cqrs_scalar/src/users/commands/create-user.command.ts

@@ -0,0 +1,8 @@
+import { Command } from '@hestjs/cqrs';
+import { CreateUserData, User } from '../entities';
+
+export class CreateUserCommand extends Command<User> {
+  constructor(public readonly userData: CreateUserData) {
+    super();
+  }
+}

package/templates/cqrs_scalar/src/users/commands/index.ts

@@ -0,0 +1,2 @@
+export * from './create-user.command';
+export * from './update-user.command';

package/templates/cqrs_scalar/src/users/commands/update-user.command.ts

@@ -0,0 +1,11 @@
+import { Command } from '@hestjs/cqrs';
+import { UpdateUserData, User } from '../entities';
+
+export class UpdateUserCommand extends Command<User> {
+  constructor(
+    public readonly userId: string,
+    public readonly userData: UpdateUserData,
+  ) {
+    super();
+  }
+}

package/templates/cqrs_scalar/src/users/entities/index.ts

@@ -0,0 +1 @@
+export * from './user.entity';

package/templates/cqrs_scalar/src/users/entities/user.entity.ts

@@ -0,0 +1,22 @@
+import { IQueryResult } from '@hestjs/cqrs';
+
+export interface User extends IQueryResult {
+  id: string;
+  name: string;
+  email: string;
+  age?: number;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface CreateUserData {
+  name: string;
+  email: string;
+  age?: number;
+}
+
+export interface UpdateUserData {
+  name?: string;
+  email?: string;
+  age?: number;
+}

package/templates/cqrs_scalar/src/users/events/index.ts

@@ -0,0 +1,2 @@
+export * from './user-created.event';
+export * from './user-updated.event';

package/templates/cqrs_scalar/src/users/events/user-created.event.ts

@@ -0,0 +1,8 @@
+import { Event } from '@hestjs/cqrs';
+import { User } from '../entities';
+
+export class UserCreatedEvent extends Event {
+  constructor(public readonly user: User) {
+    super();
+  }
+}

package/templates/cqrs_scalar/src/users/events/user-updated.event.ts

@@ -0,0 +1,8 @@
+import { Event } from '@hestjs/cqrs';
+import { User } from '../entities';
+
+export class UserUpdatedEvent extends Event {
+  constructor(public readonly user: User) {
+    super();
+  }
+}

package/templates/cqrs_scalar/src/users/handlers/create-user.handler.ts

@@ -0,0 +1,26 @@
+import { Injectable } from '@hestjs/core';
+import { CommandHandler, EventBus, ICommandHandler } from '@hestjs/cqrs';
+import { CreateUserCommand } from '../commands';
+import { User } from '../entities';
+import { UserCreatedEvent } from '../events';
+import { UserRepository } from '../repositories';
+
+@Injectable()
+@CommandHandler(CreateUserCommand)
+export class CreateUserHandler
+  implements ICommandHandler<CreateUserCommand, User>
+{
+  constructor(
+    private readonly userRepository: UserRepository,
+    private readonly eventBus: EventBus,
+  ) {}
+
+  async execute(command: CreateUserCommand): Promise<User> {
+    const user = await this.userRepository.create(command.userData);
+
+    // 发布用户创建事件
+    await this.eventBus.publish(new UserCreatedEvent(user));
+
+    return user;
+  }
+}