【系统架构设计百科】架构治理：适应度函数与演进式架构

package com.example.archunit;

import com.tngtech.archunit.core.domain.JavaClasses;
import com.tngtech.archunit.core.importer.ClassFileImporter;
import com.tngtech.archunit.library.Architectures;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.Test;

class LayeredArchitectureTest {

    private static JavaClasses classes;

    @BeforeAll
    static void setup() {
        classes = new ClassFileImporter()
                .importPackages("com.example.myapp");
    }

    @Test
    void 分层架构约束_层间依赖方向必须自上而下() {
        Architectures.layeredArchitecture()
                .consideringAllDependencies()
                .layer("Controller").definedBy("..controller..")
                .layer("Service").definedBy("..service..")
                .layer("Domain").definedBy("..domain..")
                .layer("Infrastructure").definedBy("..infrastructure..")
                .whereLayer("Controller").mayNotBeAccessedByAnyLayer()
                .whereLayer("Service").mayOnlyBeAccessedByLayers("Controller")
                .whereLayer("Domain").mayOnlyBeAccessedByLayers("Controller", "Service")
                .whereLayer("Infrastructure").mayOnlyBeAccessedByLayers("Service", "Domain")
                .check(classes);
    }
}

package com.example.archunit;

import com.tngtech.archunit.core.domain.JavaClasses;
import com.tngtech.archunit.core.importer.ClassFileImporter;
import com.tngtech.archunit.lang.ArchRule;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.Test;

import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;
import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.classes;

class PackageDependencyTest {

    private static JavaClasses importedClasses;

    @BeforeAll
    static void setup() {
        importedClasses = new ClassFileImporter()
                .importPackages("com.example.myapp");
    }

    @Test
    void 领域层不得依赖控制器层() {
        ArchRule rule = noClasses()
                .that().resideInAPackage("..domain..")
                .should().dependOnClassesThat()
                .resideInAPackage("..controller..");

        rule.check(importedClasses);
    }

    @Test
    void 订单模块不得依赖用户模块的内部实现() {
        ArchRule rule = noClasses()
                .that().resideInAPackage("..order..")
                .should().dependOnClassesThat()
                .resideInAPackage("..user.internal..");

        rule.check(importedClasses);
    }

    @Test
    void Repository接口必须位于domain包中() {
        ArchRule rule = classes()
                .that().haveSimpleNameEndingWith("Repository")
                .should().resideInAPackage("..domain..");

        rule.check(importedClasses);
    }
}

package com.example.archunit;

import com.tngtech.archunit.core.domain.JavaClasses;
import com.tngtech.archunit.core.importer.ClassFileImporter;
import com.tngtech.archunit.lang.ArchRule;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.Test;
import org.springframework.stereotype.Service;
import org.springframework.web.bind.annotation.RestController;

import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.classes;

class NamingConventionTest {

    private static JavaClasses classes;

    @BeforeAll
    static void setup() {
        classes = new ClassFileImporter()
                .importPackages("com.example.myapp");
    }

    @Test
    void Controller类必须以Controller结尾() {
        ArchRule rule = classes()
                .that().areAnnotatedWith(RestController.class)
                .should().haveSimpleNameEndingWith("Controller");

        rule.check(classes);
    }

    @Test
    void Service类必须以Service或ServiceImpl结尾() {
        ArchRule rule = classes()
                .that().areAnnotatedWith(Service.class)
                .should().haveSimpleNameEndingWith("Service")
                .orShould().haveSimpleNameEndingWith("ServiceImpl");

        rule.check(classes);
    }

    @Test
    void 所有公开API的DTO必须实现Serializable() {
        ArchRule rule = classes()
                .that().haveSimpleNameEndingWith("DTO")
                .should().implement(java.io.Serializable.class);

        rule.check(classes);
    }
}

package com.example.archunit;

import com.tngtech.archunit.core.domain.JavaClasses;
import com.tngtech.archunit.core.importer.ClassFileImporter;
import com.tngtech.archunit.library.dependencies.SlicesRuleDefinition;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.Test;

class CyclicDependencyTest {

    private static JavaClasses classes;

    @BeforeAll
    static void setup() {
        classes = new ClassFileImporter()
                .importPackages("com.example.myapp");
    }

    @Test
    void 模块间不得存在循环依赖() {
        SlicesRuleDefinition.slices()
                .matching("com.example.myapp.(*)..")
                .should().beFreeOfCycles()
                .check(classes);
    }

