---

每日一句正能量

生活的诗意不在远方，就在这些触手可及的人间烟火里。
早餐的蒸气、市场的吆喝、傍晚的归途、窗口的灯光。真正的诗意，在于“看见”并“珍视”这些平凡瞬间里蕴含的温度与美感。

摘要

摘要：在万物互联时代，设备间的"自动发现"是构建分布式协同体验的基石。本文深入剖析 HarmonyOS 分布式软总线（DSoftBus）的设备发现机制，从分层架构、多协议协同发现原理，到 HarmonyOS 6 最新 API 的完整代码实战，再到性能优化与问题排查，带你打通分布式设备发现的全链路技术栈。

---

一、分布式设备发现的背景与挑战

1.1 传统设备互联的痛点

在 IoT 时代，设备互联已成为刚需，但传统连接方式存在诸多痛点：

• 协议碎片化：蓝牙、Wi-Fi、Zigbee、NFC……每种协议都有自己的"小圈子"，设备之间想对话，得先看"语言通不通"。你家的智能灯可能只支持 Zigbee，而手机只有蓝牙和 Wi-Fi，这就尴尬了。
• 连接复杂度高：传统蓝牙配对，你得打开设置、搜索设备、选择配对、输入 PIN 码、确认配对……一套流程下来，用户的耐心都快耗尽了。
• 跨设备通信困难：即使设备连接上了，想实现真正的跨设备调用也非易事。你需要在应用层自己实现消息序列化、传输协议、错误重试、连接保活……这工作量，谁写谁知道。

1.2 HarmonyOS 的解法：分布式软总线

HarmonyOS 的分布式软总线（DSoftBus），本质上是一个统一的设备通信抽象层。它就像一个"万能翻译官"，屏蔽了底层各种通信协议的差异，为上层提供统一的设备发现、连接、数据传输能力。

软总线的核心价值：

• 自动发现：设备上电后自动广播，其他设备自动感知，无需手动搜索
• 自动连接：基于设备信任关系，自动选择最优通信通道建立连接
• 统一接口：上层应用无需关心底层协议，一套 API 搞定所有通信场景
• 智能切换：根据场景自动在蓝牙、Wi-Fi 等通道间切换，保证最佳体验

DSoftBus 的设计遵循统一抽象、无感连接、安全可靠、高效传输四大核心理念，其系统架构采用分层设计，核心组件包括设备发现模块、连接管理模块和数据传输模块。

---

二、DSoftBus 设备发现核心架构

2.1 整体架构设计

分布式软总线采用分层架构设计，位于 HarmonyOS 系统服务层，为上层应用提供统一的分布式通信能力。

图1：DSoftBus 分布式软总线分层架构

如上图所示，DSoftBus 架构从下至上分为五层：

层级	核心职责	关键组件
应用层 API	提供统一的分布式接口	DeviceDiscoveryManager、ConnectionManager、SessionManager
服务层	设备发现、连接管理、数据路由、安全认证	Discovery、Connection、Routing、Auth 四大模块
协议层	统一通信协议和极简协议栈	CoAP（发现协议）、TCP/UDP（传输协议）、TLS/DTLS（安全协议）、JSON/CBOR（序列化）
传输层	整合多物理传输能力	Wi-Fi P2P/STA、蓝牙 BLE/BR/EDR、SLE（星闪）、5G/NFC
物理层	硬件射频基础	Wi-Fi 芯片、蓝牙模组、星闪模组

这种分层设计使得上层应用无需关心底层网络细节，只需关注业务逻辑实现。

2.2 设备发现模块（Discovery Module）

设备发现模块是 DSoftBus 的入口环节，负责检测附近的 HarmonyOS 设备。它使用 CoAP 等协议进行轻量级和可靠的传输，实现了设备间的自动识别和可达性建立。

设备发现是分布式软总线的入口环节，实现了设备间的自动识别和可达性建立。HarmonyOS 的设备发现机制基于近场感知和身份关联两大技术支柱。

---

三、设备发现机制深度解析

3.1 发现流程全景

分布式设备发现的完整流程涉及"发现方"与"被发现方"的双向交互，如下图所示：

图2：分布式设备发现完整流程

