HarmonyOS开发：质量门禁

核心要点：质量门禁是代码进入主分支的安检口——没有门禁，任何代码都能合入；有了门禁，只有质量达标的代码才能放行。

背景与动机

你有没有见过这种项目？主分支随时可以合代码，没有测试覆盖率要求，没有静态分析检查，没有安全扫描。结果呢？主分支经常构建失败，上线后Bug不断，开发团队天天救火。

为什么会出现这种情况？因为没有质量门禁。任何代码都能合入主分支，质量全凭开发者自觉。你觉得大家都会自觉写测试、自觉跑静态分析？想多了。赶工期的时候，测试不写、Lint不跑、安全不管——先把功能上了再说。

质量门禁要解决的核心问题：用自动化的质量检查替代人工的质量自觉。不达标？对不起，合不了。这不是刁难开发者，是保护整个项目。

鸿蒙项目为什么特别需要质量门禁？因为鸿蒙的发布流程更严格——华为应用市场有审核，质量不达标的应用直接拒绝。你在开发阶段不设门禁，到了上架阶段被拒，损失更大。

核心原理

质量门禁的检查项

graph TD
    A[质量门禁] --> B[代码质量]
    A --> C[测试质量]
    A --> D[安全质量]
    A --> E[性能质量]
    A --> F[规范质量]
    
    B --> B1[静态分析0 Error]
    B --> B2[Lint检查通过]
    B --> B3[代码复杂度达标]
    
    C --> C1[单元测试覆盖率≥80%]
    C --> C2[关键路径测试通过]
    C --> C3[无跳过的测试用例]
    
    D --> D1[安全扫描0 Critical]
    D --> D2[无硬编码密钥]
    D --> D3[依赖无已知漏洞]
    
    E --> E1[启动时间不超基线]
    E --> E2[帧率不低于基线]
    E --> E3[内存不超基线]
    
    F --> F1[PR关联Issue]
    F --> F2[至少2人Review]
    F --> F3[提交信息规范]
    
    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,F subStyle
    class B1,B2,B3,C1,C2,C3,D1,D2,D3,E1,E2,E3,F1,F2,F3 detailStyle

门禁决策流程

graph LR
    A[代码提交] --> B[触发CI流水线]
    B --> C[静态分析]
    B --> D[单元测试]
    B --> E[安全扫描]
    B --> F[性能测试]
    
    C --> G{门禁判定}
    D --> G
    E --> G
    F --> G
    
    G -->|全部通过| H[✅ 允许合并]
    G -->|Critical未通过| I[❌ 阻断合并]
    G -->|Warning未通过| J[⚠️ 提醒但允许]
    
    classDef startStyle fill:#A8E6CF,stroke:#2ECC71,color:#333
    classDef processStyle fill:#4ECDC4,stroke:#1ABC9C,color:#fff
    classDef decisionStyle fill:#6C5CE7,stroke:#8E44AD,color:#fff
    classDef passStyle fill:#2ECC71,stroke:#27AE60,color:#fff
    classDef failStyle fill:#FF6B6B,stroke:#E74C3C,color:#fff
    classDef warnStyle fill:#FFE66D,stroke:#F39C12,color:#333
    
    class A startStyle
    class B,C,D,E,F processStyle
    class G decisionStyle
    class H passStyle
    class I failStyle
    class J warnStyle

代码实战

基础用法：门禁规则配置

// quality-gate-config.ts
// 质量门禁规则配置

// 门禁规则
interface GateRule {
  id: string;                    // 规则ID
  name: string;                  // 规则名称
  category: string;              // 分类
  threshold: number;             // 阈值
  operator: '>=' | '<=' | '==' | '!=';  // 比较操作符
  severity: 'block' | 'warn' | 'info';  // 门禁级别
  enabled: boolean;              // 是否启用
  description: string;           // 描述
}

// 门禁检查结果
interface GateResult {
  rule: GateRule;
  actualValue: number;
  passed: boolean;
  message: string;
}

// 门禁配置
class QualityGateConfig {
  private rules: GateRule[] = [];

  constructor() {
    this.initDefaultRules();
  }

