Structurizr 入门指南 | Baeldung中文网

1. 简介

本文介绍 Structurizr，这是一个基于 C4 模型的架构定义与可视化工具，提供编程式建模方案。

与传统 UML 等拖拽式架构图工具不同，Structurizr 让我们能用最熟悉的工具——Java 来描述架构元素。这种代码即架构（Code as Architecture）的方式特别适合版本控制和持续集成。

2. 快速上手

先在 pom.xml 中添加核心依赖：

<dependency>
    <groupId>com.structurizr</groupId>
    <artifactId>structurizr-core</artifactId>
    <version>1.0.0</version>
</dependency>

3. 系统建模

假设我们要构建一个带反欺诈功能的支付网关系统。先创建工作空间和模型：

Workspace workspace = new Workspace("Payment Gateway", "Payment Gateway");
Model model = workspace.getModel();

定义用户和两个软件系统：

Person user = model.addPerson("Merchant", "Merchant");
SoftwareSystem paymentTerminal = model.addSoftwareSystem(
  "Payment Terminal", "Payment Terminal");
user.uses(paymentTerminal, "Makes payment");
SoftwareSystem fraudDetector = model.addSoftwareSystem(
  "Fraud Detector", "Fraud Detector");
paymentTerminal.uses(fraudDetector, "Obtains fraud score");

创建系统上下文视图：

ViewSet viewSet = workspace.getViews();

SystemContextView contextView = viewSet.createSystemContextView(
  paymentTerminal, "context", "Payment Gateway Diagram");
contextView.addAllSoftwareSystems();
contextView.addAllPeople();

这个视图包含了所有软件系统和人员，接下来需要渲染输出。

4. 使用 PlantUML 渲染

PlantUML 是个轻量级方案，特别适合已在使用它的团队。导出代码很简单：

StringWriter stringWriter = new StringWriter();
PlantUMLWriter plantUMLWriter = new PlantUMLWriter();
plantUMLWriter.write(workspace, stringWriter);
System.out.println(stringWriter.toString());

输出结果可直接保存为 .puml 文件，渲染效果如下：

支付网关系统上下文图

5. 使用 Structurizr 官网渲染

更专业的方案是上传到 Structurizr 官网，利用其富交互界面展示：

StructurizrClient client = new StructurizrClient("key", "secret");
client.putWorkspace(1337, workspace);

⚠️ 注意：

key 和 secret 需在官网注册后获取
免费版支持单个工作空间
商业版提供更多高级功能

6. 容器建模

在 C4 模型中，容器指代可独立部署的单元（如 Web 应用、数据库等）。为支付终端添加容器：

Container f5 = paymentTerminal.addContainer(
  "Payment Load Balancer", "Payment Load Balancer", "F5");
Container jvm1 = paymentTerminal.addContainer(
  "JVM-1", "JVM-1", "Java Virtual Machine");
Container jvm2 = paymentTerminal.addContainer(
  "JVM-2", "JVM-2", "Java Virtual Machine");
Container jvm3 = paymentTerminal.addContainer(
  "JVM-3", "JVM-3", "Java Virtual Machine");
Container oracle = paymentTerminal.addContainer(
  "oracleDB", "Oracle Database", "RDBMS");

定义容器间关系：

f5.uses(jvm1, "route");
f5.uses(jvm2, "route");
f5.uses(jvm3, "route");

jvm1.uses(oracle, "storage");
jvm2.uses(oracle, "storage");
jvm3.uses(oracle, "storage");

创建容器视图：

ContainerView view = workspace.getViews()
  .createContainerView(paymentTerminal, "F5", "Container View");
view.addAllContainers();

PlantUML 渲染效果：

容器架构图

7. 组件建模

组件是 C4 模型中最细粒度的单元。以 JVM-1 为例添加组件：

Component jaxrs = jvm1.addComponent("jaxrs-jersey", 
  "restful webservice implementation", "rest");
Component gemfire = jvm1.addComponent("gemfire", 
  "Clustered Cache Gemfire", "cache");
Component hibernate = jvm1.addComponent("hibernate", 
  "Data Access Layer", "jpa");

定义组件依赖：

jaxrs.uses(gemfire, "");
gemfire.uses(hibernate, "");

创建组件视图：

ComponentView componentView = workspace.getViews()
  .createComponentView(jvm1, JVM_COMPOSITION, "JVM Components");
componentView.addAllComponents();

渲染效果：

组件架构图

8. 组件自动提取

对 Spring 项目，Structurizr 能自动扫描注解组件。先添加依赖：

<dependency>
    <groupId>com.structurizr</groupId>
    <artifactId>structurizr-spring</artifactId>
    <version>1.0.0-RC5</version>
</dependency>

配置组件发现器：

ComponentFinder componentFinder = new ComponentFinder(
  jvm, "com.baeldung.structurizr",
  new SpringComponentFinderStrategy(
    new ReferencedTypesSupportingTypesStrategy()
  ),
  new SourceCodeComponentFinderStrategy(new File("/path/to/base"), 150));

启动扫描：

componentFinder.findComponents();

✅ 支持的扫描范围：

Spring 注解组件
JAX-RS 资源
Guice 绑定器
自定义扫描策略

示例输出效果：

Spring 组件自动提取图

9. 总结

本文覆盖了 Structurizr 的核心功能：

✅ 代码化架构定义
✅ 多层级视图（系统/容器/组件）
✅ PlantUML 与官网双渲染支持
✅ Spring 项目自动组件提取

完整示例代码见 GitHub 仓库。

Persistence

REST

Security