@dangao/bun-server 1.8.1 → 1.8.3

package/docs/zh/request-lifecycle.md

@@ -20,6 +20,10 @@ HTTP Request
 └─────────────────────────────────────┘
     ↓
 ┌─────────────────────────────────────┐
+│             守卫                     │
+└─────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────┐
 │         拦截器（前置）               │
 └─────────────────────────────────────┘
     ↓
@@ -167,7 +171,39 @@ class UserController {
 }
 ```
 
-## 4. 拦截器（前置处理）
+## 4. 守卫
+
+守卫在路由匹配之后、拦截器之前执行，提供细粒度的访问控制。它们可以访问 `ExecutionContext`，提供关于当前请求的丰富信息。
+
+### 执行顺序
+
+1. **全局守卫** - 通过 `SecurityModule.forRoot({ globalGuards: [...] })` 注册
+2. **控制器守卫** - 通过 `@UseGuards()` 应用于控制器类
+3. **方法守卫** - 通过 `@UseGuards()` 应用于方法
+
+### 内置守卫
+
+- `AuthGuard`：要求认证
+- `OptionalAuthGuard`：可选认证
+- `RolesGuard`：基于角色的授权（与 `@Roles()` 装饰器一起使用）
+
+### 示例
+
+```typescript
+@Controller('/api/admin')
+@UseGuards(AuthGuard, RolesGuard)
+class AdminController {
+  @GET('/dashboard')
+  @Roles('admin')
+  public dashboard() {
+    return { message: '管理员仪表板' };
+  }
+}
+```
+
+详细文档请参阅 [守卫](./guards.md)。
+
+## 5. 拦截器（前置处理）
 
 拦截器在控制器方法之前和之后运行。前置拦截器按顺序执行：
 
@@ -200,7 +236,7 @@ class ApiController {}
 - 响应转换
 - 性能监控
 
-## 5. 参数绑定和验证
+## 6. 参数绑定和验证
 
 ### 参数装饰器
 
@@ -208,9 +244,11 @@ class ApiController {}
 |--------|------|------|
 | `@Param(name)` | URL 路径参数 | `/users/:id` → `@Param('id')` |
 | `@Query(name)` | 查询字符串 | `?page=1` → `@Query('page')` |
+| `@QueryMap()` | 所有查询参数 | `?page=1&limit=10` → `@QueryMap()` 返回 `{ page: '1', limit: '10' }` |
 | `@Body()` | 请求体 | JSON 请求体 |
 | `@Body(name)` | 请求体属性 | `body.name` → `@Body('name')` |
 | `@Header(name)` | 请求头 | `@Header('Authorization')` |
+| `@HeaderMap()` | 所有请求头 | `@HeaderMap()` 返回所有请求头作为对象 |
 | `@Context()` | 完整上下文 | 请求上下文对象 |
 | `@Session()` | 会话数据 | 会话对象 |
 
@@ -262,7 +300,7 @@ public createUser(
 }
 ```
 
-## 6. 控制器方法执行
+## 7. 控制器方法执行
 
 验证通过后，使用已解析的依赖和绑定的参数调用控制器方法。
 