  // 初始化默认门禁规则
  private initDefaultRules(): void {
    // === 代码质量门禁 ===
    this.rules.push({
      id: 'CODE-001',
      name: '静态分析错误数',
      category: '代码质量',
      threshold: 0,
      operator: '<=',
      severity: 'block',
      enabled: true,
      description: '静态分析Error数量必须为0',
    });

    this.rules.push({
      id: 'CODE-002',
      name: 'Lint错误数',
      category: '代码质量',
      threshold: 0,
      operator: '<=',
      severity: 'block',
      enabled: true,
      description: 'Lint Error数量必须为0',
    });

    this.rules.push({
      id: 'CODE-003',
      name: 'Lint警告数',
      category: '代码质量',
      threshold: 10,
      operator: '<=',
      severity: 'warn',
      enabled: true,
      description: 'Lint Warning数量不超过10',
    });

    this.rules.push({
      id: 'CODE-004',
      name: '函数最大复杂度',
      category: '代码质量',
      threshold: 15,
      operator: '<=',
      severity: 'warn',
      enabled: true,
      description: '函数圈复杂度不超过15',
    });

    // === 测试质量门禁 ===
    this.rules.push({
      id: 'TEST-001',
      name: '单元测试覆盖率',
      category: '测试质量',
      threshold: 80,
      operator: '>=',
      severity: 'block',
      enabled: true,
      description: '单元测试行覆盖率不低于80%',
    });

    this.rules.push({
      id: 'TEST-002',
      name: '测试通过率',
      category: '测试质量',
      threshold: 100,
      operator: '==',
      severity: 'block',
      enabled: true,
      description: '所有测试用例必须通过',
    });

    this.rules.push({
      id: 'TEST-003',
      name: '跳过测试数',
      category: '测试质量',
      threshold: 0,
      operator: '<=',
      severity: 'warn',
      enabled: true,
      description: '不允许跳过测试用例',
    });

    // === 安全质量门禁 ===
    this.rules.push({
      id: 'SEC-001',
      name: '严重安全漏洞数',
      category: '安全质量',
      threshold: 0,
      operator: '<=',
      severity: 'block',
      enabled: true,
      description: 'Critical/High级别安全漏洞必须为0',
    });

    this.rules.push({
      id: 'SEC-002',
      name: '硬编码密钥数',
      category: '安全质量',
      threshold: 0,
      operator: '<=',
      severity: 'block',
      enabled: true,
      description: '不允许硬编码密钥/密码',
    });

    // === 性能质量门禁 ===
    this.rules.push({
      id: 'PERF-001',
      name: '冷启动时间',
      category: '性能质量',
      threshold: 1500,
      operator: '<=',
      severity: 'warn',
      enabled: true,
      description: '冷启动时间不超过1500ms',
    });

    this.rules.push({
      id: 'PERF-002',
      name: '滚动帧率',
      category: '性能质量',
      threshold: 55,
      operator: '>=',
      severity: 'warn',
      enabled: true,
      description: '列表滚动帧率不低于55fps',
    });

    // === 规范质量门禁 ===
    this.rules.push({
      id: 'NORM-001',
      name: 'PR审核人数',
      category: '规范质量',
      threshold: 2,
      operator: '>=',
      severity: 'block',
      enabled: true,
      description: 'PR至少需要2人审核通过',
    });

    this.rules.push({
      id: 'NORM-002',
      name: 'PR关联Issue',
      category: '规范质量',
      threshold: 1,
      operator: '>=',
      severity: 'warn',
      enabled: true,
      description: 'PR必须关联至少1个Issue',
    });
  }

  // 获取所有规则
  getRules(): GateRule[] {
    return this.rules.filter(r => r.enabled);
  }

  // 获取指定分类的规则
  getRulesByCategory(category: string): GateRule[] {
    return this.rules.filter(r => r.enabled && r.category === category);
  }

  // 添加自定义规则
  addRule(rule: GateRule): void {
    this.rules.push(rule);
  }

  // 禁用规则
  disableRule(ruleId: string): void {
    const rule = this.rules.find(r => r.id === ruleId);
    if (rule) {
      rule.enabled = false;
    }
  }

  // 修改规则阈值
  updateThreshold(ruleId: string, threshold: number): void {
    const rule = this.rules.find(r => r.id === ruleId);
    if (rule) {
      rule.threshold = threshold;
    }
  }
}

进阶用法：门禁检查执行器

// quality-gate-runner.ts
// 质量门禁执行器