整个流程可分为六个阶段：

阶段一：服务发布（Publish）

设备 B（被发现方）调用 publishService() 发布自身服务能力，构建 PublishInfo 编码设备能力信息（设备类型、支持协议、认证方式等），并通过 BLE 广播帧或 Wi-Fi 组播发送信标包。

阶段二：发现订阅（Subscribe）

设备 A（发现方）调用 startDeviceDiscovery() 启动发现服务，构建 SubscribeInfo 配置发现参数（设备类型过滤、发现频率、超时时间等）。

阶段三：媒介扫描（Scan）

disc_mgr 将发现请求分发到具体媒介适配器（Wi-Fi/BLE/BR/SLE），在指定媒介上启动扫描或监听。

阶段四：信息匹配与响应

当设备 A 收到设备 B 的广播包后，解析其中的 Capability 信息，与本地 SubscribeInfo 中的过滤器进行匹配。命中后，通过 CoAP 协议发送发现请求（CON 消息），设备 B 返回 ACK 响应并携带完整的 DeviceInfo。

阶段五：身份认证

发现完成后，设备 A 调用 authenticate() 发起设备认证。双方通过 TLS/DTLS 握手建立端到端加密通道，基于华为账号体系进行多因素身份验证。

阶段六：连接建立

认证通过后，连接管理模块自动选择最优传输路径（Wi-Fi P2P > Wi-Fi STA > 蓝牙 BR/EDR > BLE），建立 Session 会话，设备进入 CONNECTED 状态。

3.2 多协议协同发现机制

DSoftBus 的核心优势在于多协议协同发现——同时利用蓝牙 BLE 广播和 Wi-Fi 组播来最大化发现效率。

图3：多协议协同发现机制

disc_mgr 作为发现管理器的核心，负责将业务层的 PublishLNN / RefreshLNN 请求分发到四个媒介适配器：

适配器	发现方式	适用场景	特点
Wi-Fi 适配器	P2P / Broadcast 组播	大文件传输、屏幕投屏	带宽大、发现范围广
BLE 适配器	Advertisement 广播扫描	低功耗设备、可穿戴设备	功耗低、响应快
BR 适配器	SDP 记录（蓝牙经典）	音频传输、控制指令	连接稳定、兼容性好
SLE 适配器	星闪广播帧	低时延场景、工业控制	超低时延、抗干扰强

业务进程调用 PublishLNN(pkgName, &PublishInfo, &cb) 后，disc_mgr 根据 medium 分发到具体媒介适配器。对端设备 discovery 接收后，解码 capability，匹配 SubscribeInfo.capability 过滤器，命中后通过 OnDeviceFound 回调上送。

广播包内容：设备 ID、设备类型、设备名称、支持的通信协议、认证能力等关键信息被编码进广播包。为了节省 BLE 广播的 31 字节限制，HarmonyOS 采用了压缩编码 + 分包传输的策略。

3.3 设备发现状态机

理解设备发现的状态流转，对于排查问题和设计健壮的业务逻辑至关重要。

图4：设备发现状态机

状态机包含六个核心状态：

• IDLE（空闲）：初始状态，未启动发现
• DISCOVERING（发现中）：正在扫描周围设备，支持 BLE / Wi-Fi / SLE 多通道并行扫描
• DEVICE_FOUND（设备已发现）：发现匹配设备，等待认证决策
• AUTHENTICATING（认证中）：正在进行设备身份认证（TLS/DTLS 握手）
• CONNECTED（已连接）：认证通过，连接建立，可进行分布式通信，同时启动心跳保活
• FAILED（失败）：认证失败或超时，可重试或终止

---

四、代码实战：基于 HarmonyOS 6 的分布式设备发现

4.1 权限配置

在 module.json5 中声明分布式设备发现所需的权限：

{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.DISTRIBUTED_DATASYNC",
        "reason": "$string:permission_distributed_sync"
      },
      {
        "name": "ohos.permission.ACCESS_BLUETOOTH",
        "reason": "$string:permission_bluetooth"
      },
      {
        "name": "ohos.permission.ACCESS_WIFI_STATE",
        "reason": "$string:permission_wifi_state"
      },
      {
        "name": "ohos.permission.GET_WIFI_INFO",
        "reason": "$string:permission_wifi_info"
      }
    ]
  }
}

