精准碰一碰把设备发现、目标选择和内容交接压缩成一个很自然的动作。真正进入持续迭代后，麻烦却常常出现在“内容已经送到，对端还是拒绝打开”这一步。发送端刚升级到第三版载荷，接收端还停在第二版；网络没有失败，UDMF 记录也能读到，失败发生在业务字段的解释上。

本文使用演示项目 TapEnvelope 的 HandoffInspectPage 说明一条克制的兼容链路。任务编号为 TAP-SCHEMA-0058，发送端载荷版本为 v3，接收端支持 [v1, v2]。双方最终协商到 v2，丢弃两个仅在 v3 中使用的可选字段 previewTheme 与 hapticPattern，状态按 RECEIVED → NEGOTIATED(v2) → ACCEPTED 推进。UDMF 中只写入一条 PlainText 记录，演示体积为 1.8 KB。这些数据来自确定性演示夹具，不冒充真实设备互碰测试。

一、版本不一致不是传输错误

业务层最容易做出的错误判断，是把“JSON 解析成功”当成“载荷可消费”。JSON 只证明字节能转成对象，不证明字段语义一致。v3 发送端可能新增预览主题、触觉样式和展示策略；v2 接收端不知道这些字段，却仍能处理资源编号和动作类型。若接收端看到 schemaVersion=3 就整体拒绝，一次可降级的交接会被包装成传输失败。

反方向也一样危险。为了追求兼容，直接忽略所有未知字段，看似宽松，实际上会掩盖必填语义变化。假设 v3 把 action=open 改成必须携带目标槽位，v2 接收端若仍按旧规则打开默认页面，结果可能不是报错，而是落到错误业务对象。兼容策略必须区分三件事：哪些字段是各版本都要理解的核心字段，哪些是可以丢弃的增强字段，哪些变化会改变动作含义并要求拒绝。

TapEnvelope 把交接拆为四层。最外层是精准碰一碰的传输适配器；第二层是 UDMF 标准化记录；第三层是业务信封；第四层才是页面动作。本文不虚构某个公开资料没有提供的精准碰一碰底层接口，而是假设传输适配器已经把 UnifiedData 交给接收页，重点只放在 UDMF 与业务协议边界。

任务 TAP-SCHEMA-0058 的核心字段为 resourceId=board-7421、action=OPEN_DETAIL、nonce=N-0058-A7、issuedAt=1790802600。其中 nonce 用来关联一次交接，不在本文中承担完整防重放语义。完整防重放还需要可信时钟、持久化窗口与身份校验，不能因为字段名字叫 nonce 就声称安全问题已经解决。

二、先把兼容规则写成数据，再写解析分支

版本判断若散落在页面的多个 if 中，第三版上线后很快会出现“列表页能降级、详情页不能降级”的分裂。更稳的做法是为每个版本声明必填字段、可选字段和动作集合，并让协商函数只返回一个明确结果。

这段代码解决什么问题：在发送端版本与接收端能力之间选择共同版本，并明确记录被降级的可选字段。

type SchemaVersion = 1 | 2 | 3

interface TapEnvelope {
  schemaVersion: SchemaVersion
  minReaderVersion: SchemaVersion
  taskId: string
  resourceId: string
  action: 'OPEN_DETAIL' | 'ADD_TO_BOARD'
  nonce: string
  issuedAt: number
  previewTheme?: string
  hapticPattern?: string
}

interface NegotiationResult {
  accepted: boolean
  selectedVersion?: SchemaVersion
  droppedFields: string[]
  reason?: string
}

function negotiate(
  envelope: TapEnvelope,
  readerVersions: SchemaVersion[]
): NegotiationResult {
  const candidates = readerVersions
    .filter((version) => version >= envelope.minReaderVersion)
    .filter((version) => version <= envelope.schemaVersion)
    .sort((a, b) => b - a)

  const selected = candidates[0]
  if (selected === undefined) {
    return { accepted: false, droppedFields: [], reason: 'NO_COMMON_VERSION' }
  }

  const dropped: string[] = []
  if (selected < 3 && envelope.previewTheme !== undefined) dropped.push('previewTheme')
  if (selected < 3 && envelope.hapticPattern !== undefined) dropped.push('hapticPattern')
  return { accepted: true, selectedVersion: selected, droppedFields: dropped }
}