// 各项检查的实际值
interface QualityMetrics {
  // 代码质量
  staticAnalysisErrors: number;
  staticAnalysisWarnings: number;
  lintErrors: number;
  lintWarnings: number;
  maxComplexity: number;
  
  // 测试质量
  testCoverage: number;        // 百分比
  testPassRate: number;        // 百分比
  skippedTests: number;
  totalTests: number;
  failedTests: number;
  
  // 安全质量
  criticalVulnerabilities: number;
  highVulnerabilities: number;
  hardcodedSecrets: number;
  
  // 性能质量
  coldStartupTime: number;     // ms
  scrollFps: number;           // fps
  peakMemory: number;          // MB
  
  // 规范质量
  reviewApprovals: number;
  linkedIssues: number;
}

class QualityGateRunner {
  private config: QualityGateConfig;
  private results: GateResult[] = [];

  constructor() {
    this.config = new QualityGateConfig();
  }

  // 执行门禁检查
  evaluate(metrics: QualityMetrics): {
    passed: boolean;
    blocked: boolean;
    results: GateResult[];
    summary: string;
  } {
    this.results = [];
    const rules = this.config.getRules();

    // 逐条检查
    for (const rule of rules) {
      const actualValue = this.getMetricValue(rule.id, metrics);
      const passed = this.evaluateRule(rule, actualValue);

      this.results.push({
        rule,
        actualValue,
        passed,
        message: passed ? 
          `${rule.name}: 通过 (实际值: ${actualValue})` :
          `${rule.name}: 未通过 (阈值: ${rule.threshold}, 实际值: ${actualValue})`,
      });
    }

    // 汇总结果
    const blocked = this.results.some(r => !r.passed && r.rule.severity === 'block');
    const hasWarning = this.results.some(r => !r.passed && r.rule.severity === 'warn');
    const passed = !blocked;

    return {
      passed,
      blocked,
      results: this.results,
      summary: this.generateSummary(passed, blocked, hasWarning),
    };
  }

  // 获取指标值
  private getMetricValue(ruleId: string, metrics: QualityMetrics): number {
    const mapping: Record<string, number> = {
      'CODE-001': metrics.staticAnalysisErrors,
      'CODE-002': metrics.lintErrors,
      'CODE-003': metrics.lintWarnings,
      'CODE-004': metrics.maxComplexity,
      'TEST-001': metrics.testCoverage,
      'TEST-002': metrics.testPassRate,
      'TEST-003': metrics.skippedTests,
      'SEC-001': metrics.criticalVulnerabilities + metrics.highVulnerabilities,
      'SEC-002': metrics.hardcodedSecrets,
      'PERF-001': metrics.coldStartupTime,
      'PERF-002': metrics.scrollFps,
      'NORM-001': metrics.reviewApprovals,
      'NORM-002': metrics.linkedIssues,
    };
    return mapping[ruleId] ?? -1;
  }

  // 评估单条规则
  private evaluateRule(rule: GateRule, actualValue: number): boolean {
    switch (rule.operator) {
      case '>=': return actualValue >= rule.threshold;
      case '<=': return actualValue <= rule.threshold;
      case '==': return actualValue === rule.threshold;
      case '!=': return actualValue !== rule.threshold;
      default: return false;
    }
  }

  // 生成摘要
  private generateSummary(
    passed: boolean, blocked: boolean, hasWarning: boolean
  ): string {
    const totalRules = this.results.length;
    const passedRules = this.results.filter(r => r.passed).length;
    const failedRules = totalRules - passedRules;

    let summary = `质量门禁检查: ${passedRules}/${totalRules} 通过\n`;

    if (blocked) {
      summary += '🚫 门禁未通过 - 存在阻断级问题，不允许合并\n';
    } else if (hasWarning) {
      summary += '⚠️ 门禁通过（有警告） - 建议修复警告项\n';
    } else {
      summary += '✅ 门禁通过 - 所有检查项达标\n';
    }

    return summary;
  }

