【系统架构设计百科】架构师工具箱：建模、可视化与决策辅助

# 方式一：使用 Structurizr Lite（本地 Docker 部署）
docker pull structurizr/lite
docker run -it --rm -p 8080:8080 \
  -v $(pwd)/workspace:/usr/local/structurizr \
  structurizr/lite

# 方式二：使用 Structurizr CLI 导出为静态图片
# 安装 CLI
curl -L https://github.com/structurizr/cli/releases/download/v2024.03.03/structurizr-cli.zip \
  -o structurizr-cli.zip
unzip structurizr-cli.zip -d structurizr-cli

# 导出为 PlantUML 格式
./structurizr-cli/structurizr.sh export \
  -workspace workspace.dsl \
  -format plantuml/structurizr

# 导出为 Mermaid 格式
./structurizr-cli/structurizr.sh export \
  -workspace workspace.dsl \
  -format mermaid

# 导出为 JSON 格式（供其他工具消费）
./structurizr-cli/structurizr.sh export \
  -workspace workspace.dsl \
  -format json

# .github/workflows/architecture.yml
name: Architecture Diagrams

on:
  push:
    paths:
      - 'docs/architecture/**'
  pull_request:
    paths:
      - 'docs/architecture/**'

jobs:
  validate-and-export:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate Structurizr DSL
        run: |
          docker run --rm \
            -v ${{ github.workspace }}/docs/architecture:/usr/local/structurizr \
            structurizr/cli \
            validate -workspace /usr/local/structurizr/workspace.dsl

      - name: Export diagrams
        run: |
          docker run --rm \
            -v ${{ github.workspace }}/docs/architecture:/usr/local/structurizr \
            structurizr/cli \
            export -workspace /usr/local/structurizr/workspace.dsl \
            -format plantuml/structurizr \
            -output /usr/local/structurizr/diagrams

      - name: Upload diagrams
        uses: actions/upload-artifact@v4
        with:
          name: architecture-diagrams
          path: docs/architecture/diagrams/

# ADR-0012: 选择 Apache Kafka 作为事件总线

## 状态

已接受（Accepted）

## 上下文

我们的电商平台需要一个事件驱动的消息中间件，用于在微服务之间传递领域事件
（如订单创建、库存变更、支付回调等）。当前候选方案有三个：
- Apache Kafka
- RabbitMQ
- Amazon SQS/SNS

关键需求：
1. 日均消息量预计 5000 万条以上
2. 需要支持消息回溯（Consumer 可以重新消费历史消息）
3. 需要支持消息的分区有序
4. 团队中有两位工程师有 Kafka 运维经验

## 决策

选择 Apache Kafka 作为事件总线。

## 理由

1. Kafka 天然支持消息持久化和回溯（基于 offset），RabbitMQ 和 SQS 不支持。
2. Kafka 的分区（Partition）机制可以保证同一分区内的消息有序，满足订单状态
   变更的顺序性要求。
3. Kafka 在高吞吐场景下的性能远优于 RabbitMQ。
4. 团队已有 Kafka 运维经验，降低了学习成本和运维风险。

## 后果

- 需要部署和维护 Kafka 集群（或使用托管服务如 Confluent Cloud）。
- 需要引入 Schema Registry 来管理事件的 Avro/Protobuf 模式。
- 对于简单的请求-响应模式，Kafka 并非最优选择，需要配合 gRPC 使用。
- RabbitMQ 适合的延迟队列场景需要单独解决（考虑 Kafka 的延迟消息插件
  或独立部署一个轻量级 RabbitMQ 实例）。

## 参与者

- 张三（架构师）
- 李四（后端负责人）
- 王五（基础设施负责人）

## 日期

2026-03-15

# 安装 adr-tools
brew install adr-tools

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

# 创建新的 ADR
adr new "选择 Apache Kafka 作为事件总线"
# 生成文件：docs/adr/0012-选择-apache-kafka-作为事件总线.md

# 查看 ADR 列表
adr list

# 生成 ADR 目录页
adr generate toc > docs/adr/README.md

# 将某条 ADR 标记为被取代
adr new -s 0012 "迁移到 Amazon MSK 托管 Kafka"

