代码审计与渐进重构 · 客户端负责人视角 · 场景:亲子识字训练。本文的系统接入与设备验收步骤需要按实际项目环境执行。

亲子识字训练技术封面

被忽略的输入前提

在接到这个改动时,我没有先把页面换成更漂亮的组件。UI上的症状可以用补丁压住,隐藏的状态所有权却不会因此改变。一次有价值的代码审计,首先要把可见反馈和真正要维护的不变量拆开。

在亲子识字训练的实现里,最让人不安的地方是:课程入口有提醒,孩子从收藏列表直达练习时却不经过入口。产品评审误以为统一弹窗组件覆盖了所有入口,实际上只有一个路由调用了它。这不是普通的文字错位,学习时长提醒会改变用户如何理解正在执行的行为。

目前掌握的现象是:课程入口有提醒,孩子从收藏列表直达练习时却不经过入口。产品评审误以为统一弹窗组件覆盖了所有入口,实际上只有一个路由调用了它。换成技术语言,至少要核对sessionAge与warningSeen是不是同一份业务事实。只检查最终页面是否出现正确字符串,既无法发现缓存与源数据分歧,也无法知道错误从哪一次状态转换开始。

亲子识字训练的这条路径依次经过“打开课程 → 计时聚合 → 提醒展示 → 家长决策 → 课程退出”。我们不应该凭直觉把它压成一个成功或失败的布尔值;从第一步到最后一步,每一阶段都可能留下尚未确认的事实。重构要先给关键交接点命名,再讨论状态应该放在哪里。

审计时先从失败条件倒着读取代码,而不是从函数第一行顺着读完。学习时长属于会话范围的业务策略,却被写成课程首页的局部副作用;浮层关闭记录也没有和当前学习会话绑定。若只在最后增加一次界面刷新,旧模块仍然拥有错误的解释权。下次增加入口或并行任务,表面的修复就会重新失效。

入口覆盖图审阅:审阅旧代码的三个切口

把问题写成一次具体反例:提醒正显示时家长从系统最近任务重新进入应用;上一会话关闭记录不能直接解释新会话的确认。这里必须分清“旧请求仍然能返回”和“旧请求仍然有资格修改当前状态”。前者是底层执行事实,后者是产品承诺;两者不应由一个普通回调自动等同。

翻开旧实现后的初步判断是:学习时长属于会话范围的业务策略,却被写成课程首页的局部副作用;浮层关闭记录也没有和当前学习会话绑定。因此第一步不应重写整个页面,先列出产生这个结果的最短调用链,把每个条件分支的输入和副作用分开。

本次审计的高价值字段是sessionAge, warningSeen, practiceMode, guardianChoice。它们在代码里可能被封装成不同数据对象,但在业务上应被视作同一个决策快照的组成部分。任何单字段修补都要回答:删除它、留空它、从历史缓存恢复它时,是否仍能推出有效结论。

将触发判断收敛到会话协调器:所有页面转入互动练习前都查询同一份策略裁决,提醒展示由单一状态机维护。这里的重构目标不是创造一个拥有所有权力的工具类,而是让计时聚合与家长决策之间的交接可被验证。不能验证的结果不能提前渲染为完成,更不能拿前端已展示的状态替代服务器或资源管理层的确认。

列出主页、收藏、通知和恢复入口四张调用图,逐一标出进入练习前的共享检查节点。最难修复的并不是新增入口,而是消除只有旧首页才会触发的隐性副作用。

谁应该拥有最终解释权

数据进入系统后,先走无副作用的规则判断,再决定是否调用家长决策。纯函数不应该依赖当前组件的局部变量、弹窗关闭次数或某个尚未完成的网络副作用。相同输入应当得到相同裁决,这样才能从日志和固定样本中重放问题。

下面的代码只实现这篇文章需要的领域裁决,不封装未经确认的系统SDK调用。它更适合放在ArkTS业务层,平台能力接入放在外侧适配器:一边可以验证未获得当前会话的有效guardianChoice时不进入连续练习状态。,另一边能单独审阅文件、网络、页面生命周期带来的错误路径。