演示信封的 schemaVersion=3，minReaderVersion=2，接收端声明 [1,2]，因此共同版本只能是 2。结果中的 droppedFields 为两个字段，页面可以明确告诉开发者发生了能力降级，而不是默默吞掉差异。

minReaderVersion 是协议作者对最低语义的承诺。如果某次升级改变了核心动作，发送端可把它提升到 3，旧接收端会得到 NO_COMMON_VERSION。这比解析到一半才发现字段缺失更清楚，也便于日志聚合。易错点是把应用版本号当协议版本号：应用 2.8.0 与信封 v3 不应绑定，否则灰度、热修和多模块演进会把兼容矩阵变得不可维护。

实际项目还要冻结每个版本的字段含义。可以新增可选字段，不能在原字段名下偷偷改变单位或枚举含义。若 issuedAt 从秒改成毫秒，应增加新字段或提升不兼容版本，不能靠“数值看起来很大”猜测。

三、UDMF 负责标准化承载，业务信封负责语义

UDMF 的价值是把跨应用数据包装为统一数据对象，并提供标准数据类型与通路。本文使用 general.plain-text 承载 JSON 信封，不是因为 JSON 天然安全，而是它便于演示、诊断和版本化。UDMF 记录描述“这是一段文本数据”，业务信封描述“这段文本如何驱动碰一碰交接”，两层职责不能混在一起。

这段代码解决什么问题：把版本化业务信封封装成一条 UDMF PlainText 记录，并写入 DATA_HUB 通路。

import {
  unifiedDataChannel,
  uniformDataStruct,
  uniformTypeDescriptor
} from '@kit.ArkData'

async function publishEnvelope(envelope: TapEnvelope): Promise<string> {
  const plainText: uniformDataStruct.PlainText = {
    uniformDataType: 'general.plain-text',
    textContent: JSON.stringify(envelope),
    abstract: `TapEnvelope ${envelope.taskId}`,
    details: {
      protocol: 'com.example.tap-envelope',
      schemaVersion: `${envelope.schemaVersion}`,
      taskId: envelope.taskId
    }
  }
  const record = new unifiedDataChannel.UnifiedRecord(
    uniformTypeDescriptor.UniformDataType.PLAIN_TEXT,
    plainText
  )
  const data = new unifiedDataChannel.UnifiedData(record)
  data.properties.tag = `tap:${envelope.taskId}`

  const options: unifiedDataChannel.Options = {
    intention: unifiedDataChannel.Intention.DATA_HUB
  }
  return await unifiedDataChannel.insertData(options, data)
}

这里使用了官方文档中的 UnifiedRecord、UnifiedData 与 insertData() 组合。details 里的字段用于快速诊断，真正的权威内容仍是 textContent。不能只改 details 中的版本号而忘记正文；生产实现可以在编码器中一次性生成两者，并在读取时检查一致性。

insertData() 返回的 key 是 UDMF 通路记录标识，不等于业务任务 ID。演示中日志可显示形如 udmf://DataHub/.../0058 的 key，但业务去重、重试和页面状态仍围绕 TAP-SCHEMA-0058。不要把生命周期不同的两个标识互相替代。

数据写入成功只代表通路接受了对象。发送端还应处理参数错误、系统服务异常和生命周期取消。若页面离开后异步写入才返回，不能继续弹出“等待碰一碰”的 UI。本文把 key 返回给调用者，由更外层会话决定是否仍消费结果。

四、接收端先验类型，再验结构，最后才协商

读取路径不能从 JSON.parse() 开始。一个 UnifiedData 可能包含多条记录，也可能没有 PlainText；类型不符时应明确返回 UNSUPPORTED_RECORD_TYPE。取得文本后再做长度上限、JSON 解析、字段类型和枚举验证，最后进入版本协商。顺序越清楚，失败原因越可观测。

这段代码解决什么问题：从 UnifiedData 中提取 PlainText 信封，对关键字段做运行时校验，拒绝“能解析但不可执行”的对象。

