@dangao/bun-server 1.1.2 → 1.1.4

package/docs/zh/guide.md

@@ -0,0 +1,361 @@
+# 使用指南
+
+涵盖从零开始构建 Bun Server 应用的关键步骤。
+
+## 1. 初始化应用
+
+```ts
+import "reflect-metadata";
+import { Application } from "../src";
+
+const app = new Application({ port: 3000 });
+app.listen();
+```
+
+> Tip: 默认端口为 3000，可通过 `app.listen(customPort)` 或
+> `new Application({ port })` 调整。
+
+## 2. 注册控制器与依赖
+
+```ts
+import {
+  Application,
+  Body,
+  Controller,
+  GET,
+  Injectable,
+  Param,
+  POST,
+} from "../src";
+
+@Injectable()
+class UserService {
+  private readonly users = new Map<string, string>([["1", "Alice"]]);
+  public get(id: string) {
+    return this.users.get(id);
+  }
+  public create(name: string) {
+    const id = String(this.users.size + 1);
+    this.users.set(id, name);
+    return { id, name };
+  }
+}
+
+@Controller("/api/users")
+class UserController {
+  public constructor(private readonly service: UserService) {}
+
+  @GET("/:id")
+  public getUser(@Param("id") id: string) {
+    return this.service.get(id) ?? { error: "Not Found" };
+  }
+
+  @POST("/")
+  public createUser(@Body() payload: { name: string }) {
+    return this.service.create(payload.name);
+  }
+}
+
+const app = new Application({ port: 3000 });
+app.registerController(UserController);
+app.listen();
+```
+
+## 3. 使用中间件
+
+```ts
+import { createCorsMiddleware, createLoggerMiddleware } from "../src";
+
+const app = new Application();
+app.use(createLoggerMiddleware({ prefix: "[Example]" }));
+app.use(createCorsMiddleware({ origin: "*" }));
+```
+
+`@UseMiddleware()` 可作用于单个控制器或方法：
+
+```ts
+import { UseMiddleware } from '../src';
+
+const auth = async (ctx, next) => {
+  if (ctx.getHeader('authorization') !== 'token') {
+    ctx.setStatus(401);
+    return ctx.createResponse({ error: 'Unauthorized' });
+  }
+  return await next();
+};
+
+@UseMiddleware(auth)
+@Controller('/secure')
+class SecureController { ... }
+```
+
+## 4. 参数验证
+
+```ts
+import { Validate, IsEmail, MinLength } from '../src';
+
+@POST('/register')
+public register(
+  @Body('email') @Validate(IsEmail()) email: string,
+  @Body('password') @Validate(MinLength(6)) password: string,
+) {
+  return { email };
+}
+```
+
+验证失败将抛出 `ValidationError`，默认错误处理中间件会返回 400 + 详细 `issues`。
+
+## 5. WebSocket 网关
+
+```ts
+import { OnMessage, WebSocketGateway } from "../src";
+
+@WebSocketGateway("/ws/chat")
+class ChatGateway {
+  @OnMessage
+  public onMessage(ws, message: string) {
+    ws.send(`echo: ${message}`);
+  }
+}
+
+app.registerWebSocketGateway(ChatGateway);
+```
+
+## 6. 文件上传与静态资源
+
+```ts
+import { createFileUploadMiddleware, createStaticFileMiddleware } from "../src";
+
+app.use(createFileUploadMiddleware({ maxSize: 5 * 1024 * 1024 }));
+app.use(
+  createStaticFileMiddleware({
+    root: "./public",
+    prefix: "/assets",
+    enableCache: true,
+  }),
+);
+```
+
+上传后的文件可在 `context.body.files` 中读取；静态资源请求会自动设置
+Content-Type 与缓存头。
+
+## 7. 错误处理与自定义过滤器
+
+```ts
+import { ExceptionFilterRegistry, HttpException } from "../src";
+
+ExceptionFilterRegistry.getInstance().register({
+  catch(error, context) {
+    if (error instanceof HttpException && error.status === 403) {
+      return context.createResponse({ error: "No permission" }, {
+        status: 403,
+      });
+    }
+    return undefined;
+  },
+});
+```
+
+默认的 `createErrorHandlingMiddleware` 已自动添加到应用，确保异常均被捕获。
+
+## 8. 扩展系统
+
+Bun Server 提供了多种扩展方式，包括中间件、应用扩展、模块系统等。详细说明请参考
+[扩展系统文档](./extensions.md)。
+
+### 快速示例
+
+#### 使用模块方式（推荐）
+
+```typescript
+import {
+  LoggerModule,
+  LogLevel,
+  Module,
+  SwaggerModule,
+} from "@dangao/bun-server";
+
+// 配置模块
+LoggerModule.forRoot({
+  logger: { prefix: "App", level: LogLevel.INFO },
+  enableRequestLogging: true,
+});
+
+SwaggerModule.forRoot({
+  info: { title: "API", version: "1.0.0" },
+  uiPath: "/swagger",
+});
+
+@Module({
+  imports: [LoggerModule, SwaggerModule],
+  controllers: [UserController],
+  providers: [UserService],
+})
+class AppModule {}
+
+const app = new Application({ port: 3000 });
+app.registerModule(AppModule);
+```
+
+#### 使用扩展方式
+
+```typescript
+import { LoggerExtension, SwaggerExtension } from "@dangao/bun-server";
+
+const app = new Application({ port: 3000 });
+
+app.registerExtension(new LoggerExtension({ prefix: "App" }));
+app.registerExtension(
+  new SwaggerExtension({
+    info: { title: "API", version: "1.0.0" },
+  }),
+);
+```
+
+#### 使用中间件
+
+```typescript
+import {
+  createCorsMiddleware,
+  createLoggerMiddleware,
+} from "@dangao/bun-server";
+
+const app = new Application({ port: 3000 });
+
+app.use(createLoggerMiddleware({ prefix: "[App]" }));
+app.use(createCorsMiddleware({ origin: "*" }));
+```
+
+更多扩展方式和使用场景，请参考 [扩展系统文档](./extensions.md)。
+
+### 进阶示例：接口 + Symbol + 模块
+
+此示例演示如何使用接口配合 Symbol token
+和基于模块的依赖注入，实现更灵活的解耦设计：
+
+```typescript
+import {
+  Application,
+  Body,
+  CONFIG_SERVICE_TOKEN,
+  ConfigModule,
+  ConfigService,
+  Controller,
+  GET,
+  Inject,
+  Injectable,
+  Module,
+  Param,
+  POST,
+} from "@dangao/bun-server";
+
+// 定义服务接口
+interface UserService {
+  find(id: string): Promise<{ id: string; name: string } | undefined>;
+  create(name: string): { id: string; name: string };
+}
+
+// 创建 Symbol token 用于依赖注入
+const UserService = Symbol("UserService");
+
+// 实现接口
+@Injectable()
+class UserServiceImpl implements UserService {
+  private readonly users = new Map<string, { id: string; name: string }>([
+    ["1", { id: "1", name: "Alice" }],
+  ]);
+
+  public async find(id: string) {
+    return this.users.get(id);
+  }
+
+  public create(name: string) {
+    const id = String(this.users.size + 1);
+    const user = { id, name };
+    this.users.set(id, user);
+    return user;
+  }
+}
+
+@Controller("/api/users")
+class UserController {
+  public constructor(
+    private readonly service: UserService,
+    @Inject(CONFIG_SERVICE_TOKEN) private readonly config: ConfigService,
+  ) {}
+
+  @GET("/:id")
+  public async getUser(@Param("id") id: string) {
+    const user = await this.service.find(id);
+    if (!user) {
+      return { error: "Not Found" };
+    }
+    return user;
+  }
+
+  @POST("/")
+  public createUser(@Body("name") name: string) {
+    return this.service.create(name);
+  }
+}
+
+// 使用 Symbol-based provider 定义模块
+@Module({
+  controllers: [UserController],
+  providers: [
+    {
+      provide: UserService,
+      useClass: UserServiceImpl,
+    },
+  ],
+  exports: [UserService],
+})
+class UserModule {}
+
+// 配置模块
+ConfigModule.forRoot({
+  defaultConfig: {
+    app: {
+      name: "Advanced App",
+      port: 3100,
+    },
+  },
+});
+
+// 注册模块并启动应用
+@Module({
+  imports: [ConfigModule],
+  controllers: [UserController],
+  providers: [
+    {
+      provide: UserService,
+      useClass: UserServiceImpl,
+    },
+  ],
+})
+class AppModule {}
+
+const app = new Application({ port: 3100 });
+app.registerModule(AppModule);
+app.listen();
+```
+
+**关键要点：**
+
+- **基于接口的设计**：使用 TypeScript 接口定义服务契约，便于解耦和测试
+- **Symbol token**：使用 `Symbol()` 创建类型安全的依赖注入 token，避免字符串
+  token 的命名冲突
+- **模块提供者**：使用 `provide: Symbol, useClass: Implementation`
+  注册提供者，支持接口与实现分离
+- **类型安全注入**：在构造函数中直接使用接口类型，框架会自动通过 Symbol token
+  解析对应的实现
+
+这种模式特别适合大型项目，可以轻松替换实现而不影响使用方代码。
+
+## 9. 测试建议
+
+- 使用 `tests/utils/test-port.ts` 获取自增端口，避免本地冲突。
+- 在 `afterEach` 钩子中调用 `RouteRegistry.getInstance().clear()` 和
+  `ControllerRegistry.getInstance().clear()`，保持全局状态干净。
+- 端到端测试中可直接实例化 `Context` 并调用
+  `router.handle(context)`，无需真正启动服务器。

