39-设置开关退出就复原-用偏好写队列和回滚状态兜住

第39篇｜设置开关退出就复原：用偏好写队列和回滚状态兜住

摘要：设置页开关最容易被写成 @State 一改就完事。实际项目里，用户快速连点、离开页面、写入失败、重启应用都会暴露问题：UI 显示已开启，持久化里还是旧值。更稳的做法是让设置写入走串行队列，页面可以乐观展示，但失败必须回滚，并用重启验证证明真的保存成功。

我处理过一个提醒开关问题：用户打开“每日提醒”，页面显示已开启，退出再进又变回关闭。日志里没有崩溃，因为 UI 状态确实变了，只是 Preferences 写入被后一次旧值覆盖。更麻烦的是用户快速点三次，最后界面和持久化各拿一个值。这个问题不能靠“加个 await”随便修，要把写入路径收成一个队列。

这篇文章解决四个实际问题：

1. 区分页面乐观状态和已落盘状态。
2. 用 SettingWriteQueue 串行处理同一个 key 的写入。
3. 写入失败时回滚 UI，并给用户可理解提示。
4. 用退出重进和杀进程重启验证持久化真实生效。

先确认复原发生在哪个时刻

设置复原可能发生在返回页面时，也可能是杀进程重启后。两个现象对应的根因不同，不能只看开关 UI。

这一步的价值是先把问题放回运行链路。只要能确认问题停在哪个位置，后面就不用靠猜测改页面。

页面只能发意图，不能直接散写偏好

设置项看起来简单，但长期维护时会有默认值、迁移、校验和失败回滚。页面直接写 Preferences 会让这些逻辑散得到处都是。

边界定清后，代码就不会在页面、服务和回调之间来回复制同一段判断。后续新增场景也能先判断应该落在哪一层。

设置状态要有 pending 标记

export interface SettingItemState {
  key: string
  value: boolean
  persistedValue: boolean
  pending: boolean
  errorText: string
}

export function createSettingState(key: string, value: boolean): SettingItemState {
  return {
    key,
    value,
    persistedValue: value,
    pending: false,
    errorText: ''
  }
}

value 是页面当前展示，persistedValue 是最后一次确认落盘的值。失败时页面能回滚到真实持久化状态，而不是随便猜一个默认值。

这类模型最好放在 models 或 common 中，页面、Service 和仓储都使用同一份类型，避免各层用字符串互相猜。

写队列保证同一个 key 顺序执行

export class SettingWriteQueue {
  private jobs: Map<string, Promise<void>> = new Map()

  enqueue(key: string, task: () => Promise<void>): Promise<void> {
    const previous = this.jobs.get(key) ?? Promise.resolve()
    const next = previous.then(task).finally(() => {
      if (this.jobs.get(key) === next) {
        this.jobs.delete(key)
      }
    })
    this.jobs.set(key, next)
    return next
  }
}

队列按 key 串行，不会让两个提醒开关互相阻塞，但能保证同一个 key 的后一次操作不会被更早的写入覆盖。

Service 的目标不是把所有逻辑都塞进去，而是把跨页面、跨生命周期或需要持久化的判断集中起来。页面只表达用户动作。

页面先乐观更新，再等确认

@Component
struct ReminderSettingRow {
  @State item: SettingItemState = createSettingState('daily_reminder', false)
  private service: SettingsService = createSettingsService()

  async toggleReminder(nextValue: boolean): Promise<void> {
    const before = this.item.persistedValue
    this.item = { ...this.item, value: nextValue, pending: true, errorText: '' }

    const saved = await this.service.saveBoolean(this.item.key, nextValue)
    if (!saved) {
      this.item = { ...this.item, value: before, pending: false, errorText: '保存失败，请重试' }
      return
    }

    this.item = { ...this.item, persistedValue: nextValue, pending: false, errorText: '' }
  }
}

乐观更新能让交互及时，但 pending 和回滚不能省。否则用户看到的是“已开启”，持久化里却可能还是关闭。

页面层要控制展示和交互节奏，但不应该拥有底层事实。这样页面重建、横竖屏变化或返回前台时，都能重新从 Service 拿到可信结果。

SettingsService 统一读写默认值

export class SettingsService {
  constructor(
    private readonly store: PreferenceStore,
    private readonly queue: SettingWriteQueue
  ) {}

  async loadBoolean(key: string, defaultValue: boolean): Promise<boolean> {
    const value = await this.store.getBoolean(key)
    return value ?? defaultValue
  }

  async saveBoolean(key: string, value: boolean): Promise<boolean> {
    return this.queue.enqueue(key, async () => {
      await this.store.putBoolean(key, value)
      await this.store.flush()
    }).then(() => true).catch(() => false)
  }
}

读默认值和写入确认都在 Service 层。页面不用知道是否需要 flush，也不会因为多个页面同时写同一个 key 出现竞争。

实际项目里，很多问题不是第一次进入页面暴露，而是在冷启动、返回前台、页面重建或回调晚到时暴露。把这段生命周期补上，修复才算闭环。

失败路径要回滚而不是假装成功

兜底路径不是可有可无。用户遇到异常时，页面至少要给出当前状态、可执行动作和可排查线索。

排查时找散写偏好

rg -n "putBoolean|getBoolean|Preferences|flush|daily_reminder" entry features common
rg -n "@State.*reminder|persistedValue|pending|SettingWriteQueue" entry features common
rg -n "onClick|onChange|Toggle|Switch" entry features common

第一组命令找旧路径，第二组命令找新边界，第三组命令看生命周期或回调位置。命中后不要只看字段名，要判断它是否仍在直接改页面状态。

验证清单

这些验证最好在真机或模拟器里按顺序走一遍。只看源码很难发现冷启动、重启和回调晚到这类问题。

常见问题和处理方式

如果现象没有出现在表里，仍然建议按“输入来源 -> 中间状态 -> 持久化或页面展示 -> 失败兜底”的顺序排查。

小结：设置项要把显示和落盘分清

开关状态不是点一下就结束。页面可以先展示用户选择，但服务层必须串行写入、确认落盘、失败回滚，最后用重启验证。这样设置页才不会出现看似保存成功、实际重进复原的问题。
| 默认值和旧 key 散落 | 集中迁移和读取 |

如果现象没有出现在表里，仍然建议按“输入来源 -> 中间状态 -> 持久化或页面展示 -> 失败兜底”的顺序排查。

小结：设置项要把显示和落盘分清

开关状态不是点一下就结束。页面可以先展示用户选择，但服务层必须串行写入、确认落盘、失败回滚，最后用重启验证。这样设置页才不会出现看似保存成功、实际重进复原的问题。