@@ -294,7 +332,7 @@ class UserController {
 - **void** - 空响应（204）
 - **Promise** - 异步操作
 
-## 7. 拦截器（后置处理）
+## 8. 拦截器（后置处理）
 
 处理器执行后，后置拦截器按相反顺序运行：
 
@@ -318,7 +356,7 @@ class TransformInterceptor implements Interceptor {
 }
 ```
 
-## 8. 异常过滤器
+## 9. 异常过滤器
 
 如果在请求生命周期中抛出任何异常，它会被异常过滤器捕获。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dangao/bun-server",
-  "version": "1.8.1",
+  "version": "1.8.3",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/controller/controller.ts

@@ -15,6 +15,7 @@ import {
   InterceptorChain,
   scanInterceptorMetadata,
 } from '../interceptor';
+import { LoggerManager } from '@dangao/logsmith';
 
 /**
  * 控制器元数据键
@@ -212,6 +213,13 @@ export class ControllerRegistry {
           // 创建响应
           return context.createResponse(responseData);
         } catch (error) {
+          LoggerManager.getLogger().debug('Controller handler error', {
+            controller: controllerClass.name,
+            method: propertyKey,
+            path: context.path,
+            errorMessage: error instanceof Error ? error.message : String(error),
+            stack: error instanceof Error ? error.stack : undefined,
+          });
           // 使用全局错误处理器，确保错误码和国际化正确应用
           const { handleError } = await import('../error/handler');
           return await handleError(error, context);
@@ -258,8 +266,8 @@ export class ControllerRegistry {
       base = '/';
     }
 
-    // 规范化 methodPath：移除前导斜杠
-    const method = methodPath.replace(/^\/+/, '');
+    // 规范化 methodPath：移除前导斜杠（支持 undefined，如 @GET() 无参）
+    const method = (methodPath ?? '').replace(/^\/+/, '');
 
     if (!method) {
       // 如果方法路径为空，返回基础路径

package/src/core/application.ts

@@ -242,6 +242,13 @@ export class Application {
    * @returns 响应对象
    */
   private async handleRequest(context: Context): Promise<Response> {
+    const logger = LoggerManager.getLogger();
+    logger.debug('[Request] Incoming', {
+      method: context.method,
+      path: context.path,
+      url: context.url?.href,
+    });
+
     // 使用 AsyncLocalStorage 包裹请求处理，确保所有中间件和控制器都在请求上下文中执行
     return await contextStore.run(context, async () => {
       // 对于 POST、PUT、PATCH 请求，提前解析 body 并缓存
@@ -265,6 +272,10 @@ export class Application {
           return response;
         }
 
+        logger.debug('[Router] No route matched', {
+          method: context.method,
+          path: context.path,
+        });
         context.setStatus(404);
         return context.createResponse({ error: 'Not Found' });
       });

package/src/error/handler.ts

@@ -3,6 +3,7 @@ import { HttpException } from './http-exception';
 import { ExceptionFilterRegistry } from './filter';
 import { ValidationError } from '../validation';
 import { ErrorMessageI18n } from './i18n';
+import { LoggerManager } from '@dangao/logsmith';
 
 /**
  * 全局错误处理
@@ -16,6 +17,15 @@ export async function handleError(error: unknown, context: Context): Promise<Res
 
   if (error instanceof HttpException) {
     context.setStatus(error.status);
+    if (error.status >= 400) {
+      LoggerManager.getLogger().debug('HttpException', {
+        method: context.method,
+        path: context.path,
+        status: error.status,
+        code: error.code,
+        message: error.message,
+      });
+    }
 
     // 如果异常有错误码，尝试国际化消息
     let errorMessage = error.message;
@@ -56,7 +66,14 @@ export async function handleError(error: unknown, context: Context): Promise<Res
   }
 
   const message = error instanceof Error ? error.message : String(error);
+  const stack = error instanceof Error ? error.stack : undefined;
   context.setStatus(500);
+  LoggerManager.getLogger().debug('Internal error (500)', {
+    method: context.method,
+    path: context.path,
+    message,
+    stack,
+  });
   return context.createResponse({
     error: 'Internal Server Error',
     details: process.env.NODE_ENV === 'production' ? undefined : message,

package/src/middleware/builtin/error-handler.ts

@@ -41,12 +41,22 @@ export function createErrorHandlingMiddleware(
     try {
       return await next();
     } catch (error) {
+      const routeHandler = (context as { routeHandler?: { controller?: { name?: string }; method?: string } }).routeHandler;
       log(error, { method: context.method, path: context.path });
       logger.error("Unhandled error", {
         method: context.method,
         path: context.path,
         error,
       });
+      logger.debug("Unhandled error details", {
+        method: context.method,
+        path: context.path,
+        routeHandler: routeHandler
+          ? `${routeHandler.controller?.name ?? 'unknown'}.${routeHandler.method ?? 'unknown'}`
+          : undefined,
+        errorMessage: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : undefined,
+      });
 
       if (error instanceof Response) {
         return error as Response;

package/src/middleware/builtin/logger.ts

@@ -38,6 +38,14 @@ export function createLoggerMiddleware(
     } finally {
       const status = response?.status ?? context.statusCode ?? 200;
       log(`${prefix} ${context.method} ${context.path} ${status}`);
+      if (status >= 400) {
+        const logger = LoggerManager.getLogger();
+        logger.debug(`${prefix} Error response`, {
+          method: context.method,
+          path: context.path,
+          statusCode: status,
+        });
+      }
     }
   };
 }
@@ -85,6 +93,15 @@ export function createRequestLoggingMiddleware(
         }ms`,
         error instanceof Error ? { error: error.message } : undefined,
       );
+      if (error instanceof Error) {
+        LoggerManager.getLogger().debug(`${prefix} Request error details`, {
+          method: context.method,
+          path: context.path,
+          durationMs: duration.toFixed(2),
+          message: error.message,
+          stack: error.stack,
+        });
+      }
       throw error;
     }
   };