    @Test
    void 各业务领域间不得存在循环依赖() {
        SlicesRuleDefinition.slices()
                .matching("com.example.myapp.domain.(*)..")
                .should().beFreeOfCycles()
                .check(classes);
    }
}

package com.example.archunit;

import com.tngtech.archunit.core.domain.JavaClass;
import com.tngtech.archunit.core.domain.JavaClasses;
import com.tngtech.archunit.core.importer.ClassFileImporter;
import com.tngtech.archunit.lang.ArchCondition;
import com.tngtech.archunit.lang.ArchRule;
import com.tngtech.archunit.lang.ConditionEvents;
import com.tngtech.archunit.lang.SimpleConditionEvent;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.Test;

import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.classes;

class CustomRuleTest {

    private static JavaClasses importedClasses;

    @BeforeAll
    static void setup() {
        importedClasses = new ClassFileImporter()
                .importPackages("com.example.myapp");
    }

    @Test
    void 聚合根的构造函数参数不得超过七个() {
        ArchRule rule = classes()
                .that().areAnnotatedWith(AggregateRoot.class)
                .should(haveConstructorWithMaxParameters(7));

        rule.check(importedClasses);
    }

    private static ArchCondition<JavaClass> haveConstructorWithMaxParameters(int max) {
        return new ArchCondition<>("构造函数参数不超过 " + max + " 个") {
            @Override
            public void check(JavaClass javaClass, ConditionEvents events) {
                javaClass.getConstructors().forEach(constructor -> {
                    int paramCount = constructor.getRawParameterTypes().size();
                    if (paramCount > max) {
                        String message = String.format(
                                "%s 的构造函数有 %d 个参数，超过上限 %d",
                                javaClass.getName(), paramCount, max
                        );
                        events.add(SimpleConditionEvent.violated(
                                javaClass, message
                        ));
                    }
                });
            }
        };
    }
}

using NetArchTest.Rules;
using Xunit;

namespace MyApp.ArchTests
{
    public class LayerDependencyTests
    {
        [Fact]
        public void Domain层不得依赖Infrastructure层()
        {
            var result = Types.InAssembly(typeof(Domain.Order).Assembly)
                .That()
                .ResideInNamespace("MyApp.Domain")
                .ShouldNot()
                .HaveDependencyOn("MyApp.Infrastructure")
                .GetResult();

            Assert.True(result.IsSuccessful,
                "域层存在对基础设施层的违规依赖");
        }

        [Fact]
        public void Controller必须以Controller结尾()
        {
            var result = Types.InAssembly(typeof(WebApi.Startup).Assembly)
                .That()
                .Inherit(typeof(Microsoft.AspNetCore.Mvc.ControllerBase))
                .Should()
                .HaveNameEndingWith("Controller")
                .GetResult();

            Assert.True(result.IsSuccessful);
        }
    }
}

// .dependency-cruiser.js
module.exports = {
  forbidden: [
    {
      name: "领域层不得依赖UI层",
      severity: "error",
      from: { path: "^src/domain" },
      to: { path: "^src/ui" }
    },
    {
      name: "禁止循环依赖",
      severity: "error",
      from: { path: "^src" },
      to: { circular: true }
    },
    {
      name: "共享模块不得依赖业务模块",
      severity: "warn",
      from: { path: "^src/shared" },
      to: { path: "^src/(order|user|payment)" }
    },
    {
      name: "禁止直接依赖数据库驱动",
      severity: "error",
      from: { path: "^src/domain" },
      to: { path: "node_modules/(pg|mysql2|mongodb)" }
    }
  ],
  options: {
    doNotFollow: { path: "node_modules" },
    tsConfig: { fileName: "tsconfig.json" },
    reporterOptions: {
      dot: { theme: { graph: { rankdir: "LR" } } }
    }
  }
};

# .github/workflows/architecture-governance.yml
name: Architecture Governance

on:
  pull_request:
    branches: [main, develop]
  push:
    branches: [main]

