@thinkbun/plugin 1.0.0

package/README.md

@@ -0,0 +1,305 @@
+# ThinkBun Plugin
+
+ThinkBun 框架的官方插件集合，提供常用的功能扩展，包括日志增强和服务器集群支持。
+
+## 子项目概述
+
+Plugin 包提供了 ThinkBun 框架的官方插件实现，这些插件可以直接集成到 ThinkBun 应用程序中，为应用提供额外的功能。当前版本包含日志插件和服务器插件，后续将添加更多官方插件。
+
+## 与主项目的关系
+
+Plugin 包依赖于 ThinkBun Core 包，为其提供扩展功能。这些插件遵循 Core 包定义的插件接口和生命周期，与框架无缝集成。
+
+## 核心插件
+
+### LoggerPlugin
+
+增强应用程序的日志功能，支持彩色输出、作用域标识和不同日志级别。
+
+#### 功能特性
+- 彩色日志输出，提高可读性
+- 支持日志作用域标识
+- 自定义日志级别
+- 与框架日志系统无缝集成
+
+#### 安装
+
+```bash
+# 使用 Bun
+bun add @thinkbun/plugin
+
+# 使用 npm
+npm install @thinkbun/plugin
+
+# 使用 yarn
+yarn add @thinkbun/plugin
+```
+
+#### 使用方法
+
+```typescript
+import { createApplication } from '@thinkbun/core';
+import { LoggerPlugin } from '@thinkbun/plugin';
+
+// 创建应用实例
+const app = await createApplication({
+  APP_PATH: './src',
+  ROOT_PATH: __dirname,
+});
+
+// 注册 LoggerPlugin
+app.loader.plugins.push(LoggerPlugin);
+
+// 设置应用
+await app.setup();
+
+// 使用增强的日志功能
+app.logger.info('应用程序已启动');
+app.logger.error('发生错误', 'ErrorScope');
+app.logger.debug('调试信息', ['Debug', 'Detail']);
+app.logger.warn('警告信息');
+```
+
+#### 日志方法
+
+- `app.logger.info(message, scope)`: 输出信息级别的日志
+- `app.logger.error(message, scope)`: 输出错误级别的日志
+- `app.logger.debug(message, scope)`: 输出调试级别的日志
+- `app.logger.warn(message, scope)`: 输出警告级别的日志
+
+**参数**：
+- `message`: 日志消息内容
+- `scope`: 可选，日志作用域，可以是字符串或字符串数组
+
+### ServerPlugin
+
+提供服务器启动和集群支持功能，优化应用程序的性能和可靠性。
+
+#### 功能特性
+- 基于 Bun.serve 的高性能服务器
+- 自动集群管理，充分利用多核 CPU
+- 工作进程自动重启
+- 优雅的关闭流程
+- 配置化的服务器参数
+
+#### 安装
+
+```bash
+# 使用 Bun
+bun add @thinkbun/plugin
+
+# 使用 npm
+npm install @thinkbun/plugin
+
+# 使用 yarn
+yarn add @thinkbun/plugin
+```
+
+#### 使用方法
+
+```typescript
+import { createApplication } from '@thinkbun/core';
+import { ServerPlugin } from '@thinkbun/plugin';
+
+// 创建应用实例
+const app = await createApplication({
+  APP_PATH: './src',
+  ROOT_PATH: __dirname,
+});
+
+// 注册 ServerPlugin
+app.loader.plugins.push(ServerPlugin);
+
+// 设置应用
+await app.setup();
+
+// 运行应用（ServerPlugin 会自动启动服务器）
+await app.run();
+```
+
+#### 配置选项
+
+在应用配置文件中配置服务器参数：
+
+```typescript
+// src/config/index.ts
+export default {
+  port: 3000,           // 服务器端口
+  host: '0.0.0.0',      // 服务器主机
+  workers: 4,           // 工作进程数量，默认自动检测 CPU 核心数
+  // 其他配置...
+};
+```
+
+#### 集群模式
+
+ServerPlugin 自动支持集群模式：
+- 主进程管理工作进程的创建和重启
+- 工作进程处理实际的 HTTP 请求
+- 当工作进程意外退出时，自动创建新的工作进程
+- 支持优雅关闭，确保请求处理完成后再退出
+
+## 插件生命周期
+
+### LoggerPlugin 生命周期
+
+| 阶段 | 执行顺序 | 功能 |
+|------|----------|------|
+| `setup` | `pre` | 初始化日志功能，替换默认日志器 |
+| `run` | - | 无 |
+| `close` | - | 无 |
+
+### ServerPlugin 生命周期
+
+| 阶段 | 执行顺序 | 功能 |
+|------|----------|------|
+| `setup` | - | 无 |
+| `run` | `post` | 启动服务器，根据配置创建工作进程 |
+| `close` | - | 优雅关闭服务器和工作进程 |
+
+## 独立运行/测试
+
+### 运行示例
+
+```bash
+# 安装依赖
+bun install
+
+# 运行测试
+bun test
+```
+
+### 测试
+
+```bash
+# 运行单元测试
+bun test
+
+# 运行测试并生成覆盖率报告
+bun test --coverage
+```
+
+## 自定义插件开发
+
+Plugin 包不仅提供官方插件，还展示了如何开发自定义插件。以下是开发自定义插件的示例：
+
+```typescript
+import { type Plugin } from '@thinkbun/core';
+
+export const CustomPlugin: Plugin = {
+  name: 'CustomPlugin',
+  enforce: 'pre',  // 插件执行顺序，可以是 'pre'、'post' 或省略
+  setup(app) {
+    // 插件初始化逻辑
+    console.log('CustomPlugin 初始化');
+  },
+  run(app) {
+    // 应用运行时逻辑
+    console.log('CustomPlugin 运行中');
+  },
+  close(app) {
+    // 应用关闭时清理逻辑
+    console.log('CustomPlugin 已关闭');
+  },
+};
+```
+
+## 插件执行顺序
+
+插件的执行顺序由 `enforce` 属性决定：
+- `pre`: 在核心功能之前执行
+- `post`: 在核心功能之后执行
+- 省略: 默认执行顺序
+
+## 最佳实践
+
+1. **插件注册**：
+   - 将插件注册放在 `plugins.ts` 文件中，集中管理
+   - 按照依赖关系和执行顺序注册插件
+
+2. **插件配置**：
+   - 将插件配置放在应用配置文件中
+   - 支持环境特定的配置
+
+3. **错误处理**：
+   - 在插件中添加适当的错误处理
+   - 提供清晰的错误信息
+
+4. **性能考虑**：
+   - 避免在插件中执行耗时操作
+   - 合理使用插件生命周期阶段
+
+## API 参考
+
+### LoggerPlugin
+
+```typescript
+interface Plugin {
+  name: 'LoggerPlugin';
+  enforce: 'pre';
+  setup(app: Application): void;
+}
+```
+
+### ServerPlugin
+
+```typescript
+interface Plugin {
+  name: 'ServerPlugin';
+  enforce: 'post';
+  run(app: Application): void;
+  close(app: Application): Promise<void>;
+}
+```
+
+## 常见问题
+
+### Q: 如何自定义日志颜色？
+
+A: 目前 LoggerPlugin 支持的颜色是预定义的，可以通过修改源代码来自定义：
+
+```typescript
+// 在 logger.ts 中修改 colorMap 对象
+const colorMap = {
+  app: 'yellow',
+  PluginManager: 'yellow',
+  // 添加自定义颜色映射
+  CustomScope: 'cyan',
+};
+```
+
+### Q: 如何配置服务器端口？
+
+A: 在应用配置文件中设置 `port` 选项：
+
+```typescript
+// src/config/index.ts
+export default {
+  port: 8080,  // 设置为不同的端口
+};
+```
+
+### Q: 如何禁用集群模式？
+
+A: 在应用配置文件中将 `workers` 设置为 1：
+
+```typescript
+// src/config/index.ts
+export default {
+  workers: 1,  // 禁用集群模式，只使用一个进程
+};
+```
+
+## 许可证
+
+[MIT License](LICENSE)
+
+## 联系方式
+
+- 📧 邮箱：contact@thinkbun.dev
+- 📦 GitHub：[https://github.com/thinkbun/thinkbun](https://github.com/thinkbun/thinkbun)
+- 💬 Discord：[ThinkBun Community](https://discord.gg/thinkbun)
+
+---
+
+**ThinkBun Plugin** - 为 ThinkBun 框架提供强大的扩展功能 🧩

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@thinkbun/plugin",
+  "version": "1.0.0",
+  "module": "src/index.ts",
+  "type": "module",
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "picocolors": "^1.1.1",
+    "@thinkbun/core": "workspace:*"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from './logger.ts';
+export * from './server.ts';

package/src/logger.ts

@@ -0,0 +1,24 @@
+import { type Plugin } from '@thinkbun/core';
+import pc from 'picocolors';
+
+const colorMap = {
+  app: 'yellow',
+  PluginManager: 'yellow',
+};
+export const LoggerPlugin: Plugin = {
+  name: 'LoggerPlugin',
+  enforce: 'pre',
+  setup(app) {
+    const genScope = (scope: string | string[]) => (Array.isArray(scope) ? scope.map((el) => `[${el}]`) : `[${scope}]`);
+    app.logger = {
+      // @ts-ignore
+      info: (msg: string, scope = 'app') => console.log(pc[colorMap[scope] || 'yellow'](genScope(scope)), msg),
+      // @ts-ignore
+      error: (msg: string, scope = 'app') => console.error(pc[colorMap[scope] || 'yellow'](genScope(scope)), msg),
+      // @ts-ignore
+      debug: (msg: string, scope = 'app') => console.debug(pc[colorMap[scope] || 'yellow'](genScope(scope)), msg),
+      // @ts-ignore
+      warn: (msg: string, scope = 'app') => console.warn(pc[colorMap[scope] || 'yellow'](genScope(scope)), msg),
+    };
+  },
+};

package/src/server.ts

@@ -0,0 +1,83 @@
+import cluster from 'node:cluster';
+import os from 'node:os';
+
+import { type Plugin } from '@thinkbun/core';
+
+const isTest = typeof Bun !== 'undefined' && Bun.env.NODE_ENV === 'test';
+
+let shuttingDown = false;
+let isPrimary = false;
+export const ServerPlugin: Plugin = {
+  name: 'ServerPlugin',
+  enforce: 'post',
+  run(app) {
+    isPrimary = cluster.isPrimary;
+    isPrimary = cluster.isPrimary;
+    const cpuCount = os.cpus().length;
+    const workers = Math.max(1, Math.min(cpuCount, app.loader.config.workers));
+
+    if (isPrimary && workers > 1) {
+      for (let i = 0; i < workers; i++) {
+        cluster.fork();
+      }
+
+      cluster.on('exit', () => {
+        if (shuttingDown) return;
+        cluster.fork();
+      });
+    } else {
+      app.server = Bun.serve({
+        port: app.loader.config.port,
+        hostname: app.loader.config.host,
+        reusePort: true,
+        routes: app.routes,
+      });
+
+      process.on('message', async (msg: { type: string }) => {
+        if (typeof msg === 'object' && msg !== null && msg.type === 'shutdown') {
+          await app.server?.stop?.();
+          process.exit(0);
+        }
+      });
+    }
+  },
+  async close(app) {
+    if (isTest) {
+      // 只关闭 server，不退出进程
+      await app.server?.stop?.();
+      return;
+    }
+    // 只允许 primary 主动关闭 cluster
+    if (!isPrimary) {
+      await app.server?.stop?.();
+      process.exit(0);
+    }
+
+    if (shuttingDown) return;
+    shuttingDown = true;
+
+    // 通知所有 worker
+    for (const id in cluster.workers) {
+      cluster.workers[id]?.send({ type: 'shutdown' });
+    }
+
+    // 等待 worker 退出 or 强杀
+    await new Promise<void>((resolve) => {
+      const timer = setTimeout(() => {
+        for (const id in cluster.workers) {
+          cluster.workers[id]?.kill('SIGKILL');
+        }
+        resolve();
+      }, 5000);
+
+      cluster.on('exit', () => {
+        if (Object.keys(cluster?.workers || {}).length === 0) {
+          clearTimeout(timer);
+          resolve();
+        }
+      });
+    });
+
+    process.exit(0);
+  },
+};

package/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../../tsconfig.json",
+  "include": ["src"],
+}