function readEnvelope(data: unifiedDataChannel.UnifiedData): TapEnvelope {
  const record = data.getRecords().find((item) =>
    item.getTypes().includes(uniformTypeDescriptor.UniformDataType.PLAIN_TEXT)
  )
  if (!record) throw new Error('UNSUPPORTED_RECORD_TYPE')

  const entry = record.getEntry(
    uniformTypeDescriptor.UniformDataType.PLAIN_TEXT
  ) as uniformDataStruct.PlainText
  if (entry.textContent.length > 16 * 1024) throw new Error('PAYLOAD_TOO_LARGE')

  const raw = JSON.parse(entry.textContent) as Record<string, Object>
  if (typeof raw.schemaVersion !== 'number') throw new Error('INVALID_VERSION')
  if (typeof raw.minReaderVersion !== 'number') throw new Error('INVALID_MIN_READER')
  if (typeof raw.taskId !== 'string' || raw.taskId.length === 0) {
    throw new Error('INVALID_TASK_ID')
  }
  if (typeof raw.resourceId !== 'string' || typeof raw.action !== 'string') {
    throw new Error('MISSING_CORE_FIELD')
  }
  if (raw.action !== 'OPEN_DETAIL' && raw.action !== 'ADD_TO_BOARD') {
    throw new Error('UNSUPPORTED_ACTION')
  }
  return raw as unknown as TapEnvelope
}

ArkTS 静态类型不能替代外部数据校验。as TapEnvelope 只影响编译器，不会把错误字段变正确。代码先把未知对象视为键值集合，再逐项确认。示例只列核心检查；生产项目还应限制字符串长度、版本整数范围、时间单位和可选字段类型。

状态在这个阶段仍是 RECEIVED，因为信封只是通过结构校验。只有 negotiate() 返回共同版本，才进入 NEGOTIATED(v2)。动作执行成功后才是 ACCEPTED。把这三个阶段分开后，HiLog 能回答“数据没到、结构不对、版本无交集，还是页面动作失败”，而不是全部记录成 handoff failed。

异常消息不应直接展示原始载荷。诊断页只展示任务号、版本、字段名和错误码，避免把业务内容写进日志。即使 textContent 只有 1.8 KB，也不能默认它不含敏感信息。

开发配图采用白色主题，左侧项目树包含 EnvelopeCodec.ets、VersionNegotiator.ets 与 HandoffInspectPage.ets；中间代码停在共同版本选择；右侧模拟器显示 NEGOTIATED v2；底部 HiLog 对齐 TAP-SCHEMA-0058、v3 → v2 和两个丢弃字段。这是与本文数据一致的演示图，不是实际 DevEco Studio 截图或真机证据。

五、字段降级必须可见，也必须不可逆猜测

降级不是把 v3 对象原样塞给 v2 页面。接收端应生成一个目标版本视图，只保留 v2 明确理解的字段。这样后续业务代码不会意外读取 previewTheme，也不会因为某个页面“碰巧认识”v3 字段而形成半兼容状态。

这段代码解决什么问题：把已校验的 v3 信封投影为 v2 消费模型，并用 reducer 保证状态只能单向推进。

interface EnvelopeV2 {
  taskId: string
  resourceId: string
  action: 'OPEN_DETAIL' | 'ADD_TO_BOARD'
  nonce: string
  issuedAt: number
}

type HandoffState = 'IDLE' | 'RECEIVED' | 'NEGOTIATED_V2' | 'ACCEPTED' | 'REJECTED'

function toV2(source: TapEnvelope): EnvelopeV2 {
  return {
    taskId: source.taskId,
    resourceId: source.resourceId,
    action: source.action,
    nonce: source.nonce,
    issuedAt: source.issuedAt
  }
}

function nextState(current: HandoffState, event: string): HandoffState {
  if (current === 'IDLE' && event === 'RECEIVE_OK') return 'RECEIVED'
  if (current === 'RECEIVED' && event === 'NEGOTIATE_V2') return 'NEGOTIATED_V2'
  if (current === 'NEGOTIATED_V2' && event === 'ACTION_OK') return 'ACCEPTED'
  if (event === 'FAIL') return 'REJECTED'
  return current
}

投影函数没有扩展运算符，这是有意的。{...source} 再删除两个字段，很容易在 v4 新增字段后忘记更新删除清单；显式白名单让目标版本的语义固定。代价是代码稍长，但协议边界更适合冗长而确定，而不是简短却含糊。

状态机禁止从 RECEIVED 直接跳到 ACCEPTED，也不会让迟到的协商回调覆盖终态。实际项目应再加入会话 generation：页面重新进入或新一次碰一碰开始后，旧任务回调只能被丢弃。本文不把它扩展成重试与冲突恢复，避免与既有 SlideDrop 状态系列重复。