同时需要在应用启动时动态申请权限：

import { abilityAccessCtrl, Permissions } from '@kit.AbilityKit';

const permissions: Permissions[] = [
  'ohos.permission.DISTRIBUTED_DATASYNC',
  'ohos.permission.ACCESS_BLUETOOTH'
];

async function requestPermissions(): Promise<boolean> {
  const atManager = abilityAccessCtrl.createAtManager();
  const authResults = await atManager.requestPermissionsFromUser(
    getContext(), permissions
  );
  return authResults.authResults.every(result => result === 0);
}

4.2 设备发现管理器封装

以下是一个生产级的设备发现管理器封装，支持 HarmonyOS 6 最新 API：

import { DeviceDiscoveryManager, DeviceInfo, SubscribeInfo } 
  from '@ohos.distributedHardware.deviceManager';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const TAG = 'DeviceDiscovery';
const DOMAIN = 0xFF00;

/**
 * 分布式设备发现管理器
 * 封装 DSoftBus 设备发现能力，支持多协议协同发现
 */
export class DistributedDiscoveryManager {
  private discoveryManager: DeviceDiscoveryManager | null = null;
  private discoveredDevices: Map<string, DeviceInfo> = new Map();
  private discoveryCallbacks: Array<(device: DeviceInfo) => void> = [];
  private isDiscovering: boolean = false;
  private subscribeId: string = '';

  /**
   * 初始化设备发现服务
   */
  async initialize(): Promise<boolean> {
    try {
      this.discoveryManager = DeviceDiscoveryManager.create();
      
      // 注册设备发现监听器
      this.discoveryManager.on('deviceFound', (device: DeviceInfo) => {
        this.onDeviceFound(device);
      });
      
      this.discoveryManager.on('deviceLost', (deviceId: string) => {
        this.onDeviceLost(deviceId);
      });

      hilog.info(DOMAIN, TAG, '设备发现服务初始化成功');
      return true;
    } catch (error) {
      const err = error as BusinessError;
      hilog.error(DOMAIN, TAG, `初始化失败: ${err.message}`);
      return false;
    }
  }

  /**
   * 开始设备发现
   * @param options 发现配置选项
   */
  async startDiscovery(options: DiscoveryOptions = {}): Promise<boolean> {
    if (!this.discoveryManager || this.isDiscovering) {
      hilog.warn(DOMAIN, TAG, '发现管理器未初始化或已在发现中');
      return false;
    }

    try {
      // 清空历史发现记录
      this.discoveredDevices.clear();

      const subscribeInfo: SubscribeInfo = {
        subscribeId: this.generateSubscribeId(),
        mode: options.mode ?? 'DISCOVER_MODE_ACTIVE',
        medium: options.medium ?? 'AUTO',
        freq: options.freq ?? 'MID',
        isSameAccount: options.isSameAccount ?? false,
        isWakeRemote: options.isWakeRemote ?? true,
        capability: options.capability ?? 'osdCapability'
      };

      this.subscribeId = subscribeInfo.subscribeId;
      await this.discoveryManager.startDeviceDiscovery(subscribeInfo);
      this.isDiscovering = true;

      hilog.info(DOMAIN, TAG, 
        `开始设备发现: mode=${subscribeInfo.mode}, medium=${subscribeInfo.medium}`);
      
      // 设置超时自动停止
      if (options.timeout && options.timeout > 0) {
        setTimeout(() => this.stopDiscovery(), options.timeout);
      }
      
      return true;
    } catch (error) {
      const err = error as BusinessError;
      hilog.error(DOMAIN, TAG, `启动发现失败: ${err.message}`);
      return false;
    }
  }

  /**
   * 停止设备发现
   */
  async stopDiscovery(): Promise<void> {
    if (!this.discoveryManager || !this.isDiscovering) {
      return;
    }

    try {
      await this.discoveryManager.stopDeviceDiscovery(this.subscribeId);
      this.isDiscovering = false;
      hilog.info(DOMAIN, TAG, '设备发现已停止');
    } catch (error) {
      const err = error as BusinessError;
      hilog.error(DOMAIN, TAG, `停止发现失败: ${err.message}`);
    }
  }

