create-hest-app 0.1.0

package/templates/base_scalar/src/app.controller.ts

@@ -0,0 +1,196 @@
+import { Controller, Get, NotFoundException, Param, Post } from '@hestjs/core';
+import {
+  ApiBody,
+  ApiOperation,
+  ApiParam,
+  ApiResponse,
+  ApiTags,
+} from '@hestjs/scalar';
+import { Body } from '@hestjs/validation';
+import { AppService } from './app.service';
+import { CreateUserDto } from './modules/users/dto/user.dto';
+
+@Controller('/api')
+@ApiTags('Application')
+export class AppController {
+  constructor(private readonly appService: AppService) {}
+
+  @Get('/')
+  @ApiOperation({
+    summary: 'Get hello message',
+    description: 'Returns a hello world message',
+    tags: ['Health Check', 'Application'],
+  })
+  @ApiResponse('200', {
+    description: 'Successful response',
+    content: {
+      'application/json': {
+        schema: {
+          type: 'object',
+          properties: {
+            message: { type: 'string', example: 'Hello World!' },
+          },
+        },
+      },
+    },
+  })
+  getHello() {
+    return { message: this.appService.getHello() };
+  }
+
+  @Get('/users')
+  @ApiOperation({
+    summary: 'Get all users',
+    description: 'Returns a list of all users',
+  })
+  @ApiResponse('200', {
+    description: 'List of users',
+    content: {
+      'application/json': {
+        schema: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              id: { type: 'string' },
+              name: { type: 'string' },
+              email: { type: 'string' },
+            },
+          },
+        },
+      },
+    },
+  })
+  getUsers() {
+    return this.appService.getUsers();
+  }
+
+  @Get('/users/:id')
+  @ApiOperation({
+    summary: 'Get user by ID',
+    description: 'Returns a single user by their ID',
+  })
+  @ApiParam('id', {
+    description: 'User ID',
+    schema: { type: 'string' },
+    example: '123',
+  })
+  @ApiResponse('200', {
+    description: 'User found',
+    content: {
+      'application/json': {
+        schema: {
+          type: 'object',
+          properties: {
+            id: { type: 'string' },
+            name: { type: 'string' },
+            email: { type: 'string' },
+          },
+        },
+      },
+    },
+  })
+  @ApiResponse('404', {
+    description: 'User not found',
+    content: {
+      'application/json': {
+        schema: {
+          type: 'object',
+          properties: {
+            message: { type: 'string', example: 'User with id 123 not found' },
+          },
+        },
+      },
+    },
+  })
+  getUser(@Param('id') id: string) {
+    const user = this.appService.getUser(id);
+    if (!user) {
+      throw new NotFoundException(`User with id ${id} not found`);
+    }
+    return user;
+  }
+
+  @Post('/users')
+  @ApiOperation({
+    summary: 'Create a new user',
+    description: 'Creates a new user with the provided data',
+  })
+  @ApiBody(
+    {
+      'application/json': {
+        schema: {
+          type: 'object',
+          required: ['name', 'email'],
+          properties: {
+            name: { type: 'string', example: 'John Doe' },
+            email: {
+              type: 'string',
+              format: 'email',
+              example: 'john@example.com',
+            },
+          },
+        },
+      },
+    },
+    {
+      description: 'User creation data',
+      required: true,
+    },
+  )
+  @ApiResponse('201', {
+    description: 'User created successfully',
+    content: {
+      'application/json': {
+        schema: {
+          type: 'object',
+          properties: {
+            id: { type: 'string' },
+            name: { type: 'string' },
+            email: { type: 'string' },
+            createdAt: { type: 'string', format: 'date-time' },
+          },
+        },
+      },
+    },
+  })
+  @ApiResponse('400', {
+    description: 'Invalid input data',
+    content: {
+      'application/json': {
+        schema: {
+          type: 'object',
+          properties: {
+            message: { type: 'string' },
+            errors: { type: 'array', items: { type: 'string' } },
+          },
+        },
+      },
+    },
+  })
+  createUser(@Body(CreateUserDto) createUserDto: CreateUserDto) {
+    return this.appService.createUser(createUserDto);
+  }
+
+  @Get('/error')
+  @ApiOperation({
+    summary: 'Test error endpoint',
+    description: 'Throws an error for testing error handling',
+  })
+  @ApiResponse('500', {
+    description: 'Internal server error',
+    content: {
+      'application/json': {
+        schema: {
+          type: 'object',
+          properties: {
+            message: { type: 'string', example: 'This is a test error' },
+          },
+        },
+      },
+    },
+  })
+  throwError() {
+    throw new Error('This is a test error');
+  }
+}

package/templates/base_scalar/src/app.module.ts

@@ -0,0 +1,12 @@
+import { Module } from '@hestjs/core';
+import { AppController } from './app.controller';
+import { AppService } from './app.service';
+import { UsersModule } from './modules/users/users.module';
+import { CustomValidationModule } from './modules/custom-validation/custom-validation.module';
+
+@Module({
+  imports: [UsersModule, CustomValidationModule],
+  controllers: [AppController],
+  providers: [AppService],
+})
+export class AppModule {}

package/templates/base_scalar/src/app.service.ts