运行页显示时间 05:18、电量 68%，任务 TAP-SCHEMA-0058，发送版本 v3、接收能力 [v1, v2]、共同版本 v2。状态链为 RECEIVED → NEGOTIATED(v2) → ACCEPTED，UDMF 记录数为 1，载荷为 1.8 KB。红色箭头只解释版本回退和字段丢弃。

图中“保留字段 12”包含六个协议核心字段与六个 UDMF/诊断元数据字段；动作投影只消费前者，后者不会进入页面业务模型。这个区分避免把记录层标签误当成业务字段。

六、诊断页要回答“为何可接受”，不是只写成功

一个绿色的 ACCEPTED 无法证明兼容策略正确。诊断页应同时展示输入契约、接收能力、协商规则与输出视图。演示中 minReaderVersion=2，因此虽然接收端声明支持 v1，v1 不能参与本次协商；v2 满足下界并且不高于发送版本，成为唯一结果。

被丢弃的 previewTheme 与 hapticPattern 都是增强字段，不改变 OPEN_DETAIL 的业务含义。输出视图保留 resourceId=board-7421、nonce=N-0058-A7 和时间戳。若被丢字段属于动作必需项，协议作者应提升 minReaderVersion，此时结果会从 NEGOTIATED 变成 REJECTED/NO_COMMON_VERSION。

详情图与运行页不同，它展示协议检查链：记录类型 general.plain-text、正文与 details 版本一致、必填字段完整、共同版本为 2、丢弃字段为 2。红圈用于指出 v3 → v2 与“核心字段 6/6 保留”，让图片承担技术解释。

七、进入生产前还要补的边界

第一，版本目录需要进入代码评审。每次增加字段时说明它从哪个版本开始、是否可选、旧端如何降级、是否改变动作语义。没有这份目录，schemaVersion 只是一个数字装饰。

第二，UDMF 生命周期与业务任务生命周期分开治理。通路记录什么时候删除、是否允许其他应用读取、页面离开后是否继续保留，需要按产品场景配置。本文只展示写入和读取，不把公共数据通路当永久数据库。

第三，限制输入规模。演示上限是 16 KB，实际值应根据动作复杂度制定。PlainText 中不应内嵌大图或大文件；资源内容应使用合适的标准类型或受控 URI，信封只保存描述和引用。

第四，安全语义不能借兼容逻辑偷懒。版本协商不验证发送方身份，不提供完整防重放，也不保证载荷没有被篡改。若场景涉及授权、支付、门禁或隐私内容，应引入平台安全能力与服务端校验，不能依靠 nonce 和 issuedAt 两个字段自证可信。

第五，测试要覆盖无共同版本、必填字段缺失、未知动作、details 与正文不一致、重复记录、超长文本和页面离场。成功夹具 v3 → v2 只是其中一条；真正有价值的是失败原因保持稳定，且不会执行半个动作。

第六，文案要把“降级”翻译成用户可理解的结果。普通用户不需要看到 schema 版本；开发诊断页可以展示完整字段，产品页只需提示“已按兼容模式打开，部分预览效果未同步”。技术事实保留在日志和诊断页，不应把协议细节倾倒给用户。

1. 兼容矩阵要从“版本对版本”变成“能力对能力”

测试若只列发送端 v1/v2/v3 与接收端 v1/v2/v3，很快会变成一张看似完整、实际没有覆盖语义的矩阵。同一个 v3 发送端可能使用 OPEN_DETAIL，也可能使用 v3 新增动作；同一个 v2 接收端可能支持纯文本，不支持文件 URI。更可靠的测试维度是最低读取版本、动作、必填字段集合、可选能力和记录类型。

TAP-SCHEMA-0058 至少需要六类夹具：v3 到 v2 且只新增可选字段，应选择 v2；v3 到 v1 而最低版本为 v2，应拒绝；v2 到 v3，应按 v2 消费；共同版本存在但动作未知，应拒绝；版本可协商但核心字段缺失，应在协商前拒绝；PlainText 之外的记录，应返回类型不支持。每个夹具不仅断言终态，还要断言失败发生在哪一层。

对被丢字段也要建立快照。今天只有两个字段，后续 v4 新增字段时，测试应明确它在降到 v2、v3 时分别保留或丢弃。这样协议作者修改投影函数后，评审能看到兼容面发生了什么，而不是只看到一段新的条件分支。