  /**
   * 设备发现回调处理
   */
  private onDeviceFound(device: DeviceInfo): void {
    // 使用设备ID去重，避免多协议重复上报
    if (this.discoveredDevices.has(device.deviceId)) {
      hilog.debug(DOMAIN, TAG, `设备已存在，更新信息: ${device.deviceName}`);
      this.discoveredDevices.set(device.deviceId, device);
      return;
    }

    hilog.info(DOMAIN, TAG,
      `发现新设备: name=${device.deviceName}, type=${device.deviceType}, ` +
      `id=${device.deviceId.substring(0, 8)}...`);

    this.discoveredDevices.set(device.deviceId, device);

    // 通知所有注册的回调
    this.discoveryCallbacks.forEach(callback => {
      try {
        callback(device);
      } catch (error) {
        hilog.error(DOMAIN, TAG, `回调执行异常: ${error}`);
      }
    });
  }

  /**
   * 设备离线处理
   */
  private onDeviceLost(deviceId: string): void {
    if (this.discoveredDevices.has(deviceId)) {
      const device = this.discoveredDevices.get(deviceId);
      hilog.info(DOMAIN, TAG, `设备离线: ${device?.deviceName}`);
      this.discoveredDevices.delete(deviceId);
    }
  }

  /**
   * 注册设备发现回调
   */
  onDeviceFound(callback: (device: DeviceInfo) => void): void {
    this.discoveryCallbacks.push(callback);
  }

  /**
   * 获取已发现设备列表
   */
  getDiscoveredDevices(): DeviceInfo[] {
    return Array.from(this.discoveredDevices.values());
  }

  /**
   * 按设备类型过滤
   */
  filterByType(deviceType: string): DeviceInfo[] {
    return this.getDiscoveredDevices().filter(d => d.deviceType === deviceType);
  }

  /**
   * 释放资源
   */
  release(): void {
    this.stopDiscovery();
    this.discoveryCallbacks = [];
    this.discoveredDevices.clear();
    this.discoveryManager = null;
    hilog.info(DOMAIN, TAG, '设备发现管理器已释放');
  }

  private generateSubscribeId(): string {
    return `sub_${Date.now()}_${Math.random().toString(36).substring(2, 8)}`;
  }
}

/**
 * 发现配置选项
 */
interface DiscoveryOptions {
  mode?: 'DISCOVER_MODE_ACTIVE' | 'DISCOVER_MODE_PASSIVE';
  medium?: 'AUTO' | 'BLE' | 'COAP' | 'USB' | 'BLE_SLE';
  freq?: 'LOW' | 'MID' | 'HIGH' | 'SUPER_HIGH';
  isSameAccount?: boolean;
  isWakeRemote?: boolean;
  capability?: string;
  timeout?: number;
}

4.3 场景化发现策略配置

不同场景对设备发现的频率、范围和功耗有不同的要求。以下是按场景配置发现策略的示例：

/**
 * 场景化发现策略工厂
 */
export class DiscoveryStrategyFactory {
  
  /**
   * 智能家居场景：低频扫描，关注家电设备
   */
  static smartHome(): DiscoveryOptions {
    return {
      mode: 'DISCOVER_MODE_PASSIVE',  // 被动发现，节能
      medium: 'AUTO',
      freq: 'LOW',                    // 低频扫描
      isSameAccount: true,            // 同账号设备
      isWakeRemote: false,
      timeout: 60000                  // 持续1分钟
    };
  }

  /**
   * 办公协同场景：高频扫描，快速发现手机/平板/PC
   */
  static officeCollaboration(): DiscoveryOptions {
    return {
      mode: 'DISCOVER_MODE_ACTIVE',   // 主动发现
      medium: 'AUTO',
      freq: 'HIGH',                   // 高频扫描
      isSameAccount: false,           // 允许跨账号
      isWakeRemote: true,             // 唤醒远程设备
      timeout: 15000                  // 持续15秒
    };
  }

