create-dp-koa 1.0.1 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-dp-koa",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Scaffold a DP-Koa framework project from the official template",
   "type": "module",
   "bin": {

package/template/.cursor/commands/cheatsheet-backend-controller.md

@@ -38,8 +38,8 @@
 - 入参 DTO 应放在哪个目录、命名建议
 - Service 方法签名建议（含返回类型）
 
-【对齐的项目样例（必须列出）】
-- 列出你参考的文件路径（至少 2 个）
+【对齐的参考来源（必须列出）】
+- 至少列出 **`11-backend-controller-recipes.skill.md` 内嵌示例**中的 2 个小节编号（例如 1.1.2、1.1.4）；若同时参考了仓库内 `src/controllers/base.controller.ts` 或 `src/controllers/example/*`，可一并写出路径
 ```
 
 

package/template/.cursor/commands/implement-backend-api-controller.md

@@ -50,9 +50,11 @@
 ---
 
 ## 写代码前的对齐动作（必须）
-- 在生成/修改 Controller 代码前，先对齐本项目示例写法：
-  - `src/controllers/example/NewAnnotationExampleController.ts`
-  - `src/controllers/home/ytUser.controller.ts`
-  - `src/controllers/base.controller.ts`
+- 在生成/修改 Controller 代码前，先对齐 **`11-backend-controller-recipes.skill.md` 内嵌示例**（章节 **1.1**），重点核对：
+  - **1.1.1** `BaseController` / `ControllerResponse` 与 `success` / `fail` 用法
+  - **1.1.2** `@State()` 读取整段 `ctx.state`
+  - **1.1.3** `@State('user')` 只读 `ctx.state.user`
+  - **1.1.4** `@ResponseValidateIf` 条件响应校验
+- 若仓库中仍存在 `src/controllers/base.controller.ts` 或 `src/controllers/example/*`，可作为**补充**对照（以实现代码为准）。
 
 

package/template/.cursor/rules/11-backend-controller-recipes.skill.md

@@ -12,11 +12,91 @@ alwaysApply: false
 
 ## 一、写 Controller 的推荐范式（必须对齐）
 
-### 1.1 参考样例（写代码前先对齐）
-- 推荐在实现前先对齐以下文件的写法（不要臆造新风格）：
-  - `src/controllers/example/NewAnnotationExampleController.ts`
-  - `src/controllers/home/ytUser.controller.ts`
-  - `src/controllers/base.controller.ts`
+### 1.1 内嵌参考样例（本 Skill 自包含）
+以下为从本项目常用写法整理的最小示例；**实现新接口时请先对齐本节的装饰器与类型风格**。若仓库中另有 `src/controllers/example/*` 等运行时代码，可作为补充参考，但**不必依赖**特定业务 Controller 文件是否存在。
+
+#### 1.1.1 `BaseController` 与 `ControllerResponse`（统一响应）
+
+```ts
+export class ControllerResponse<T> {
+  code = 0;
+  data: T | null = null;
+  message = '';
+
+  constructor(code: number, data: T | null, message?: string) {
+    this.code = code;
+    this.data = data;
+    if (message) this.message = message;
+  }
+}
+
+export class BaseController {
+  success<T>(data: T, message?: string) {
+    return new ControllerResponse<T>(0, data, message);
+  }
+  fail<T>(code: number, message?: string) {
+    return new ControllerResponse<T>(code, null, message);
+  }
+}
+```
+
+#### 1.1.2 `@State()`：读取整段 `ctx.state`
+
+```ts
+import { Get, State } from '@src/framework/decorator/controller';
+import { BaseController, ControllerResponse } from '@src/controllers/base.controller';
+
+export class ExampleStateController extends BaseController {
+  @Get('/example/state-full')
+  async getWithFullState(
+    @State() state: { user: { userId: number; type?: number } },
+  ): Promise<ControllerResponse<{ userId: number }>> {
+    return this.success({ userId: state.user.userId });
+  }
+}
+```
+
+#### 1.1.3 `@State('user')`：只读 `ctx.state.user`
+
+```ts
+import { Get, State } from '@src/framework/decorator/controller';
+import { BaseController, ControllerResponse } from '@src/controllers/base.controller';
+
+export class ExampleUserSliceController extends BaseController {
+  @Get('/example/state-user')
+  async getWithUser(
+    @State('user') user: { userId: number; type?: number },
+  ): Promise<ControllerResponse<{ ok: boolean }>> {
+    return this.success({ ok: user.userId > 0 });
+  }
+}
+```
+
+#### 1.1.4 `@ResponseValidateIf`：仅在条件成立时校验响应体
+
+```ts
+import { Get, State, ResponseValidateIf } from '@src/framework/decorator/controller';
+import { BaseController, ControllerResponse } from '@src/controllers/base.controller';
+
+// 示例 DTO：按实际接口替换
+class UserProfileResponseDto {
+  id!: number;
+  nickName!: string;
+}
+
+export class ExampleResponseValidateController extends BaseController {
+  @ResponseValidateIf(UserProfileResponseDto, (data) => Boolean(data && data.data))
+  @Get('/example/profile')
+  async getProfile(
+    @State() state: { user: { userId: number } },
+  ): Promise<ControllerResponse<UserProfileResponseDto | null>> {
+    return this.success({
+      id: state.user.userId,
+      nickName: 'demo',
+    });
+  }
+}
+```
 
 ### 1.2 Controller 标准骨架（复制这个结构）
 目标：DTO 入参 → 调用 Service → 统一响应（`success/fail`）→ try/catch + logger
@@ -76,10 +156,10 @@ export class SomeController extends BaseController {
   - 读取 body 参数
   - 推荐写法：`@Body(SomeBodyDto) body: XxxBodyDto`
 - **`@State()`**：
-  - 读取整个 `ctx.state`（样例：`ytUser.controller.ts`）
+  - 读取整个 `ctx.state`（样例：见 **1.1.2**）
   - 推荐写法：`@State() state: { user: { userId: number; type?: number } }`
 - **`@State('user')`**：
-  - 读取 `ctx.state.user`（样例：`NewAnnotationExampleController.ts`）
+  - 读取 `ctx.state.user`（样例：见 **1.1.3**）
   - 推荐写法：`@State('user') user: { userId: number; type?: number }`
 
 禁止：
@@ -91,7 +171,7 @@ export class SomeController extends BaseController {
 
 ### 2.4 响应校验注解（进阶，按需）
 - **`@ResponseValidator(DtoClass, objectKey?)`**：对响应数据做校验
-- **`@ResponseValidateIf(DtoClass, fn)`**：仅当 fn 返回真时才校验（样例：`ytUser.controller.ts`）
+- **`@ResponseValidateIf(DtoClass, fn)`**：仅当 fn 返回真时才校验（样例：见 **1.1.4**）
 
 ---
 
@@ -101,9 +181,8 @@ export class SomeController extends BaseController {
 - `@Get('/xxx') + @State('user')`（或 `@State()` 取整段 state）
 
 ### 3.2 带 body 的 POST 接口
-- `@Post('/xxx') + @Body(SomeBodyDto) body: DtSomeBodyDtoo + @ResponseCode(201)`
+- `@Post('/xxx') + @Body(SomeBodyDto) body: SomeBodyDto + @ResponseCode(201)`
 
 ### 3.3 需要自定义 header
 - `@ResponseHeader('X-XXX', 'value')`
 
-

package/template/.trae/skills/11-backend-controller-recipes.skill.md

@@ -12,11 +12,91 @@ alwaysApply: false
 
 ## 一、写 Controller 的推荐范式（必须对齐）
 
-### 1.1 参考样例（写代码前先对齐）
-- 推荐在实现前先对齐以下文件的写法（不要臆造新风格）：
-  - `src/controllers/example/NewAnnotationExampleController.ts`
-  - `src/controllers/home/ytUser.controller.ts`
-  - `src/controllers/base.controller.ts`
+### 1.1 内嵌参考样例（本 Skill 自包含）
+以下为从本项目常用写法整理的最小示例；**实现新接口时请先对齐本节的装饰器与类型风格**。若仓库中另有 `src/controllers/example/*` 等运行时代码，可作为补充参考，但**不必依赖**特定业务 Controller 文件是否存在。
+
+#### 1.1.1 `BaseController` 与 `ControllerResponse`（统一响应）
+
+```ts
+export class ControllerResponse<T> {
+  code = 0;
+  data: T | null = null;
+  message = '';
+
+  constructor(code: number, data: T | null, message?: string) {
+    this.code = code;
+    this.data = data;
+    if (message) this.message = message;
+  }
+}
+
+export class BaseController {
+  success<T>(data: T, message?: string) {
+    return new ControllerResponse<T>(0, data, message);
+  }
+  fail<T>(code: number, message?: string) {
+    return new ControllerResponse<T>(code, null, message);
+  }
+}
+```
+
+#### 1.1.2 `@State()`：读取整段 `ctx.state`
+
+```ts
+import { Get, State } from '@src/framework/decorator/controller';
+import { BaseController, ControllerResponse } from '@src/controllers/base.controller';
+
+export class ExampleStateController extends BaseController {
+  @Get('/example/state-full')
+  async getWithFullState(
+    @State() state: { user: { userId: number; type?: number } },
+  ): Promise<ControllerResponse<{ userId: number }>> {
+    return this.success({ userId: state.user.userId });
+  }
+}
+```
+
+#### 1.1.3 `@State('user')`：只读 `ctx.state.user`
+
+```ts
+import { Get, State } from '@src/framework/decorator/controller';
+import { BaseController, ControllerResponse } from '@src/controllers/base.controller';
+
+export class ExampleUserSliceController extends BaseController {
+  @Get('/example/state-user')
+  async getWithUser(
+    @State('user') user: { userId: number; type?: number },
+  ): Promise<ControllerResponse<{ ok: boolean }>> {
+    return this.success({ ok: user.userId > 0 });
+  }
+}
+```
+
+#### 1.1.4 `@ResponseValidateIf`：仅在条件成立时校验响应体
+
+```ts
+import { Get, State, ResponseValidateIf } from '@src/framework/decorator/controller';
+import { BaseController, ControllerResponse } from '@src/controllers/base.controller';
+
+// 示例 DTO：按实际接口替换
+class UserProfileResponseDto {
+  id!: number;
+  nickName!: string;
+}
+
+export class ExampleResponseValidateController extends BaseController {
+  @ResponseValidateIf(UserProfileResponseDto, (data) => Boolean(data && data.data))
+  @Get('/example/profile')
+  async getProfile(
+    @State() state: { user: { userId: number } },
+  ): Promise<ControllerResponse<UserProfileResponseDto | null>> {
+    return this.success({
+      id: state.user.userId,
+      nickName: 'demo',
+    });
+  }
+}
+```
 
 ### 1.2 Controller 标准骨架（复制这个结构）
 目标：DTO 入参 → 调用 Service → 统一响应（`success/fail`）→ try/catch + logger
@@ -76,10 +156,10 @@ export class SomeController extends BaseController {
   - 读取 body 参数
   - 推荐写法：`@Body(SomeBodyDto) body: XxxBodyDto`
 - **`@State()`**：
-  - 读取整个 `ctx.state`（样例：`ytUser.controller.ts`）
+  - 读取整个 `ctx.state`（样例：见 **1.1.2**）
   - 推荐写法：`@State() state: { user: { userId: number; type?: number } }`
 - **`@State('user')`**：
-  - 读取 `ctx.state.user`（样例：`NewAnnotationExampleController.ts`）
+  - 读取 `ctx.state.user`（样例：见 **1.1.3**）
   - 推荐写法：`@State('user') user: { userId: number; type?: number }`
 
 禁止：
@@ -91,7 +171,7 @@ export class SomeController extends BaseController {
 
 ### 2.4 响应校验注解（进阶，按需）
 - **`@ResponseValidator(DtoClass, objectKey?)`**：对响应数据做校验
-- **`@ResponseValidateIf(DtoClass, fn)`**：仅当 fn 返回真时才校验（样例：`ytUser.controller.ts`）
+- **`@ResponseValidateIf(DtoClass, fn)`**：仅当 fn 返回真时才校验（样例：见 **1.1.4**）
 
 ---
 
@@ -101,7 +181,8 @@ export class SomeController extends BaseController {
 - `@Get('/xxx') + @State('user')`（或 `@State()` 取整段 state）
 
 ### 3.2 带 body 的 POST 接口
-- `@Post('/xxx') + @Body(SomeBodyDto) body: DtSomeBodyDtoo + @ResponseCode(201)`
+- `@Post('/xxx') + @Body(SomeBodyDto) body: SomeBodyDto + @ResponseCode(201)`
 
 ### 3.3 需要自定义 header
-- `@ResponseHeader('X-XXX', 'value')`
+- `@ResponseHeader('X-XXX', 'value')`
+

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

@@ -3,6 +3,20 @@ import { Logging, Permission, RateLimit } from '@src/framework/decorator/process
 import { PerformanceMonitor } from '@src/annotations/decorators/PerformanceMonitor';
 import { BaseController } from '@src/controllers/base.controller';
 import { Api, ApiTags, ApiResponse, ApiOperation } from '@src/framework/decorator/swagger';
+import { ProcessorManager } from '@src/framework/decorator/processor/ProcessorManager';
+import { LoggingProcessor, PermissionProcessor, RateLimitProcessor } from '@src/framework/decorator/processor/processors/CustomProcessors';
+import { logger } from '@src/framework/utils/logger';
+
+/**
+ * 测试/示例用：注册自定义注解处理器。
+ * 注意：此函数不会影响框架的默认初始化流程；只用于按需注册。
+ */
+export function initializeCustomProcessors(): void {
+    ProcessorManager.registerProcessor(new LoggingProcessor());
+    ProcessorManager.registerProcessor(new PermissionProcessor());
+    ProcessorManager.registerProcessor(new RateLimitProcessor());
+    logger.info('自定义注解处理器已注册');
+}
 
 /**
  * 示例控制器 - 展示新的注解系统用法

package/template/src/entity/index.ts

@@ -1,15 +1 @@
-import { GoodsImagesUnlockKeyEntity } from "@src/entity/goodsImagesUnlockKey.entity";
-import { YtGoodsUnlockerEntity } from "@src/entity/goodsUnlocker.entity";
-import { ShopEntity } from "@src/entity/shop.entity";
-import { ShopAndUserEntity } from "@src/entity/shopUser.entity";
-import { YtGoodsEntity } from "@src/entity/ytGoods.entity";
-import { YtUserEntity } from "@src/entity/ytUser.entity";
-
-export default [
-    YtUserEntity,
-    YtGoodsEntity,
-    YtGoodsUnlockerEntity,
-    GoodsImagesUnlockKeyEntity,
-    ShopEntity,
-    ShopAndUserEntity,
-]
+export default []

package/template/src/framework/decorator/processor/AnnotationProcessor.ts

@@ -1,5 +1,6 @@
 import { Context } from 'koa';
 import { annotationRegistry } from '@src/framework/decorator/processor/AnnotationRegistry';
+import { logger } from '@src/framework/utils/logger';
 
 /**
  * 注解处理器接口
@@ -111,7 +112,10 @@ export class AnnotationExecutor {
                         return false;
                     }
                 } catch (error) {
-                    console.error(`注解处理器 ${processor.name} 执行失败:`, error);
+                    // 处理器异常不应中断后续处理器；测试用例里该异常属于“预期流程”时不打印堆栈噪音
+                    if (process.env.NODE_ENV !== 'test') {
+                        logger.error(`注解处理器 ${processor.name} 执行失败`, error as Error);
+                    }
                     // 可以选择是否继续执行其他处理器
                     // 这里选择继续执行
                 }

package/template/src/routers/index.ts

@@ -1,49 +1,14 @@
-// import { UserController } from "../controllers/user.controller";
 import { logger } from "@src/framework/utils/logger";
 import { bindRouter } from "@src/framework/utils/router";
-import tokenMiddleware from "@src/middlewares/token.middleware";
-import { EmailSendController } from "@src/controllers/public/emailSend.controller";
-import { YtUserRegisterController } from "@src/controllers/home/register.controller";
-import { YtUserAuthController } from "@src/controllers/public/ytUserAuth.controller";
-import { YtUserController } from "@src/controllers/home/ytUser.controller";
-import { YtShopController } from "@src/controllers/home/ytShop.controller";
-import { YtGoodsController } from "@src/controllers/home/ytGoods.controller";
-import { HealthController } from "@src/controllers/health.controller";
-import { CacheManagementController } from "@src/controllers/cacheManagement.controller";
-import { TestDataController } from "@src/controllers/testData.controller";
 import { ExampleController } from "@src/controllers/example/ExampleController";
 import { AnnotationDemoController } from "@src/controllers/demo/AnnotationDemoController";
 import { EnterpriseExampleController } from "@src/controllers/example/EnterpriseExampleController";
-import { LogManagementController } from "@src/controllers/logManagement.controller";
 
 
 export default () => {
-    // bindRouter("/a", tokenMiddleware(), aMiddleware(), UserController);
-    bindRouter("/home/user/yt_user", tokenMiddleware(), YtUserController);
-    bindRouter("/home/shop/common", YtShopController);
-    bindRouter("/home/goods/common", tokenMiddleware(), YtGoodsController);
-    bindRouter("/home/register/yt_user", YtUserRegisterController);
-    bindRouter("/home/register/yt_user", YtUserRegisterController);
-    bindRouter("/public/auth/yt_user", YtUserAuthController);
-    bindRouter("/public/email", EmailSendController);
-    
-    // 健康检查端点
-    bindRouter("/health", HealthController);
-    
-    // 缓存管理端点
-    bindRouter("/admin/cache", CacheManagementController);
-    
-    // 测试数据管理端点（仅在内存数据库模式下有效）
-    bindRouter("/test", TestDataController);
-
-
     bindRouter("/example/", ExampleController);
     bindRouter("/demo/", AnnotationDemoController);
     bindRouter("/enterprise/", EnterpriseExampleController);
-    
-    // 日志管理端点
-    bindRouter("/admin/logs", tokenMiddleware(), LogManagementController);
 
-    
     logger.info("路由绑定完成");
 }