# 安装 Log4brains
npm install -g log4brains

# 初始化
log4brains init

# 创建新的 ADR
log4brains adr new "选择 Apache Kafka 作为事件总线"

# 启动本地预览服务器
log4brains preview

# 构建静态站点
log4brains build

# Lattix CLI 示例：分析 Java 项目
lattix-cli analyze \
  --project ecommerce-platform \
  --source ./src/main/java \
  --classpath ./target/classes \
  --output ./reports/dsm.html

# 检查架构规则违规
lattix-cli check \
  --project ecommerce-platform \
  --rules ./architecture-rules.lattix \
  --fail-on-violation

// sonargraph-rules.groovy
// 定义分层架构规则

artifact("Application") {
    // 表示层只能依赖业务逻辑层
    layer("Presentation") {
        include "**/controller/**"
        include "**/web/**"
    }
    // 业务逻辑层只能依赖数据访问层和领域层
    layer("Business") {
        include "**/service/**"
        include "**/usecase/**"
    }
    // 领域层不依赖任何其他层
    layer("Domain") {
        include "**/domain/**"
        include "**/model/**"
    }
    // 数据访问层只能依赖领域层
    layer("Persistence") {
        include "**/repository/**"
        include "**/dao/**"
    }

    // 定义层级依赖规则
    "Presentation" -> "Business"
    "Business" -> "Domain"
    "Business" -> "Persistence"
    "Persistence" -> "Domain"

    // 禁止反向依赖
    deny "Domain" -> "Persistence"
    deny "Domain" -> "Business"
    deny "Domain" -> "Presentation"
    deny "Persistence" -> "Business"
    deny "Persistence" -> "Presentation"
    deny "Business" -> "Presentation"
}

# 安装
npm install --save-dev dependency-cruiser

# 初始化配置
npx depcruise --init

# 运行依赖分析
npx depcruise --config .dependency-cruiser.cjs src

# 生成依赖图（SVG 格式）
npx depcruise --config .dependency-cruiser.cjs \
  --output-type dot src | dot -T svg > dependency-graph.svg

# 生成 Mermaid 格式的依赖图
npx depcruise --config .dependency-cruiser.cjs \
  --output-type mermaid src > dependency-graph.mmd

// .dependency-cruiser.cjs
module.exports = {
  forbidden: [
    {
      name: "no-circular",
      severity: "error",
      comment: "禁止循环依赖",
      from: {},
      to: {
        circular: true,
      },
    },
    {
      name: "no-orphans",
      severity: "warn",
      comment: "检测孤立模块",
      from: {
        orphan: true,
        pathNot: [
          "(^|/)\\.[^/]+\\.(js|cjs|mjs|ts)$",
          "\\.d\\.ts$",
          "(^|/)tsconfig\\.json$",
        ],
      },
      to: {},
    },
    {
      name: "controller-not-to-repository",
      severity: "error",
      comment: "Controller 层不能直接访问 Repository 层",
      from: {
        path: "^src/controller/",
      },
      to: {
        path: "^src/repository/",
      },
    },
    {
      name: "domain-not-to-infrastructure",
      severity: "error",
      comment: "领域层不能依赖基础设施层",
      from: {
        path: "^src/domain/",
      },
      to: {
        path: "^src/infrastructure/",
      },
    },
  ],
  options: {
    doNotFollow: {
      path: "node_modules",
    },
    tsPreCompilationDeps: true,
    tsConfig: {
      fileName: "tsconfig.json",
    },
    enhancedResolveOptions: {
      exportsFields: ["exports"],
      conditionNames: ["import", "require", "node", "default"],
    },
  },
};

// ArchitectureTest.java
package com.ecommerce.architecture;

import com.tngtech.archunit.core.domain.JavaClasses;
import com.tngtech.archunit.core.importer.ClassFileImporter;
import com.tngtech.archunit.core.importer.ImportOption;
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.*;
import static com.tngtech.archunit.library.Architectures.layeredArchitecture;
import static com.tngtech.archunit.library.dependencies.SlicesRuleDefinition.slices;

class ArchitectureTest {

    private static JavaClasses classes;