jobs:
  arch-tests:
    name: 架构适应度函数检查
    runs-on: ubuntu-latest
    steps:
      - name: 检出代码
        uses: actions/checkout@v4

      - name: 配置 JDK 21
        uses: actions/setup-java@v4
        with:
          java-version: '21'
          distribution: 'temurin'

      - name: 缓存 Gradle 依赖
        uses: actions/cache@v4
        with:
          path: |
            ~/.gradle/caches
            ~/.gradle/wrapper
          key: ${{ runner.os }}-gradle-${{ hashFiles('**/*.gradle*') }}

      - name: 执行架构测试
        run: ./gradlew archTest --no-daemon

      - name: 上传架构测试报告
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: arch-test-report
          path: build/reports/tests/archTest/

  dependency-check:
    name: 依赖关系合规检查
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: 安装 dependency-cruiser
        run: npm install -g dependency-cruiser

      - name: 检查前端依赖合规
        run: depcruise --config .dependency-cruiser.js src/
        working-directory: frontend/

  metrics-collection:
    name: 架构度量指标采集
    runs-on: ubuntu-latest
    needs: [arch-tests]
    steps:
      - uses: actions/checkout@v4

      - name: 计算耦合度指标
        run: |
          ./gradlew jdepend --no-daemon
          python3 scripts/collect_arch_metrics.py

      - name: 上报指标到治理仪表盘
        run: |
          curl -X POST "${{ secrets.GOVERNANCE_API }}/metrics" \
            -H "Content-Type: application/json" \
            -d @build/arch-metrics.json

// build.gradle
plugins {
    id 'java'
}

dependencies {
    testImplementation 'com.tngtech.archunit:archunit-junit5:1.3.0'
    testImplementation 'org.junit.jupiter:junit-jupiter:5.10.2'
}

// 将架构测试独立为单独的测试任务
sourceSets {
    archTest {
        java {
            srcDir 'src/arch-test/java'
        }
        compileClasspath += main.output + test.output
        runtimeClasspath += main.output + test.output
    }
}

configurations {
    archTestImplementation.extendsFrom testImplementation
    archTestRuntimeOnly.extendsFrom testRuntimeOnly
}

tasks.register('archTest', Test) {
    description = '执行架构适应度函数测试'
    group = 'verification'
    testClassesDirs = sourceSets.archTest.output.classesDirs
    classpath = sourceSets.archTest.runtimeClasspath
    useJUnitPlatform()

    reports {
        html.required = true
        junitXml.required = true
    }

    // 架构测试失败应阻断构建
    ignoreFailures = false
}

// 将架构测试纳入标准验证流程
check.dependsOn archTest

# ADR-{编号}: {决策标题}

## 状态

{提议 | 已接受 | 已废弃 | 已取代}

## 日期

{YYYY-MM-DD}

## 背景

{描述促成这一决策的上下文和问题陈述。
包括相关的技术约束、业务需求、团队现状等。}

## 决策

{清晰地陈述做出的架构决策。}

## 备选方案

### 方案一：{名称}
- 优点：{列出优点}
- 缺点：{列出缺点}
- 适用场景：{描述适用场景}

### 方案二：{名称}
- 优点：{列出优点}
- 缺点：{列出缺点}
- 适用场景：{描述适用场景}

## 决策理由

{解释为什么选择当前方案而不是其他备选方案。
引用具体的评估标准和权衡过程。}

## 后果

### 正面影响
- {列出正面影响}

### 负面影响
- {列出负面影响}

### 风险
- {列出潜在风险}

## 合规性检查

- [ ] 适应度函数已创建
- [ ] CI 流水线已集成
- [ ] 团队已知晓

## 相关决策

- 取代：{ADR-xxx}
- 关联：{ADR-xxx}

# ADR-042: 采用 Apache Kafka 作为核心事件总线

## 状态

已接受

## 日期

2026-03-15

## 背景

订单系统需要一个事件总线来实现跨服务的异步通信。
当前系统使用 RabbitMQ，但在日均 5000 万条消息的负载下出现了
以下问题：
1. 消息积压超过 200 万条时性能急剧下降
2. 缺乏原生的消息回溯（Replay）能力
3. 多消费者组场景下的扩展性不足

团队规模：12 名后端工程师，其中 4 名有 Kafka 使用经验。
运维团队已有 Kubernetes 环境，可使用 Strimzi Operator 部署。

## 决策

采用 Apache Kafka 3.7 作为核心事件总线，替换 RabbitMQ。

## 备选方案

### 方案一：升级 RabbitMQ 集群
- 优点：无需迁移成本，团队熟悉
- 缺点：无法根本解决消息回溯需求，水平扩展受限
- 适用场景：消息量低于 1000 万/天的场景

