一、前置思考

当分布式应用从Demo演变为商业产品时，架构设计的复杂度呈指数级增长——不再是一个KVStore搞定所有同步，而是要面对：多团队协作开发、独立模块热更新、不同业务线的数据隔离、A/B测试、灰度发布等挑战。

本文聚焦：

• 分布式能力的分层架构设计（UI层/业务层/数据层/通信层）
• 模块间依赖管理与接口契约
• 分布式服务的插件化架构
• 大型项目的代码组织与团队协作规范

二、核心架构设计

2.1 分层架构

┌────────────────────────────────────────┐
│           UI Layer (各端独立)           │
│  phone_ui/  pad_ui/  pc_ui/  tv_ui/   │
├────────────────────────────────────────┤
│         Business Layer (共享)          │
│  ┌──────────┬──────────┬──────────┐   │
│  │doc模块   │media模块  │chat模块  │   │
│  │(文档协同)│(媒体播放) │(消息)    │   │
│  └──────────┴──────────┴──────────┘   │
├────────────────────────────────────────┤
│         Service Layer (HAR/HSP)        │
│  ┌─────────────────────────────────┐  │
│  │ dist-service-core.hsp           │  │
│  │ ├── SoftBusService (通信)       │  │
│  │ ├── DataSyncService (同步)      │  │
│  │ ├── AuthService (认证)          │  │
│  │ └── EventBus (事件总线)         │  │
│  └─────────────────────────────────┘  │
├────────────────────────────────────────┤
│       Data Layer (分布式数据)          │
│  ├── KVStore (键值)                   │
│  ├── RDB (关系型)                     │
│  └── DistributedFile (文件)           │
└────────────────────────────────────────┘

2.2 模块拆分方案

// 使用HSP实现服务模块化
// entry/oh-package.json5
// {
//   "dependencies": {
//     "@ohos/dist-service-core": "file:../dist-service-core"
//   }
// }

// dist-service-core/src/main/ets/services/SoftBusService.ts
export class SoftBusService {
  private static instance: SoftBusService;

  static getInstance(): SoftBusService {
    if (SoftBusService.instance === undefined) {
      SoftBusService.instance = new SoftBusService();
    }
    return SoftBusService.instance;
  }

  async connect(deviceId: string): Promise<boolean> {
    // 封装软总线连接逻辑
    return true;
  }

  async send(targetDeviceId: string, data: ArrayBuffer): Promise<void> {
    // 封装软总线发送逻辑
  }

  onDeviceFound(callback: (deviceInfo: DeviceInfo) => void): void {
    // 注册设备发现回调
  }

  onDeviceLost(callback: (deviceId: string) => void): void {
    // 注册设备丢失回调
  }
}

interface DeviceInfo {
  deviceId: string;
  deviceName: string;
  deviceType: number;
}

2.3 服务注册与发现

// 分布式服务注册中心
class ServiceRegistry {
  private services: Map<string, ServiceDescriptor> = new Map();

  // 注册服务
  register(name: string, service: Object, version: string): void {
    this.services.set(name, {
      name: name,
      service: service,
      version: version,
      registeredAt: Date.now()
    });
  }

  // 获取服务
  get<T>(name: string): T | null {
    const desc: ServiceDescriptor | undefined = this.services.get(name);
    if (desc === undefined) return null;
    return desc.service as T;
  }

  // 列出所有已注册服务
  listServices(): string[] {
    const names: string[] = [];
    const entries: MapIterator<[string, ServiceDescriptor]> =
      this.services.entries();
    for (let entry = entries.next(); !entry.done; entry = entries.next()) {
      names.push(entry.value[0] + '@' + entry.value[1].version);
    }
    return names;
  }
}

interface ServiceDescriptor {
  name: string;
  service: Object;
  version: string;
  registeredAt: number;
}

// 使用示例
const registry: ServiceRegistry = new ServiceRegistry();
registry.register('softbus', SoftBusService.getInstance(), '1.0.0');
registry.register('dataSync', DataSyncService.getInstance(), '1.0.0');
registry.register('eventBus', EventBusService.getInstance(), '1.0.0');

// 业务模块获取服务
const softbus: SoftBusService | null =
  registry.get<SoftBusService>('softbus');

三、团队协作规范

四、避坑速查

五、总结

大型分布式应用的架构原则：

1. 分层解耦：UI/业务/服务/数据 四层独立
2. HSP服务化：核心能力封装为HSP模块
3. 服务注册中心：管理分布式服务生命周期
4. 接口契约：模块间通过接口而非实现依赖