HarmonyOS开发：依赖关系检查

📌 核心要点：依赖关系是项目的血管系统——循环依赖是血栓，版本冲突是高血压，不查不治，迟早出大问题。

背景与动机

你有没有遇到过这种诡异的事？明明代码没改，构建突然失败了。排查半天发现是某个依赖库悄悄升了版本，API变了，你的代码调不动了。更离谱的是，你项目里同时存在同一个库的3个版本，每个版本行为还不一样——你调的是哪个版本？天知道。

依赖管理是项目基础设施中最容易被忽视、出问题最隐蔽的环节。代码层面的Bug好排查——报错信息明确，堆栈清晰。依赖问题呢？编译过了但运行时行为异常，排查起来像大海捞针。

鸿蒙项目的依赖问题更复杂。HAP、HSP、HAR三种模块类型，每种有不同的依赖传播规则。HSP的依赖会传递给依赖它的模块，HAR的依赖不会。搞混了？恭喜你，运行时找不到类。

循环依赖更是鸿蒙项目的噩梦。两个HSP互相依赖，编译器可能不报错，但运行时初始化顺序不对，直接白屏。这种Bug在开发环境可能不出现，到了真机就炸了。

核心原理

鸿蒙模块依赖体系

graph TD
    A[鸿蒙模块依赖体系] --> B[HAP应用模块]
    A --> C[HSP共享包]
    A --> D[HAR静态共享包]
    
    B --> B1[可以依赖HSP和HAR]
    B --> B2[不能依赖其他HAP]
    B --> B3[依赖传递: HSP的依赖会传递]
    
    C --> C1[可以依赖HSP和HAR]
    C --> C2[依赖传递: 依赖会传递给上层]
    C --> C3[运行时动态加载]
    
    D --> D1[可以依赖HAR]
    D --> D2[依赖不传递]
    D --> D3[编译时静态合并]
    
    classDef mainStyle fill:#FF6B6B,stroke:#C0392B,color:#fff,font-weight:bold
    classDef moduleStyle fill:#4ECDC4,stroke:#1ABC9C,color:#fff
    classDef detailStyle fill:#FFE66D,stroke:#F39C12,color:#333
    
    class A mainStyle
    class B,C,D moduleStyle
    class B1,B2,B3,C1,C2,C3,D1,D2,D3 detailStyle

依赖检查的四个维度

graph LR
    A[依赖检查] --> B[结构检查]
    A --> C[版本检查]
    A --> D[安全检查]
    A --> E[合规检查]
    
    B --> B1[循环依赖检测]
    B --> B2[依赖方向验证]
    B --> B3[层级规则检查]
    
    C --> C1[版本冲突检测]
    C --> C2[版本范围约束]
    C --> C3[废弃版本检测]
    
    D --> D1[已知漏洞扫描]
    D --> D2[许可证合规]
    D --> D3[供应链安全]
    
    E --> E1[最小依赖原则]
    E --> E2[依赖数量控制]
    E --> E3[依赖来源审核]
    
    classDef mainStyle fill:#FF6B6B,stroke:#C0392B,color:#fff,font-weight:bold
    classDef subStyle fill:#4ECDC4,stroke:#1ABC9C,color:#fff
    classDef detailStyle fill:#FFE66D,stroke:#F39C12,color:#333
    
    class A mainStyle
    class B,C,D,E subStyle
    class B1,B2,B3,C1,C2,C3,D1,D2,D3,E1,E2,E3 detailStyle

代码实战

基础用法：解析模块依赖关系

先搞清楚项目里到底有哪些依赖：

// dependency-parser.ts
// 解析oh-package.json5中的依赖关系

// 依赖信息
interface DependencyInfo {
  name: string;           // 依赖名称
  version: string;        // 版本号
  type: 'oh-package' | 'npm';  // 依赖来源
  isDev: boolean;         // 是否开发依赖
  resolved?: string;      // 实际解析的版本
}

// 模块依赖信息
interface ModuleDependencyInfo {
  moduleName: string;     // 模块名
  moduleType: 'hap' | 'hsp' | 'har';
  dependencies: DependencyInfo[];
  devDependencies: DependencyInfo[];
}