  // 生成详细报告
  generateReport(): string {
    let report = '╔══════════════════════════════════════════╗\n';
    report +=    '║      质量门禁检查报告                    ║\n';
    report +=    '╚══════════════════════════════════════════╝\n\n';

    // 按分类分组
    const categories = new Map<string, GateResult[]>();
    for (const result of this.results) {
      const cat = result.rule.category;
      if (!categories.has(cat)) {
        categories.set(cat, []);
      }
      categories.get(cat)!.push(result);
    }

    for (const [category, results] of categories) {
      report += `📋 ${category}\n`;
      for (const result of results) {
        const icon = result.passed ? '✅' : 
                     result.rule.severity === 'block' ? '❌' : '⚠️';
        report += `   ${icon} ${result.rule.name}: ${result.actualValue} (阈值: ${result.rule.threshold})\n`;
      }
      report += '\n';
    }

    return report;
  }
}

完整示例：CI/CD中的质量门禁集成

// ci-quality-gate.ts
// CI/CD流水线中的质量门禁

import { exec } from 'child_process';
import { promisify } from 'util';

const execAsync = promisify(exec);

class CIQualityGate {
  private runner: QualityGateRunner;

  constructor() {
    this.runner = new QualityGateRunner();
  }

  // CI流水线入口
  async runPipeline(): Promise<boolean> {
    console.log('🚀 启动质量门禁检查...\n');

    // 步骤1：采集代码质量指标
    console.log('📊 采集代码质量指标...');
    const codeMetrics = await this.collectCodeMetrics();

    // 步骤2：运行测试并采集测试指标
    console.log('🧪 运行测试...');
    const testMetrics = await this.collectTestMetrics();

    // 步骤3：运行安全扫描
    console.log('🔒 运行安全扫描...');
    const securityMetrics = await this.collectSecurityMetrics();

    // 步骤4：采集性能指标
    console.log('⚡ 采集性能指标...');
    const perfMetrics = await this.collectPerformanceMetrics();

    // 步骤5：采集规范指标
    console.log('📋 采集规范指标...');
    const normMetrics = await this.collectNormMetrics();

    // 汇总所有指标
    const metrics: QualityMetrics = {
      ...codeMetrics,
      ...testMetrics,
      ...securityMetrics,
      ...perfMetrics,
      ...normMetrics,
    };

    // 执行门禁检查
    console.log('\n🔍 执行门禁检查...\n');
    const result = this.runner.evaluate(metrics);

    // 输出报告
    console.log(this.runner.generateReport());
    console.log(result.summary);

    // CI结果
    if (result.blocked) {
      console.log('\n❌ 质量门禁未通过，阻断合并');
      return false;
    }

    console.log('\n✅ 质量门禁通过，允许合并');
    return true;
  }

  // 采集代码质量指标
  private async collectCodeMetrics(): Promise<Partial<QualityMetrics>> {
    try {
      // 运行ESLint
      const { stdout } = await execAsync(
        'npx eslint entry/src/main/ets --ext .ets,.ts -f json',
        { cwd: process.cwd() }
      );

      const lintResults = JSON.parse(stdout);
      let lintErrors = 0;
      let lintWarnings = 0;

      for (const fileResult of lintResults) {
        for (const message of fileResult.messages) {
          if (message.severity === 2) lintErrors++;
          else lintWarnings++;
        }
      }

      return {
        staticAnalysisErrors: 0,  // 编译通过则为0
        staticAnalysisWarnings: 0,
        lintErrors,
        lintWarnings,
        maxComplexity: 10,  // 简化，实际需要从Lint结果提取
      };
    } catch (error) {
      return {
        staticAnalysisErrors: 1,
        staticAnalysisWarnings: 0,
        lintErrors: 0,
        lintWarnings: 0,
        maxComplexity: 0,
      };
    }
  }

  // 采集测试指标
  private async collectTestMetrics(): Promise<Partial<QualityMetrics>> {
    try {
      // 运行单元测试
      const { stdout } = await execAsync(
        'hvigorw test@entry --mode module -p module=entry@default',
        { cwd: process.cwd() }
      );

      // 解析测试结果（简化）
      return {
        testCoverage: 85,
        testPassRate: 100,
        skippedTests: 0,
        totalTests: 120,
        failedTests: 0,
      };
    } catch (error) {
      return {
        testCoverage: 0,
        testPassRate: 0,
        skippedTests: 0,
        totalTests: 0,
        failedTests: 1,
      };
    }
  }

  // 采集安全指标
  private async collectSecurityMetrics(): Promise<Partial<QualityMetrics>> {
    // 运行安全扫描（简化）
    return {
      criticalVulnerabilities: 0,
      highVulnerabilities: 0,
      hardcodedSecrets: 0,
    };
  }