### 方案二：Apache Pulsar
- 优点：分层存储、原生多租户
- 缺点：社区生态较 Kafka 弱，团队无使用经验
- 适用场景：需要多租户隔离的 SaaS 场景

### 方案三：Apache Kafka
- 优点：高吞吐、消息回溯、成熟生态、团队有经验
- 缺点：运维复杂度较高，ZooKeeper 依赖（KRaft 模式可消除）
- 适用场景：大规模事件驱动架构

## 决策理由

1. Kafka 的日志追加模型天然支持消息回溯需求
2. 团队中 33% 的工程师有 Kafka 实战经验，降低学习成本
3. 使用 KRaft 模式可消除 ZooKeeper 依赖，简化运维
4. Kafka Connect 生态丰富，方便后续数据集成

## 后果

### 正面影响
- 消息吞吐能力提升至亿级/天
- 支持多消费者组独立消费同一 Topic
- 消息回溯窗口可配置（默认 7 天）

### 负面影响
- 迁移期间需要维护双系统（预计 6 周）
- JVM 调优和分区策略需要专项投入

### 风险
- 分区数过多可能导致 Leader 选举延迟
- 消费者 Rebalance 期间可能出现短暂中断

## 合规性检查

- [x] 适应度函数已创建（Kafka 延迟监控告警）
- [x] CI 流水线已集成（集成测试使用 Testcontainers）
- [x] 团队已知晓（2026-03-18 技术分享会）

## 相关决策

- 取代：ADR-017（采用 RabbitMQ 作为消息中间件）
- 关联：ADR-039（事件驱动架构设计规范）

# 安装 adr-tools
brew install adr-tools

# 初始化 ADR 目录
adr init docs/architecture/decisions

# 创建新的 ADR
adr new "采用 Kafka 作为核心事件总线"

# 记录取代关系
adr new -s 17 "采用 Kafka 替换 RabbitMQ"

# 生成 ADR 目录索引
adr generate toc > docs/architecture/decisions/README.md

# 生成 ADR 关系图
adr generate graph | dot -Tpng -o adr-graph.png

package com.example.archunit;

import com.tngtech.archunit.core.domain.JavaClasses;
import com.tngtech.archunit.core.importer.ClassFileImporter;
import com.tngtech.archunit.lang.ArchRule;
import com.tngtech.archunit.lang.CompositeArchRule;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.Test;

import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;
import static com.tngtech.archunit.library.Architectures.layeredArchitecture;
import static com.tngtech.archunit.library.dependencies.SlicesRuleDefinition.slices;

class CompositeArchitectureTest {

    private static JavaClasses classes;

    @BeforeAll
    static void setup() {
        classes = new ClassFileImporter()
                .importPackages("com.example.myapp");
    }

    @Test
    void 系统架构整体适应度评估() {
        ArchRule layerRule = layeredArchitecture()
                .consideringAllDependencies()
                .layer("Controller").definedBy("..controller..")
                .layer("Service").definedBy("..service..")
                .layer("Domain").definedBy("..domain..")
                .layer("Infrastructure").definedBy("..infrastructure..")
                .whereLayer("Controller").mayNotBeAccessedByAnyLayer()
                .whereLayer("Service").mayOnlyBeAccessedByLayers("Controller")
                .whereLayer("Domain").mayOnlyBeAccessedByLayers("Controller", "Service");

        ArchRule noCyclesRule = slices()
                .matching("com.example.myapp.(*)..")
                .should().beFreeOfCycles();

        ArchRule noInfraInDomain = noClasses()
                .that().resideInAPackage("..domain..")
                .should().dependOnClassesThat()
                .resideInAPackage("..infrastructure..");

        CompositeArchRule compositeRule = CompositeArchRule
                .of(layerRule)
                .and(noCyclesRule)
                .and(noInfraInDomain);

        compositeRule.check(classes);
    }
}

package com.example.fitness;

import io.micrometer.core.instrument.MeterRegistry;
import io.micrometer.core.instrument.Timer;
import org.springframework.scheduling.annotation.Scheduled;
import org.springframework.stereotype.Component;

@Component
public class RuntimeFitnessFunction {