数据字段归属职责需要阻断的条件
sessionAge打开课程无效值不得自动进入计时聚合
warningSeen计时聚合无效值不得自动进入提醒展示
practiceMode提醒展示无效值不得自动进入家长决策
guardianChoice家长决策无效值不得自动进入课程退出

本轮重构把约束写得很清楚:将触发判断收敛到会话协调器:所有页面转入互动练习前都查询同一份策略裁决,提醒展示由单一状态机维护。这样即使将来换成另一种展示组件,规则也不会因为某个按钮换了位置而悄悄失效。

真正的审计工作往往始于“如果字段不存在怎么办”。比如warningSeen并非必然存在;如果它来自上次任务、上个窗口或另一名用户,就不能继续沿用。重构后的调用方应处理拒绝、重新获取和用户确认三种分支,而不是在逻辑中偷偷给一个看似合理的默认值。

再看时序条件:提醒正显示时家长从系统最近任务重新进入应用;上一会话关闭记录不能直接解释新会话的确认。这个条件下旧实现很可能继续调用视图更新,而新实现必须比较请求绑定的版本与当前版本。即使底层任务不能及时取消,也应该丢弃已失效的结果,避免历史操作夺回页面控制权。

儿童学习时长提示的例外路径:应用竖屏页面的状态与字段呈现

替换逻辑之前先定数据形状

失败出口还需要资源层面的处理。一次被拒绝的变更,可能已经创建暂存文件、产生订阅令牌或准备了请求体。如果不能保证调用方执行清理,应该把资源交还动作写成显式协议。会话丢失时回到安全的课程待开始态,不依赖旧页面的布尔变量猜测是否已提醒。这比捕获所有异常后统一显示“请重试”更有工程价值。

可单独审阅的ArkTS/TypeScript业务规则

type StudySession = { id: string; exceeded: boolean; noticeSeen: boolean; guardianAck: string | null };
function mayStartPractice(s: StudySession): { allowed: boolean; next: string } {
  if (!s.exceeded) return { allowed: true, next: 'practice' };
  if (!s.noticeSeen) return { allowed: false, next: 'showNotice' };
  if (s.guardianAck === s.id) return { allowed: true, next: 'practice' };
  return { allowed: false, next: 'guardianConfirm' };
}

这一段针对sessionAge的约束是纯逻辑实现,不包含SDK绑定。项目里可在entry/src/main/ets/domain/建立对应模块,通过ArkTS接口适配调用,保留可独立运行的测试输入。

逐个穷举首页、收藏、任务通知、历史课表四类入口,再覆盖后台恢复和应用重启,记录相同会话编号是否仅形成一次有效提醒。这些用例的重点不是让测试数量好看,而是能否分辨不同错误来源。输入准备最好由独立于被测函数的规格表驱动,避免把函数当下的输出复制为预期答案。

为每个用例保留四份信息:输入快照、预期的不变量、实际得到的领域决策、调用方应呈现的动作。发生偏差时先看sessionAge和guardianChoice是否一致,再定位是否为并发、缓存或业务解释差异。不要把视觉截图当作唯一证明。

在真实项目里还需要一组“旧输入与新代码混用”的兼容测试。版本升级之后历史数据不会突然消失,亲子识字训练中的旧记录可能很长时间后才被再次打开。新代码对旧字段的容错必须有上界;遇到无法判断的状态,宁可留下待确认,也不能编造一个已完成的结论。

异常状态要有去处

重构的收益和成本需要同时记录:统一协调器增加跨页面接口,但显著降低新增入口时漏掉防护动作的概率。它会影响测试夹具、跨端协议、产品文案乃至客服排查方式,不能只凭代码行数的减少决定取舍。需要删除旧分支时,先证明新旧版本在允许的样本范围内得到同一个结果。

发布前还要审查权限与数据最小化边界。用于排障的sessionAge可以是可复核的匿名键,私人信息不应因为开发者想要排错就被原样写入日志。若确需保留审计证据,应标注保存期限、接触角色和删除规则,并与产品实际隐私说明一致。

