openharmonyinsight R021: hypium版本号>=1.0.26
规则信息
| 属性 | 值 |
|---|---|
| 规则编号 | R021 |
| 问题类型 | hypium版本号不满足要求 |
| 严重级别 | Critical |
| 规则复杂度 | simple |
| 扫描范围 | 独立XTS工程根目录下的 oh-package.json5 |
| testcase字段 | -（配置文件，不在it()块内） |
问题描述
一个独立XTS工程的 oh-package.json5 文件中，devDependencies 下的 "@ohos/hypium" 字段值必须 >= 1.0.26。
修复建议
将 "@ohos/hypium" 的版本号升级到 1.0.26 或以上。
修复建议格式
路径: {文件路径}, 行号: {行号}, 问题描述: 在独立XTS工程 '{工程名称}' 中，oh-package.json5的devDependencies.@ohos/hypium版本号为 '{当前版本}'，低于最低要求版本 1.0.26。
扫描逻辑
Step 1: 识别独立XTS工程
复用R011的独立XTS工程识别逻辑（必须使用修正后的版本，正确处理group类型父BUILD.gn，见R019陷阱6）。
Step 2: 定位oh-package.json5
在每个独立XTS工程的根目录下查找 oh-package.json5 文件。注意：
- 只检查工程根目录下的
oh-package.json5，不检查entry/oh-package.json5或cpp/*/oh-package.json5等子目录文件 - 如果根目录下没有
oh-package.json5，跳过该工程
Step 3: 提取hypium版本号
在 oh-package.json5 文件中，提取 devDependencies 下 "@ohos/hypium" 的版本号字符串。
关键: 必须跳过注释行。oh-package.json5 支持 // 单行注释，注释掉的依赖不参与检查。
import re
import os
HYPIMUM_PATTERN = re.compile(
r'"@ohos/hypium"\s*:\s*"([^"]+)"'
)
def parse_version(version_str):
parts = version_str.strip().split('.')
result = []
for p in parts:
m = re.match(r'(\d+)', p)
result.append(int(m.group(1)) if m else 0)
while len(result) < 3:
result.append(0)
return tuple(result)
def scan_r021(scan_root, base_dir):
MIN_VERSION = (1, 0, 26)
issues = []
projects = find_independent_projects(scan_root)
for project_dir in projects:
pkg_path = os.path.join(project_dir, 'oh-package.json5')
if not os.path.isfile(pkg_path):
continue
with open(pkg_path, 'r', encoding='utf-8') as f:
lines = f.readlines()
for line_idx, line in enumerate(lines):
stripped = line.strip()
# 跳过注释行（// 开头或全行被注释）
if stripped.startswith('//'):
continue
# 跳过 @ohos/hypium 被注释的情况
# 例如: // "@ohos/hypium": "1.0.21",
code_part = stripped
if '//' in stripped:
# 取 // 之前的部分
code_part = stripped[:stripped.index('//')].strip()
match = HYPIMUM_PATTERN.search(code_part)
if not match:
continue
version_str = match.group(1)
version = parse_version(version_str)
if version < MIN_VERSION:
rel_path = os.path.relpath(pkg_path, base_dir)
rel_project = os.path.relpath(project_dir, base_dir)
line_num = line_idx + 1
issues.append({
'rule': 'R021',
'type': 'hypium版本号不满足要求',
'severity': 'Critical',
'file': rel_path,
'line': line_num,
'testcase': '-',
'snippet': f'"@ohos/hypium": "{version_str}"',
'suggestion': (
f"路径: {rel_path}, 行号: {line_num}, "
f"问题描述: 在独立XTS工程 '{rel_project}' 中，"
f"oh-package.json5的devDependencies.@ohos/hypium版本号为 "
f"'{version_str}'，低于最低要求版本 1.0.26。"
),
})
return issues
错误示例
{
"modelVersion": "6.0.0",
"description": "Please describe the basic information.",
"dependencies": {
},
"devDependencies": {
"@ohos/hypium": "1.0.25" // ✗ 错误：版本低于 1.0.26
}
}
{
"devDependencies": {
"@ohos/hypium": "1.0.6" // ✗ 错误：版本低于 1.0.26
}
}
正确示例
{
"modelVersion": "6.0.0",
"description": "Please describe the basic information.",
"dependencies": {
},
"devDependencies": {
"@ohos/hypium": "1.0.26" // ✓ 版本号满足最低要求
}
}
{
"devDependencies": {
"@ohos/hypium": "1.0.27" // ✓ 版本号满足最低要求
}
}
陷阱与注意事项
陷阱1: 必须跳过注释行
oh-package.json5 支持 // 单行注释。被注释掉的 @ohos/hypium 条目不参与检查。
"devDependencies": {
// "@ohos/hypium": "1.0.21", // ← 被注释掉，不检查
}
如果不过滤注释行，会将注释中的旧版本号误报为问题。
判断方法: 行去除首尾空白后以 // 开头，或行内 // 之前的部分不含 @ohos/hypium。
陷阱2: 只检查工程根目录的oh-package.json5
独立XTS工程下可能存在多个 oh-package.json5 文件：
{工程根目录}/oh-package.json5← 只检查这个{工程根目录}/entry/oh-package.json5← 不检查{工程根目录}/entry/src/main/cpp/types/libxxx/oh-package.json5← 不检查
陷阱3: 版本号格式可能不标准
大部分工程的版本号为标准semver格式（如 1.0.26），但可能存在非标准格式。解析时只取数字部分进行比较：
def parse_version(version_str):
parts = version_str.strip().split('.')
result = []
for p in parts:
m = re.match(r'(\d+)', p)
result.append(int(m.group(1)) if m else 0)
while len(result) < 3:
result.append(0)
return tuple(result)
陷阱4: devDependencies可能不存在
部分工程的 oh-package.json5 中可能没有 devDependencies 字段，或者 devDependencies 下没有 "@ohos/hypium" 条目。这种情况下不报错（规则只检查存在的hypium版本号是否满足要求）。
输出格式
每条issue的字段：
| 字段 | 值 |
|---|---|
| rule | R021 |
| type | hypium版本号不满足要求 |
| severity | Critical |
| file | 相对路径（如arkui/xxx/oh-package.json5） |
| line | "@ohos/hypium" 所在行号 |
| testcase | - |
| snippet | "@ohos/hypium": "1.0.25" |
| suggestion | 路径: {文件路径}, 行号: {行号}, 问题描述: 在独立XTS工程 '{工程名}' 中，oh-package.json5的devDependencies.@ohos/hypium版本号为 '{版本}'，低于最低要求版本 1.0.26。 |
排除规则
- 被注释掉的
@ohos/hypium条目不检查 entry/oh-package.json5等子目录文件不检查- 工程根目录下无
oh-package.json5的不检查 devDependencies中无@ohos/hypium条目的不检查
技术规范
检测范围补充说明
检查:
- 独立XTS工程根目录下的
oh-package.json5中，devDependencies.@ohos/hypium的版本号 - 版本号 <
1.0.26时报告问题
不检查:
- 被注释掉的依赖条目
- 子目录中的
oh-package.json5 - 无
@ohos/hypium条目的文件
实际案例
全仓扫描结果（版本分布）:
- 1.0.26: 2954个工程（合规）
- 1.0.21: 33个工程（不合规，大部分已注释）
- 1.0.6: 18个工程（不合规，部分为活跃依赖如officeservice、web子系统）
- 1.0.24: 4个工程（不合规，如multimedia/av_codec）
- 1.0.25: 3个工程（不合规，如web子系统）
与其他规则的关系
R021与其他配置文件检查规则（R007/Test.json、R010/BUILD.gn、R012/p7b、R017/syscap.json）类似，都是检查工程配置文件中的特定字段值。区别在于：
- R021的扫描对象是
oh-package.json5（非标准JSON，支持注释和尾逗号） - R021使用正则提取而非
json.loads()解析，以兼容JSON5格式