HarmonyOS 分布式数据同步完整架构
时间: 2026-04-15 11:22:32
(部分内容来自网络，其真实性存疑，为了避免对您造成误导，请谨慎甄别。)
好，不废话。给你完整的架构图，你自己选。
一、HarmonyOS 分布式数据同步完整架构
从底层到上层，一共 4 层：
┌─────────────────────────────────────────────────────────────────┐
│ 应用层 (Your App) │
├─────────────────────────────────────────────────────────────────┤
│ 开发者接口层 (JS/TS API) │
├──────────────────┬──────────────────┬──────────────────────────┤
│ 分布式数据对象 │ 分布式KVStore │ 分布式关系型数据库(RDB) │
│ (DDO) │ (Single/Device) │ (本地 + 手动同步) │
├──────────────────┴──────────────────┴──────────────────────────┤
│ 数据管理服务 (DatamgrService) │
│ - 同步引擎 - 冲突解决 - 版本控制 │
├─────────────────────────────────────────────────────────────────┤
│ 分布式软总线 (Soft Bus) │
│ - 设备发现 - 连接管理 - 数据传输 │
└─────────────────────────────────────────────────────────────────┘
二、各层详细说明
第1层：应用层
就是你写的代码。调用什么API，传什么数据，处理什么回调。
第2层：开发者接口层（你要选的，一共3个）
| 接口 | 数据形态 | 存储位置 | 生命周期 | 同步方式 | 适合什么 |
|---|---|---|---|---|---|
| 分布式数据对象 (DDO) | JS对象属性 | 内存 | 应用退出即丢 | 实时自动同步 | 实时状态、光标位置、播放进度 |
| 分布式KVStore | 键值对 | 磁盘 | 持久化 | 手动/自动可配 | 配置、设置、结构化数据 |
| 分布式RDB | SQL表 | 磁盘 | 持久化 | 需自己实现 | 复杂查询的大数据量 |
第3层：数据管理服务 (DatamgrService)
- 接收上层接口的同步请求
- 管理同步队列、处理冲突、控制版本
- 与软总线通信收发数据
第4层：分布式软总线
- 设备发现 (基于Wi-Fi/蓝牙)
- 设备认证 (同账号)
- 底层数据传输
三、这3个接口的具体差异（你要选哪个）
1. 分布式数据对象 (DDO)
import { distributedDataObject } from '@kit.ArkData';
// 创建
let obj = distributedDataObject.createDistributedObject({
title: '标题',
content: '内容',
progress: 0
});
// 设置sessionId（同ID自动组网同步）
obj.setSessionId('my_session_123');
// 修改自动同步到其他设备
obj.title = '新标题'; // 这行一执行，其他设备马上收到变化
// 监听其他设备的修改
obj.on('change', (sessionId, fields) => {
console.log('变化字段:', fields);
console.log('新标题:', obj.title);
});特点：
- 数据在内存里，应用退出就没了
- 修改属性就自动同步，不用调任何发送方法
- 单个对象不超过 500KB（协同场景）
适合： 实时协同编辑的光标位置、播放器的播放进度、游戏中的实时状态
2. 分布式KVStore
import { distributedKVStore } from '@kit.ArkData';
// 创建KVManager
let kvManager = distributedKVStore.createKVManager({
context: this.context,
bundleName: 'com.example.app'
});
// 获取KVStore（两种类型）
let kvStore = await kvManager.getKVStore('store_name', {
kvStoreType: distributedKVStore.KVStoreType.SINGLE_VERSION, // 或 DEVICE_COLLABORATION
autoSync: true // 自动同步
});
// 写数据
await kvStore.put('key_name', 'value_content');
// 读数据
let value = await kvStore.get('key_name');
// 监听远端变化
kvStore.on('dataChange',
distributedKVStore.SubscribeType.SUBSCRIBE_TYPE_REMOTE,
(data) => { console.log('远端改了:', data); }
);两种KVStore的区别：
| 类型 | 行为 | 适合场景 |
|---|---|---|
| SINGLE_VERSION | 同key后写覆盖 | 全局配置、主题设置 |
| DEVICE_COLLABORATION | 按设备分片，互不覆盖 | 图库缩略图、各设备独立数据 |
特点：
- 数据存在磁盘上，应用退出还在
- 支持手动/自动同步
- 没有大小限制（磁盘够就行）
适合： 用户设置、待办清单、笔记内容、联系人
3. 分布式RDB（关系型数据库）
import { relationalStore } from '@kit.ArkData';
// 创建本地RDB
let store = await relationalStore.getRdbStore(context, {
name: 'my_data.db',
securityLevel: relationalStore.SecurityLevel.S1
});
// 增删改查（本地）
await store.insert('users', { name: '张三', age: 25 });
// 跨设备同步需要自己实现
// 方案1：把变更数据写到KVStore，另一端收到后写RDB
// 方案2：用DDO传SQL语句特点：
- RDB本身不支持自动跨设备同步
- 需要自己用KVStore或DDO来传数据，另一端收到后写本地RDB
适合： 需要复杂SQL查询的场景，且你能自己处理同步逻辑
四、选型决策树（你自己对着选）
你要做什么？
│
├─ 实时状态同步（光标、播放进度、开关状态）
│ └─ 数据丢了无所谓？ → 分布式数据对象 (DDO)
│
├─ 结构化数据同步（配置、待办、笔记）
│ └─ 需要持久化存盘？ → 分布式KVStore
│ ├─ 多端共用一个值（主题色、语言） → SINGLE_VERSION
│ └─ 各端独立维护自己的数据（图库缩略图） → DEVICE_COLLABORATION
│
├─ 需要SQL查询大数据
│ └─ 自己处理同步逻辑 → RDB本地 + KVStore传变更
│
└─ 传大文件（图片、视频）
└─ 用分布式文件系统 (distributedFilesDir) + 资产(Asset)机制
五、传数据/文件的最稳妥组合
根据你的需求（设备间传数据/文件），我的建议：
| 数据大小 | 推荐方案 | 原因 |
|---|---|---|
| < 500KB 且可接受内存存储 | DDO | 代码最少，实时性最高 |
| < 500KB 且需要持久化 | KVStore (SINGLE_VERSION) | 存磁盘，自动同步，稳 |
| 大文件（图片、视频） | 分布式文件 + Asset | KVStore只传文件路径，文件本体走资产同步 |
代码示例（大文件方案）：
// 1. 把文件放到分布式目录 let context = getContext(); let distributedDir = context.distributedFilesDir; let filePath = distributedDir + '/photo.jpg'; // ... 把文件写到这里
// 2. 用KVStore只传文件路径 await kvStore.put('asset_path', 'photo.jpg');
// 3. 另一端收到路径，从分布式目录读取 let remotePath = await kvStore.get('asset_path'); let file = fs.openSync(distributedDir + '/' + remotePath);
现在你可以自己选了： 你的数据多大？要不要存盘？实时性要求多高？
