代码审计与渐进重构 · 规范审计员视角 · 场景:校园文创抽签。本文的系统接入与设备验收步骤需要按实际项目环境执行。

校园文创抽签技术封面

先把反馈变成可审的变更

评审材料最初只有一张缺陷截图,但这一类问题的成本通常不在截图上的那几行文字。必须恢复输入从哪里来、由哪个模块解释、什么时候失去有效性,才能知道需要改的是呈现、领域规则还是保存的历史事实。

在校园文创抽签的实现里,最让人不安的地方是:用户打开活动页看到的中奖概率属于上一轮奖池,后台却已经切换了奖项数量。页面的概率总和仍是百分之百,因此只做数值求和无法发现错误。这不是普通的文字错位,奖池披露卡会改变用户如何理解正在执行的行为。

目前掌握的现象是:用户打开活动页看到的中奖概率属于上一轮奖池,后台却已经切换了奖项数量。页面的概率总和仍是百分之百,因此只做数值求和无法发现错误。换成技术语言,至少要核对poolRevision与visibleOdds是不是同一份业务事实。只检查最终页面是否出现正确字符串,既无法发现缓存与源数据分歧,也无法知道错误从哪一次状态转换开始。

校园文创抽签的这条路径依次经过“奖池建档 → 规则核验 → 公开卡生成 → 抽签请求 → 结果归档”。我们不应该凭直觉把它压成一个成功或失败的布尔值;从第一步到最后一步,每一阶段都可能留下尚未确认的事实。重构要先给关键交接点命名,再讨论状态应该放在哪里。

审计时先从失败条件倒着读取代码,而不是从函数第一行顺着读完。管理后台发布新奖池时只清理了活动详情缓存,未刷新独立维护的概率卡数据,且两套接口各使用自己的版本戳。若只在最后增加一次界面刷新,旧模块仍然拥有错误的解释权。下次增加入口或并行任务,表面的修复就会重新失效。

规则差异回放:旧实现最危险的默认值

把问题写成一次具体反例:在页面打开后管理员撤回奖池的瞬间发起抽签;旧卡不能被无声替换,更不能继续显示“已验证”。这里必须分清“旧请求仍然能返回”和“旧请求仍然有资格修改当前状态”。前者是底层执行事实,后者是产品承诺;两者不应由一个普通回调自动等同。

翻开旧实现后的初步判断是:管理后台发布新奖池时只清理了活动详情缓存,未刷新独立维护的概率卡数据,且两套接口各使用自己的版本戳。因此第一步不应重写整个页面,先列出产生这个结果的最短调用链,把每个条件分支的输入和副作用分开。

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

把概率说明、奖项明细和生效区间打成同一个不可拆分的披露版本,抽签请求必须回传用户确认的版本号,服务端负责最终裁定。这里的重构目标不是创造一个拥有所有权力的工具类,而是让规则核验与抽签请求之间的交接可被验证。不能验证的结果不能提前渲染为完成,更不能拿前端已展示的状态替代服务器或资源管理层的确认。

以两个奖池的概率明细为输入,在逻辑层先聚合百万分率,再对照生效窗口;任何概率值虽合法但版本不一致的样本都必须拒绝,不允许用界面总和等于百分之百替代规则确认。

权责和数据契约

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

下面的代码只实现这篇文章需要的领域裁决,不封装未经确认的系统SDK调用。它更适合放在ArkTS业务层,平台能力接入放在外侧适配器:一边可以验证同一奖池版本内所有奖项的可见概率按明细归集,时间范围不在区间内一律拒绝展示为可参与。,另一边能单独审阅文件、网络、页面生命周期带来的错误路径。

数据字段归属职责需要阻断的条件
poolRevision奖池建档无效值不得自动进入规则核验
visibleOdds规则核验无效值不得自动进入公开卡生成
issuedAt公开卡生成无效值不得自动进入抽签请求
awardKey抽签请求无效值不得自动进入结果归档

本轮重构把约束写得很清楚:把概率说明、奖项明细和生效区间打成同一个不可拆分的披露版本,抽签请求必须回传用户确认的版本号,服务端负责最终裁定。这样即使将来换成另一种展示组件,规则也不会因为某个按钮换了位置而悄悄失效。

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