// 解析oh-package.json5
function parseOhPackage(configStr: string): ModuleDependencyInfo {
  // oh-package.json5格式示例:
  // {
  //   "name": "@ohos/entry",
  //   "version": "1.0.0",
  //   "description": "entry module",
  //   "main": "Index.ets",
  //   "author": "",
  //   "license": "",
  //   "dependencies": {
  //     "@ohos/common": "1.0.0",
  //     "@ohos/network": "../network"
  //   },
  //   "devDependencies": {
  //     "@ohos/hypium": "1.0.0"
  //   }
  // }

  const config = JSON.parse(configStr);

  const dependencies: DependencyInfo[] = [];
  if (config.dependencies) {
    for (const [name, version] of Object.entries(config.dependencies)) {
      dependencies.push({
        name,
        version: version as string,
        type: name.startsWith('@ohos/') ? 'oh-package' : 'npm',
        isDev: false,
      });
    }
  }

  const devDependencies: DependencyInfo[] = [];
  if (config.devDependencies) {
    for (const [name, version] of Object.entries(config.devDependencies)) {
      devDependencies.push({
        name,
        version: version as string,
        type: name.startsWith('@ohos/') ? 'oh-package' : 'npm',
        isDev: true,
      });
    }
  }

  return {
    moduleName: config.name || 'unknown',
    moduleType: 'hap',  // 需要根据build-profile.json5补充
    dependencies,
    devDependencies,
  };
}

// 构建项目依赖树
function buildDependencyTree(
  modules: ModuleDependencyInfo[]
): Map<string, string[]> {
  const depTree = new Map<string, string[]>();

  for (const module of modules) {
    const deps = module.dependencies
      .filter(d => d.type === 'oh-package')
      .map(d => d.name);
    depTree.set(module.moduleName, deps);
  }

  return depTree;
}

进阶用法：循环依赖检测与版本冲突分析

// dependency-analyzer.ts
// 依赖关系深度分析器

interface CircularDep {
  cycle: string[];        // 循环路径
  severity: 'error' | 'warning';
  message: string;
}

interface VersionConflict {
  packageName: string;
  versions: Map<string, string[]>;  // 版本号 -> 依赖该版本的模块列表
  isConflict: boolean;
}

class DependencyAnalyzer {
  private depTree: Map<string, string[]> = new Map();
  private moduleVersions: Map<string, Map<string, string>> = new Map();
  // 模块名 -> (依赖包名 -> 版本号)

  // 设置依赖树
  setDependencyTree(tree: Map<string, string[]>): void {
    this.depTree = tree;
  }

  // 设置模块版本信息
  setModuleVersions(versions: Map<string, Map<string, string>>): void {
    this.moduleVersions = versions;
  }

  // ==========================================
  // 循环依赖检测
  // ==========================================
  detectCircularDependencies(): CircularDep[] {
    const results: CircularDep[] = [];
    const visited = new Set<string>();
    const recursionStack = new Set<string>();

    const dfs = (node: string, path: string[]): void => {
      visited.add(node);
      recursionStack.add(node);

      const neighbors = this.depTree.get(node) || [];
      for (const neighbor of neighbors) {
        if (!visited.has(neighbor)) {
          dfs(neighbor, [...path, neighbor]);
        } else if (recursionStack.has(neighbor)) {
          // 找到循环
          const cycleStart = path.indexOf(neighbor);
          const cycle = [...path.slice(cycleStart), neighbor];

          // 判断严重程度：HSP间的循环依赖是error，HAR间是warning
          const severity: 'error' | 'warning' = 'error'; // 简化判断

          results.push({
            cycle,
            severity,
            message: `循环依赖: ${cycle.join(' → ')}`,
          });
        }
      }

      recursionStack.delete(node);
    };

    for (const node of this.depTree.keys()) {
      if (!visited.has(node)) {
        dfs(node, [node]);
      }
    }

    return results;
  }

  // ==========================================
  // 版本冲突检测
  // ==========================================
  detectVersionConflicts(): VersionConflict[] {
    const results: VersionConflict[] = [];

    // 收集每个依赖包的所有版本
    const packageVersions = new Map<string, Map<string, string[]>>();
    // 包名 -> (版本号 -> 使用该版本的模块列表)

    for (const [moduleName, deps] of this.moduleVersions) {
      for (const [packageName, version] of deps) {
        if (!packageVersions.has(packageName)) {
          packageVersions.set(packageName, new Map());
        }
        const versionMap = packageVersions.get(packageName)!;
        if (!versionMap.has(version)) {
          versionMap.set(version, []);
        }
        versionMap.get(version)!.push(moduleName);
      }
    }

    // 检查是否有多个版本
    for (const [packageName, versionMap] of packageVersions) {
      if (versionMap.size > 1) {
        results.push({
          packageName,
          versions: versionMap,
          isConflict: true,
        });
      }
    }

    return results;
  }