专门保留一个不容易被正常测试覆盖的条件:提醒正显示时家长从系统最近任务重新进入应用;上一会话关闭记录不能直接解释新会话的确认。它是审查增量代码的重要样本,因为它往往能揭露时序、缓存与版本所有权的真实边界。

本篇真正应当被审核的是一条不变量:未获得当前会话的有效guardianChoice时不进入连续练习状态。这种句子可以被写成自动化断言,也能被产品、测试和审查人员读懂。相比“优化用户体验”“加强稳定性”,它给出了明确的失败判定,因此适合作为后续改造的长期契约。

当某个页面声称动作已完成时,必须能够回答是谁完成了什么、对应哪份输入、记录在哪里。课程退出是这条流程的终点,却不意味着从此不需要版本。只要历史有机会回看,回看时就必须识别当时的规则与现在的规则并不必然相同。

儿童学习时长提示的例外路径:从旧链路到新契约的交接节点

从反例推导测试

工程验证需要分层:纯函数可以用固定数据在本地测试,系统接口需要与真实设备或目标SDK集成,跨端框架还要做协议一致性核对。本篇不以预先编造的帧率、耗时或通过率证明方案有效;所有需要实机采样的结论都留给项目CI和设备记录。

审阅者准备的反例表

| 情况 | 输入特征 | 期望处理 |
|---|---|
| 正常输入 | sessionAge与guardianChoice一致 | 按业务规则继续 |
| 缺少字段 | warningSeen为空或非法 | 拒绝并指明缺失项 |
| 旧数据回流 | sessionAge已过期 | 保留当前状态,提示复核 |
| 并发交错 | 提醒展示先于前序动作返回 | 以契约版本判断是否可提交 |

关键回归集不应只从正向流程生成。逐个穷举首页、收藏、任务通知、历史课表四类入口,再覆盖后台恢复和应用重启,记录相同会话编号是否仅形成一次有效提醒。同时必须检查用户端的解释是否对应实际拒绝原因,避免页面虽然正确拒绝,却用错误提示误导后续操作。

最容易诱惑维护者的简化,是把practiceMode和guardianChoice在界面层合并成一个状态字段。这样看似避免了多次赋值,实则掩盖了“谁提出、谁接受、谁可撤销”的不同责任。字段只要参与权限、金额、身份或资源释放,就应该保留清晰的所有权。

评审还有一个实用问题:如果只修改提醒展示,系统剩下的路径会不会仍按照旧规则执行?如果答案是不确定,那么提交范围不应仅包含页面组件。应把入口适配器、领域规则、失败提示和必要的持久化字段放到同一轮受控修改中,避免半新半旧的协议长期共存。

为了让差异可被复核,代码提交应记录旧行为的最小反例、新契约的字段定义,以及对业务含义有影响的命名变更。尤其是warningSeen,一旦从可选值变成必填值,必须同步排查历史记录、跨端消息和测试夹具,不能让编译通过成为唯一的验收条件。

交付边界与资料来源

如果团队关心为什么现在值得承担这次改造成本,可以回到两种方案的取舍:统一协调器增加跨页面接口,但显著降低新增入口时漏掉防护动作的概率。这类成本和收益可以在设计评审中讨论,却不能从一次页面截图推断。

面对生产故障,先止损再迁移:会话丢失时回到安全的课程待开始态,不依赖旧页面的布尔变量猜测是否已提醒。恢复策略要能够连续执行两次而不引入新问题。无论用户是主动重试、窗口被系统重新创建,还是后台任务刚刚恢复,都不应该产生更多不可解释的中间状态。

最后安排一名没有参与修改的审查者,只凭用例与领域约束推导预期结果。如果他不能解释为什么sessionAge变化后必须使某个缓存失效,说明文档仍过度依赖作者脑海中的隐含规则。让审查者找出一个不同于开发者所列样本的反例,通常比重复走一遍幸福路径更有效。

官方资料与适用范围

未成年人相关内容告知与用户体验是此篇需要跟踪的规范范围;具体平台API与审核条款以实际提交日和目标SDK文档为准。下列是可复核的官方入口,不代表本文代码已经在设备上跑通。

Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