tencentcloud-webar 1.0.29-2 → 1.0.29-3

package/doc//345/244/232SDK/345/256/236/344/276/213/344/272/222/347/233/270/345/275/261/345/223/215/347/232/204/345/270/270/350/247/201/351/227/256/351/242/230/345/217/212/350/247/243/345/206/263/346/226/271/346/241/210.md

@@ -0,0 +1,625 @@
+# 多SDK实例互相影响的常见问题及解决方案
+
+## 概述
+
+在SDK开发中，支持单页面多实例是一个常见但复杂的需求。除了EventBus之外，还有许多常见的代码写法会导致多SDK实例互相影响。本文档总结了这些问题及其解决方案。
+
+## 1. 单例模式（Singleton Pattern）
+
+### 问题描述
+单例模式是最常见的多实例问题来源，因为单例模式天然只允许一个实例存在。
+
+### 常见形式
+```typescript
+// 静态实例属性
+class AROptionsManager extends EventObj {
+  static instance: AROptionsManager = new AROptionsManager();
+}
+
+// 静态获取方法
+class QualityManager {
+  static instance: QualityManager = new QualityManager();
+}
+
+// 静态属性
+class GesturePipe extends EventObj {
+  static instance: GesturePipe = new GesturePipe();
+}
+```
+
+### 问题场景
+当页面创建多个SDK实例时，所有实例都会共享同一个单例对象，导致配置冲突、状态混乱等问题。
+
+### 解决方案
+1. **实例化单例**：将单例改为实例属性
+```typescript
+class ArSdk {
+  private optionsManager: AROptionsManager;
+  private qualityManager: QualityManager;
+  
+  constructor(config: Config) {
+    this.optionsManager = new AROptionsManager();
+    this.qualityManager = new QualityManager();
+  }
+}
+```
+
+2. **依赖注入**：通过构造函数传递
+```typescript
+class ArMainImpl {
+  private optionsManager: AROptionsManager;
+  
+  constructor(optionsManager: AROptionsManager) {
+    this.optionsManager = optionsManager;
+  }
+}
+```
+
+---
+
+## 2. 全局状态存储
+
+### 问题描述
+使用全局变量或对象存储状态，导致多实例共享状态。
+
+### 常见形式
+```typescript
+// 全局变量
+let resolution = 1;
+
+// 全局对象
+const globalData = {
+  defaultRoot: '',
+  version: '1.0.0'
+};
+
+// window对象属性
+window._arCustomReport = reportor.report.bind(reportor);
+```
+
+### 问题场景
+多个SDK实例修改全局状态，导致实例间状态互相影响。
+
+### 解决方案
+1. **实例级状态**：将全局状态移到SDK实例中
+```typescript
+class ArSdk {
+  private resolution: number = 1;
+  private customReport: Function;
+  
+  constructor(config: Config) {
+    this.customReport = reportor.report.bind(reportor);
+  }
+}
+```
+
+2. **上下文对象**：创建上下文对象管理状态
+```typescript
+interface SDKContext {
+  resolution: number;
+  customReport: Function;
+}
+
+class ArSdk {
+  private context: SDKContext;
+  
+  constructor(config: Config) {
+    this.context = {
+      resolution: 1,
+      customReport: reportor.report.bind(reportor)
+    };
+  }
+}
+```
+
+---
+
+## 3. 全局事件监听
+
+### 问题描述
+直接在全局对象（如window、document）上添加事件监听器，导致多实例事件处理混乱。
+
+### 常见形式
+```typescript
+// document事件监听
+document.addEventListener("visibilitychange", this._visibilityChangeFunc);
+
+// window事件监听
+window.addEventListener('resize', this._handleResize);
+
+// 全局对象事件监听
+AROptionsManager.instance.on('mirrorChange', this._handleMirrorChange);
+```
+
+### 问题场景
+多个SDK实例都监听同一个全局事件，导致事件被多次处理，或者一个实例的事件处理影响其他实例。
+
+### 解决方案
+1. **实例级事件处理**：在事件处理函数中检查实例关联
+```typescript
+class ArSdk {
+  private _visibilityChangeFunc: (e: Event) => any;
+  
+  constructor(config: Config) {
+    this._visibilityChangeFunc = (e) => {
+      // 检查是否是当前实例的事件
+      if (this.paused) return;
+      // 处理逻辑
+    };
+    document.addEventListener("visibilitychange", this._visibilityChangeFunc);
+  }
+  
+  destroy() {
+    document.removeEventListener("visibilitychange", this._visibilityChangeFunc);
+  }
+}
+```
+
+2. **事件命名空间**：为每个实例添加唯一标识
+```typescript
+class ArSdk {
+  private instanceId: string;
+  
+  constructor(config: Config) {
+    this.instanceId = `sdk_${Date.now()}_${Math.random()}`;
+    
+    // 使用命名空间事件
+    AROptionsManager.instance.on(`mirrorChange.${this.instanceId}`, this._handleMirrorChange);
+  }
+  
+  destroy() {
+    AROptionsManager.instance.off(`mirrorChange.${this.instanceId}`, this._handleMirrorChange);
+  }
+}
+```
+
+---
+
+## 4. DOM操作冲突
+
+### 问题描述
+多个SDK实例操作同一个DOM元素，或者创建具有相同ID的DOM元素。
+
+### 常见形式
+```typescript
+// 创建固定ID的元素
+this.canvas = document.createElement("canvas");
+this.canvas.id = "ar-renderer-canvas";
+
+// 添加到body
+document.body.appendChild(this.canvas);
+
+// 查找固定ID的元素
+const container = document.getElementById(containerId);
+```
+
+### 问题场景
+多个SDK实例创建相同ID的元素，导致DOM查询返回错误的元素，或者样式、事件绑定混乱。
+
+### 解决方案
+1. **唯一ID生成**：为每个实例生成唯一ID
+```typescript
+class ArSdk {
+  private instanceId: string;
+  
+  constructor(config: Config) {
+    this.instanceId = `sdk_${Date.now()}_${Math.random()}`;
+  }
+  
+  createCanvas() {
+    const canvas = document.createElement("canvas");
+    canvas.id = `ar-renderer-canvas-${this.instanceId}`;
+    return canvas;
+  }
+}
+```
+
+2. **容器隔离**：每个SDK实例使用独立的容器
+```typescript
+class ArSdk {
+  private container: HTMLElement;
+  
+  constructor(config: Config, containerId: string) {
+    this.container = document.getElementById(containerId);
+    if (!this.container) {
+      throw new Error(`Container with id ${containerId} not found`);
+    }
+  }
+  
+  createCanvas() {
+    const canvas = document.createElement("canvas");
+    this.container.appendChild(canvas);
+    return canvas;
+  }
+}
+```
+
+---
+
+## 5. Web Worker共享
+
+### 问题描述
+多个SDK实例共享同一个Web Worker，导致消息处理混乱。
+
+### 常见形式
+```typescript
+// 全局Worker实例
+let detectWorker: Worker;
+
+// 多个实例使用同一个Worker
+if (!detectWorker) {
+  detectWorker = new Worker('/detect.worker.js');
+}
+detectWorker.postMessage({ command: "init", options });
+```
+
+### 问题场景
+多个SDK实例向同一个Worker发送消息，Worker无法区分消息来源，导致响应发送给错误的实例。
+
+### 解决方案
+1. **实例级Worker**：每个SDK实例创建自己的Worker
+```typescript
+class ArSdk {
+  private worker: Worker;
+  
+  constructor(config: Config) {
+    this.worker = new Worker('/detect.worker.js');
+    this.worker.onmessage = this._handleWorkerMessage.bind(this);
+  }
+  
+  destroy() {
+    this.worker.terminate();
+  }
+}
+```
+
+2. **消息路由**：在Worker中添加消息路由机制
+```typescript
+// 在Worker中
+const messageHandlers = new Map();
+
+self.onmessage = function(e) {
+  const { instanceId, command, data } = e.data;
+  const handler = messageHandlers.get(instanceId);
+  if (handler) {
+    handler({ command, data });
+  }
+};
+
+// 在SDK实例中
+class ArSdk {
+  private instanceId: string;
+  
+  constructor(config: Config) {
+    this.instanceId = `sdk_${Date.now()}_${Math.random()}`;
+    
+    // 注册消息处理器
+    detectWorker.postMessage({
+      command: "register",
+      instanceId: this.instanceId
+    });
+  }
+}
+```
+
+---
+
+## 6. 资源加载冲突
+
+### 问题描述
+多个SDK实例同时加载相同资源，导致资源冲突或重复加载。
+
+### 常见形式
+```typescript
+// 全局资源缓存
+const resourceCache = new Map();
+
+// 全局加载状态
+let isLoading = false;
+```
+
+### 问题场景
+多个SDK实例同时加载相同资源，可能导致资源被多次加载，或者加载状态混乱。
+
+### 解决方案
+1. **实例级资源管理**：每个SDK实例管理自己的资源
+```typescript
+class ArSdk {
+  private resourceCache: Map<string, any> = new Map();
+  
+  async loadResource(url: string) {
+    if (this.resourceCache.has(url)) {
+      return this.resourceCache.get(url);
+    }
+    
+    const resource = await fetch(url);
+    this.resourceCache.set(url, resource);
+    return resource;
+  }
+}
+```
+
+2. **共享资源池**：使用引用计数管理共享资源
+```typescript
+class ResourcePool {
+  private static instance: ResourcePool;
+  private resources = new Map<string, { data: any, refCount: number }>();
+  
+  static getInstance(): ResourcePool {
+    if (!ResourcePool.instance) {
+      ResourcePool.instance = new ResourcePool();
+    }
+    return ResourcePool.instance;
+  }
+  
+  async getResource(url: string): Promise<any> {
+    if (this.resources.has(url)) {
+      const resource = this.resources.get(url);
+      resource.refCount++;
+      return resource.data;
+    }
+    
+    const data = await fetch(url);
+    this.resources.set(url, { data, refCount: 1 });
+    return data;
+  }
+  
+  releaseResource(url: string): void {
+    if (this.resources.has(url)) {
+      const resource = this.resources.get(url);
+      resource.refCount--;
+      if (resource.refCount <= 0) {
+        this.resources.delete(url);
+      }
+    }
+  }
+}
+```
+
+---
+
+## 7. 异步操作竞态条件
+
+### 问题描述
+多个SDK实例同时执行异步操作，导致操作结果互相覆盖。
+
+### 常见形式
+```typescript
+// 全局异步操作状态
+let isInitializing = false;
+
+// 全局异步操作结果
+let initResult: any;
+```
+
+### 问题场景
+多个SDK实例同时初始化，可能导致初始化状态混乱，或者一个实例的初始化结果覆盖另一个实例的结果。
+
+### 解决方案
+1. **实例级异步状态**：每个SDK实例管理自己的异步状态
+```typescript
+class ArSdk {
+  private isInitializing = false;
+  private initPromise: Promise<void> | null = null;
+  
+  async init(): Promise<void> {
+    if (this.isInitializing) {
+      return this.initPromise;
+    }
+    
+    this.isInitializing = true;
+    this.initPromise = this._doInit();
+    
+    try {
+      await this.initPromise;
+    } finally {
+      this.isInitializing = false;
+    }
+  }
+  
+  private async _doInit(): Promise<void> {
+    // 初始化逻辑
+  }
+}
+```
+
+---
+
+## 8. 定时器和动画帧冲突
+
+### 问题描述
+多个SDK实例使用全局定时器或动画帧，导致性能问题或逻辑混乱。
+
+### 常见形式
+```typescript
+// 全局定时器ID
+let tickerId: number;
+
+// 全局动画帧ID
+let animationFrameId: number;
+```
+
+### 问题场景
+多个SDK实例都启动自己的动画循环，可能导致性能问题，或者一个实例停止动画影响其他实例。
+
+### 解决方案
+1. **实例级定时器**：每个SDK实例管理自己的定时器
+```typescript
+class ArSdk {
+  private animationFrameId: number | null = null;
+  
+  startAnimation() {
+    if (this.animationFrameId) {
+      return;
+    }
+    
+    const animate = () => {
+      // 动画逻辑
+      this.animationFrameId = requestAnimationFrame(animate);
+    };
+    
+    this.animationFrameId = requestAnimationFrame(animate);
+  }
+  
+  stopAnimation() {
+    if (this.animationFrameId) {
+      cancelAnimationFrame(this.animationFrameId);
+      this.animationFrameId = null;
+    }
+  }
+}
+```
+
+---
+
+## 9. 配置覆盖
+
+### 问题描述
+多个SDK实例修改全局配置，导致配置互相覆盖。
+
+### 常见形式
+```typescript
+// 全局配置对象
+const globalConfig = {
+  width: 640,
+  height: 480,
+  mirror: false
+};
+
+// 直接修改全局配置
+globalConfig.mirror = true;
+```
+
+### 问题场景
+一个SDK实例修改全局配置，影响其他实例的行为。
+
+### 解决方案
+1. **实例级配置**：每个SDK实例维护自己的配置
+```typescript
+class ArSdk {
+  private config: SDKConfig;
+  
+  constructor(config: SDKConfig) {
+    this.config = { ...defaultConfig, ...config };
+  }
+  
+  updateConfig(newConfig: Partial<SDKConfig>): void {
+    this.config = { ...this.config, ...newConfig };
+  }
+}
+```
+
+---
+
+## 10. 日志和上报冲突
+
+### 问题描述
+多个SDK实例使用全局日志或上报系统，导致日志混乱或上报数据错误。
+
+### 常见形式
+```typescript
+// 全局日志配置
+let logLevel = 'info';
+
+// 全局上报函数
+window._arCustomReport = reportor.report.bind(reportor);
+```
+
+### 问题场景
+多个SDK实例设置不同的日志级别，或者上报数据时无法区分来源实例。
+
+### 解决方案
+1. **实例级日志系统**：每个SDK实例使用自己的日志配置
+```typescript
+class ArSdk {
+  private logger: Logger;
+  private instanceId: string;
+  
+  constructor(config: SDKConfig) {
+    this.instanceId = `sdk_${Date.now()}_${Math.random()}`;
+    this.logger = new Logger({
+      level: config.logLevel || 'info',
+      prefix: `[${this.instanceId}]`
+    });
+  }
+}
+```
+
+---
+
+## 最佳实践总结
+
+### 1. 避免全局状态
+- 将所有状态封装在SDK实例中
+- 避免使用全局变量和单例模式
+- 使用依赖注入而非全局访问
+
+### 2. 资源隔离
+- 每个SDK实例使用独立的资源
+- 为DOM元素、Worker等资源添加唯一标识
+- 实现正确的资源清理机制
+
+### 3. 事件隔离
+- 使用命名空间区分不同实例的事件
+- 在事件处理函数中检查实例关联
+- 正确移除事件监听器
+
+### 4. 异步操作管理
+- 每个SDK实例管理自己的异步状态
+- 避免全局异步操作状态
+- 正确处理异步操作的竞态条件
+
+### 5. 配置隔离
+- 每个SDK实例维护自己的配置
+- 避免修改全局配置
+- 提供配置合并和更新机制
+
+### 6. 生命周期管理
+- 实现正确的初始化和销毁流程
+- 确保所有资源在销毁时被正确释放
+- 避免内存泄漏
+
+## 检查清单
+
+在开发支持多实例的SDK时，请检查以下问题：
+
+- [ ] 是否使用了单例模式？
+- [ ] 是否有全局变量或全局状态？
+- [ ] 是否直接在全局对象上添加事件监听？
+- [ ] 是否创建具有相同ID的DOM元素？
+- [ ] 是否共享Web Worker？
+- [ ] 是否有全局资源缓存？
+- [ ] 是否有全局异步操作状态？
+- [ ] 是否使用全局定时器或动画帧？
+- [ ] 是否修改全局配置？
+- [ ] 是否使用全局日志或上报系统？
+
+通过解决这些问题，可以确保SDK支持多实例而不会出现互相影响的情况。
+
+---
+
+## 当前SDK中发现的问题
+
+基于对当前代码的分析，发现以下可能导致多实例互相影响的问题：
+
+1. **单例模式**：
+   - `AROptionsManager.instance`
+   - `QualityManager.instance`
+   - `GesturePipe.instance`
+   - `TextureRefManager.instance`
+
+2. **全局状态**：
+   - `resolution` 变量
+   - `window._arCustomReport` 全局函数
+
+3. **全局事件监听**：
+   - `document.addEventListener("visibilitychange")`
+   - `AROptionsManager.instance.on("mirrorChange")`
+
+4. **DOM操作冲突**：
+   - 固定ID的canvas元素：`"ar-renderer-canvas"`
+
+5. **Worker共享**：
+   - 全局Worker实例
+
+这些问题需要按照上述解决方案进行修复，以确保SDK支持多实例而不会出现互相影响的情况。