  // ==========================================
  // 依赖深度分析
  // ==========================================
  calculateDependencyDepth(): Map<string, number> {
    const depths = new Map<string, number>();
    const calculating = new Set<string>();

    const calcDepth = (node: string): number => {
      if (depths.has(node)) return depths.get(node)!;
      if (calculating.has(node)) return 0;  // 循环依赖，返回0

      calculating.add(node);
      const neighbors = this.depTree.get(node) || [];

      if (neighbors.length === 0) {
        depths.set(node, 0);
        calculating.delete(node);
        return 0;
      }

      let maxChildDepth = 0;
      for (const neighbor of neighbors) {
        maxChildDepth = Math.max(maxChildDepth, calcDepth(neighbor));
      }

      const depth = maxChildDepth + 1;
      depths.set(node, depth);
      calculating.delete(node);
      return depth;
    };

    for (const node of this.depTree.keys()) {
      calcDepth(node);
    }

    return depths;
  }

  // ==========================================
  // 生成综合分析报告
  // ==========================================
  generateReport(): string {
    let report = '╔══════════════════════════════════════════╗\n';
    report +=    '║      依赖关系分析报告                    ║\n';
    report +=    '╚══════════════════════════════════════════╝\n\n';

    // 1. 循环依赖
    const circularDeps = this.detectCircularDependencies();
    report += `🔄 循环依赖: ${circularDeps.length} 个\n`;
    if (circularDeps.length > 0) {
      for (const dep of circularDeps) {
        const icon = dep.severity === 'error' ? '❌' : '⚠️';
        report += `   ${icon} ${dep.message}\n`;
      }
    } else {
      report += '   ✅ 未检测到循环依赖\n';
    }
    report += '\n';

    // 2. 版本冲突
    const conflicts = this.detectVersionConflicts();
    report += `📦 版本冲突: ${conflicts.length} 个\n`;
    if (conflicts.length > 0) {
      for (const conflict of conflicts) {
        report += `   ⚠️ ${conflict.packageName}:\n`;
        for (const [version, modules] of conflict.versions) {
          report += `      v${version} ← ${modules.join(', ')}\n`;
        }
      }
    } else {
      report += '   ✅ 未检测到版本冲突\n';
    }
    report += '\n';

    // 3. 依赖深度
    const depths = this.calculateDependencyDepth();
    report += `📏 依赖深度:\n`;
    const sortedDepths = [...depths.entries()]
      .sort((a, b) => b[1] - a[1]);
    for (const [module, depth] of sortedDepths.slice(0, 10)) {
      const bar = '▓'.repeat(depth) + '░'.repeat(Math.max(0, 5 - depth));
      report += `   ${module}: ${bar} ${depth}层\n`;
    }
    report += '\n';

    // 4. 总结
    const hasError = circularDeps.some(d => d.severity === 'error') || 
                     conflicts.length > 0;
    if (hasError) {
      report += '🚫 依赖检查未通过，请修复上述问题\n';
    } else {
      report += '✅ 依赖检查通过\n';
    }

    return report;
  }
}

// 使用示例
const analyzer = new DependencyAnalyzer();

// 构建依赖树
const depTree = new Map<string, string[]>([
  ['@ohos/entry', ['@ohos/home', '@ohos/common']],
  ['@ohos/home', ['@ohos/common', '@ohos/network']],
  ['@ohos/network', ['@ohos/common']],
  ['@ohos/common', []],
]);

analyzer.setDependencyTree(depTree);

// 设置版本信息
const versions = new Map<string, Map<string, string>>([
  ['@ohos/entry', new Map([
    ['@ohos/common', '1.0.0'],
    ['@ohos/home', '1.0.0'],
  ])],
  ['@ohos/home', new Map([
    ['@ohos/common', '1.1.0'],  // 版本不一致！
    ['@ohos/network', '1.0.0'],
  ])],
  ['@ohos/network', new Map([
    ['@ohos/common', '1.0.0'],
  ])],
]);

analyzer.setModuleVersions(versions);
console.log(analyzer.generateReport());

完整示例：依赖安全审计

// dependency-security-audit.ts
// 依赖安全审计工具

interface SecurityIssue {
  package: string;
  version: string;
  severity: 'critical' | 'high' | 'medium' | 'low';
  type: string;
  description: string;
  recommendation: string;
}

interface LicenseInfo {
  package: string;
  license: string;
  isCompatible: boolean;  // 是否与项目许可证兼容
}

class DependencySecurityAuditor {
  private issues: SecurityIssue[] = [];
  private licenses: LicenseInfo[] = [];

