抽象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/wechat-minigame.md
+++ b/docs/guide/platform-adapter/wechat-minigame.md
@@ -0,0 +1,621 @@
+# 微信小游戏适配器
+
+## 概述
+
+微信小游戏平台适配器专为微信小游戏环境设计，处理微信小游戏的特殊限制和API。
+
+## 特性支持
+
+- ✅ **Worker**: 支持（通过 `wx.createWorker` 创建，需要配置 game.json）
+- ❌ **SharedArrayBuffer**: 不支持
+- ❌ **Transferable Objects**: 不支持（只支持可序列化对象）
+- ✅ **高精度时间**: 使用 `Date.now()` 或 `wx.getPerformance()`
+- ✅ **设备信息**: 完整的微信小游戏设备信息
+
+## 完整实现
+
+```typescript
+import type {
+    IPlatformAdapter,
+    PlatformWorker,
+    WorkerCreationOptions,
+    PlatformConfig,
+    WeChatDeviceInfo
+} from '@esengine/ecs-framework';
+
+/**
+ * 微信小游戏平台适配器
+ * 支持微信小游戏环境
+ */
+export class WeChatMiniGameAdapter implements IPlatformAdapter {
+    public readonly name = 'wechat-minigame';
+    public readonly version: string;
+    private systemInfo: any;
+
+    constructor() {
+        // 获取微信小游戏版本信息
+        this.systemInfo = this.getSystemInfo();
+        this.version = this.systemInfo.version || 'unknown';
+    }
+
+    /**
+     * 检查是否支持Worker
+     */
+    public isWorkerSupported(): boolean {
+        // 微信小游戏支持Worker，通过wx.createWorker创建
+        return typeof wx !== 'undefined' && typeof wx.createWorker === 'function';
+    }
+
+    /**
+     * 检查是否支持SharedArrayBuffer（不支持）
+     */
+    public isSharedArrayBufferSupported(): boolean {
+        return false; // 微信小游戏不支持SharedArrayBuffer
+    }
+
+    /**
+     * 获取硬件并发数
+     */
+    public getHardwareConcurrency(): number {
+        // 微信小游戏官方限制：最多只能创建 1 个 Worker
+        return 1;
+    }
+
+    /**
+     * 创建Worker
+     * @param script 脚本内容或文件路径
+     * @param options Worker创建选项
+     */
+    public createWorker(script: string, options: WorkerCreationOptions = {}): PlatformWorker {
+        if (!this.isWorkerSupported()) {
+            throw new Error('微信小游戏不支持Worker');
+        }
+
+        try {
+            return new WeChatWorker(script, options);
+        } catch (error) {
+            throw new Error(`创建微信Worker失败: ${(error as Error).message}`);
+        }
+    }
+
+    /**
+     * 创建SharedArrayBuffer（不支持）
+     */
+    public createSharedArrayBuffer(length: number): SharedArrayBuffer | null {
+        return null; // 微信小游戏不支持SharedArrayBuffer
+    }
+
+    /**
+     * 获取高精度时间戳
+     */
+    public getHighResTimestamp(): number {
+        // 尝试使用微信的性能API，否则使用Date.now()
+        if (typeof wx !== 'undefined' && wx.getPerformance) {
+            const performance = wx.getPerformance();
+            return performance.now();
+        }
+        return Date.now();
+    }
+
+    /**
+     * 获取平台配置
+     */
+    public getPlatformConfig(): PlatformConfig {
+        return {
+            maxWorkerCount: 1, // 微信小游戏最多支持 1 个 Worker
+            supportsModuleWorker: false, // 不支持模块Worker
+            supportsTransferableObjects: this.checkTransferableObjectsSupport(),
+            maxSharedArrayBufferSize: 0,
+            workerScriptPrefix: '',
+            limitations: {
+                noEval: true, // 微信小游戏限制eval使用
+                requiresWorkerInit: false,
+                memoryLimit: this.getMemoryLimit(),
+                workerNotSupported: false,
+                workerLimitations: [
+                    '最多只能创建 1 个 Worker',
+                    '创建新Worker前必须先调用 Worker.terminate()',
+                    'Worker脚本必须为项目内相对路径',
+                    '需要在 game.json 中配置 workers 路径',
+                    '使用 worker.onMessage() 而不是 self.onmessage',
+                    '需要基础库 1.9.90 及以上版本'
+                ]
+            },
+            extensions: {
+                platform: 'wechat-minigame',
+                systemInfo: this.systemInfo,
+                appId: this.systemInfo.host?.appId || 'unknown'
+            }
+        };
+    }
+
+    /**
+     * 获取微信小游戏设备信息
+     */
+    public getDeviceInfo(): WeChatDeviceInfo {
+        return {
+            // 设备基础信息
+            brand: this.systemInfo.brand,
+            model: this.systemInfo.model,
+            platform: this.systemInfo.platform,
+            system: this.systemInfo.system,
+            benchmarkLevel: this.systemInfo.benchmarkLevel,
+            cpuType: this.systemInfo.cpuType,
+            memorySize: this.systemInfo.memorySize,
+            deviceAbi: this.systemInfo.deviceAbi,
+            abi: this.systemInfo.abi,
+
+            // 窗口信息
+            screenWidth: this.systemInfo.screenWidth,
+            screenHeight: this.systemInfo.screenHeight,
+            screenTop: this.systemInfo.screenTop,
+            windowWidth: this.systemInfo.windowWidth,
+            windowHeight: this.systemInfo.windowHeight,
+            pixelRatio: this.systemInfo.pixelRatio,
+            statusBarHeight: this.systemInfo.statusBarHeight,
+            safeArea: this.systemInfo.safeArea,
+
+            // 应用信息
+            version: this.systemInfo.version,
+            language: this.systemInfo.language,
+            theme: this.systemInfo.theme,
+            SDKVersion: this.systemInfo.SDKVersion,
+            enableDebug: this.systemInfo.enableDebug,
+            fontSizeSetting: this.systemInfo.fontSizeSetting,
+            host: this.systemInfo.host
+        };
+    }
+
+    /**
+     * 异步获取完整的平台配置
+     */
+    public async getPlatformConfigAsync(): Promise<PlatformConfig> {
+        // 可以在这里添加异步获取设备性能信息的逻辑
+        const baseConfig = this.getPlatformConfig();
+
+        // 尝试获取设备性能信息
+        try {
+            const benchmarkLevel = await this.getBenchmarkLevel();
+            baseConfig.extensions = {
+                ...baseConfig.extensions,
+                benchmarkLevel
+            };
+        } catch (error) {
+            console.warn('获取性能基准失败:', error);
+        }
+
+        return baseConfig;
+    }
+
+    /**
+     * 检查是否支持Transferable Objects
+     */
+    private checkTransferableObjectsSupport(): boolean {
+        // 微信小游戏不支持 Transferable Objects
+        // 基础库 2.20.2 之前只支持可序列化的 key-value 对象
+        // 2.20.2 之后支持任意类型数据，但仍然不支持 Transferable Objects
+        return false;
+    }
+
+    /**
+     * 获取系统信息
+     */
+    private getSystemInfo(): any {
+        if (typeof wx !== 'undefined' && wx.getSystemInfoSync) {
+            try {
+                return wx.getSystemInfoSync();
+            } catch (error) {
+                console.warn('获取微信系统信息失败:', error);
+                return {};
+            }
+        }
+        return {};
+    }
+
+    /**
+     * 获取内存限制
+     */
+    private getMemoryLimit(): number {
+        // 微信小游戏通常有内存限制
+        const memorySize = this.systemInfo.memorySize;
+        if (memorySize) {
+            // 解析内存大小字符串（如 "4GB"）
+            const match = memorySize.match(/(\d+)([GM]B)?/i);
+            if (match) {
+                const value = parseInt(match[1], 10);
+                const unit = match[2]?.toUpperCase();
+
+                if (unit === 'GB') {
+                    return value * 1024 * 1024 * 1024;
+                } else if (unit === 'MB') {
+                    return value * 1024 * 1024;
+                }
+            }
+        }
+
+        // 默认限制为512MB
+        return 512 * 1024 * 1024;
+    }
+
+    /**
+     * 异步获取设备性能基准
+     */
+    private async getBenchmarkLevel(): Promise<number> {
+        return new Promise((resolve) => {
+            if (typeof wx !== 'undefined' && wx.getDeviceInfo) {
+                wx.getDeviceInfo({
+                    success: (res: any) => {
+                        resolve(res.benchmarkLevel || 0);
+                    },
+                    fail: () => {
+                        resolve(0);
+                    }
+                });
+            } else {
+                resolve(this.systemInfo.benchmarkLevel || 0);
+            }
+        });
+    }
+}
+
+/**
+ * 微信Worker封装
+ */
+class WeChatWorker implements PlatformWorker {
+    private _state: 'running' | 'terminated' = 'running';
+    private worker: any;
+    private scriptPath: string;
+    private isTemporaryFile: boolean = false;
+
+    constructor(script: string, options: WorkerCreationOptions = {}) {
+        if (typeof wx === 'undefined' || typeof wx.createWorker !== 'function') {
+            throw new Error('微信小游戏不支持Worker');
+        }
+
+        try {
+            // 判断 script 是文件路径还是脚本内容
+            if (this.isFilePath(script)) {
+                // 直接使用文件路径
+                this.scriptPath = script;
+                this.isTemporaryFile = false;
+                this.worker = wx.createWorker(this.scriptPath);
+            } else {
+                // 将脚本内容写入文件系统
+                this.scriptPath = this.writeScriptToFile(script, options.name);
+                this.isTemporaryFile = true;
+                this.worker = wx.createWorker(this.scriptPath);
+            }
+        } catch (error) {
+            throw new Error(`创建微信Worker失败: ${(error as Error).message}`);
+        }
+    }
+
+    /**
+     * 判断是否为文件路径
+     */
+    private isFilePath(script: string): boolean {
+        // 简单判断：如果包含 .js 后缀且不包含换行符或分号，认为是文件路径
+        return script.endsWith('.js') &&
+               !script.includes('\n') &&
+               !script.includes(';') &&
+               script.length < 200; // 文件路径通常不会太长
+    }
+
+    /**
+     * 将脚本内容写入文件系统
+     */
+    private writeScriptToFile(script: string, name?: string): string {
+        const fs = wx.getFileSystemManager();
+        const fileName = name ? `worker-${name}.js` : `worker-${Date.now()}.js`;
+        const filePath = `${wx.env.USER_DATA_PATH}/${fileName}`;
+
+        try {
+            fs.writeFileSync(filePath, script, 'utf8');
+            return filePath;
+        } catch (error) {
+            throw new Error(`写入Worker脚本文件失败: ${(error as Error).message}`);
+        }
+    }
+
+    public get state(): 'running' | 'terminated' {
+        return this._state;
+    }
+
+    public postMessage(message: any, transfer?: Transferable[]): void {
+        if (this._state === 'terminated') {
+            throw new Error('Worker已被终止');
+        }
+
+        try {
+            // 微信小游戏 Worker 只支持可序列化对象，忽略 transfer 参数
+            this.worker.postMessage(message);
+        } catch (error) {
+            throw new Error(`发送消息到微信Worker失败: ${(error as Error).message}`);
+        }
+    }
+
+    public onMessage(handler: (event: { data: any }) => void): void {
+        // 微信小游戏使用 onMessage 方法，不是 onmessage 属性
+        this.worker.onMessage((res: any) => {
+            handler({ data: res });
+        });
+    }
+
+    public onError(handler: (error: ErrorEvent) => void): void {
+        // 注意：微信小游戏 Worker 的错误处理可能与标准不同
+        if (this.worker.onError) {
+            this.worker.onError(handler);
+        }
+    }
+
+    public terminate(): void {
+        if (this._state === 'running') {
+            try {
+                this.worker.terminate();
+                this._state = 'terminated';
+
+                // 清理临时脚本文件
+                this.cleanupScriptFile();
+            } catch (error) {
+                console.error('终止微信Worker失败:', error);
+            }
+        }
+    }
+
+    /**
+     * 清理临时脚本文件
+     */
+    private cleanupScriptFile(): void {
+        // 只清理临时创建的文件，不清理用户提供的文件路径
+        if (this.scriptPath && this.isTemporaryFile) {
+            try {
+                const fs = wx.getFileSystemManager();
+                fs.unlinkSync(this.scriptPath);
+            } catch (error) {
+                console.warn('清理Worker脚本文件失败:', error);
+            }
+        }
+    }
+}
+```
+
+## 使用方法
+
+### 1. 复制代码
+
+将上述代码复制到你的项目中，例如 `src/platform/WeChatMiniGameAdapter.ts`。
+
+### 2. 注册适配器
+
+```typescript
+import { PlatformManager } from '@esengine/ecs-framework';
+import { WeChatMiniGameAdapter } from './platform/WeChatMiniGameAdapter';
+
+// 检查是否在微信小游戏环境
+if (typeof wx !== 'undefined') {
+    const wechatAdapter = new WeChatMiniGameAdapter();
+    PlatformManager.getInstance().registerAdapter(wechatAdapter);
+}
+```
+
+### 3. Worker 使用方式
+
+微信小游戏适配器支持两种 Worker 使用方式：
+
+#### 方式一：使用脚本文件路径（推荐）
+
+```typescript
+// 1. 在 game.json 中配置 Worker 路径
+/*
+{
+  "workers": "workers"
+}
+*/
+
+// 2. 创建 Worker 脚本文件 workers/physics.js
+// workers/physics.js 内容：
+/*
+// 微信小游戏 Worker 中使用 worker 对象，不是 self
+worker.onMessage(function(data) {
+    const { entities, deltaTime, systemConfig } = data;
+
+    // 处理物理计算
+    const results = entities.map(entity => {
+        entity.vy += systemConfig.gravity * deltaTime;
+        entity.x += entity.vx * deltaTime;
+        entity.y += entity.vy * deltaTime;
+        return entity;
+    });
+
+    worker.postMessage({ result: results });
+});
+*/
+
+// 2. 在 WorkerEntitySystem 中使用
+class PhysicsSystem extends WorkerEntitySystem {
+    constructor() {
+        super(Matcher.all(Transform, Velocity), {
+            enableWorker: true,
+            workerCount: 1, // 微信小游戏限制
+            systemConfig: { gravity: 100 }
+        });
+    }
+
+    // 重写创建 Worker 脚本的方法，返回文件路径
+    private createWorkerScript(): string {
+        return 'workers/physics.js'; // 微信小游戏使用相对路径
+    }
+}
+```
+
+#### 方式二：动态脚本内容（自动处理）
+
+```typescript
+// WorkerEntitySystem 会自动将用户的 workerProcess 函数序列化
+class PhysicsSystem extends WorkerEntitySystem {
+    protected workerProcess(entities, deltaTime, config) {
+        return entities.map(entity => {
+            entity.vy += config.gravity * deltaTime;
+            entity.x += entity.vx * deltaTime;
+            entity.y += entity.vy * deltaTime;
+            return entity;
+        });
+    }
+}
+// 框架会自动将此函数内容写入临时文件并创建 Worker
+```
+
+### 4. 获取设备信息
+
+```typescript
+const manager = PlatformManager.getInstance();
+if (manager.hasAdapter()) {
+    const adapter = manager.getAdapter();
+    console.log('微信设备信息:', adapter.getDeviceInfo());
+}
+```
+
+## 官方文档参考
+
+在使用微信小游戏 Worker 之前，建议先阅读官方文档：
+
+- [wx.createWorker API](https://developers.weixin.qq.com/minigame/dev/api/worker/wx.createWorker.html)
+- [Worker.postMessage API](https://developers.weixin.qq.com/minigame/dev/api/worker/Worker.postMessage.html)
+- [Worker.onMessage API](https://developers.weixin.qq.com/minigame/dev/api/worker/Worker.onMessage.html)
+- [Worker.terminate API](https://developers.weixin.qq.com/minigame/dev/api/worker/Worker.terminate.html)
+
+## 重要注意事项
+
+### Worker 限制和配置
+
+微信小游戏的 Worker 有以下限制：
+
+- **数量限制**: 最多只能创建 1 个 Worker
+- **版本要求**: 需要基础库 1.9.90 及以上版本
+- **配置要求**: 必须在 `game.json` 中配置 workers 路径
+- **文件路径**: Worker 脚本必须为项目内的相对路径
+- **生命周期**: 创建新 Worker 前必须先调用 `Worker.terminate()` 终止当前 Worker
+- **API 差异**: 使用 `worker.onMessage()` 而不是 `self.onmessage`
+
+#### 必要配置
+
+在 `game.json` 中添加 workers 配置：
+
+```json
+{
+  "deviceOrientation": "portrait",
+  "showStatusBar": false,
+  "workers": "workers",
+  "subpackages": []
+}
+```
+
+### 内存限制
+
+微信小游戏有严格的内存限制：
+
+- 通常限制在 256MB - 512MB
+- 需要及时释放不用的资源
+- 避免内存泄漏
+
+### API 限制
+
+- 不支持 `eval()` 函数
+- 不支持 `Function` 构造器
+- DOM API 受限
+- 文件系统 API 受限
+
+## 性能优化建议
+
+### 1. 分帧处理
+
+```typescript
+class FramedProcessor {
+    private tasks: (() => void)[] = [];
+    private isProcessing = false;
+
+    public addTask(task: () => void): void {
+        this.tasks.push(task);
+        if (!this.isProcessing) {
+            this.processNextFrame();
+        }
+    }
+
+    private processNextFrame(): void {
+        this.isProcessing = true;
+        const startTime = Date.now();
+        const frameTime = 16; // 16ms per frame
+
+        while (this.tasks.length > 0 && Date.now() - startTime < frameTime) {
+            const task = this.tasks.shift();
+            if (task) task();
+        }
+
+        if (this.tasks.length > 0) {
+            setTimeout(() => this.processNextFrame(), 0);
+        } else {
+            this.isProcessing = false;
+        }
+    }
+}
+```
+
+### 2. 内存管理
+
+```typescript
+class MemoryManager {
+    private static readonly MAX_MEMORY = 256 * 1024 * 1024; // 256MB
+
+    public static checkMemoryUsage(): void {
+        if (typeof wx !== 'undefined' && wx.getPerformance) {
+            const performance = wx.getPerformance();
+            const memoryInfo = performance.getEntries().find(
+                (entry: any) => entry.entryType === 'memory'
+            );
+
+            if (memoryInfo && memoryInfo.usedJSHeapSize > this.MAX_MEMORY * 0.8) {
+                console.warn('内存使用率过高，建议清理资源');
+                // 触发垃圾回收或资源清理
+            }
+        }
+    }
+}
+```
+
+## 调试技巧
+
+```typescript
+// 检查微信小游戏环境
+if (typeof wx !== 'undefined') {
+    const adapter = new WeChatMiniGameAdapter();
+
+    console.log('微信版本:', adapter.version);
+    console.log('设备信息:', adapter.getDeviceInfo());
+    console.log('平台配置:', adapter.getPlatformConfig());
+
+    // 检查功能支持
+    console.log('Worker支持:', adapter.isWorkerSupported());
+    console.log('SharedArrayBuffer支持:', adapter.isSharedArrayBufferSupported());
+}
+```
+
+## 微信小游戏特殊API
+
+```typescript
+// 获取设备性能等级
+if (typeof wx !== 'undefined' && wx.getDeviceInfo) {
+    wx.getDeviceInfo({
+        success: (res) => {
+            console.log('设备性能等级:', res.benchmarkLevel);
+        }
+    });
+}
+
+// 监听内存警告
+if (typeof wx !== 'undefined' && wx.onMemoryWarning) {
+    wx.onMemoryWarning(() => {
+        console.warn('收到内存警告，开始清理资源');
+        // 清理不必要的资源
+    });
+}
+```