package/docs/zh/migration.md

@@ -0,0 +1,86 @@
+# 迁移指南
+
+适用于从项目早期版本或其他框架迁移到最新 Bun Server Framework 的场景。
+
+## 1. 项目结构调整
+
+- 统一入口到 `src/index.ts`，示例项目可放在 `examples/`。
+- 确保 `tsconfig.json` 开启：
+  ```json
+  {
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": true
+  }
+  ```
+- 在应用入口（如 `main.ts`）导入一次 `reflect-metadata`：
+  ```ts
+  import 'reflect-metadata';
+  ```
+
+## 2. 路由与控制器
+
+- 将旧的函数式注册迁移到装饰器：
+  ```ts
+  // 旧
+  router.get('/users/:id', handler);
+
+  // 新
+  @Controller('/users')
+  class UserController {
+    @GET('/:id')
+    public get(@Param('id') id: string) { ... }
+  }
+  app.registerController(UserController);
+  ```
+- 若暂时需要保留函数式路由，可通过 `RouteRegistry.getInstance().register(method, path, handler)`。
+
+## 3. 依赖注入
+
+- 所有可复用服务需添加 `@Injectable()`，并通过构造函数注入使用。
+- 旧的单例或全局对象可改为 `app.getContainer().registerInstance(...)` 注入。
+
+## 4. 中间件与错误处理
+
+- 统一使用 `app.use(createErrorHandlingMiddleware())`，并移除 Controller 内的 try/catch。
+- 自定义错误响应时，使用 `ExceptionFilterRegistry`：
+  ```ts
+  ExceptionFilterRegistry.getInstance().register({
+    catch(error, ctx) {
+      if (error instanceof MyCustomError) {
+        return ctx.createResponse({ error: 'custom' }, { status: 418 });
+      }
+      return undefined;
+    },
+  });
+  ```
+
+## 5. 文件与静态资源
+
+- 旧的上传实现可迁移到 `createFileUploadMiddleware()`，上传结果可从 `context.body.files` 获取。
+- 静态资源统一使用 `createStaticFileMiddleware({ root, prefix })`，避免重复编写路径安全逻辑。
+
+## 6. WebSocket
+
+- 将原本在 `Bun.serve({ websocket })` 中手写的逻辑迁移到 `@WebSocketGateway`：
+  ```ts
+  @WebSocketGateway('/ws/chat')
+  class ChatGateway {
+    @OnMessage onMessage(ws, msg) { ws.send(msg); }
+  }
+  app.registerWebSocketGateway(ChatGateway);
+  ```
+- 应用启动时会自动处理升级与事件分发。
+
+## 7. 测试与工具
+
+- 使用 `tests/utils/test-port.ts` 生成端口，避免冲突。
+- 在 `afterEach` 中调用 `RouteRegistry.getInstance().clear()`、`ControllerRegistry.getInstance().clear()`、`WebSocketGatewayRegistry.getInstance().clear()` 保持测试隔离。
+- 若需模拟 Request，可直接 new `Context(new Request(...))`。
+
+## 8. 配置与依赖
+
+- 推荐 Node/Bun 版本：Bun v1.3+、TypeScript 5.4+。
+- 若引入额外依赖（如数据库驱动），建议在 Service 层封装并通过 DI 注入，保持控制器轻量。
+
+完成以上步骤即可平滑过渡到最新的 Bun Server Framework。若遇到破坏性变更，可查阅 changelog 或提交 issue。
+