plantuml-ascii

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

輸出格式

旗標	格式	說明
-txt	ASCII	純 ASCII 字元
-utxt	Unicode ASCII	使用方框繪製字元增強

基本工作流程

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 有寫入權限