create-hest-app 0.1.0 → 0.1.2

package/templates/cqrs_scalar/eslint.config.ts

@@ -17,8 +17,6 @@ export default [
       '*.d.ts',
       '.bun/**',
       'bun.lockb',
-      // shadcn 目录
-      'src/components/ui/**',
       // scripts 目录
       'scripts/**',
     ],

package/templates/cqrs_scalar/package.json

@@ -30,9 +30,10 @@
   "author": "aqz236",
   "license": "MIT",
   "dependencies": {
-    "@hestjs/core": "^0.1.8",
+    "@hestjs/core": "^0.1.9",
     "@hestjs/validation": "^0.1.5",
-    "@hestjs/cqrs": "^0.1.2",
+    "@hestjs/cqrs": "^0.1.3",
+    "@hestjs/scalar": "^0.1.4",
     "hono": "^4.8.9",
     "reflect-metadata": "^0.2.2"
   },

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

@@ -1,15 +1,58 @@
 import { Controller, Get } from '@hestjs/core';
+import { ApiOperation, ApiResponse, ApiTags } from '@hestjs/scalar';
 import { AppService } from './app.service';
 
 @Controller('/')
+@ApiTags('Application')
 export class AppController {
   constructor(private readonly appService: AppService) {}
 
   @Get('/')
+  @ApiOperation({
+    summary: 'Get application info',
+    description: 'Returns application information and available endpoints',
+    tags: ['Health Check', 'Application'],
+  })
+  @ApiResponse('200', {
+    description: 'Application information',
+    content: {
+      'application/json': {
+        schema: {
+          type: 'object',
+          properties: {
+            message: {
+              type: 'string',
+              example: 'Hello World from HestJS CQRS!',
+            },
+            description: {
+              type: 'string',
+              example:
+                'HestJS CQRS Demo - A demonstration of CQRS pattern using HestJS framework',
+            },
+            endpoints: {
+              type: 'object',
+              properties: {
+                users: {
+                  type: 'object',
+                  properties: {
+                    getAll: { type: 'string', example: 'GET /users' },
+                    getById: { type: 'string', example: 'GET /users/:id' },
+                    create: { type: 'string', example: 'POST /users' },
+                    update: { type: 'string', example: 'PUT /users/:id' },
+                  },
+                },
+              },
+            },
+          },
+        },
+      },
+    },
+  })
   getHello() {
     return {
       message: this.appService.getHello(),
-      description: 'HestJS CQRS Demo - A demonstration of CQRS pattern using HestJS framework',
+      description:
+        'HestJS CQRS Demo - A demonstration of CQRS pattern using HestJS framework',
       endpoints: {
         users: {
           getAll: 'GET /users',
@@ -22,6 +65,26 @@ export class AppController {
   }
 
   @Get('/error')
+  @ApiOperation({
+    summary: 'Test error endpoint',
+    description: 'Throws an error for testing exception handling and filters',
+  })
+  @ApiResponse('500', {
+    description: 'Internal server error',
+    content: {
+      'application/json': {
+        schema: {
+          type: 'object',
+          properties: {
+            message: {
+              type: 'string',
+              example: 'This is a test error for exception handling',
+            },
+          },
+        },
+      },
+    },
+  })
   throwError() {
     throw new Error('This is a test error for exception handling');
   }

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

@@ -2,11 +2,11 @@ import { Module } from '@hestjs/core';
 import { CqrsModule } from '@hestjs/cqrs';
 import { AppController } from './app.controller';
 import { AppService } from './app.service';
-import { UserModule } from './users';
+import { UserController, UserModule } from './users';
 
 @Module({
   imports: [CqrsModule.forRoot(), UserModule],
-  controllers: [AppController],
+  controllers: [AppController, UserController],
   providers: [AppService],
 })
 export class AppModule {}

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

@@ -19,13 +19,12 @@ export class ResponseInterceptor implements Interceptor {
     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`,
+      `🚀 Response: ${request.method} ${request.url} - ${duration}ms`,
     );
 
     return {

package/templates/cqrs_scalar/src/index.ts

@@ -1,7 +1,7 @@
 import { HestFactory, logger } from '@hestjs/core';
+import '@hestjs/scalar'; // 导入scalar扩展
 import { ValidationInterceptor } from '@hestjs/validation';
 import { cors } from 'hono/cors';
-import { logger as log } from 'hono/logger';
 import { AppModule } from './app.module';
 import { HttpExceptionFilter } from './common/filters/http-exception.filter';
 import { ResponseInterceptor } from './common/interceptors/response.interceptor';
@@ -12,7 +12,7 @@ async function bootstrap() {
 
     const app = await HestFactory.create(AppModule);
     app.hono().use(cors()); // 使用 Hono 的 CORS 中间件
-    app.hono().use('*', log()); // 使用 Hono 的日志中间件
+    // app.hono().use('*', log()); // 使用 Hono 的日志中间件
 
     // 全局拦截器 - 验证拦截器应该在响应拦截器之前
     app.useGlobalInterceptors(new ValidationInterceptor());
@@ -21,6 +21,60 @@ async function bootstrap() {
     // 全局异常过滤器
     app.useGlobalFilters(new HttpExceptionFilter());
 
+    // 设置OpenAPI规范端点
+    app.useSwagger(
+      {
+        info: {
+          title: 'HestJS CQRS Demo API',
+          version: '1.0.0',
+          description:
+            'A demonstration of HestJS CQRS framework capabilities with Scalar API documentation (Auto-discovered controllers)',
+        },
+        servers: [
+          {
+            url: 'http://localhost:3002',
+            description: 'Development server',
+          },
+        ],
+      },
+      {
+        path: '/docs',
+        theme: 'elysia', // 使用elysia主题
+        enableMarkdown: true,
+        markdownPath: '/api-docs.md',
+      },
+    );
+
+    // 可选：仍然支持手动指定控制器的方式
+    // app.useScalarWithControllers(
+    //   [AppController, UserController], // 传入需要生成文档的控制器
+    //   {
+    //     info: {
+    //       title: 'HestJS CQRS Demo API',
+    //       version: '1.0.0',
+    //       description:
+    //         'A demonstration of HestJS CQRS 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');
+
     const server = Bun.serve({
       port: 3002,
       fetch: app.hono().fetch,

package/templates/cqrs_scalar/src/users/repositories/user.repository.ts

@@ -4,7 +4,46 @@ import { User, CreateUserData, UpdateUserData } from '../entities';
 @Injectable()
 export class UserRepository {
   private users: Map<string, User> = new Map();
-  private nextId = 1;
+  private nextId = 4; // 从4开始，因为我们预填充了3个用户
+
+  constructor() {
+    // 初始化一些 mock 数据
+    this.initializeMockData();
+  }
+
+  private initializeMockData() {
+    const mockUsers: User[] = [
+      {
+        id: '1',
+        name: 'Alice Johnson',
+        email: 'alice@example.com',
+        age: 28,
+        createdAt: new Date('2024-01-15T08:30:00Z'),
+        updatedAt: new Date('2024-01-15T08:30:00Z'),
+      },
+      {
+        id: '2',
+        name: 'Bob Smith',
+        email: 'bob@example.com',
+        age: 32,
+        createdAt: new Date('2024-01-16T10:15:00Z'),
+        updatedAt: new Date('2024-01-16T10:15:00Z'),
+      },
+      {
+        id: '3',
+        name: 'Charlie Brown',
+        email: 'charlie@example.com',
+        age: 25,
+        createdAt: new Date('2024-01-17T14:20:00Z'),
+        updatedAt: new Date('2024-01-17T14:20:00Z'),
+      },
+    ];
+
+    // 将 mock 数据添加到内存存储中
+    mockUsers.forEach(user => {
+      this.users.set(user.id, user);
+    });
+  }
 
   async create(userData: CreateUserData): Promise<User> {
     const id = this.nextId.toString();

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

@@ -1,11 +1,19 @@
-import { Controller, Get, Post, Put, Context } from '@hestjs/core';
 import type { HestContext } from '@hestjs/core';
+import { Context, Controller, Get, Post, Put } from '@hestjs/core';
 import { CommandBus, QueryBus } from '@hestjs/cqrs';
+import {
+  ApiBody,
+  ApiOperation,
+  ApiParam,
+  ApiResponse,
+  ApiTags,
+} from '@hestjs/scalar';
 import { CreateUserCommand, UpdateUserCommand } from './commands';
 import { CreateUserData, UpdateUserData } from './entities';
 import { GetAllUsersQuery, GetUserQuery } from './queries';
 
 @Controller('/users')
+@ApiTags('Users')
 export class UserController {
   constructor(
     private readonly commandBus: CommandBus,
@@ -13,6 +21,85 @@ export class UserController {
   ) {}
 
   @Post('/')
+  @ApiOperation({
+    summary: 'Create a new user',
+    description: 'Creates a new user using CQRS pattern with command bus',
+  })
+  @ApiBody(
+    {
+      'application/json': {
+        schema: {
+          type: 'object',
+          required: ['name', 'email'],
+          properties: {
+            name: {
+              type: 'string',
+              example: 'John Doe',
+              description: 'User full name',
+            },
+            email: {
+              type: 'string',
+              format: 'email',
+              example: 'john@example.com',
+              description: 'User email address',
+            },
+            age: {
+              type: 'number',
+              example: 25,
+              description: 'User age (optional)',
+              minimum: 0,
+              maximum: 150,
+            },
+          },
+        },
+      },
+    },
+    {
+      description: 'User creation data',
+      required: true,
+    },
+  )
+  @ApiResponse('201', {
+    description: 'User created successfully',
+    content: {
+      'application/json': {
+        schema: {
+          type: 'object',
+          properties: {
+            success: { type: 'boolean', example: true },
+            data: {
+              type: 'object',
+              properties: {
+                id: { type: 'string', example: '1' },
+                name: { type: 'string', example: 'John Doe' },
+                email: { type: 'string', example: 'john@example.com' },
+                age: { type: 'number', example: 25 },
+                createdAt: { type: 'string', format: 'date-time' },
+                updatedAt: { type: 'string', format: 'date-time' },
+              },
+            },
+          },
+        },
+      },
+    },
+  })
+  @ApiResponse('400', {
+    description: 'Invalid input data',
+    content: {
+      'application/json': {
+        schema: {
+          type: 'object',
+          properties: {
+            success: { type: 'boolean', example: false },
+            error: {
+              type: 'string',
+              example: 'Name and email are required',
+            },
+          },
+        },
+      },
+    },
+  })
   async createUser(@Context() c: HestContext) {
     const userData = await c.req.json<CreateUserData>();
 
@@ -25,16 +112,69 @@ export class UserController {
     }
 
     const user = await this.commandBus.execute(new CreateUserCommand(userData));
-    return c.json({ success: true, data: user }, 201);
+    // 直接返回数据，让拦截器处理响应格式
+    // 注意：这里我们无法通过拦截器设置状态码为201，如果需要可以抛出特殊异常或使用其他方式
+    return user;
   }
 
   @Get('/')
-  async getAllUsers(@Context() c: HestContext) {
+  async getAllUsers() {
+    
+    // 使用查询总线获取所有用户
     const result = await this.queryBus.execute(new GetAllUsersQuery());
-    return c.json({ success: true, data: result.users });
+    
+    // 直接返回数据，让拦截器处理响应格式
+    return result.users;
   }
 
   @Get('/:id')
+  @ApiOperation({
+    summary: 'Get user by ID',
+    description: 'Retrieves a specific user by their ID using CQRS pattern',
+  })
+  @ApiParam('id', {
+    description: 'User unique identifier',
+    schema: { type: 'string' },
+    example: '1',
+  })
+  @ApiResponse('200', {
+    description: 'User found successfully',
+    content: {
+      'application/json': {
+        schema: {
+          type: 'object',
+          properties: {
+            success: { type: 'boolean', example: true },
+            data: {
+              type: 'object',
+              properties: {
+                id: { type: 'string', example: '1' },
+                name: { type: 'string', example: 'John Doe' },
+                email: { type: 'string', example: 'john@example.com' },
+                age: { type: 'number', example: 25 },
+                createdAt: { type: 'string', format: 'date-time' },
+                updatedAt: { type: 'string', format: 'date-time' },
+              },
+            },
+          },
+        },
+      },
+    },
+  })
+  @ApiResponse('404', {
+    description: 'User not found',
+    content: {
+      'application/json': {
+        schema: {
+          type: 'object',
+          properties: {
+            success: { type: 'boolean', example: false },
+            error: { type: 'string', example: 'User not found' },
+          },
+        },
+      },
+    },
+  })
   async getUserById(@Context() c: HestContext) {
     const id = c.req.param('id');
     const result = await this.queryBus.execute(new GetUserQuery(id));
@@ -43,10 +183,108 @@ export class UserController {
       return c.json({ success: false, error: 'User not found' }, 404);
     }
 
-    return c.json({ success: true, data: result.user });
+    // 直接返回数据，让拦截器处理响应格式
+    return result.user;
   }
 
   @Put('/:id')
+  @ApiOperation({
+    summary: 'Update user by ID',
+    description: 'Updates an existing user using CQRS pattern with command bus',
+  })
+  @ApiParam('id', {
+    description: 'User unique identifier',
+    schema: { type: 'string' },
+    example: '1',
+  })
+  @ApiBody(
+    {
+      'application/json': {
+        schema: {
+          type: 'object',
+          properties: {
+            name: {
+              type: 'string',
+              example: 'Jane Doe',
+              description: 'User full name (optional)',
+            },
+            email: {
+              type: 'string',
+              format: 'email',
+              example: 'jane@example.com',
+              description: 'User email address (optional)',
+            },
+            age: {
+              type: 'number',
+              example: 30,
+              description: 'User age (optional)',
+              minimum: 0,
+              maximum: 150,
+            },
+          },
+        },
+      },
+    },
+    {
+      description: 'User update data (all fields are optional)',
+      required: true,
+    },
+  )
+  @ApiResponse('200', {
+    description: 'User updated successfully',
+    content: {
+      'application/json': {
+        schema: {
+          type: 'object',
+          properties: {
+            success: { type: 'boolean', example: true },
+            data: {
+              type: 'object',
+              properties: {
+                id: { type: 'string', example: '1' },
+                name: { type: 'string', example: 'Jane Doe' },
+                email: { type: 'string', example: 'jane@example.com' },
+                age: { type: 'number', example: 30 },
+                createdAt: { type: 'string', format: 'date-time' },
+                updatedAt: { type: 'string', format: 'date-time' },
+              },
+            },
+          },
+        },
+      },
+    },
+  })
+  @ApiResponse('404', {
+    description: 'User not found',
+    content: {
+      'application/json': {
+        schema: {
+          type: 'object',
+          properties: {
+            success: { type: 'boolean', example: false },
+            error: { type: 'string', example: 'User not found' },
+          },
+        },
+      },
+    },
+  })
+  @ApiResponse('500', {
+    description: 'Internal server error',
+    content: {
+      'application/json': {
+        schema: {
+          type: 'object',
+          properties: {
+            success: { type: 'boolean', example: false },
+            error: {
+              type: 'string',
+              example: 'An error occurred while updating the user',
+            },
+          },
+        },
+      },
+    },
+  })
   async updateUser(@Context() c: HestContext) {
     const id = c.req.param('id');
     const userData = await c.req.json<UpdateUserData>();
@@ -55,7 +293,8 @@ export class UserController {
       const user = await this.commandBus.execute(
         new UpdateUserCommand(id, userData),
       );
-      return c.json({ success: true, data: user });
+      // 直接返回数据，让拦截器处理响应格式
+      return user;
     } catch (error) {
       if (error instanceof Error && error.message.includes('not found')) {
         return c.json({ success: false, error: 'User not found' }, 404);