  // 采集性能指标
  private async collectPerformanceMetrics(): Promise<Partial<QualityMetrics>> {
    // 运行性能测试（简化）
    return {
      coldStartupTime: 1200,
      scrollFps: 58,
      peakMemory: 256,
    };
  }

  // 采集规范指标
  private async collectSecurityMetrics2(): Promise<Partial<QualityMetrics>> {
    // 从PR信息中提取（简化）
    return {
      reviewApprovals: 2,
      linkedIssues: 1,
    };
  }

  private async collectNormMetrics(): Promise<Partial<QualityMetrics>> {
    return {
      reviewApprovals: 2,
      linkedIssues: 1,
    };
  }
}

// CI入口
const gate = new CIQualityGate();
gate.runPipeline().then(passed => {
  process.exit(passed ? 0 : 1);
});

踩坑与注意事项

坑1：门禁太严格，开发效率下降

每个PR都要过5道门禁，每道门禁都要跑5分钟，一个PR要等25分钟才能合并。开发者受不了，开始绕过门禁。

解决方案：

• 分级门禁：PR只跑核心门禁（静态分析+单元测试），全量门禁在夜间构建跑
• 增量检查：只检查变更文件，不跑全量
• 快速反馈：门禁检查并行执行，不是串行

坑2：门禁规则一刀切

核心模块和边缘模块用同样的门禁标准。核心模块的80%覆盖率要求合理，但一个简单的工具类也要80%覆盖率就过分了。

解决方案：

• 按模块配置不同的门禁标准
• 核心模块：严格门禁（覆盖率80%+安全扫描+性能基线）
• 边缘模块：基础门禁（覆盖率60%+静态分析）
• 测试代码：宽松门禁（只检查编译通过）

坑3：门禁误报导致信任崩塌

门禁报了一个Critical问题，开发者花半天排查发现是误报。这种事多来几次，开发者就不信门禁了。

解决方案：

• 定期review门禁规则，删除误报率高的规则
• 误报可以标记为"已知误报"，不影响门禁结果
• 门禁规则的变更也要走Review

坑4：门禁检查不全面

只检查了静态分析和单元测试，安全扫描和性能基线没检查。结果安全漏洞和性能退化都漏过去了。

解决方案：

• 门禁检查项要覆盖：代码质量+测试质量+安全质量+性能质量+规范质量
• 定期review门禁覆盖率：哪些问题类型没被门禁覆盖到
• 从线上问题反推：每个线上问题都应该对应一条门禁规则

坑5：门禁结果不可追溯

门禁通过了，但3个月后出了问题，想查当时门禁的具体数据，发现没保存。

解决方案：

• 每次门禁结果保存到数据库
• 门禁报告归档，至少保留6个月
• 门禁历史趋势可视化，方便追溯

HarmonyOS 6适配说明

HarmonyOS 6在质量门禁方面的改进：

1. 构建时门禁：HarmonyOS 6的构建系统内置了质量门禁检查，构建失败时会明确提示是哪条门禁规则未通过。不再需要单独配置CI脚本。

2. 门禁规则模板：华为提供了鸿蒙项目的门禁规则模板，包括应用类、游戏类、IoT类等不同场景的推荐配置。团队可以基于模板定制。

3. 门禁结果可视化：DevEco Studio 6内置了门禁结果仪表盘，可以查看门禁通过率趋势、各类问题的分布、门禁规则的命中率等。

4. 智能门禁：基于历史数据，门禁系统可以智能调整阈值。比如某个模块的测试覆盖率一直是90%，门禁阈值可以自动从80%调高到85%。

5. 门禁与Issue联动：门禁未通过时自动创建Issue，分配给对应的开发者。修复后门禁自动重新检查。

总结

质量门禁是代码质量的最后一道防线。没有门禁，任何代码都能合入主分支；有了门禁，只有质量达标的代码才能放行。

核心要点：

• 门禁要全面：代码+测试+安全+性能+规范，缺一不可
• 门禁要分级：block必须通过，warn建议修复，info仅供参考
• 门禁要高效：快速反馈，不要让开发者等太久
• 门禁要灵活：不同模块不同标准，不要一刀切
• 门禁要持续优化：定期review规则，删除误报，补充遗漏