再看时序条件:在页面打开后管理员撤回奖池的瞬间发起抽签;旧卡不能被无声替换,更不能继续显示“已验证”。这个条件下旧实现很可能继续调用视图更新,而新实现必须比较请求绑定的版本与当前版本。即使底层任务不能及时取消,也应该丢弃已失效的结果,避免历史操作夺回页面控制权。

抽签活动概率公示的版本链:DevEco Studio白色开发环境图,审查领域校验与目录位置

从纯函数开始动刀

失败出口还需要资源层面的处理。一次被拒绝的变更,可能已经创建暂存文件、产生订阅令牌或准备了请求体。如果不能保证调用方执行清理,应该把资源交还动作写成显式协议。旧版本只作为历史阅读材料,用户必须重新查看当前披露卡后才能继续参与。这比捕获所有异常后统一显示“请重试”更有工程价值。

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

type Prize = { key: string; partsPerMillion: number };
type Pool = { revision: string; from: number; until: number; prizes: Prize[] };
function canDraw(pool: Pool, seenRevision: string, now: number): boolean {
  const sum = pool.prizes.reduce((acc, p) => acc + p.partsPerMillion, 0);
  const unique = new Set(pool.prizes.map(p => p.key)).size === pool.prizes.length;
  return unique && sum === 1000000 && pool.revision === seenRevision
    && pool.from <= now && now < pool.until;
}

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

构造规则A、规则B与已撤回规则C三份输入,分别测试版本一致、客户端缓存过期、奖池未生效;逐项核对按钮可用性与审计记录。这些用例的重点不是让测试数量好看,而是能否分辨不同错误来源。输入准备最好由独立于被测函数的规格表驱动,避免把函数当下的输出复制为预期答案。

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

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

把失败出口补齐

重构的收益和成本需要同时记录:比直接强制刷新多一次确认动作,却换来概率文案和实际执行规则可以一一对应。它会影响测试夹具、跨端协议、产品文案乃至客服排查方式,不能只凭代码行数的减少决定取舍。需要删除旧分支时,先证明新旧版本在允许的样本范围内得到同一个结果。

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

专门保留一个不容易被正常测试覆盖的条件:在页面打开后管理员撤回奖池的瞬间发起抽签;旧卡不能被无声替换,更不能继续显示“已验证”。它是审查增量代码的重要样本,因为它往往能揭露时序、缓存与版本所有权的真实边界。

本篇真正应当被审核的是一条不变量:同一奖池版本内所有奖项的可见概率按明细归集,时间范围不在区间内一律拒绝展示为可参与。这种句子可以被写成自动化断言,也能被产品、测试和审查人员读懂。相比“优化用户体验”“加强稳定性”,它给出了明确的失败判定,因此适合作为后续改造的长期契约。

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

抽签活动概率公示的版本链:从旧链路到新契约的交接节点

回归用例不只看通过率

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

审阅者准备的反例表

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

关键回归集不应只从正向流程生成。构造规则A、规则B与已撤回规则C三份输入,分别测试版本一致、客户端缓存过期、奖池未生效;逐项核对按钮可用性与审计记录。同时必须检查用户端的解释是否对应实际拒绝原因,避免页面虽然正确拒绝,却用错误提示误导后续操作。

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

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

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

收口时还要核对什么

如果团队关心为什么现在值得承担这次改造成本,可以回到两种方案的取舍:比直接强制刷新多一次确认动作,却换来概率文案和实际执行规则可以一一对应。这类成本和收益可以在设计评审中讨论,却不能从一次页面截图推断。

面对生产故障,先止损再迁移:旧版本只作为历史阅读材料,用户必须重新查看当前披露卡后才能继续参与。恢复策略要能够连续执行两次而不引入新问题。无论用户是主动重试、窗口被系统重新创建,还是后台任务刚刚恢复,都不应该产生更多不可解释的中间状态。

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

官方资料与适用范围

应用上架规范与内容信息一致性审查是此篇需要跟踪的规范范围;具体平台API与审核条款以实际提交日和目标SDK文档为准。下列是可复核的官方入口,不代表本文代码已经在设备上跑通。

Logo

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

更多推荐