| name | hmos-arkts-deprecated-interface-checker |
| description | 检查 HarmonyOS 项目中的废弃 SDK 接口并提供修复建议。当需要清理废弃 API、升级 API 版本、优化代码质量或进行静态语法检查时使用。提供详细的迁移方案、修复优先级分类和代码示例。 |
HarmonyOS 废弃接口检查与修复
技能概述
本技能专门用于检查 HarmonyOS 项目中使用的废弃（Deprecated）SDK 接口，并提供详细的修复建议和迁移方案。帮助开发者保持代码的现代性和可维护性。
使用场景
- ✅ 项目升级 HarmonyOS API 版本前
- ✅ 清理技术债务，移除废弃 API 调用
- ✅ 准备发布新版本，提升代码质量
- ✅ 代码审查时发现废弃接口警告
- ✅ 迁移到新 HarmonyOS 版本（如 API 10/11/12）
工作流程
0. 检查MCP工具依赖
⚠️ 重要提示：本技能依赖MCP工具
在执行任何检查操作之前，必须先检查MCP工具是否可用：
依赖的MCP工具：
mcp_codegenie-mcp_check_ets_files - ETS文件静态语法检查mcp_codegenie-mcp_harmonyos_knowledge_search - HarmonyOS知识搜索（可选）
检查方法：
尝试调用 mcp_codegenie-mcp_check_ets_files
如果工具不可用，会收到错误提示
如果MCP工具未安装：
❌ MCP工具未安装或不可用
本技能需要依赖 CodeGenie MCP Server 工具才能正常工作。
📦 安装方式：
在 MCP 配置文件中添加以下配置：
{
"mcpServers": {
"codegenie-mcp": {
"command": "npx",
"args": [
"-y",
"@deveco-codegenie/mcp@beta",
"--registry=https://registry.npmjs.org"
],
"env": {
"PROJECT_PATH": "${workspaceFolder}",
"DEVECO_PATH": "path to deveco studio"
}
}
}
}
📚 详细文档：
- GitHub: https://github.com/open-deveco/deveco-toolbox
- 飞书指导文档: https://my.feishu.cn/wiki/open-deveco/deveco-toolbox
💡 安装完成后，请重新使用本技能。
验证成功后继续执行后续步骤。
1. 项目分析
首先分析项目结构和配置：
2. 执行静态语法检查
使用 MCP 工具进行 ArkTS 静态语法检查：
步骤：
-
获取项目 ETS 源文件列表
- 使用 Glob 工具搜索
**/*.ets 文件
- 排除
oh_modules 和 build 目录
-
调用静态检查工具
mcp_codegenie-mcp_check_ets_files
参数: files - ETS 文件路径列表
-
分析检查结果
- 解析返回的诊断信息
- 识别废弃接口（code: 6387, deprecatedSymbol）
- 统计警告和错误数量
3. 生成检查报告
报告包含以下信息：
报告格式示例：
📊 HarmonyOS 废弃接口检查报告
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔴 严重：X 个错误
🟡 警告：X 个警告
ℹ️ 信息：X 个废弃接口提示
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
【信息】使用已废弃的 API
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📍 文件：entry/src/main/ets/pages/Index.ets:8:12
⚠️ 问题：使用了 @Deprecated 的 px2vp 方法
📚 废弃原因：该签名已被标记为废弃
💡 替代方案：使用新的 API 接口
🔗 官方文档：https://developer.huawei.com/consumer/cn/doc/harmonyos-references/
📋 迁移示例：
// 旧代码:
px2vp(100)
// 新代码:
// 使用推荐的替代方法
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
【警告】未使用的变量
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📍 文件：entry/src/main/ets/pages/Index.ets:8:8
⚠️ 问题：变量 'a' 已声明但从未被使用
💡 建议：删除未使用的变量或使用下划线前缀命名
4. 提供修复方案
针对每个问题提供：
修复优先级分类
- P0 - 必须修复：影响应用稳定性或兼容性的错误
- P1 - 强烈建议：废弃 API 警告，有明显替代方案
- P2 - 可选优化：未使用变量等代码质量问题
迁移指导
每个修复建议包含：
- ✅ 具体的代码替换示例
- ✅ 兼容性说明（最低支持 API 级别）
- ✅ 性能影响评估
- ✅ 测试建议
5. 辅助修复（可选）
提供自动化修复指导：
- 使用 DevEco Studio 的快速修复功能（Alt+Enter）
- 手动应用修复建议
- 批量替换废弃 API
检查清单
Critical（必须修复）
Warning（强烈建议）
Info（建议优化）
决策树
开始检查流程
│
├─ MCP工具可用？
│ ├─ 否 → 提示安装MCP工具 → 终止
│ └─ 是 → 继续
│
├─ 发现废弃 API 警告
│ │
│ ├─ 是否有直接替代 API？
│ │ ├─ 是 → 检查最低支持版本
│ │ │ ├─ 满足要求 → 使用替代 API（P1）
│ │ │ └─ 不满足 → 保持现状，添加注释说明（P2）
│ │ │
│ │ └─ 否 → 需要重构代码逻辑
│ │ ├─ 影响核心功能 → 立即处理（P0）
│ │ └─ 非核心功能 → 计划迁移（P1）
│ │
│ └─ 问题严重程度判定
│ ├─ 导致编译失败 → Critical（P0）
│ │ └─ 行动：必须立即修复
│ ├─ 运行时可能出错 → Warning（P1）
│ │ └─ 行动：强烈建议修复
│ └─ 仅警告提示 → Info（P2）
│ └─ 行动：可选优化
常见废弃 API 及替代方案
详细的废弃 API 列表、迁移示例和错误码参考请查看 废弃 API 参考。
快速参考
| 废弃 API | 替代方案 | 说明 |
|---|
px2vp(value: number) | 使用新的签名 | 参数类型变更 |
vp2px(value: number) | 使用新的签名 | 参数类型变更 |
@ohos.fileio | @ohos.file.fs | 模块迁移 |
配置建议
详细的配置示例和说明请查看 配置参考。
快速配置
code-linter.json5:
{
"files": ["**/*.ets"],
"ignore": ["**/oh_modules/**", "**/build/**"],
"rules": {
"no-unused-vars": "warn"
}
}
最佳实践
✅ 推荐做法
- 定期检查：将废弃接口检查纳入开发流程
- 渐进式迁移：优先修复 P0 级别的问题
- 充分测试：每次迁移后进行全面测试
- 文档记录：记录迁移决策和注意事项
- 关注版本：及时关注 HarmonyOS 版本更新日志
❌ 避免做法
- 不要忽略废弃接口警告
- 不要在关键业务逻辑中使用废弃 API
- 不要在没有测试的情况下批量替换
- 不要忽视兼容性要求
执行步骤
当用户需要检查废弃接口时：
-
确认项目信息
- 当前 HarmonyOS API 版本
- 最低支持的 API 版本
- 项目规模（文件数量）
-
获取源文件列表
-
运行静态检查
mcp_codegenie-mcp_check_ets_files(files: [...])
-
分析报告
-
制定迁移计划
-
辅助实施
工具命令参考
MCP 工具
| 工具名称 | 用途 |
|---|
mcp_codegenie-mcp_check_ets_files | ETS 文件静态语法检查 |
mcp_codegenie-mcp_build_project | 构建项目 |
mcp_codegenie-mcp_harmonyos_knowledge_search | 搜索 HarmonyOS 开发文档 |
常见错误码
| 错误码 | 类型 | 说明 |
|---|
| 6133 | Warning | 未使用的变量/符号 |
| 6387 | Information | 使用了废弃的 API |
详细的诊断信息格式和错误码说明请查看 废弃 API 参考。
输出示例
执行检查后，将提供：
- 📊 统计摘要：各类问题数量统计
- 📋 问题清单：按文件和优先级排序
- 🔧 修复建议：每个问题的具体修复方案
- 📝 代码示例：修复前后的代码对比
注意事项
- ⚠️ 本技能依赖 CodeGenie MCP Server 工具，使用前请确保已安装并配置 MCP 服务
- ⚠️ 某些废弃 API 可能没有直接替代品，需要重构代码逻辑
- ⚠️ 迁移时注意最低支持版本要求
- ⚠️ 建议在 DevEco Studio 中打开项目以获得更好的 IDE 支持
相关资源
MCP工具
HarmonyOS开发
