抽象worker接口，避免污染项目

2025-09-29 18:15:47 +08:00
parent 62bc6b547e
commit 90ad4b3ec4
14 changed files with 2027 additions and 931 deletions
--- a/docs/guide/platform-adapter.md
+++ b/docs/guide/platform-adapter.md
@@ -0,0 +1,289 @@
+# 平台适配器
+
+## 概述
+
+ECS框架提供了平台适配器接口，允许用户为不同的运行环境实现自定义的平台适配器。
+
+**核心库只提供接口定义，平台适配器实现代码请从文档中复制使用。**
+
+## 为什么不提供单独的适配器包？
+
+1. **灵活性**: 不同项目对平台适配的需求可能不同，复制代码可以让用户根据需要自由修改
+2. **减少依赖**: 避免引入不必要的依赖包，保持核心框架的精简
+3. **定制化**: 用户可以根据具体的运行环境和需求进行定制
+
+## 支持的平台
+
+### 🌐 [浏览器适配器](./platform-adapter/browser.md)
+
+支持所有现代浏览器环境，包括 Chrome、Firefox、Safari、Edge 等。
+
+**特性支持**:
+- ✅ Worker (Web Worker)
+- ✅ SharedArrayBuffer (需要COOP/COEP)
+- ✅ Transferable Objects
+- ✅ Module Worker (现代浏览器)
+
+**适用场景**: Web游戏、Web应用、PWA
+
+---
+
+### 📱 [微信小游戏适配器](./platform-adapter/wechat-minigame.md)
+
+专为微信小游戏环境设计，处理微信小游戏的特殊限制和API。
+
+**特性支持**:
+- ✅ Worker (最多1个，需配置game.json)
+- ❌ SharedArrayBuffer
+- ❌ Transferable Objects
+- ✅ 微信设备信息API
+
+**适用场景**: 微信小游戏开发
+
+---
+
+### 🖥️ [Node.js适配器](./platform-adapter/nodejs.md)
+
+为 Node.js 服务器环境提供支持，适用于游戏服务器和计算服务器。
+
+**特性支持**:
+- ✅ Worker Threads
+- ✅ SharedArrayBuffer
+- ✅ Transferable Objects
+- ✅ 完整系统信息
+
+**适用场景**: 游戏服务器、计算服务器、CLI工具
+
+---
+
+## 核心接口
+
+### IPlatformAdapter
+
+```typescript
+export interface IPlatformAdapter {
+    readonly name: string;
+    readonly version?: string;
+
+    isWorkerSupported(): boolean;
+    isSharedArrayBufferSupported(): boolean;
+    getHardwareConcurrency(): number;
+    createWorker(script: string, options?: WorkerCreationOptions): PlatformWorker;
+    createSharedArrayBuffer(length: number): SharedArrayBuffer | null;
+    getHighResTimestamp(): number;
+    getPlatformConfig(): PlatformConfig;
+    getPlatformConfigAsync?(): Promise<PlatformConfig>;
+}
+```
+
+### PlatformWorker 接口
+
+```typescript
+export interface PlatformWorker {
+    postMessage(message: any, transfer?: Transferable[]): void;
+    onMessage(handler: (event: { data: any }) => void): void;
+    onError(handler: (error: ErrorEvent) => void): void;
+    terminate(): void;
+    readonly state: 'running' | 'terminated';
+}
+```
+
+## 使用方法
+
+### 1. 选择合适的平台适配器
+
+根据你的运行环境选择对应的适配器：
+
+```typescript
+import { PlatformManager } from '@esengine/ecs-framework';
+
+// 浏览器环境
+if (typeof window !== 'undefined') {
+    const { BrowserAdapter } = await import('./platform/BrowserAdapter');
+    PlatformManager.getInstance().registerAdapter(new BrowserAdapter());
+}
+
+// 微信小游戏环境
+else if (typeof wx !== 'undefined') {
+    const { WeChatMiniGameAdapter } = await import('./platform/WeChatMiniGameAdapter');
+    PlatformManager.getInstance().registerAdapter(new WeChatMiniGameAdapter());
+}
+
+// Node.js环境
+else if (typeof process !== 'undefined' && process.versions?.node) {
+    const { NodeAdapter } = await import('./platform/NodeAdapter');
+    PlatformManager.getInstance().registerAdapter(new NodeAdapter());
+}
+```
+
+### 2. 检查适配器状态
+
+```typescript
+const manager = PlatformManager.getInstance();
+
+// 检查是否已注册适配器
+if (manager.hasAdapter()) {
+    const adapter = manager.getAdapter();
+    console.log('当前平台:', adapter.name);
+    console.log('平台版本:', adapter.version);
+
+    // 检查功能支持
+    console.log('Worker支持:', manager.supportsFeature('worker'));
+    console.log('SharedArrayBuffer支持:', manager.supportsFeature('shared-array-buffer'));
+}
+```
+
+## 创建自定义适配器
+
+如果现有的平台适配器不能满足你的需求，你可以创建自定义适配器：
+
+### 1. 实现接口
+
+```typescript
+import type { IPlatformAdapter, PlatformWorker, WorkerCreationOptions, PlatformConfig } from '@esengine/ecs-framework';
+
+export class CustomAdapter implements IPlatformAdapter {
+    public readonly name = 'custom';
+    public readonly version = '1.0.0';
+
+    public isWorkerSupported(): boolean {
+        // 实现你的 Worker 支持检查逻辑
+        return false;
+    }
+
+    public isSharedArrayBufferSupported(): boolean {
+        // 实现你的 SharedArrayBuffer 支持检查逻辑
+        return false;
+    }
+
+    public getHardwareConcurrency(): number {
+        // 返回你的平台的并发数
+        return 1;
+    }
+
+    public createWorker(script: string, options?: WorkerCreationOptions): PlatformWorker {
+        throw new Error('Worker not supported on this platform');
+    }
+
+    public createSharedArrayBuffer(length: number): SharedArrayBuffer | null {
+        return null;
+    }
+
+    public getHighResTimestamp(): number {
+        return Date.now();
+    }
+
+    public getPlatformConfig(): PlatformConfig {
+        return {
+            maxWorkerCount: 1,
+            supportsModuleWorker: false,
+            supportsTransferableObjects: false,
+            limitations: {
+                workerNotSupported: true
+            }
+        };
+    }
+}
+```
+
+### 2. 注册自定义适配器
+
+```typescript
+import { PlatformManager } from '@esengine/ecs-framework';
+import { CustomAdapter } from './CustomAdapter';
+
+const customAdapter = new CustomAdapter();
+PlatformManager.getInstance().registerAdapter(customAdapter);
+```
+
+## 最佳实践
+
+### 1. 平台检测顺序
+
+建议按照以下顺序检测和注册平台适配器：
+
+```typescript
+async function initializePlatform() {
+    const manager = PlatformManager.getInstance();
+
+    try {
+        // 1. 微信小游戏 (优先级最高，环境特征最明显)
+        if (typeof wx !== 'undefined' && wx.getSystemInfoSync) {
+            const { WeChatMiniGameAdapter } = await import('./platform/WeChatMiniGameAdapter');
+            manager.registerAdapter(new WeChatMiniGameAdapter());
+            return;
+        }
+
+        // 2. Node.js 环境
+        if (typeof process !== 'undefined' && process.versions?.node) {
+            const { NodeAdapter } = await import('./platform/NodeAdapter');
+            manager.registerAdapter(new NodeAdapter());
+            return;
+        }
+
+        // 3. 浏览器环境 (最后检测，覆盖面最广)
+        if (typeof window !== 'undefined' && typeof document !== 'undefined') {
+            const { BrowserAdapter } = await import('./platform/BrowserAdapter');
+            manager.registerAdapter(new BrowserAdapter());
+            return;
+        }
+
+        // 4. 未知环境，使用默认适配器
+        console.warn('未识别的平台环境，使用默认适配器');
+        manager.registerAdapter(new CustomAdapter());
+
+    } catch (error) {
+        console.error('平台适配器初始化失败:', error);
+        throw error;
+    }
+}
+```
+
+### 2. 功能降级处理
+
+```typescript
+function createWorkerSystem() {
+    const manager = PlatformManager.getInstance();
+
+    if (!manager.hasAdapter()) {
+        throw new Error('未注册平台适配器');
+    }
+
+    const config: WorkerSystemConfig = {
+        enableWorker: manager.supportsFeature('worker'),
+        workerCount: manager.supportsFeature('worker') ?
+            manager.getAdapter().getHardwareConcurrency() : 1,
+        useSharedArrayBuffer: manager.supportsFeature('shared-array-buffer')
+    };
+
+    // 如果不支持Worker，自动降级到同步处理
+    if (!config.enableWorker) {
+        console.info('当前平台不支持Worker，使用同步处理模式');
+    }
+
+    return new PhysicsSystem(config);
+}
+```
+
+### 3. 错误处理
+
+```typescript
+try {
+    await initializePlatform();
+
+    // 验证适配器功能
+    const manager = PlatformManager.getInstance();
+    const adapter = manager.getAdapter();
+
+    console.log(`平台适配器初始化成功: ${adapter.name} v${adapter.version}`);
+
+} catch (error) {
+    console.error('平台初始化失败:', error);
+
+    // 提供降级方案
+    const fallbackAdapter = new CustomAdapter();
+    PlatformManager.getInstance().registerAdapter(fallbackAdapter);
+
+    console.warn('使用降级适配器继续运行');
+}
+```