    private final MeterRegistry meterRegistry;
    private static final double P99_LATENCY_THRESHOLD_MS = 200.0;
    private static final int MAX_DB_CONNECTION_POOL_USAGE_PERCENT = 80;

    public RuntimeFitnessFunction(MeterRegistry meterRegistry) {
        this.meterRegistry = meterRegistry;
    }

    @Scheduled(fixedRate = 60000)
    public void checkApiLatencyFitness() {
        Timer timer = meterRegistry.find("http.server.requests")
                .tag("uri", "/api/**")
                .timer();

        if (timer != null) {
            double p99Ms = timer.percentile(0.99)
                    .toMilliseconds();

            meterRegistry.gauge(
                    "architecture.fitness.api_latency",
                    p99Ms <= P99_LATENCY_THRESHOLD_MS ? 1.0 : 0.0
            );

            if (p99Ms > P99_LATENCY_THRESHOLD_MS) {
                alertTeam(String.format(
                        "API P99 延迟 %.1fms 超过阈值 %.1fms",
                        p99Ms, P99_LATENCY_THRESHOLD_MS
                ));
            }
        }
    }

    @Scheduled(fixedRate = 30000)
    public void checkDatabaseConnectionFitness() {
        double activeConnections = meterRegistry.find("hikaricp.connections.active")
                .gauge().value();
        double maxConnections = meterRegistry.find("hikaricp.connections.max")
                .gauge().value();

        double usagePercent = (activeConnections / maxConnections) * 100;

        meterRegistry.gauge(
                "architecture.fitness.db_pool_usage",
                usagePercent <= MAX_DB_CONNECTION_POOL_USAGE_PERCENT
                        ? 1.0 : 0.0
        );
    }

    private void alertTeam(String message) {
        // 发送到告警通道（Slack、PagerDuty 等）
    }
}

package com.example.archunit;

import com.tngtech.archunit.core.domain.JavaClasses;
import com.tngtech.archunit.core.importer.ClassFileImporter;
import com.tngtech.archunit.lang.ArchRule;
import com.tngtech.archunit.library.freeze.FreezingArchRule;
import org.junit.jupiter.api.BeforeAll;
import org.junit.jupiter.api.Test;

import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.noClasses;

class GradualConvergenceTest {

    private static JavaClasses classes;

    @BeforeAll
    static void setup() {
        classes = new ClassFileImporter()
                .importPackages("com.example.myapp");
    }

    @Test
    void 冻结现有违规_只阻断新增违规() {
        ArchRule rule = noClasses()
                .that().resideInAPackage("..domain..")
                .should().dependOnClassesThat()
                .resideInAPackage("..controller..");

        // FreezingArchRule 会记录当前违规基线
        // 后续只有新增违规才会导致测试失败
        FreezingArchRule.freeze(rule).check(classes);
    }
}

{
  "dashboard": {
    "title": "架构治理仪表盘",
    "panels": [
      {
        "title": "适应度函数通过率",
        "type": "gauge",
        "targets": [
          {
            "expr": "sum(architecture_fitness_passed) / sum(architecture_fitness_total) * 100",
            "legendFormat": "通过率"
          }
        ],
        "fieldConfig": {
          "defaults": {
            "thresholds": {
              "steps": [
                { "value": 0, "color": "red" },
                { "value": 80, "color": "yellow" },
                { "value": 95, "color": "green" }
              ]
            },
            "max": 100,
            "unit": "percent"
          }
        }
      },
      {
        "title": "架构违规趋势",
        "type": "timeseries",
        "targets": [
          {
            "expr": "architecture_violations_total",
            "legendFormat": "{{violation_type}}"
          }
        ]
      },
      {
        "title": "模块耦合度热力图",
        "type": "heatmap",
        "targets": [
          {
            "expr": "module_coupling_score",
            "legendFormat": "{{source_module}} -> {{target_module}}"
          }
        ]
      }
    ]
  }
}

#!/usr/bin/env python3
"""架构度量指标采集脚本"""

import json
import subprocess
import xml.etree.ElementTree as ET
from dataclasses import dataclass, asdict
from datetime import datetime
from pathlib import Path


@dataclass
class ArchitectureMetrics:
    """架构度量指标数据模型"""
    timestamp: str
    commit_sha: str
    cyclic_dependencies: int
    layer_violations: int
    coupling_score: float
    instability_score: float
    adr_count: int
    fitness_functions_count: int
    fitness_functions_passed: int

    @property
    def fitness_pass_rate(self) -> float:
        if self.fitness_functions_count == 0:
            return 0.0
        return self.fitness_functions_passed / self.fitness_functions_count