  /**
   * 车载场景：BLE优先，低功耗发现
   */
  static carScenario(): DiscoveryOptions {
    return {
      mode: 'DISCOVER_MODE_ACTIVE',
      medium: 'BLE',                  // 优先蓝牙
      freq: 'MID',
      isSameAccount: true,
      isWakeRemote: true,
      timeout: 30000
    };
  }

  /**
   * 星闪低时延场景：SLE优先
   */
  static sleLowLatency(): DiscoveryOptions {
    return {
      mode: 'DISCOVER_MODE_ACTIVE',
      medium: 'BLE_SLE',              // 星闪协议
      freq: 'SUPER_HIGH',             // 超高频
      isSameAccount: true,
      isWakeRemote: true,
      timeout: 10000
    };
  }
}

4.4 使用示例

// 初始化发现管理器
const discoveryManager = new DistributedDiscoveryManager();
await discoveryManager.initialize();

// 注册发现回调
discoveryManager.onDeviceFound((device: DeviceInfo) => {
  console.info(`新设备: ${device.deviceName} [${device.deviceType}]`);
  // 更新UI或自动连接
});

// 根据场景选择策略
const strategy = DiscoveryStrategyFactory.officeCollaboration();
await discoveryManager.startDiscovery(strategy);

// 获取已发现设备
const devices = discoveryManager.getDiscoveredDevices();
console.info(`共发现 ${devices.length} 台设备`);

// 页面销毁时释放资源
// discoveryManager.release();

---

五、性能优化与最佳实践

5.1 发现性能优化

在实际应用中，设备发现需要平衡发现速度和能耗：

/**
 * 智能发现优化器
 * 基于历史记录和场景感知的自适应发现策略
 */
export class SmartDiscoveryOptimizer {
  private discoveryManager: DistributedDiscoveryManager;
  private discoveryHistory: Map<string, number> = new Map();

  constructor(manager: DistributedDiscoveryManager) {
    this.discoveryManager = manager;
  }

  /**
   * 两阶段智能发现
   * 第一阶段：高频快速发现（10秒）
   * 第二阶段：低频节能维持（间歇扫描）
   */
  async startSmartDiscovery(): Promise<void> {
    // 阶段一：快速发现
    hilog.info(DOMAIN, TAG, '阶段一：快速发现模式');
    await this.discoveryManager.startDiscovery({
      mode: 'DISCOVER_MODE_ACTIVE',
      freq: 'HIGH',
      timeout: 10000
    });

    // 阶段二：切换为节能模式
    setTimeout(async () => {
      hilog.info(DOMAIN, TAG, '阶段二：节能维持模式');
      await this.startLowPowerDiscovery();
    }, 10000);
  }

  /**
   * 低功耗间歇发现
   * 每30秒扫描3秒，大幅降低功耗
   */
  private async startLowPowerDiscovery(): Promise<void> {
    const intervalId = setInterval(async () => {
      await this.discoveryManager.startDiscovery({
        mode: 'DISCOVER_MODE_PASSIVE',
        freq: 'LOW',
        timeout: 3000
      });
    }, 30000);

    // 保存intervalId以便清理
    return intervalId as unknown as void;
  }

  /**
   * 预测性发现：基于历史使用模式优化
   */
  setupPredictiveDiscovery(): void {
    const hour = new Date().getHours();
    let config: DiscoveryOptions;

    if (hour >= 9 && hour <= 18) {
      // 工作时间：办公场景
      config = DiscoveryStrategyFactory.officeCollaboration();
    } else if (hour >= 19 && hour <= 23) {
      // 晚间：智能家居场景
      config = DiscoveryStrategyFactory.smartHome();
    } else {
      // 深夜：节能模式
      config = { mode: 'DISCOVER_MODE_PASSIVE', freq: 'LOW', timeout: 5000 };
    }

    this.discoveryManager.startDiscovery(config);
  }
}

5.2 关键优化建议

优化方向	具体措施	预期效果
设备去重	使用 deviceId 作为唯一键，多协议上报时合并	避免列表重复，提升UI体验
超时控制	设置合理的发现超时（10~30秒）	防止长时间扫描导致功耗过高
频率调节	根据场景动态调整扫描频率	平衡发现速度与电量消耗
缓存复用	缓存已发现设备信息，增量更新	减少重复扫描，提升响应速度
权限最小化	仅申请必要的分布式权限	降低用户隐私顾虑，提升通过率
生命周期管理	页面销毁时及时释放资源	避免内存泄漏和后台耗电