  // 已知漏洞数据库（实际项目中应该从远程获取）
  private knownVulnerabilities: Map<string, SecurityIssue[]> = new Map([
    ['@ohos/old-crypto@1.0.0', [{
      package: '@ohos/old-crypto',
      version: '1.0.0',
      severity: 'critical',
      type: 'CVE-2024-XXXX',
      description: '加密算法存在已知漏洞，可被中间人攻击',
      recommendation: '升级到@ohos/old-crypto@2.0.0或使用@ohos/crypto-framework',
    }]],
  ]);

  // 不兼容的许可证列表
  private incompatibleLicenses: string[] = [
    'GPL-3.0',       // 传染性开源协议
    'AGPL-3.0',      // 网络传染性
    'SSPL',          // 非开源
  ];

  // 检查已知漏洞
  auditVulnerabilities(
    dependencies: Map<string, string>
  ): SecurityIssue[] {
    this.issues = [];

    for (const [name, version] of dependencies) {
      const key = `${name}@${version}`;
      const vulns = this.knownVulnerabilities.get(key);
      if (vulns) {
        this.issues.push(...vulns);
      }

      // 检查是否使用了过旧的版本
      if (version.startsWith('0.')) {
        this.issues.push({
          package: name,
          version,
          severity: 'medium',
          type: 'pre-release',
          description: `${name}@${version} 是预发布版本，不建议在生产环境使用`,
          recommendation: `升级到正式发布版本`,
        });
      }
    }

    return this.issues;
  }

  // 检查许可证合规
  auditLicenses(
    dependencies: Map<string, string>
  ): LicenseInfo[] {
    this.licenses = [];

    for (const [name, version] of dependencies) {
      // 实际项目中需要读取包的LICENSE文件
      // 这里用模拟数据
      const license = this.getPackageLicense(name);
      const isCompatible = !this.incompatibleLicenses.includes(license);

      this.licenses.push({
        package: name,
        license,
        isCompatible,
      });
    }

    return this.licenses;
  }

  // 检查依赖来源可信度
  auditSourceTrust(
    dependencies: Map<string, string>
  ): SecurityIssue[] {
    const trustIssues: SecurityIssue[] = [];

    for (const [name, version] of dependencies) {
      // 检查是否来自官方源
      if (!name.startsWith('@ohos/') && !name.startsWith('@hw/')) {
        trustIssues.push({
          package: name,
          version,
          severity: 'low',
          type: 'untrusted-source',
          description: `${name} 不是华为官方包，请确认来源可信`,
          recommendation: '优先使用@ohos官方包，第三方包需审核',
        });
      }

      // 检查是否使用了本地路径依赖
      if (version.startsWith('file:') || version.startsWith('../')) {
        trustIssues.push({
          package: name,
          version,
          severity: 'medium',
          type: 'local-dependency',
          description: `${name} 使用了本地路径依赖，发布时可能丢失`,
          recommendation: '发布前确保本地依赖已替换为版本号',
        });
      }
    }

    return trustIssues;
  }

  // 生成审计报告
  generateAuditReport(
    dependencies: Map<string, string>
  ): string {
    let report = '╔══════════════════════════════════════════╗\n';
    report +=    '║      依赖安全审计报告                    ║\n';
    report +=    '╚══════════════════════════════════════════╝\n\n';

    // 漏洞审计
    const vulns = this.auditVulnerabilities(dependencies);
    report += `🔒 安全漏洞: ${vulns.length} 个\n`;
    const criticalCount = vulns.filter(v => v.severity === 'critical').length;
    const highCount = vulns.filter(v => v.severity === 'high').length;
    if (vulns.length > 0) {
      report += `   严重: ${criticalCount} | 高危: ${highCount}\n`;
      for (const vuln of vulns) {
        const icon = vuln.severity === 'critical' ? '🔴' :
                     vuln.severity === 'high' ? '🟠' :
                     vuln.severity === 'medium' ? '🟡' : '🟢';
        report += `   ${icon} [${vuln.type}] ${vuln.package}@${vuln.version}\n`;
        report += `      ${vuln.description}\n`;
        report += `      建议: ${vuln.recommendation}\n`;
      }
    } else {
      report += '   ✅ 未发现已知漏洞\n';
    }
    report += '\n';

    // 许可证审计
    const licenses = this.auditLicenses(dependencies);
    const incompatibleLicenses = licenses.filter(l => !l.isCompatible);
    report += `📋 许可证合规: ${incompatibleLicenses.length} 个不兼容\n`;
    if (incompatibleLicenses.length > 0) {
      for (const lic of incompatibleLicenses) {
        report += `   ⚠️ ${lic.package}: ${lic.license} (不兼容)\n`;
      }
    } else {
      report += '   ✅ 所有依赖许可证兼容\n';
    }
    report += '\n';

    // 来源审计
    const sourceIssues = this.auditSourceTrust(dependencies);
    report += `🌐 来源可信度: ${sourceIssues.length} 个需关注\n`;
    if (sourceIssues.length > 0) {
      for (const issue of sourceIssues) {
        report += `   ⚠️ ${issue.package}: ${issue.description}\n`;
      }
    } else {
      report += '   ✅ 所有依赖来源可信\n';
    }

    return report;
  }

