ARCHITECTURE.md

QuickBox 架构设计文档

📐 架构概述

QuickBox 采用适配器模式（Adapter Pattern），为核心设计理念，通过统一的API接口抽象各厂商的差异，为开发者提供一致的使用体验。

🏗️ 核心架构

┌─────────────────────────────────────────────────────────┐
│                    应用层 (Your App)                     │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────┐
│              QuickBox 统一API层                           │
│  ┌──────────┬──────────┬──────────┬──────────┐          │
│  │ Request  │ Storage  │ Router   │ Payment  │  ...     │
│  └──────────┴──────────┴──────────┴──────────┘          │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────┐
│              核心层 (Core Layer)                          │
│  ┌──────────────┬──────────────┬──────────────┐         │
│  │  Detector    │  Registry    │   Global     │         │
│  │ (厂商检测)    │ (适配器注册)  │ (API访问工具) │         │
│  └──────────────┴──────────────┴──────────────┘         │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────┐
│           适配器层 (Adapter Layer)                        │
│  ┌──────┬──────┬──────┬──────┬──────┐                  │
│  │ OPPO │ vivo │小米  │华为  │荣耀  │  ...              │
│  └──────┴──────┴──────┴──────┴──────┘                  │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────┐
│           厂商原生API (Native APIs)                       │
│  ┌──────────────────────────────────────────┐           │
│  │  global.system.* / global.quickapp.*      │           │
│  └──────────────────────────────────────────┘           │
└──────────────────────────────────────────────────────────┘

🔧 核心模块说明

1. Detector (厂商检测器)

位置: src/core/detector.ts

职责:

• 自动检测当前运行环境所属厂商
• 识别品牌、子品牌（如小米/红米、OPPO/一加）
• 检测框架版本和能力支持

关键方法:

detector.detect(): VendorInfo  // 检测厂商信息
isXiaomi(): boolean            // 是否为小米系
isHuaweiGroup(): boolean       // 是否为华为系

2. Registry (适配器注册中心)

位置: src/core/registry.ts

职责:

• 管理所有厂商适配器的注册
• 根据检测结果返回对应的适配器实例
• 提供适配器缓存机制

关键方法:

registry.register(vendor, AdapterClass)  // 注册适配器
registry.getAdapter(vendorInfo)          // 获取适配器

3. Global API工具

位置: src/core/global.ts

职责:

• 统一封装对快应用全局API的访问
• 提供类型安全的API访问方法
• 确保兼容性（global.system.* 和 global.quickapp.*）

关键方法:

getSystemAPI(name): any        // 获取系统API
getServiceAPI(name): any       // 获取服务API
isAPIAvailable(api, method)    // 检查API可用性

4. BaseAdapter (适配器基类)

位置: src/core/adapter.ts

职责:

• 定义适配器接口规范
• 提供默认实现（适用于大部分厂商）
• 子类只需覆盖差异部分

设计原则:

• 默认实现优先: 大部分API在各厂商间实现相同，基类提供默认实现
• 差异覆盖: 子类只需覆盖有差异的方法（如支付、登录、返回首页）
• 工具方法: 提供 getGlobalAPI、getSystemAPI 等工具方法

📦 API模块设计

统一访问模式

所有API模块遵循统一的访问模式：

export class SomeAPI {
  private static getAdapter(): IAdapter {
    return registry.getAdapter(detector.detect());
  }
  
  static async someMethod(): Promise<Result> {
    // 通过适配器访问，或直接使用global工具函数
    return this.getAdapter().someMethod();
  }
}

API分类

1. 通过适配器访问的API（需要厂商差异处理）:

   • Request、Storage、Router、Payment、Account、Ad

2. 直接访问global的API（各厂商实现一致）:

   • Device、Prompt、Share、Clipboard、WebView、Push、Calendar、App、Network

🎯 命名规范

类命名

• API类: 使用单数名词，首字母大写（如 Request, Storage, Router）
• 工具类:
  • 纯工具函数类：使用 Utils 后缀（如 ReaderUtils, ShortcutUtils）
  • 有状态管理的类：使用 Manager 后缀（如 TokenManager, ConfigManager, AppStateManager）
  • 追踪类：使用 Tracker 后缀（如 SourceTracker）

方法命名

• 静态方法: 使用动词开头（如 get, set, create, show）
• 实例方法: 使用动词开头（如 load, show, destroy）

文件命名

• 适配器: 使用厂商名小写（如 oppo.ts, huawei.ts）
• API模块: 使用功能名小写（如 request.ts, storage.ts）
• 工具模块: 使用功能名小写（如 common.ts, reader.ts）

🔄 扩展性设计

添加新厂商支持

1. 创建适配器文件 src/adapters/newvendor.ts:

export class NewVendorAdapter extends BaseAdapter {
  readonly vendor: Vendor = 'newvendor';
  readonly minVersion = 1100;
  
  // 只覆盖有差异的方法
  pay(options: PayOptions): Promise<PayResult> {
    // 新厂商特定的支付实现
  }
}

2. 在 src/index.ts 中注册:

import { NewVendorAdapter } from './adapters/newvendor';
registry.register('newvendor', NewVendorAdapter);

3. 更新 src/core/detector.ts 添加品牌识别:

const VENDOR_BRANDS = {
  // ...
  newvendor: ['newvendor', 'brand1', 'brand2']
};

添加新API

1. 创建API文件 src/api/newapi.ts:

import { getSystemAPI, isAPIAvailable } from '../core/global';

export class NewAPI {
  static async someMethod(): Promise<Result> {
    const api = getSystemAPI('newapi');
    if (!isAPIAvailable(api, 'someMethod')) {
      throw new Error('[QuickBox] NewAPI not supported');
    }
    // 实现逻辑
  }
}

2. 在 src/index.ts 中导出:

export { NewAPI } from './api/newapi';

3. 添加到默认导出对象（可选）:

const QuickBox = {
  // ...
  NewAPI,
  someMethod: NewAPI.someMethod.bind(NewAPI)
};

🚀 性能优化

1. 适配器缓存: Registry 缓存当前适配器实例，避免重复创建
2. 延迟检测: 厂商检测只在首次调用时执行
3. API可用性检查: 使用 isAPIAvailable 统一检查，避免重复代码

🔒 兼容性保证

1. 版本检测: 所有适配器明确声明 minVersion
2. 能力检测: 通过 canIUse 和 canIUseAd 检查功能支持
3. 降级处理: 不支持的功能提供友好的错误提示或降级方案
4. 统一错误: 所有错误使用 [QuickBox] 前缀，便于调试

📝 代码质量

1. TypeScript: 完整的类型定义，确保类型安全
2. 无依赖: 核心代码无外部依赖，保持轻量
3. 文档完善: 每个公共API都有JSDoc注释和使用示例
4. 测试友好: 清晰的接口设计，便于单元测试

🎨 设计原则

1. 单一职责: 每个模块只负责一个功能领域
2. 开闭原则: 对扩展开放，对修改关闭
3. 依赖倒置: 依赖抽象（IAdapter），而非具体实现
4. 接口隔离: 提供细粒度的API，避免臃肿的接口
5. DRY原则: 通过BaseAdapter和工具函数消除重复代码

🔮 未来演进

1. 插件系统: 支持第三方插件扩展功能
2. 性能监控: 内置性能监控和错误上报
3. 开发工具: 提供开发时的调试工具
4. 更多厂商: 持续支持更多厂商和功能