create-dp-koa 1.0.0

package/template/src/controllers/example/SwaggerExampleController.ts

@@ -0,0 +1,205 @@
+import { Get, Post, Put, Del, Body, Query, Params } from '@src/framework/decorator/controller';
+import { BaseController } from '@src/controllers/base.controller';
+import { Api, ApiTags, ApiResponse, ApiBody, ApiParam } from '@src/framework/decorator/swagger';
+import { logger } from '@src/framework/utils/logger';
+
+/**
+ * Swagger示例控制器 - 展示完整的Swagger注解用法
+ */
+@ApiTags('Swagger示例', 'API文档完整示例')
+export class SwaggerExampleController extends BaseController {
+    
+    /**
+     * GET请求 - 带查询参数
+     */
+    @Get('/user/list')
+    @Api({
+        tags: ['用户管理'],
+        summary: '获取用户列表',
+        description: '根据查询参数获取用户列表',
+        operationId: 'getUserList',
+    })
+    @ApiResponse({
+        status: 200,
+        description: '成功返回用户列表',
+        schema: {
+            type: 'object',
+            properties: {
+                code: { type: 'number', example: 0 },
+                data: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            id: { type: 'number' },
+                            name: { type: 'string' },
+                            email: { type: 'string' },
+                        },
+                    },
+                },
+                message: { type: 'string' },
+            },
+        },
+    })
+    async getUserList(@Query() query: { page: number; pageSize: number; keyword?: string }) {
+        return this.success({
+            users: [
+                { id: 1, name: '张三', email: 'zhang@example.com' },
+                { id: 2, name: '李四', email: 'li@example.com' },
+            ],
+            total: 2,
+            page: query.page || 1,
+            pageSize: query.pageSize || 10,
+        }, '获取用户列表成功');
+    }
+    
+    /**
+     * GET请求 - 带路径参数
+     */
+    @Get('/user/:id')
+    @Api({
+        tags: ['用户管理'],
+        summary: '获取用户详情',
+        description: '根据用户ID获取用户详细信息',
+    })
+    @ApiResponse({
+        status: 200,
+        description: '成功返回用户详情',
+    })
+    @ApiResponse({
+        status: 404,
+        description: '用户不存在',
+    })
+    async getUserById(@Params() params: { id: number }) {
+        return this.success({
+            id: params.id,
+            name: '张三',
+            email: 'zhang@example.com',
+            avatar: 'https://example.com/avatar.jpg',
+        }, '获取用户详情成功');
+    }
+    
+    /**
+     * POST请求 - 带请求体
+     */
+    @Post('/user')
+    @Api({
+        tags: ['用户管理'],
+        summary: '创建新用户',
+        description: '创建新用户并返回用户信息',
+    })
+    @ApiBody({
+        description: '用户信息',
+        required: true,
+        schema: {
+            type: 'object',
+            required: ['name', 'email'],
+            properties: {
+                name: { type: 'string', description: '用户名', example: '张三' },
+                email: { type: 'string', format: 'email', description: '邮箱', example: 'zhang@example.com' },
+                age: { type: 'number', description: '年龄', example: 25 },
+            },
+        },
+        examples: {
+            example1: {
+                summary: '示例数据1',
+                value: {
+                    name: '张三',
+                    email: 'zhang@example.com',
+                    age: 25,
+                },
+            },
+        },
+    })
+    @ApiResponse({
+        status: 200,
+        description: '成功创建用户',
+        schema: {
+            type: 'object',
+            properties: {
+                code: { type: 'number' },
+                data: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'number' },
+                        name: { type: 'string' },
+                        email: { type: 'string' },
+                    },
+                },
+                message: { type: 'string' },
+            },
+        },
+    })
+    @ApiResponse({
+        status: 400,
+        description: '参数验证失败',
+    })
+    async createUser(@Body() body: { name: string; email: string; age?: number }) {
+        return this.success({
+            id: Math.floor(Math.random() * 1000),
+            name: body.name,
+            email: body.email,
+            age: body.age,
+        }, '创建用户成功');
+    }
+    
+    /**
+     * PUT请求 - 更新资源
+     */
+    @Put('/user/:id')
+    @Api({
+        tags: ['用户管理'],
+        summary: '更新用户信息',
+        description: '根据用户ID更新用户信息',
+    })
+    @ApiBody({
+        description: '更新的用户信息',
+        required: true,
+        schema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: '用户名' },
+                email: { type: 'string', format: 'email', description: '邮箱' },
+                age: { type: 'number', description: '年龄' },
+            },
+        },
+    })
+    @ApiResponse({
+        status: 200,
+        description: '成功更新用户信息',
+    })
+    @ApiResponse({
+        status: 404,
+        description: '用户不存在',
+    })
+    async updateUser(@Params() params: { id: number }, @Body() body: { name?: string; email?: string; age?: number }) {
+        return this.success({
+            id: params.id,
+            ...body,
+        }, '更新用户成功');
+    }
+    
+    /**
+     * DELETE请求 - 删除资源
+     */
+    @Del('/user/:id')
+    @Api({
+        tags: ['用户管理'],
+        summary: '删除用户',
+        description: '根据用户ID删除用户',
+    })
+    @ApiResponse({
+        status: 200,
+        description: '成功删除用户',
+    })
+    @ApiResponse({
+        status: 404,
+        description: '用户不存在',
+    })
+    async deleteUser(@Params() params: { id: number }) {
+        logger.debug('🔍 deleteUser 方法被调用');
+        logger.debug('📋 参数:', params);
+        return this.success(null, '删除用户成功');
+    }
+}
+