package/src/router/decorators.ts

@@ -25,10 +25,10 @@ export interface RouteMetadata {
 /**
  * 路由装饰器工厂
  * @param method - HTTP 方法
- * @param path - 路由路径
+ * @param path - 路由路径（可选，默认 ''，即 @GET() 等价于根路径）
  * @returns 方法装饰器
  */
-function createRouteDecorator(method: HttpMethod, path: string) {
+function createRouteDecorator(method: HttpMethod, path: string = '') {
   return function (target: any, propertyKey: string | symbol, descriptor: PropertyDescriptor) {
     // 注意：装饰器应用顺序问题
     // 方法装饰器（@GET）在类装饰器（@Controller）之前应用
@@ -72,9 +72,9 @@ function createRouteDecorator(method: HttpMethod, path: string) {
       }
     }
     
-    existingRoutes.push({ 
-      method, 
-      path, 
+    existingRoutes.push({
+      method,
+      path: path ?? '',
       handler: descriptor.value as RouteHandler,
       propertyKey: propertyKeyStr || undefined,
     });
@@ -84,40 +84,40 @@ function createRouteDecorator(method: HttpMethod, path: string) {
 
 /**
  * GET 路由装饰器
- * @param path - 路由路径
+ * @param path - 路由路径（可选，默认 ''，即 @GET() 映射到控制器基础路径或 /）
  */
-export function GET(path: string) {
+export function GET(path: string = '') {
   return createRouteDecorator('GET', path);
 }
 
 /**
  * POST 路由装饰器
- * @param path - 路由路径
+ * @param path - 路由路径（可选，默认 ''）
  */
-export function POST(path: string) {
+export function POST(path: string = '') {
   return createRouteDecorator('POST', path);
 }
 
 /**
  * PUT 路由装饰器
- * @param path - 路由路径
+ * @param path - 路由路径（可选，默认 ''）
  */
-export function PUT(path: string) {
+export function PUT(path: string = '') {
   return createRouteDecorator('PUT', path);
 }
 
 /**
  * DELETE 路由装饰器
- * @param path - 路由路径
+ * @param path - 路由路径（可选，默认 ''）
  */
-export function DELETE(path: string) {
+export function DELETE(path: string = '') {
   return createRouteDecorator('DELETE', path);
 }
 
 /**
  * PATCH 路由装饰器
- * @param path - 路由路径
+ * @param path - 路由路径（可选，默认 ''）
  */
-export function PATCH(path: string) {
+export function PATCH(path: string = '') {
   return createRouteDecorator('PATCH', path);
 }

package/src/router/router.ts

@@ -3,6 +3,7 @@ import type { Constructor } from '../core/types';
 import { Route } from './route';
 import type { HttpMethod, RouteHandler, RouteMatch } from './types';
 import type { Middleware } from '../middleware';
+import { LoggerManager } from '@dangao/logsmith';
 
 /**
  * 路由器类
@@ -168,14 +169,23 @@ export class Router {
   public async preHandle(context: Context): Promise<void> {
     const method = context.method as HttpMethod;
     const path = this.normalizePath(context.path);
+    const logger = LoggerManager.getLogger();
 
     // 使用 findRouteWithMatch 避免重复匹配
     const result = this.findRouteWithMatch(method, path);
     if (!result) {
+      logger.debug('[Router] Route not matched', { method, path });
       return;
     }
 
     const { route, match } = result;
+    logger.debug('[Router] Route matched', {
+      method,
+      path,
+      routePath: route.path,
+      controller: route.controllerClass?.name,
+      methodName: route.methodName,
+    });
     if (match.matched) {
       context.params = match.params;
     }
@@ -196,6 +206,7 @@ export class Router {
   public async handle(context: Context): Promise<Response | undefined> {
     const method = context.method as HttpMethod;
     const path = this.normalizePath(context.path);
+    const logger = LoggerManager.getLogger();
 
     // 使用 findRouteWithMatch 获取路由和匹配结果
     const result = this.findRouteWithMatch(method, path);
@@ -204,7 +215,13 @@ export class Router {
     }
 
     const { route, match } = result;
-    
+
+    logger.debug('[Router] Executing handler', {
+      path: route.path,
+      controller: route.controllerClass?.name,
+      methodName: route.methodName,
+    });
+
     // 设置路径参数
     if (match.matched) {
       context.params = match.params;

package/tests/controller/path-combination.test.ts

@@ -483,6 +483,141 @@ describe('Controller Path Normalization', () => {
     expect(data.success).toBe(true);
   });
 
+  // 场景 a: @Controller() + @GET('test') / @POST('test') -> /test
+  test('scenario a: @Controller() with @GET("test") and @POST("test") should match /test', async () => {
+    @Controller()
+    class TestController {
+      @GET('test')
+      public getTest() {
+        return { method: 'GET', path: 'test' };
+      }
+
+      @POST('test')
+      public postTest() {
+        return { method: 'POST', path: 'test' };
+      }
+    }
+
+    app.registerController(TestController);
+    await app.listen();
+
+    const getRes = await fetch(`http://localhost:${port}/test`);
+    expect(getRes.status).toBe(200);
+    expect((await getRes.json()).method).toBe('GET');
+
+    const postRes = await fetch(`http://localhost:${port}/test`, { method: 'POST' });
+    expect(postRes.status).toBe(200);
+    expect((await postRes.json()).method).toBe('POST');
+  });
+
+  // 场景 b: @Controller() + @GET('/test') / @POST('/test') -> /test
+  test('scenario b: @Controller() with @GET("/test") and @POST("/test") should match /test', async () => {
+    @Controller()
+    class TestController {
+      @GET('/test')
+      public getTest() {
+        return { method: 'GET', path: 'test' };
+      }
+
+      @POST('/test')
+      public postTest() {
+        return { method: 'POST', path: 'test' };
+      }
+    }
+
+    app.registerController(TestController);
+    await app.listen();
+
+    const getRes = await fetch(`http://localhost:${port}/test`);
+    expect(getRes.status).toBe(200);
+    expect((await getRes.json()).method).toBe('GET');
+
+    const postRes = await fetch(`http://localhost:${port}/test`, { method: 'POST' });
+    expect(postRes.status).toBe(200);
+    expect((await postRes.json()).method).toBe('POST');
+  });
+
+  // 场景 c: @Controller('') + @GET() / @POST() -> /
+  test('scenario c: @Controller("") with @GET() and @POST() should match /', async () => {
+    @Controller('')
+    class TestController {
+      @GET()
+      public getRoot() {
+        return { method: 'GET', path: '/' };
+      }
+
+      @POST()
+      public postRoot() {
+        return { method: 'POST', path: '/' };
+      }
+    }
+
+    app.registerController(TestController);
+    await app.listen();
+
+    const getRes = await fetch(`http://localhost:${port}/`);
+    expect(getRes.status).toBe(200);
+    expect((await getRes.json()).method).toBe('GET');
+
+    const postRes = await fetch(`http://localhost:${port}/`, { method: 'POST' });
+    expect(postRes.status).toBe(200);
+    expect((await postRes.json()).method).toBe('POST');
+  });
+
+  // 场景 d: @Controller() + @GET() / @POST() -> /
+  test('scenario d: @Controller() with @GET() and @POST() should match /', async () => {
+    @Controller()
+    class TestController {
+      @GET()
+      public getRoot() {
+        return { method: 'GET', path: '/' };
+      }
+
+      @POST()
+      public postRoot() {
+        return { method: 'POST', path: '/' };
+      }
+    }
+
+    app.registerController(TestController);
+    await app.listen();
+
+    const getRes = await fetch(`http://localhost:${port}/`);
+    expect(getRes.status).toBe(200);
+    expect((await getRes.json()).method).toBe('GET');
+
+    const postRes = await fetch(`http://localhost:${port}/`, { method: 'POST' });
+    expect(postRes.status).toBe(200);
+    expect((await postRes.json()).method).toBe('POST');
+  });
+
+  // 场景 e: @Controller() + @GET('/') / @POST('/') -> /
+  test('scenario e: @Controller() with @GET("/") and @POST("/") should match /', async () => {
+    @Controller()
+    class TestController {
+      @GET('/')
+      public getRoot() {
+        return { method: 'GET', path: '/' };
+      }
+
+      @POST('/')
+      public postRoot() {
+        return { method: 'POST', path: '/' };
+      }
+    }
+
+    app.registerController(TestController);
+    await app.listen();
+
+    const getRes = await fetch(`http://localhost:${port}/`);
+    expect(getRes.status).toBe(200);
+    expect((await getRes.json()).method).toBe('GET');
+
+    const postRes = await fetch(`http://localhost:${port}/`, { method: 'POST' });
+    expect(postRes.status).toBe(200);
+    expect((await postRes.json()).method).toBe('POST');
+  });
+
   // 测试所有场景在同一应用中同时工作
   test('should handle all path normalization scenarios simultaneously', async () => {
     @Controller('/')