PlantUML ASCII 艺术图生成器

概述

使用 PlantUML 创建基于文本的 ASCII 艺术图。非常适合在终端环境、README 文件、电子邮件或任何不适合使用图形图表的场景中进行文档记录。

什么是 PlantUML ASCII 艺术？

PlantUML 可以生成纯文本（ASCII 艺术）格式的图表，而不是图像。这在以下场景中非常有用：

• 基于终端的工作流程
• 不支持图像的 Git 提交/PR
• 需要进行版本控制的文档
• 无法使用图形工具的环境

安装

# macOS
brew install plantuml

# Linux (因发行版而异)
sudo apt-get install plantuml  # Ubuntu/Debian
sudo yum install plantuml      # RHEL/CentOS

# 或者直接下载 JAR 包
wget https://github.com/plantuml/plantuml/releases/download/v1.2024.0/plantuml-1.2024.0.jar

输出格式

基本工作流程

1. 创建 PlantUML 图表文件

@startuml
participant Bob
actor Alice

Bob -> Alice : hello
Alice -> Bob : Is it ok?
@enduml

2. 生成 ASCII 艺术图

# 标准 ASCII 输出
plantuml -txt diagram.puml

# Unicode 增强输出（视觉效果更好）
plantuml -utxt diagram.puml

# 直接使用 JAR 包
java -jar plantuml.jar -txt diagram.puml
java -jar plantuml.jar -utxt diagram.puml

3. 查看输出

输出保存为 diagram.atxt（ASCII）或 diagram.utxt（Unicode）。

支持的图表类型

序列图

@startuml
actor User
participant "Web App" as App
database "Database" as DB

User -> App : Login Request
App -> DB : Validate Credentials
DB --> App : User Data
App --> User : Auth Token
@enduml

类图

@startuml
class User {
  +id: int
  +name: string
  +email: string
  +login(): bool
}

class Order {
  +id: int
  +total: float
  +items: List
  +calculateTotal(): float
}

User "1" -- "*" Order : places
@enduml

活动图

@startuml
start
:Initialize;
if (Is Valid?) then (yes)
  :Process Data;
  :Save Result;
else (no)
  :Log Error;
  stop
endif
:Complete;
stop
@enduml

状态图

@startuml
[*] --> Idle
Idle --> Processing : start
Processing --> Success : complete
Processing --> Error : fail
Success --> [*]
Error --> Idle : retry
@enduml

组件图

@startuml
[Client] as client
[API Gateway] as gateway
[Service A] as svcA
[Service B] as svcB
[Database] as db

client --> gateway
gateway --> svcA
gateway --> svcB
svcA --> db
svcB --> db
@enduml

用例图

@startuml
actor "User" as user
actor "Admin" as admin

rectangle "System" {
  user -- (Login)
  user -- (View Profile)
  user -- (Update Settings)
  admin -- (Manage Users)
  admin -- (Configure System)
}
@enduml

部署图

@startuml
actor "User" as user
node "Load Balancer" as lb
node "Web Server 1" as ws1
node "Web Server 2" as ws2
database "Primary DB" as db1
database "Replica DB" as db2

user --> lb
lb --> ws1
lb --> ws2
ws1 --> db1
ws2 --> db1
db1 --> db2 : replicate
@enduml

命令行选项

# 指定输出目录
plantuml -txt -o ./output diagram.puml

# 处理目录中的所有文件
plantuml -txt ./diagrams/

# 包含点文件（隐藏文件）
plantuml -txt -includeDot diagrams/

# 详细输出
plantuml -txt -v diagram.puml

# 指定字符集
plantuml -txt -charset UTF-8 diagram.puml

Ant 任务集成

<target name="generate-ascii">
  <plantuml dir="./src" format="txt" />
</target>

<target name="generate-unicode-ascii">
  <plantuml dir="./src" format="utxt" />
</target>

生成更好 ASCII 图表的技巧

1. 保持简洁：复杂的图表在 ASCII 中渲染效果不佳
2. 标签要短：长文本会破坏 ASCII 对齐
3. 使用 Unicode (-utxt)：使用制表符绘制字符可获得更好的视觉效果
4. 分享前测试：在使用等宽字体的终端中进行验证
5. 考虑替代方案：对于复杂图表，请使用 Mermaid.js 或 graphviz

输出示例对比

标准 ASCII (-txt)：

     ,---.          ,---.
     |Bob|          |Alice|
     `---'          `---'
      |   hello      |
      |------------->|
      |              |
      |  Is it ok?   |
      |<-------------|
      |              |

Unicode ASCII (-utxt)：

┌─────┐        ┌─────┐
│ Bob │        │Alice│
└─────┘        └─────┘
  │   hello      │
  │─────────────>│
  │              │
  │  Is it ok?   │
  │<─────────────│
  │              │

快速参考

# 创建 ASCII 序列图
cat > seq.puml << 'EOF'
@startuml
Alice -> Bob: Request
Bob --> Alice: Response
@enduml
EOF

plantuml -txt seq.puml
cat seq.atxt

# 使用 Unicode 创建
plantuml -utxt seq.puml
cat seq.utxt

故障排除

问题：Unicode 字符乱码

• 解决方案：确保终端支持 UTF-8 并且有合适的字体

问题：图表看起来不对齐

• 解决方案：使用等宽字体（Courier、Monaco、Consolas）

问题：找不到命令

• 解决方案：安装 PlantUML 或直接使用 Java JAR 包

问题：未创建输出文件

• 解决方案：检查文件权限，确保 PlantUML 具有写入权限