package/template/src/controllers/example/TransactionExample.controller.ts

@@ -0,0 +1,336 @@
+/**
+ * 事务管理器使用示例控制器
+ * 演示在实际 API 中如何使用 TransactionManager
+ */
+
+import { Post, Get, Put, Del } from '@src/framework/decorator/controller';
+import { Context } from 'koa';
+import { transactionManager } from '@src/framework/utils/TransactionManager';
+import { YtUserEntity } from '@src/entity/ytUser.entity';
+import { logger } from '@src/framework/utils/logger';
+import * as bcrypt from 'bcryptjs';
+
+export class TransactionExampleController {
+
+    /**
+     * 示例 1: 基本事务 - 创建用户
+     * POST /api/example/transaction/create-user
+     */
+    @Post('/create-user')
+    async createUser(ctx: Context) {
+        const { email, telnumber, password } = ctx.request.body;
+
+        try {
+            const result = await transactionManager.executeInTransaction(async (manager) => {
+                // 检查用户是否已存在
+                const existingUser = await manager.findOne(YtUserEntity, {
+                    where: [{ email }, { telnumber }] as any
+                });
+
+                if (existingUser) {
+                    throw new Error('用户已存在');
+                }
+
+                // 创建新用户
+                const user = new YtUserEntity();
+                user.email = email;
+                user.telnumber = telnumber;
+                user.password = await bcrypt.hash(password, 10);
+                user.createDate = new Date();
+                user.updateDate = new Date();
+
+                return await manager.save(user);
+            });
+
+            ctx.body = {
+                success: true,
+                message: '用户创建成功',
+                data: result
+            };
+            ctx.status = 200;
+
+        } catch (error) {
+            logger.error('创建用户失败:', error as Error);
+            ctx.body = {
+                success: false,
+                message: error instanceof Error ? error.message : '创建用户失败',
+                error: '事务已回滚'
+            };
+            ctx.status = 500;
+        }
+    }
+
+    /**
+     * 示例 2: 更新用户信息（使用隔离级别）
+     * PUT /api/example/transaction/update-user/:id
+     */
+    @Put('/update-user/:id')
+    async updateUser(ctx: Context) {
+        const id = parseInt(ctx.params.id);
+        const { email, telnumber } = ctx.request.body;
+
+        try {
+            const result = await transactionManager.executeInTransaction(
+                async (manager) => {
+                    // 查找用户
+                    const user = await manager.findOne(YtUserEntity, {
+                        where: { id } as any
+                    });
+
+                    if (!user) {
+                        throw new Error('用户不存在');
+                    }
+
+                    // 更新用户信息
+                    if (email) {
+                        // 检查邮箱是否被其他用户使用
+                        const existingUser = await manager.findOne(YtUserEntity, {
+                            where: { email } as any
+                        });
+                        if (existingUser && existingUser.id !== id) {
+                            throw new Error('邮箱已被其他用户使用');
+                        }
+                        user.email = email;
+                    }
+
+                    if (telnumber) {
+                        // 检查手机号是否被其他用户使用
+                        const existingUser = await manager.findOne(YtUserEntity, {
+                            where: { telnumber } as any
+                        });
+                        if (existingUser && existingUser.id !== id) {
+                            throw new Error('手机号已被其他用户使用');
+                        }
+                        user.telnumber = telnumber;
+                    }
+
+                    user.updateDate = new Date();
+                    return await manager.save(user);
+                },
+                'SERIALIZABLE' // 使用最高隔离级别，防止并发更新冲突
+            );
+
+            ctx.body = {
+                success: true,
+                message: '用户更新成功',
+                data: result
+            };
+            ctx.status = 200;
+
+        } catch (error) {
+            logger.error('更新用户失败:', error as Error);
+            ctx.body = {
+                success: false,
+                message: error instanceof Error ? error.message : '更新用户失败',
+                error: '事务已回滚'
+            };
+            ctx.status = 500;
+        }
+    }
+
+    /**
+     * 示例 3: 批量创建用户
+     * POST /api/example/transaction/batch-create
+     */
+    @Post('/batch-create')
+    async batchCreateUsers(ctx: Context) {
+        const { users } = ctx.request.body; // [{ email, telnumber, password }, ...]
+
+        try {
+            const operations = users.map((userData: any) => {
+                return async (manager: any) => {
+                    // 验证数据
+                    if (!userData.email || !userData.password) {
+                        throw new Error('邮箱和密码不能为空');
+                    }
+
+                    // 加密密码
+                    const hashedPassword = await bcrypt.hash(userData.password, 10);
+
+                    // 创建用户
+                    const user = new YtUserEntity();
+                    user.email = userData.email;
+                    user.telnumber = userData.telnumber;
+                    user.password = hashedPassword;
+                    user.createDate = new Date();
+                    user.updateDate = new Date();
+
+                    return await manager.save(user);
+                };
+            });
+
+            const results = await transactionManager.executeBatchTransaction(operations);
+
+            ctx.body = {
+                success: true,
+                message: `成功创建 ${results.length} 个用户`,
+                data: results
+            };
+            ctx.status = 200;
+
+        } catch (error) {
+            logger.error('批量创建用户失败:', error as Error);
+            ctx.body = {
+                success: false,
+                message: '批量创建用户失败，所有更改已回滚',
+                error: error instanceof Error ? error.message : '未知错误'
+            };
+            ctx.status = 500;
+        }
+    }
+
+    /**
+     * 示例 4: 删除用户（演示事务回滚）
+     * DELETE /api/example/transaction/delete-user/:id
+     */
+    @Del('/delete-user/:id')
+    async deleteUser(ctx: Context) {
+        const id = parseInt(ctx.params.id);
+
+        try {
+            await transactionManager.executeInTransaction(async (manager) => {
+                // 查找用户
+                const user = await manager.findOne(YtUserEntity, {
+                    where: { id } as any
+                });
+
+                if (!user) {
+                    throw new Error('用户不存在');
+                }
+
+                // 模拟业务规则：不允许删除管理员用户
+                if (user.userType && String(user.userType) === 'admin') {
+                    throw new Error('不能删除管理员用户');
+                }
+
+                // 删除用户
+                await manager.remove(user);
+
+                // 模拟额外操作（如果有的话）
+                // await manager.save(DeleteLog, { userId: id });
+            });
+
+            ctx.body = {
+                success: true,
+                message: '用户删除成功'
+            };
+            ctx.status = 200;
+
+        } catch (error) {
+            logger.error('删除用户失败:', error as Error);
+            ctx.body = {
+                success: false,
+                message: error instanceof Error ? error.message : '删除用户失败',
+                error: '事务已回滚'
+            };
+            ctx.status = 500;
+        }
+    }
+
+    /**
+     * 示例 5: 查询统计（使用只读事务）
+     * GET /api/example/transaction/stats
+     */
+    @Get('/stats')
+    async getStats(ctx: Context) {
+        try {
+            const stats = await transactionManager.executeInReadOnlyTransaction(async (manager) => {
+                // 只读事务，不会产生任何写操作
+                const totalUsers = await manager.count(YtUserEntity);
+                const activeUsers = await manager.count(YtUserEntity, {
+                    where: { status: 'normal' } as any
+                });
+
+                const users = await manager.find(YtUserEntity, {
+                    take: 10,
+                    order: { createDate: 'DESC' } as any
+                });
+
+                return {
+                    total: totalUsers,
+                    active: activeUsers,
+                    inactive: totalUsers - activeUsers,
+                    recentUsers: users
+                };
+            });
+
+            ctx.body = {
+                success: true,
+                data: stats
+            };
+            ctx.status = 200;
+
+        } catch (error) {
+            logger.error('获取统计信息失败:', error as Error);
+            ctx.body = {
+                success: false,
+                message: '获取统计信息失败'
+            };
+            ctx.status = 500;
+        }
+    }
+
+    /**
+     * 示例 6: 复杂业务场景 - 用户迁移
+     * POST /api/example/transaction/migrate-user
+     */
+    @Post('/migrate-user')
+    async migrateUser(ctx: Context) {
+        const { fromUserId, toEmail } = ctx.request.body;
+
+        try {
+            const result = await transactionManager.executeInTransaction(async (manager) => {
+                // 步骤 1: 查找原用户
+                const fromUser = await manager.findOne(YtUserEntity, {
+                    where: { id: fromUserId } as any
+                });
+
+                if (!fromUser) {
+                    throw new Error('原用户不存在');
+                }
+
+                // 步骤 2: 检查新邮箱是否已使用
+                const existingUser = await manager.findOne(YtUserEntity, {
+                    where: { email: toEmail } as any
+                });
+
+                if (existingUser) {
+                    throw new Error('新邮箱已被使用');
+                }
+
+                // 步骤 3: 创建新用户（复制数据）
+                const newUser = new YtUserEntity();
+                newUser.email = toEmail;
+                newUser.telnumber = fromUser.telnumber;
+                newUser.password = fromUser.password;
+                newUser.createDate = new Date();
+                newUser.updateDate = new Date();
+                const savedNewUser = await manager.save(newUser);
+
+                // 步骤 4: 删除原用户
+                await manager.remove(fromUser);
+
+                return {
+                    oldUser: fromUser,
+                    newUser: savedNewUser
+                };
+            });
+
+            ctx.body = {
+                success: true,
+                message: '用户迁移成功',
+                data: result
+            };
+            ctx.status = 200;
+
+        } catch (error) {
+            logger.error('用户迁移失败:', error as Error);
+            ctx.body = {
+                success: false,
+                message: error instanceof Error ? error.message : '用户迁移失败',
+                error: '所有操作已回滚'
+            };
+            ctx.status = 500;
+        }
+    }
+}