  // 辅助方法：获取包的许可证
  private getPackageLicense(name: string): string {
    // 模拟数据
    const licenseMap: Map<string, string> = new Map([
      ['@ohos/common', 'Apache-2.0'],
      ['@ohos/network', 'Apache-2.0'],
      ['@ohos/old-crypto', 'MIT'],
      ['third-party-lib', 'GPL-3.0'],
    ]);
    return licenseMap.get(name) || 'Unknown';
  }
}

踩坑与注意事项

坑1：HSP依赖传递的陷阱

HSP的依赖会传递给上层模块。你在HSP A里依赖了HSP B，那么依赖HSP A的HAP也会间接依赖HSP B。如果你不知道这一点，可能会在HAP里直接使用HSP B的API，结果HSP B升级后HAP行为变了，你还不知道为什么。

解决方案：

• HSP的依赖要精简，只依赖必要的包
• HSP导出的API要明确，不要暴露内部依赖
• 在oh-package.json5中明确标注哪些依赖会传递

坑2：HAR和HSP搞混

HAR是静态合并的，HSP是动态加载的。混用会导致各种诡异问题：类找不到、单例不唯一、资源冲突。

解决方案：

• 公共基础库用HAR：工具类、常量、类型定义
• 功能模块用HSP：需要独立更新、体积较大的模块
• 不要在HAR里引用HSP的类，编译时HSP还没加载

坑3：版本范围写法导致不确定性

"@ohos/common": "^1.0.0"这种写法允许安装1.x的任何版本。今天装的是1.0.0，明天可能是1.2.0，行为可能不同。

解决方案：

• 生产项目锁定精确版本："@ohos/common": "1.0.0"
• 使用lock文件：oh-package-lock.json5确保每次安装版本一致
• CI中检查lock文件是否与oh-package.json5一致

坑4：循环依赖的隐蔽性

两个模块A和B互相依赖，但不是直接依赖——A依赖C，C依赖D，D依赖B，B依赖A。这种间接循环依赖更难发现。

解决方案：

• 使用依赖分析工具自动检测所有循环路径
• CI中集成循环依赖检查，发现就阻断
• 模块设计时遵循单向依赖原则

坑5：依赖升级的连锁反应

升级一个依赖，发现它依赖的其他包也跟着升了，导致整个依赖树变了。

解决方案：

• 升级前先看changelog，了解breaking changes
• 使用--dry-run先看升级会影响哪些包
• 升级后跑全量测试，确保没有回归

HarmonyOS 6适配说明

HarmonyOS 6在依赖管理方面的改进：

1. oh-package-lock.json5自动生成：构建时自动生成lock文件，确保团队成员安装的依赖版本完全一致。之前需要手动管理，现在构建系统自动处理。

2. 依赖冲突自动解析：当检测到版本冲突时，构建系统会自动选择兼容的最高版本，并给出冲突提示。不再需要手动排查版本冲突。

3. 循环依赖编译时检测：HarmonyOS 6的方舟编译器在编译阶段就能检测循环依赖，直接报错，不用等到运行时才发现。

4. 依赖树可视化工具：DevEco Studio 6内置了依赖树可视化工具，可以图形化展示模块间的依赖关系，循环依赖用红色高亮，版本冲突用黄色标记。

5. 依赖安全扫描集成：构建时自动扫描依赖的安全漏洞，发现已知漏洞会给出警告和修复建议。

总结

依赖管理是项目基础设施的基石。循环依赖、版本冲突、安全漏洞——这些问题不解决，项目迟早翻车。

核心要点：

• 搞清HSP/HAR的区别：依赖传递行为完全不同
• 循环依赖零容忍：发现就修，不要积累
• 版本要锁定：生产项目不用范围版本
• 安全审计不能少：第三方依赖可能带漏洞
• 依赖要精简：能不依赖就不依赖，最小化原则