2. 可观测字段应稳定，日志文本可以变化

生产日志建议至少保留 taskId、发送版本、最低读取版本、接收能力摘要、选择版本、丢弃字段数量、终态与稳定错误码。字段值要适合聚合，例如错误码使用 NO_COMMON_VERSION，不要把整句中文作为统计维度。页面文案以后可以调整，错误码不应随措辞变化。

载荷内容、资源标题和用户文本没有必要进入日志。调试时如果确实需要确认字段，可记录字段名集合或值的长度，不记录原值。resourceId 是否可记也取决于业务；若它能关联用户内容，应做脱敏或会话内哈希。协议诊断不应成为额外的数据泄露通道。

关键指标不是“碰一碰成功率”一个数字，而是分层漏斗：收到 UDMF、通过类型检查、通过结构检查、找到共同版本、动作执行完成。若大量任务停在共同版本之前，说明升级策略有问题；若都能协商却动作失败，问题在页面或业务资源。分层后，团队不会用重试去掩盖协议不兼容。

3. 页面与会话生命周期需要隔离

碰一碰动作可能在页面切换边界到达。接收页创建后开始解析，用户随即退出；稍后协商完成，如果仍更新旧组件，就会产生幽灵提示或把新页面导航到旧资源。页面应为每次接收生成 generation，回调提交前比较当前 generation 与 taskId，两者任一不匹配就丢弃。

UDMF 记录的删除也要有明确所有者。若接收成功后立即删除，另一个合法消费者可能还未读取；若长期保留，旧数据会再次被查询。产品应决定是单消费者、限时共享还是多消费者，并用对应通路策略管理。本文只处理单次消费视图，未把“查询到的数据”默认等同于“本任务唯一数据”。

当应用进入后台时，协议解析可以继续，页面动作应等待可见状态恢复，或转成通知/任务中心。不要在不可见窗口里直接执行导航。状态机可以停在 NEGOTIATED_V2，回到前台后再提交 ACTION_OK；若任务过期，则进入 REJECTED/SESSION_EXPIRED。

4. 协议治理要能回答谁批准了不兼容变化

协议文件应和代码一起版本控制，字段变更通过专门评审。新增可选字段可以保持最低读取版本；新增必填语义、改变动作含义、改变单位或删除字段则需要不兼容版本。评审记录要说明旧端看到新载荷时的结果，不能只描述新端能力。

还可以为每个版本生成一份机器可读 schema，用它驱动夹具与文档。运行时仍保留手写的业务校验，因为 JSON schema 很难表达所有动作语义；机器 schema 负责字段形状，代码负责跨字段约束，两者互补。若文档、schema 与实现中的版本号不一致，构建应失败。

协议退役也需要节奏。当数据表明 v1 消费者已经低于阈值，发送端仍不应突然把最低版本提高到 3。先停止产生 v1 专属字段，再观察兼容模式使用量，最后提升下界，并为仍在旧版的用户保留明确升级提示。兼容不是永久背负所有历史，而是可观测地收缩支持范围。

八、结语：协议兼容的目标是确定，不是宽松

精准碰一碰让交互看起来像一个瞬间动作，应用内部仍要面对长期演进。UDMF 解决统一数据承载，业务信封解决字段语义，版本协商解决新旧端共存。三层拆开后，传输成功不再等于业务成功，未知字段也不再被无条件忽略。

TapEnvelope 的演示结论可以被复查：任务 TAP-SCHEMA-0058 收到一条 1.8 KB 的 PlainText 记录；发送端 v3，接收端支持 v1/v2，最低读取版本为 v2；最终选择 v2，丢弃两个增强字段，六个核心字段完整保留，状态进入 ACCEPTED。它证明的是协议算法闭环，不替代真实设备、账号权限和底层传输验证。

参考资料：

• 精准碰一碰主题资料：https://developer.huawei.com/consumer/cn/forum/topic/0208223729721325967
• OpenHarmony UDMF 标准化数据通路：https://github.com/openharmony/docs/blob/master/zh-cn/application-dev/database/unified-data-channels.md
• OpenHarmony 标准化数据结构：https://github.com/openharmony/docs/blob/master/zh-cn/application-dev/reference/apis-arkdata/js-apis-data-uniformDataStruct.md