    @BeforeAll
    static void setup() {
        classes = new ClassFileImporter()
            .withImportOption(ImportOption.Predefined.DO_NOT_INCLUDE_TESTS)
            .importPackages("com.ecommerce");
    }

    @Test
    void 分层架构规则() {
        ArchRule rule = layeredArchitecture()
            .consideringAllDependencies()
            .layer("Controller").definedBy("..controller..")
            .layer("Service").definedBy("..service..")
            .layer("Domain").definedBy("..domain..")
            .layer("Repository").definedBy("..repository..")
            .layer("Infrastructure").definedBy("..infrastructure..")

            .whereLayer("Controller").mayNotBeAccessedByAnyLayer()
            .whereLayer("Controller").mayOnlyAccessLayers("Service", "Domain")
            .whereLayer("Service").mayOnlyAccessLayers("Domain", "Repository")
            .whereLayer("Repository").mayOnlyAccessLayers("Domain", "Infrastructure")
            .whereLayer("Domain").mayOnlyAccessLayers();  // 领域层不依赖任何层

        rule.check(classes);
    }

    @Test
    void 禁止循环依赖() {
        ArchRule rule = slices()
            .matching("com.ecommerce.(*)..")
            .should().beFreeOfCycles();

        rule.check(classes);
    }

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

        rule.check(classes);
    }

    @Test
    void Service类不能直接使用JPA的EntityManager() {
        ArchRule rule = noClasses()
            .that().resideInAPackage("..service..")
            .should().accessClassesThat()
            .haveFullyQualifiedName("jakarta.persistence.EntityManager");

        rule.check(classes);
    }

    @Test
    void 领域对象不能使用Spring注解() {
        ArchRule rule = noClasses()
            .that().resideInAPackage("..domain..")
            .should().beAnnotatedWith("org.springframework.stereotype.Service")
            .orShould().beAnnotatedWith("org.springframework.stereotype.Component")
            .orShould().beAnnotatedWith("org.springframework.stereotype.Repository");

        rule.check(classes);
    }

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

        rule.check(classes);
    }
}

// ArchitectureTests.cs
using NetArchTest.Rules;
using Xunit;

namespace ECommerce.Tests.Architecture
{
    public class ArchitectureTests
    {
        [Fact]
        public void Domain层不能依赖Infrastructure层()
        {
            var result = Types.InAssembly(typeof(Domain.Order).Assembly)
                .ShouldNot()
                .HaveDependencyOn("ECommerce.Infrastructure")
                .GetResult();

            Assert.True(result.IsSuccessful,
                $"领域层违规依赖了基础设施层：{string.Join(", ",
                    result.FailingTypeNames ?? Array.Empty<string>())}");
        }

