PlantUML 配图方法论：如何用代码生成文章封面图

一套用 PlantUML 为不同类型文章生成专属配图的方法论。

---

一、背景与问题

写技术文章时，封面图是个头疼的问题：

• 用 PS 太麻烦
• 用截图工具不够美观
• 找素材网站又容易撞图

PlantUML 的优势：

• 代码绘制，所见即所得
• 风格统一，可复用
• 完全免费，无需设计基础

---

二、PlantUML 图纸类型与文章适配

2.1 架构类文章 → Component Diagram（组件图）

场景：系统设计、架构分析、技术选型

示例主题：

• 微服务架构
• AI Agent 系统架构
• 全屋智能系统

推荐样式：

skinparam componentStyle rectangle
package "模块1" { [组件A] }
package "模块2" { [组件B] }
组件A --> 组件B

关键元素：

• package：分组模块
• component：组件
• -->：箭头表示关系
• skinparam componentStyle rectangle：方角风格更专业

---

2.2 流程类文章 → Activity Diagram（活动图）

场景：流程说明、步骤讲解、自动化脚本

示例主题：

• 开发流程
• 用户操作路径
• CI/CD 流水线

注意：PlantUML JAR 版本 if/else/loop 不稳定，改用 partition 分区或线性步骤。

---

2.3 时序类文章 → Sequence Diagram（时序图）

场景：API 调用、模块交互、调试分析

示例主题：

• HTTP 请求流程
• 用户登录过程
• 消息队列交互

关键元素：

• participant：参与者
• actor：用户
• -->：消息箭头
• note：注释说明

---

2.4 分类/对比类文章 → Class Diagram / Package

场景：技术对比、分类整理、功能盘点

示例主题：

• AI 模型对比
• 编程语言对比
• 工具选型

关键元素：

• package 或 class：分类框
• rectangle：简化方块
• [标签] as 别名：命名简化

---

2.5 状态/演进类文章 → State Diagram / Clock

场景：状态机、生命周期、版本演进

示例主题：

• 订单状态流转
• 用户生命周期
• 技术架构演进

---

2.6 地理/网络类文章 → Network / NWDiag

场景：网络拓扑、服务器部署、IoT 架构

示例主题：

• 网络拓扑设计
• 服务器架构
• VLAN 划分

---

三、通用设计规范

3.1 主题选择

主题	适用场景	特点
plain	通用	简洁清晰
lightgray	浅色背景	柔和
modern	现代风格	科技感

3.2 配色规范

• 蓝色系（科技/技术）：#87CEEB SteelBlue DodgerBlue
• 绿色系（AI/创新）：#90EE90 SeaGreen MediumSeaGreen
• 紫色系（创意/设计）：#DDA0DD Plum MediumOrchid
• 灰色系（商务/数据）：LightGray Silver DimGray

3.3 字体设置

skinparam defaultFontSize 14
skinparam defaultFontName Arial

3.4 布局方向

top to bottom direction    # 上下布局
left to right direction    # 左右布局

---

四、生成流程

4.1 创建 puml 文件

@startuml
!theme plain

title 文章标题

skinparam componentStyle rectangle
skinparam defaultFontSize 12

package "分类1" {
  [元素A] as A
  [元素B] as B
}

package "分类2" {
  [元素C] as C
}

A --> C
B --> C

@enduml

4.2 渲染图片

python3 /path/to/plantuml.py article-cover.puml

输出：article-cover.png

4.3 应用于文章

![封面](diagrams/article-cover.png)

---

五、实战模板

模板1：技术架构图（最常用）

@startuml
!theme plain

title 技术架构概览

top to bottom direction

package "用户层" {
  [Web] as Web
  [App] as App
}

package "服务层" {
  [API Gateway] as API
  [AI Engine] as AI
  [Data Layer] as Data
}

package "基础设施" {
  [Server] as Server
  [Storage] as Storage
}

Web --> API
App --> API
API --> AI
API --> Data
AI --> Data
Server --> Storage

@enduml

模板2：流程图（线性）

@startuml
!theme plain

title 操作流程

start

:Step 1;
partition Step2 {
  :Action A;
  :Action B;
}
:Step 3;

stop

@enduml

模板3：对比分类图

@startuml
!theme plain

title 分类对比

left to right direction

package "方案A" {
  [优势1]
  [优势2]
  [劣势1]
}

package "方案B" {
  [优势1]
  [优势2]
  [劣势1]
}

note bottom of 方案A
  适用场景：xxx
end note

note bottom of 方案B
  适用场景：yyy
end note

@enduml

模板4：时序图

@startuml
!theme plain

title 交互时序

actor User
participant "客户端" as Client
participant "服务端" as Server

User -> Client : 请求
Client -> Server : 转发
Server --> Client : 响应
Client --> User : 返回

note right of Server
  处理时间：100ms
end note

@enduml

---

六、避坑指南

坑	解法
if/else 不支持	改用 partition 分区
\n 换行报错	不使用换行符
中文乱码	使用 UTF-8 编码保存
箭头显示异常	调整布局方向
图片模糊	调整 skinparam 分辨率

---

七、总结

文章类型	推荐图类型	关键词
系统架构	Component Diagram	package、component
操作流程	Activity + Partition	partition、线性步骤
时序交互	Sequence Diagram	participant、–>
分类对比	Package + Rectangle	package、rectangle
网络拓扑	Network / NWDiag	network、nwdiag
状态演进	State Diagram	state、transition

核心原则：用最简单的元素表达核心概念，风格统一，代码即文档。

---

PlantUML 的精髓：不在于图多复杂，而在于用最少的代码表达最清晰的意思。

---

转载请注明来源，欢迎对文章中的引用来源进行考证，欢迎指出任何有错误或不够清晰的表达。可以在下面评论区评论，也可以邮件至 1056615746@qq.com