def collect_jdepend_metrics(report_path: str) -> dict:
    """从 JDepend 报告中提取耦合度指标"""
    tree = ET.parse(report_path)
    root = tree.getroot()

    total_ca = 0
    total_ce = 0
    package_count = 0
    cycles = 0

    for package in root.findall(".//Package"):
        stats = package.find("Stats")
        if stats is not None:
            total_ca += int(stats.findtext("Ca", "0"))
            total_ce += int(stats.findtext("Ce", "0"))
            package_count += 1

            if stats.findtext("CyclicDeps", "false") == "true":
                cycles += 1

    avg_coupling = (total_ca + total_ce) / max(package_count, 1)
    instability = total_ce / max(total_ca + total_ce, 1)

    return {
        "coupling_score": round(avg_coupling, 2),
        "instability_score": round(instability, 2),
        "cyclic_dependencies": cycles
    }


def count_adrs(adr_dir: str) -> int:
    """统计 ADR 文件数量"""
    adr_path = Path(adr_dir)
    if not adr_path.exists():
        return 0
    return len(list(adr_path.glob("*.md"))) - 1  # 减去 README


def parse_test_results(report_path: str) -> dict:
    """解析架构测试结果"""
    tree = ET.parse(report_path)
    root = tree.getroot()

    total = int(root.attrib.get("tests", "0"))
    failures = int(root.attrib.get("failures", "0"))
    errors = int(root.attrib.get("errors", "0"))

    return {
        "fitness_functions_count": total,
        "fitness_functions_passed": total - failures - errors
    }


def get_commit_sha() -> str:
    """获取当前 Git 提交 SHA"""
    result = subprocess.run(
        ["git", "rev-parse", "HEAD"],
        capture_output=True, text=True
    )
    return result.stdout.strip()[:8]


def main():
    jdepend = collect_jdepend_metrics("build/reports/jdepend/jdepend-report.xml")
    tests = parse_test_results("build/reports/tests/archTest/TEST-results.xml")

    metrics = ArchitectureMetrics(
        timestamp=datetime.utcnow().isoformat(),
        commit_sha=get_commit_sha(),
        cyclic_dependencies=jdepend["cyclic_dependencies"],
        layer_violations=0,
        coupling_score=jdepend["coupling_score"],
        instability_score=jdepend["instability_score"],
        adr_count=count_adrs("docs/architecture/decisions"),
        fitness_functions_count=tests["fitness_functions_count"],
        fitness_functions_passed=tests["fitness_functions_passed"],
    )

    output_path = Path("build/arch-metrics.json")
    output_path.parent.mkdir(parents=True, exist_ok=True)
    output_path.write_text(json.dumps(asdict(metrics), indent=2))

    print(f"架构度量采集完成：通过率 {metrics.fitness_pass_rate:.1%}")
    print(f"循环依赖：{metrics.cyclic_dependencies}")
    print(f"耦合度评分：{metrics.coupling_score}")


if __name__ == "__main__":
    main()

## 架构治理 Quick Start 检查清单

### 基础设施
- [ ] 添加 ArchUnit 依赖到 build.gradle/pom.xml
- [ ] 创建 src/arch-test 源码目录
- [ ] 配置独立的 archTest Gradle 任务
- [ ] 在 CI 流水线中添加架构测试步骤

### 核心规则
- [ ] 分层架构约束（层间依赖方向）
- [ ] 循环依赖检测（模块间、包间）
- [ ] 命名规约检查（Controller、Service、Repository）
- [ ] 领域层纯净性（不依赖基础设施和 UI）

### ADR 实践
- [ ] 初始化 ADR 目录（adr init）
- [ ] 编写第一条 ADR（记录架构决策实践本身）
- [ ] 在 PR 模板中添加 ADR 提示
- [ ] 将 ADR 纳入新人培训材料

### 度量与可视化
- [ ] 配置 JDepend 或 SonarQube 采集耦合度
- [ ] 搭建 Grafana 治理仪表盘
- [ ] 设置架构违规趋势告警

### 组织保障
- [ ] 成立架构治理工作组
- [ ] 安排首次架构 Kata 工作坊
- [ ] 发布团队架构原则文档