Once三大作用域详解：THIS_APP_INSTALL、THIS_APP_VERSION与THIS_APP_SESSION场景选型指南

Once 是一款轻量级 Android 库，专门帮你管理应用中的"一次性操作"：新手引导只显示一次、升级公告每个版本只弹一次、会话内提示只出现一次。它的核心抽象就是三个作用域常量（定义于 Once.java）：THIS_APP_INSTALL、THIS_APP_VERSION、THIS_APP_SESSION。本文用通俗的讲解带你理解每个作用域的边界，并给出一份直接可抄的选型清单。

为什么需要"一次性操作"作用域？

📌 你一定写过这样的代码：

"用户引导要弹，但别每次都弹"——于是自己在SharedPreferences里存个showedTour布尔值。

问题很快出现：

• 升级版本后要重新弹"What's New"？旧标记怎么办？
• 有的提示只要"本次打开 App 期间"有效，进程结束就该消失；
• 手动管理标记容易漏掉清理，布尔值也无法表达"做过几次"。

Once 的思路是：给每次操作起一个tag（字符串标签），再用作用域回答"在这个范围内做没做过"。底层持久化由 PersistedMap.java 基于 SharedPreferences 完成，你完全不用碰存储细节。

快速上手：两步接入

第一步，在Application.onCreate()中初始化（示例见 ExampleApplication.java）：

Once.initialise(this);

第二步，检查 → 执行 → 标记完成：

if (!Once.beenDone(Once.THIS_APP_INSTALL, "showAppTour")) { showAppTour(); Once.markDone("showAppTour"); }

beenDone(scope, tag)返回true表示该 tag 在此作用域内已经做过。接下来逐个拆解三个作用域。

作用域一：THIS_APP_INSTALL —— 整个安装期内只做一次

这是"最严格"的作用域，也是最常用的默认值——不带作用域的 beenDone(tag) 就等价于beenDone(THIS_APP_INSTALL, tag)。

判定逻辑：tag 的完成时间戳会永久累积在本地（跨版本、跨重启都保留），只要做过一次，之后一直返回true。

典型场景：

• 新手引导 / 功能导览
• 首次启动的隐私协议展示
• "欢迎页"只出现一次

// 安装后一生只执行一次 if (!Once.beenDone("tourDone")) { runOnboarding(); Once.markDone("tourDone"); }

⚠️ 注意：卸载重装后标记会清空（因为数据存在应用私有空间），但覆盖安装升级不会重置。

作用域二：THIS_APP_VERSION —— 每个版本只执行一次

它的基准是应用更新时间戳：initialise()时读取PackageInfo.lastUpdateTime（Once.java），beenDone(THIS_APP_VERSION, tag)只统计新版本之后的完成记录（Once.java）。

判定逻辑：老版本的"做过"不算数，新版本第一次启动时自动重新可用。

典型场景：

• 每次升级后的 "What's New" 弹窗
• 新版引导提示（只针对改动过的功能）
• 版本相关的埋点补采

// 每次应用升级后只执行一次 String whatNew = "showWhatsNew"; if (!Once.beenDone(Once.THIS_APP_VERSION, whatNew)) { startActivity(new Intent(this, WhatsNewActivity.class)); Once.markDone(whatNew); }

此外，配合toDoAPI 可以跨页面传递"待办任务"：toDo(Once.THIS_APP_VERSION, tag)只在本版本内尚未标记过时才重新加入待办集合（Once.java），避免用户反复看到基础页面时任务被反复重置。

作用域三：THIS_APP_SESSION —— 每次启动 App 只执行一次

这是最"轻量"的作用域：记录保存在内存中的 sessionList（Once.java），进程被杀或应用完全退出后即消失，不落盘。

判定逻辑：本次会话内做过就返回true；下次冷启动重新可用。

典型场景：

• "今天第一次打开"类的全局提示（一天多次启动只提示一次）
• 会话内只触发一次的浮层 / 横幅
• 避免同一次使用中的重复操作（如重复提交确认）

// 本次应用会话内只执行一次 if (!Once.beenDone(Once.THIS_APP_SESSION, "sessionTip")) { showBannerTip(); Once.markDone("sessionTip"); }

💡 官方示例 App 对三种作用域做了完整演示，可直接对照阅读 MainActivity.java。

三大作用域对比与选型清单

30秒选型口诀

1. 用户一生只做一次→THIS_APP_INSTALL
2. 每次发新版做一次→THIS_APP_VERSION
3. 每次打开 App 做一次→THIS_APP_SESSION
4. 按时间间隔限频（如每小时一次）→ 不用作用域，改用时间版 API：Once.beenDone(TimeUnit.HOURS, 1, tag)
5. 按次数触发（如用满 3 次后弹评分）→Once.beenDone(tag, exactly(3))配合 Amount.java 中的exactly / moreThan / lessThan

常见误区：用THIS_APP_INSTALL做"每次升级提示"——升级后不会重新触发；用THIS_APP_SESSION做新手引导——用户关掉再开 App 就会反复看到。先想清楚"重置边界"，再选作用域。

调试技巧：如何重置标记？

开发调试时可用以下 API 清理状态（Once.java）：

• Once.clearDone(tag)：清空单个 tag 的"已完成"记录
• Once.clearAll()：清空全部 tag（示例 App 的 Reset 按钮就是这么做的）
• Once.clearToDo(tag)/Once.clearAllToDos()：清理待办集合

发布正式版本前建议调用Once.lastDone(tag)（Once.java）打印关键 tag 的最后完成时间，验证作用域行为是否符合预期。

小结

Once 用极小的 API 面解决了"一次性操作"的全部常见需求：initialise初始化一次，markDone记录一次，beenDone按需查询。三个作用域的分工清晰——INSTALL 管安装期、VERSION 管版本周期、SESSION 管进程会话。记住上面的选型口诀，配合 README.md 中的完整用法说明，就可以快速上手，把重复弹窗、重复引导这些烦心事交给 Once 处理。