PlantUML 组件图语法指南

什么是组件图？

一个组件图是一种结构化的UML 图用于描绘软件系统的高层次模块化结构。作为统一建模语言（UML）规范中的关键组成部分，这种特定的UML 图类型可视化物理代码模块、库、微服务、执行包和数据库层在结构上如何分组和连接。它将文档重点从细粒度的类定义转移开，使软件架构师和主要工程师能够清晰地展示系统集成边界、API 编排路径以及第三方依赖关系。

无论你是描绘现代云原生微服务拓扑，还是展示内部框架库如何接入你的遗留应用核心，UML 组件图都能提供系统边界清晰且结构化的概览。借助VPasCode，你的组件布局将根据声明式文本自动渲染，无需手动调整布局框或连接线，省去繁琐操作。

核心语法指南：元素与构造

要在 PlantUML 中设计出优雅且符合标准的 UML 组件图，你需要掌握模块化代码块声明、接口连接机制、系统包分组以及方向性连接参数。

1. 声明软件组件

你使用component关键字来声明一个软件模块。或者，你可以将一个清晰的文本标识符用方括号包裹（[组件名称]），这作为一个全局简写标识符：

component PaymentEngine
[Auth Service] as AuthService

专业提示：始终将较长的组件字符串与一个as标识符（例如as AuthService）以保持关系线清晰且易于阅读。

2. 定义端口和接口

组件通过结构化入口点相互交互。您可以使用“interface”关键字显式建模标准UML接口（在视觉上以简洁的“棒棒糖”圆形图标表示）：interface关键字：

interface "REST API v2" as WebAPI
[AuthService] --() WebAPI : "exposes"

3. 映射组件依赖关系

要表示一个系统模块依赖于或与另一个模块通信，使用方向箭头（-->）。您还可以使用标准的虚线依赖线（..>）来表示较松散的关系，例如消息队列消费模式或临时运行时调用：

[前端应用] --> WebAPI
WebAPI ..> [数据库引擎] : "SQL查询"

4. 使用包来组织边界

为了建立清晰的子系统边界或根据部署环境对组件进行分类，将您的模块块包裹在结构化的package或cloud包装器中：

package "安全上下文" {
    [认证服务]
    [令牌验证器]
}

清晰组件子系统的最佳实践

• 保持节点名称的高层次性： 避免根据特定的内部代码文件或目录来命名组件。使用功能性强、层次较高的名称，例如[通知路由器] 或 [缓存层].
• 利用棒棒糖标记法： 不要直接在方框之间绘制普通线条，而是通过显式的接口节点来传递连接。这能清晰地区分*暴露了什么*接口，以及*由谁*在使用它。
• 控制布局扩展： 在追踪多个子系统时，组件图会迅速扩展。在依赖箭头中使用空间标志（例如-right-> 或 -down->）来清晰地组织组件在画布网格中的布局。

现实世界中的PlantUML对象图示例

示例1：核心API网关网格（接口与包分组）

此模板演示了一个标准的多层系统Web架构，突出展示了公共用户应用程序如何通过结构化的REST API接口接入内部微服务。

@startuml
package "公共展示层" {
    [Web SPA客户端] as client
    [移动iOS客户端] as mobile
}

package "API网关子系统" {
    interface "HTTPS网关端点" as HTTP_GW
    [Kong API网关] as gateway
}

package "核心后端服务" {
    interface "用户管理API" as UserAPI
    interface "计费API" as BillingAPI
    
    [身份服务] as auth
    [支付处理引擎] as billing
}

' 将展示层连接到网关
client --> HTTP_GW
mobile --> HTTP_GW
HTTP_GW -- gateway

' 将网关连接到后端接口
gateway --> UserAPI
gateway --> BillingAPI

UserAPI -- auth
BillingAPI -- billing
@enduml

语法解析： 通过将模块嵌套在清晰的package 边界内，自动布局引擎会创建出美观且分明的区域。展示层客户端仅连接到单一暴露的HTTP_GW 网关端口，该端口随后负责将内部流量路由到下方的专业化后端微服务层。

示例2：云数据处理流水线（异步云与队列）

此高级企业蓝图描绘了现实世界中的异步云数据架构，追踪数据摄入流水线、解耦的消息代理以及物理存储端点。

@startuml
cloud "AWS 云网络边界" {
    [数据接收 Webhook] as webhook
    queue "Apache Kafka 集群" as broker
    [流处理事件工作线程] as worker
    database "Amazon S3 数据湖" as storage
}

database "企业数据仓库" as redshift

' 处理管道流程机制
[外部客户端应用] --> webhook : "POST /telemetry"
webhook -right-> broker : "发布原始日志"

broker ..> worker : "消费主题数据流"
worker --> storage : "写入压缩的 Parquet 文件"

storage ..> redshift : "每日 ETL 同步"
@enduml

语法分解： 此示例介绍了专用的 cloud 和 queue 形状，为开发者提供了关于结构拓扑的即时视觉提示。使用水平箭头覆盖 -right-> 确保数据摄入在网格网络中从左到右平滑流动，而虚线依赖关系（..>）准确地表示了解耦的异步通信。