---

六、常见问题与排查

6.1 发现不到设备

现象：调用 startDeviceDiscovery() 后，onDeviceFound 始终未触发。

排查清单：

1. 权限检查：确认 module.json5 中已声明 ohos.permission.DISTRIBUTED_DATASYNC 和 ohos.permission.ACCESS_BLUETOOTH，且运行时权限已授权。

2. 网络环境：确保两台设备处于同一局域网（Wi-Fi 发现场景），或蓝牙已开启（BLE 发现场景）。

3. 账号限制：如果设置了 isSameAccount: true，确认两台设备登录了同一华为账号。

4. 设备类型过滤：检查 SubscribeInfo 中的 capability 是否与被发现的 PublishInfo 匹配。

5. 日志排查：抓取 hilog 中 DSoftBus 相关日志，查看 disc_mgr 是否正常分发到媒介适配器。

// 快速诊断函数
async function diagnoseDiscovery(): Promise<string[]> {
  const issues: string[] = [];
  
  // 检查权限
  const hasPermission = await checkDistributedPermission();
  if (!hasPermission) issues.push('缺少分布式同步权限');
  
  // 检查蓝牙状态
  const bluetoothEnabled = await checkBluetoothState();
  if (!bluetoothEnabled) issues.push('蓝牙未开启');
  
  // 检查Wi-Fi状态
  const wifiConnected = await checkWifiConnection();
  if (!wifiConnected) issues.push('Wi-Fi未连接');
  
  return issues;
}

6.2 设备列表重复

现象：同一设备在列表中出现多次。

根因：设备同时通过 BLE 和 Wi-Fi 被发现，导致重复上报。

解决方案：

// ✅ 正确做法：使用 deviceId 去重
private deviceMap = new Map<string, DeviceInfo>();

onDeviceFound(device: DeviceInfo): void {
  if (!this.deviceMap.has(device.deviceId)) {
    this.deviceMap.set(device.deviceId, device);
    updateDeviceList(Array.from(this.deviceMap.values()));
  }
}

6.3 发现后连接失败

现象：设备已发现，但 authenticate() 或 connect() 失败。

排查方向：

• 检查设备是否已完成首次配对（部分场景需要手动确认）
• 确认设备间的网络连通性（防火墙、路由器隔离等）
• 查看认证日志，确认 TLS/DTLS 握手是否成功
• 检查设备时间是否同步（证书验证依赖正确的时间）

---

七、总结

分布式设备发现是 HarmonyOS “超级终端” 体验的技术基石。通过本文的深入讲解，我们从 DSoftBus 的分层架构出发，剖析了多协议协同发现的核心机制，梳理了从服务发布到连接建立的完整状态机，并提供了基于 HarmonyOS 6 最新 API 的生产级代码实战。

核心要点回顾：

1. 架构理解：DSoftBus 通过分层设计屏蔽底层协议差异，应用层只需关注业务逻辑
2. 发现机制：多协议协同（BLE + Wi-Fi + SLE）最大化发现效率，CoAP 轻量级协议承载发现信令
3. 状态管理：掌握 IDLE → DISCOVERING → DEVICE_FOUND → AUTHENTICATING → CONNECTED 的完整状态流转
4. 场景适配：根据智能家居、办公协同、车载等不同场景，配置差异化的发现策略
5. 性能优化：两阶段发现（快速 + 节能）、设备去重、生命周期管理是生产环境的关键
6. 问题排查：权限、网络、账号、Capability 匹配是发现失败的四大根因

掌握分布式设备发现，你就掌握了 HarmonyOS 分布式开发的"第一张门票"。从设备发现出发，后续的分布式数据管理、分布式任务调度、分布式硬件虚拟化都将水到渠成。

---

本文属于技术实战系列第四百五十二篇，承接前篇《包体积监控》，后续将继续深入分布式连接管理与数据传输实战。

---

转载自：https://blog.csdn.net/u014727709/article/details/164063855
欢迎 👍点赞✍评论⭐收藏，欢迎指正