harmonyos-review

HarmonyOS 代码审查

发现真正的缺陷，而非流于形式的臆测。代码库中的代码和配置决定应用的实际行为；华为官方文档用于确认依赖版本的平台契约。

1. 确定审查范围

• 审查前阅读代码库说明，并检查工作区状态。
• 确定请求的边界：差异／PR、文件、模块、子系统或整个代码库。
• 审查变更时，确定确切的基准，并检查差异和受影响的调用点。
• 阅读 build-profile.json5、oh-package.json5、module.json5 和相关配置，以确认 SDK 级别、应用模型、设备、权限、依赖项和构建变体。
• 除非用户提出要求，否则不要修改代码、创建报告、评定等级或估算工作量。

2. 梳理相关执行路径

先广泛检查，再沿证据追踪：

• 定位入口点、生命周期回调、状态所有者、异步边界、持久化操作、文件操作、权限、事件订阅和外部输入。
• 沿调用方和被调用方追踪值与资源。检查清理、取消、重试、失败和部分成功路径。
• 查看测试和文档，了解预期行为，但不要将其视为生产代码安全的证明。
• 使用有针对性的搜索查找候选项。文本匹配只是线索，不是发现。

示例初步侦察命令：

rg -n --glob '*.ets' --glob '*.ts' 'eventHub\.(on|off)|emitter\.(on|off)|setInterval|setTimeout'
rg -n --glob '*.ets' 'ResultSet|relationalStore|executeSql|beginTransaction|commit|rollBack'
rg -n --glob '*.ets' 'requestPermissionsFromUser|checkAccessToken|canIUse'
rg -n --glob '*.ets' --glob '*.json5' '(password|secret|token|api[_-]?key)'
rg -n --glob '*.json5' 'compileSdkVersion|compatibleSdkVersion|targetSdkVersion|requestPermissions'

根据代码库调整搜索模式。若生成文件、依赖项、构建输出、夹具和测试数据目录会造成干扰，请将其排除。

3. 仅分析适用类别

加载 references/checklist.md，并根据范围选择适用类别：

• 正确性和错误传播
• 安全、隐私和敏感数据
• 生命周期、资源所有权和取消
• V1/V2 状态管理和并发更新
• RDB、Preferences、文件、迁移和原子性
• 权限、SysCaps、设备和 API 兼容性
• 网络和外部输入处理
• 有具体高开销路径的性能问题
• 覆盖已变更或高风险行为的测试

对于依赖平台的论断，请查阅 references/official-docs.md，并根据最新的华为官方文档进行核实。不要硬编码“当前” API 版本，也不要根据其他框架推断要求。

4. 证实每项发现

一项可报告的发现必须满足以下所有条件：

1. 精确的源代码位置。
2. 可触发的条件或执行路径。
3. 错误行为或违反的项目／平台契约。
4. 对用户、数据、安全、兼容性或运维造成的具体影响。
5. 证据表明现有防护、清理逻辑或调用方并未阻止该问题。

报告前，尝试证伪候选问题：

• 阅读完整函数及相关调用方／被调用方。
• 检查所有成功、错误、取消和拆除路径。
• 搜索其他位置是否存在补偿性验证或清理。
• 根据项目实际的 SDK 范围确认 API／装饰器／权限行为。
• 区分生产代码与示例代码、生成代码、死代码和测试夹具。

不要报告风格偏好、任意大小限制、泛泛的“可能”风险，也不要报告未经证实影响的扫描器匹配项。

5. 根据影响确定严重程度

• 严重：可利用的安全问题、不可逆的数据丢失，或核心路径上的发布阻断故障。
• 高：可能导致崩溃、数据损坏、安全／隐私泄露或核心功能故障。
• 中：在较窄条件下出现的真实缺陷、可恢复的影响或显著性能退化。
• 低：影响有限的具体小缺陷；除非用户提出要求，否则省略纯粹的润色建议。

严重程度取决于影响和发生可能性，而非修复难度。

6. 首先报告发现

除非用户要求提供仓库文档，否则请在对话中回复。仅在需要完整的 Markdown 文档时，使用 references/report-template.md。

按严重程度排列发现。每项发现应包含：

• [severity] 简洁标题
• path/to/file.ets:line
• 触发条件和证据
• 影响
• 有针对性的修复建议
• 如果发现依赖 HarmonyOS 契约，提供官方来源

如果没有符合证据标准的发现，请明确说明。然后分别注明覆盖范围缺口和未运行的验证；不要将它们夸大为发现。

退出标准

• 明确说明范围及 SDK/设备假设。
• 每项发现都有源代码证据，且可独立采取行动。
• 根据项目的版本范围核实平台相关声明。
• 明确区分发现、待解决问题和未经验证的风险。
• 准确报告已运行的测试/构建；未运行的检查不得描述为已通过。