hmos-arkts-deprecated-interface-checker

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. 项目分析

首先分析项目结构和配置：

# 检查项目类型（ArkTS/ETS）
# 查看 build-profile.json5 配置
# 确定 compileSdkVersion 和 compatibleSdkVersion
# 查看 module.json5 中的配置

2. 执行静态语法检查

使用 MCP 工具进行 ArkTS 静态语法检查：

步骤：

1. 获取项目 ETS 源文件列表

   • 使用 Glob 工具搜索 **/*.ets 文件
   • 排除 oh_modules 和 build 目录

2. 调用静态检查工具

   mcp_codegenie-mcp_check_ets_files
   参数: files - ETS 文件路径列表
   

3. 分析检查结果

   • 解析返回的诊断信息
   • 识别废弃接口（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（必须修复）

• 验证MCP工具可用性（必需）
• 所有废弃 API 已识别并记录
• P0 级别错误已全部修复
• 影响应用稳定性的问题已解决
• 兼容性问题已处理（最低 API 版本）

Warning（强烈建议）

• P1 级别废弃 API 已迁移
• 所有替代方案已验证可用
• 迁移后功能测试通过
• 性能无明显下降

Info（建议优化）

• P2 级别代码质量问题已处理
• 未使用的变量/导入已清理
• 代码风格符合规范
• 文档已更新

决策树

开始检查流程
│
├─ 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"
  }
}

最佳实践

✅ 推荐做法

1. 定期检查：将废弃接口检查纳入开发流程
2. 渐进式迁移：优先修复 P0 级别的问题
3. 充分测试：每次迁移后进行全面测试
4. 文档记录：记录迁移决策和注意事项
5. 关注版本：及时关注 HarmonyOS 版本更新日志

❌ 避免做法

1. 不要忽略废弃接口警告
2. 不要在关键业务逻辑中使用废弃 API
3. 不要在没有测试的情况下批量替换
4. 不要忽视兼容性要求

执行步骤

当用户需要检查废弃接口时：

1. 确认项目信息

   • 当前 HarmonyOS API 版本
   • 最低支持的 API 版本
   • 项目规模（文件数量）

2. 获取源文件列表

   • 搜索项目中的 ETS 文件
   • 排除第三方依赖目录

3. 运行静态检查

   mcp_codegenie-mcp_check_ets_files(files: [...])
   

4. 分析报告

   • 统计问题数量
   • 按严重程度分类
   • 识别废弃接口

5. 制定迁移计划

   • 确定修复优先级
   • 评估工作量
   • 提供修复建议

6. 辅助实施

   • 提供代码示例
   • 解答迁移问题
   • 验证修复结果

工具命令参考

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 参考。

输出示例

执行检查后，将提供：

1. 📊 统计摘要：各类问题数量统计
2. 📋 问题清单：按文件和优先级排序
3. 🔧 修复建议：每个问题的具体修复方案
4. 📝 代码示例：修复前后的代码对比

注意事项

• ⚠️ 本技能依赖 CodeGenie MCP Server 工具，使用前请确保已安装并配置 MCP 服务
  • 安装方式：https://github.com/open-deveco/deveco-toolbox
• ⚠️ 某些废弃 API 可能没有直接替代品，需要重构代码逻辑
• ⚠️ 迁移时注意最低支持版本要求
• ⚠️ 建议在 DevEco Studio 中打开项目以获得更好的 IDE 支持

相关资源

MCP工具

• CodeGenie MCP Server 安装指南
• 飞书指导文档

HarmonyOS开发

• HarmonyOS API 参考
• HarmonyOS 开发指南
• ArkTS 语法规范
• HarmonyOS 版本变更说明