        [Fact]
        public void Controller必须以Controller结尾()
        {
            var result = Types.InAssembly(typeof(API.Startup).Assembly)
                .That()
                .ResideInNamespace("ECommerce.API.Controllers")
                .Should()
                .HaveNameEndingWith("Controller")
                .GetResult();

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

#!/usr/bin/env python3
"""
从 Jaeger 追踪数据生成服务依赖图（Mermaid 格式）
"""

import requests
import json
from collections import defaultdict


def fetch_dependencies(jaeger_url: str) -> list[dict]:
    """从 Jaeger API 获取服务依赖关系"""
    response = requests.get(
        f"{jaeger_url}/api/dependencies",
        params={"endTs": "now", "lookback": "86400000"}  # 最近 24 小时
    )
    response.raise_for_status()
    return response.json()["data"]


def generate_mermaid(dependencies: list[dict]) -> str:
    """将依赖关系转换为 Mermaid 图"""
    lines = ["graph LR"]
    services = set()

    for dep in dependencies:
        parent = dep["parent"]
        child = dep["child"]
        call_count = dep["callCount"]

        services.add(parent)
        services.add(child)

        lines.append(
            f'    {_safe_id(parent)}["{parent}"] '
            f'-->|"{call_count} calls"| '
            f'{_safe_id(child)}["{child}"]'
        )

    return "\n".join(lines)


def _safe_id(name: str) -> str:
    """将服务名转换为合法的 Mermaid 节点 ID"""
    return name.replace("-", "_").replace(".", "_")


if __name__ == "__main__":
    jaeger_url = "http://localhost:16686"
    deps = fetch_dependencies(jaeger_url)
    mermaid_content = generate_mermaid(deps)
    print(mermaid_content)

    with open("service-dependencies.mmd", "w") as f:
        f.write(mermaid_content)
    print("依赖图已生成：service-dependencies.mmd")

// ModuleBoundaryTest.java
package com.ecommerce.architecture;

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

import static com.tngtech.archunit.library.Architectures.layeredArchitecture;
import static com.tngtech.archunit.library.dependencies.SlicesRuleDefinition.slices;

class ModuleBoundaryTest {

    private static JavaClasses classes;

    @BeforeAll
    static void setup() {
        classes = new ClassFileImporter()
            .withImportOption(ImportOption.Predefined.DO_NOT_INCLUDE_TESTS)
            .importPackages("com.ecommerce");
    }

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

    @Test
    void 模块间只能通过公开API交互() {
        // 各模块只暴露 api 子包中的接口
        slices()
            .matching("com.ecommerce.(*)..")
            .should().notDependOnEachOther()
            .ignoreDependency(
                // 允许依赖其他模块的 api 子包
                clazz -> true,
                clazz -> clazz.getPackageName().contains(".api.")
                    || clazz.getPackageName().contains(".shared.")
            )
            .check(classes);
    }

    @Test
    void 每个模块内部遵循分层架构() {
        layeredArchitecture()
            .consideringAllDependencies()
            .layer("API").definedBy("..api..")
            .layer("Application").definedBy("..application..")
            .layer("Domain").definedBy("..domain..")
            .layer("Infrastructure").definedBy("..infrastructure..")

            .whereLayer("API").mayNotBeAccessedByAnyLayer()
            .whereLayer("API").mayOnlyAccessLayers("Application", "Domain")
            .whereLayer("Application").mayOnlyAccessLayers("Domain", "Infrastructure")
            .whereLayer("Infrastructure").mayOnlyAccessLayers("Domain")
            .whereLayer("Domain").mayOnlyAccessLayers()

            .check(classes);
    }
}

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

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

jobs:
  architecture-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

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

      - name: Run architecture tests
        run: |
          ./gradlew test --tests "com.ecommerce.architecture.*" \
            --no-daemon --info

      - name: Check for architecture violations
        if: failure()
        run: |
          echo "::error::架构规则检查失败！请查看测试报告。"
          echo "常见问题："
          echo "1. 模块间存在循环依赖"
          echo "2. 违反了分层架构规则"
          echo "3. 命名不符合规范"

  architecture-diagrams:
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4

      - name: Generate architecture diagrams
        run: |
          docker run --rm \
            -v ${{ github.workspace }}/docs/architecture:/usr/local/structurizr \
            structurizr/cli \
            export -workspace /usr/local/structurizr/workspace.dsl \
            -format plantuml/structurizr \
            -output /usr/local/structurizr/diagrams

      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/architecture/diagrams

  adr-site:
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Build ADR site
        run: |
          npm install -g log4brains
          log4brains build --out ./adr-site

      - name: Deploy ADR site
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./adr-site
          destination_dir: adr

# catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: order-service
  description: 订单服务：处理订单创建、支付、取消等生命周期管理
  annotations:
    backstage.io/techdocs-ref: dir:.
    github.com/project-slug: ecommerce/order-service
    pagerduty.com/service-id: P1234567
  tags:
    - java
    - spring-boot
    - grpc
  links:
    - url: https://grafana.internal/d/order-service
      title: Grafana Dashboard
    - url: https://docs.internal/adr
      title: Architecture Decision Records
spec:
  type: service
  lifecycle: production
  owner: team-order
  system: ecommerce-platform
  providesApis:
    - order-api
  consumesApis:
    - inventory-api
    - payment-gateway-api
  dependsOn:
    - resource:order-database
    - resource:kafka-cluster

{
  "title": "电商平台技术雷达 - 2026 Q2",
  "rings": [
    {"id": "adopt", "name": "采纳", "color": "#2ecc71"},
    {"id": "trial", "name": "试用", "color": "#3498db"},
    {"id": "assess", "name": "评估", "color": "#f39c12"},
    {"id": "hold", "name": "暂缓", "color": "#e74c3c"}
  ],
  "quadrants": [
    {"id": "languages", "name": "语言与框架"},
    {"id": "tools", "name": "工具"},
    {"id": "platforms", "name": "平台"},
    {"id": "techniques", "name": "技术实践"}
  ],
  "entries": [
    {
      "label": "Java 21 Virtual Threads",
      "quadrant": "languages",
      "ring": "adopt",
      "description": "已在订单服务中使用，显著降低了线程管理复杂度"
    },
    {
      "label": "Structurizr DSL",
      "quadrant": "tools",
      "ring": "adopt",
      "description": "已全面采用，所有架构描述均使用 DSL 定义"
    },
    {
      "label": "ArchUnit",
      "quadrant": "tools",
      "ring": "adopt",
      "description": "所有 Java 模块均已接入架构测试"
    },
    {
      "label": "D2 语言",
      "quadrant": "tools",
      "ring": "trial",
      "description": "在部分团队试用中，语法简洁，适合快速出图"
    },
    {
      "label": "gRPC + Protobuf",
      "quadrant": "languages",
      "ring": "adopt",
      "description": "内部服务间通信标准协议"
    },
    {
      "label": "GraphQL",
      "quadrant": "languages",
      "ring": "assess",
      "description": "评估是否用于 BFF 层的 API 聚合"
    },
    {
      "label": "Backstage",
      "quadrant": "platforms",
      "ring": "trial",
      "description": "正在试点部署，用于服务目录管理"
    },
    {
      "label": "手动架构图（PPT/Visio）",
      "quadrant": "tools",
      "ring": "hold",
      "description": "已全面迁移到代码化架构描述，不再使用手动绘图"
    }
  ]
}

#!/usr/bin/env python3
"""
架构门户静态站点生成器
整合 Structurizr 图、ADR、技术雷达到一个站点
"""

import json
import subprocess
from pathlib import Path


def generate_architecture_portal(config_path: str) -> None:
    """生成架构门户静态站点"""
    config = json.loads(Path(config_path).read_text())

    output_dir = Path(config["output_dir"])
    output_dir.mkdir(parents=True, exist_ok=True)

    # 步骤一：导出 Structurizr 图
    print("正在导出架构图...")
    subprocess.run([
        "structurizr-cli", "export",
        "-workspace", config["structurizr_workspace"],
        "-format", "plantuml/structurizr",
        "-output", str(output_dir / "diagrams")
    ], check=True)

    # 步骤二：构建 ADR 站点
    print("正在构建 ADR 站点...")
    subprocess.run([
        "log4brains", "build",
        "--out", str(output_dir / "adr")
    ], check=True)

    # 步骤三：生成技术雷达页面
    print("正在生成技术雷达...")
    radar_data = json.loads(
        Path(config["tech_radar_data"]).read_text()
    )
    generate_radar_page(radar_data, output_dir / "radar")

    # 步骤四：生成首页
    print("正在生成首页...")
    generate_index_page(config, output_dir)

    print(f"架构门户已生成到：{output_dir}")


def generate_radar_page(radar_data: dict, output_dir: Path) -> None:
    """生成技术雷达 HTML 页面"""
    output_dir.mkdir(parents=True, exist_ok=True)
    html_content = render_radar_template(radar_data)
    (output_dir / "index.html").write_text(html_content)


def generate_index_page(config: dict, output_dir: Path) -> None:
    """生成门户首页"""
    index_html = f"""<!DOCTYPE html>
<html lang="zh-CN">
<head>
    <meta charset="UTF-8">
    <title>{config['title']}</title>
</head>
<body>
    <h1>{config['title']}</h1>
    <nav>
        <ul>
            <li><a href="diagrams/">架构图</a></li>
            <li><a href="adr/">架构决策记录</a></li>
            <li><a href="radar/">技术雷达</a></li>
        </ul>
    </nav>
</body>
</html>"""
    (output_dir / "index.html").write_text(index_html)


def render_radar_template(data: dict) -> str:
    """渲染技术雷达 HTML 模板"""
    return f"<html><body><h1>{data['title']}</h1></body></html>"


if __name__ == "__main__":
    generate_architecture_portal("portal-config.json")