@@ -0,0 +1,30 @@
+import { Injectable } from '@hestjs/core';
+
+@Injectable()
+export class AppService {
+  private users = [
+    { id: '1', name: 'John Doe', email: 'john@example.com' },
+    { id: '2', name: 'Jane Smith', email: 'jane@example.com' },
+  ];
+
+  getHello(): string {
+    return 'Hello from HestJS!';
+  }
+
+  getUsers() {
+    return this.users;
+  }
+
+  getUser(id: string) {
+    return this.users.find(user => user.id === id);
+  }
+
+  createUser(userData: { name: string; email: string }) {
+    const user = {
+      id: Date.now().toString(),
+      ...userData,
+    };
+    this.users.push(user);
+    return user;
+  }
+}

package/templates/base_scalar/src/common/filters/http-exception.filter.ts

@@ -0,0 +1,34 @@
+import type {
+  ArgumentsHost,
+  ExceptionFilter,
+  HttpException,
+} from '@hestjs/core';
+import { createLogger } from '@hestjs/core';
+
+const logger = createLogger('HttpExceptionFilter');
+
+/**
+ * 自定义 HTTP 异常过滤器
+ */
+export class HttpExceptionFilter implements ExceptionFilter<HttpException> {
+  catch(exception: HttpException, host: ArgumentsHost) {
+    const ctx = host.getContext();
+    const request = host.getRequest();
+
+    const status = exception.status;
+    const response = {
+      statusCode: status,
+      timestamp: new Date().toISOString(),
+      path: request.url,
+      message: exception.message,
+      error: exception.error || 'Http Exception',
+    };
+
+    logger.error(`🔥 HTTP Exception [${status}]: ${exception.message}`, {
+      requestUrl: request.url,
+      stack: exception.stack,
+    });
+
+    return ctx.json(response, status);
+  }
+}

package/templates/base_scalar/src/common/interceptors/response.interceptor.ts

@@ -0,0 +1,38 @@
+import type { CallHandler, ExecutionContext, Interceptor } from '@hestjs/core';
+import { createLogger } from '@hestjs/core';
+
+const logger = createLogger('ResponseInterceptor');
+
+/**
+ * 响应转换拦截器
+ */
+export class ResponseInterceptor implements Interceptor {
+  async intercept(
+    context: ExecutionContext,
+    next: CallHandler,
+  ): Promise<{
+    success: boolean;
+    data: unknown;
+    timestamp: string;
+    duration: string;
+  }> {
+    const startTime = Date.now();
+    const request = context.switchToHttp().getRequest();
+
+    logger.info(`🚀  Request: ${request.method} ${request.url}`);
+
+    const result = await next.handle();
+
+    const duration = Date.now() - startTime;
+    logger.info(
+      `✅ Response: ${request.method} ${request.url} - ${duration}ms`,
+    );
+
+    return {
+      success: true,
+      data: result,
+      timestamp: new Date().toISOString(),
+      duration: `${duration}ms`,
+    };
+  }
+}

package/templates/base_scalar/src/index.ts

@@ -0,0 +1,67 @@
+import { HestFactory } from '@hestjs/core';
+import { logger } from '@hestjs/logger';
+import '@hestjs/scalar'; // 导入scalar扩展
+import { ValidationInterceptor } from '@hestjs/validation';
+import { cors } from 'hono/cors';
+import { AppController } from './app.controller';
+import { AppModule } from './app.module';
+import { HttpExceptionFilter } from './common/filters/http-exception.filter';
+import { ResponseInterceptor } from './common/interceptors/response.interceptor';
+
+async function bootstrap() {
+  try {
+    logger.info('🚀 Starting HestJS application...');
+
+    const app = await HestFactory.create(AppModule);
+    app.hono().use(cors()); // 使用 Hono 的 CORS 中间件
+    // app.hono().use('*', log()); // 使用 Hono 的日志中间件
+
+    // 全局拦截器 - 验证拦截器应该在响应拦截器之前
+    app.useGlobalInterceptors(new ValidationInterceptor());
+    app.useGlobalInterceptors(new ResponseInterceptor());
+
+    // 全局异常过滤器
+    app.useGlobalFilters(new HttpExceptionFilter());
+
+    // 设置OpenAPI规范端点 - 基于注解生成
+    app.useScalarWithControllers(
+      [AppController], // 传入需要生成文档的控制器
+      {
+        info: {
+          title: 'HestJS Demo API',
+          version: '1.0.0',
+          description:
+            'A demonstration of HestJS framework capabilities with Scalar API documentation',
+        },
+        servers: [
+          {
+            url: 'http://localhost:3002',
+            description: 'Development server',
+          },
+        ],
+      },
+      {
+        path: '/docs',
+        theme: 'elysia', // 使用elysia主题
+        enableMarkdown: true,
+        markdownPath: '/api-docs.md',
+      },
+    );
+
+    logger.info('📚 API Documentation available at:');
+    logger.info('  • Scalar UI: http://localhost:3002/docs');
+    logger.info('  • OpenAPI JSON: http://localhost:3002/openapi.json');
+    logger.info('  • Markdown (for LLMs): http://localhost:3002/api-docs.md');
+
+    Bun.serve({
+      port: 3002,
+      fetch: app.hono().fetch,
+      reusePort: true, // 启用端口复用
+    });
+  } catch (error) {
+    logger.error('❌ Failed to start application:', error);
+    process.exit(1);
+  }
+}
+
+bootstrap();

package/templates/base_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/base_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/base_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/base_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;
+}