PlantUML
Công cụ sinh sơ đồ từ mã văn bản, phủ gần hết UML 2.x cùng C4 và nhiều loại khác. Mạnh hơn Mermaid về UML đầy đủ, đổi lại phải có chỗ render và đôi khi cần cài thêm Graphviz.
Định nghĩa
Cũng là vẽ bằng chữ, nhưng PlantUML nghiêm túc hơn hẳn về UML: phủ gần đủ các loại sơ đồ trong UML 2.x, thêm C4, wireframe, gantt, sơ đồ mạng. Xuất được PNG và SVG, chạy offline bằng một file jar.
Chọn PlantUML khi cần UML đúng chuẩn và sơ đồ lớn. Chọn Mermaid khi cần nhanh và cần nó tự hiện trong wiki.
Một sequence diagram thật
@startuml
actor "Nhan vien kho" as NV
participant "App kho" as App
participant "Backend WMS" as BE
database "CSDL" as DB
NV -> App: Quet ma vach
App -> BE: POST /inbound/scan
BE -> DB: Ghi dong nhap kho
DB --> BE: OK
BE --> App: So luong luy ke
App --> NV: Hien thi 120/150
@endumlVà một class diagram:
@startuml
class HopDong {
+String maHopDong
+Date ngayBatDau
+Date ngayKetThuc
+boolean conHieuLuc()
}
class DieuKhoan {
+String noiDung
+BigDecimal mucTangMoiKy
}
HopDong "1" *-- "0..*" DieuKhoan
@endumlMọi thứ nằm giữa @startuml và @enduml. Dấu *-- là composition, o-- là aggregation, <|-- là kế thừa. Đúng ký hiệu UML, không phải xấp xỉ.
Một chỗ hay vấp: sequence diagram thì jar tự vẽ được, còn class, state hay component thì mặc định cần cài thêm Graphviz. Không cài được Graphviz trên máy công ty thì thêm dòng !pragma layout smetana vào đầu file, PlantUML sẽ dùng engine tự có bên trong.
So với Mermaid
| Mermaid | PlantUML | |
|---|---|---|
| Render sẵn ở đâu | GitHub, GitLab, Notion, Obsidian, nhiều wiki | Cần server, plugin hoặc jar cục bộ |
| Độ phủ UML | Vài loại phổ biến | Gần đủ UML 2.x, thêm C4 |
| Tuỳ biến hình thức | Ít | Nhiều, qua skinparam và theme |
| Học mất bao lâu | Một buổi trưa | Vài ngày nếu muốn dùng sâu |
| Sơ đồ lớn | Rối từ khoảng 30 node | Chịu tốt hơn nhiều |
| Rào cản với team | Gần như không có | Phải thuyết phục ai đó cài đặt |
Ví dụ thực tế
Ở một dự án core banking mình tham gia, toàn bộ sơ đồ tích hợp gồm 18 sequence diagram nằm trong repo dưới dạng file .puml, đặt cạnh code. CI sinh SVG mỗi lần merge, Confluence chỉ nhúng ảnh đầu ra. Cuối dự án rà lại, lệch đúng hai chỗ, cả hai đều là luồng sửa gấp lúc hotfix rồi quên cập nhật .puml. Hai chỗ trong mười tám sơ đồ, sau sáu tháng — so với dự án trước thì đó là trời với vực.
So với dự án trước đó, nơi sơ đồ là ảnh PNG dán vào Word: tới tháng thứ tư thì không ai biết bản nào mới nhất, và cách kiểm tra duy nhất là đi hỏi dev.
Ai thật sự cần
BA làm dự án có tài liệu kỹ thuật dày, có kiến trúc sư, hoặc công ty đã dựng sẵn PlantUML server. Trong trường hợp đó, đây là công cụ đáng học.
Còn nếu team đang dùng Confluence trắng, không ai được quyền cài thêm app, mà bạn thì cần một sơ đồ để họp chiều nay thì đừng cố. Mermaid hoặc draw.io giải quyết xong trong mười phút.
Mẹo khi đi làm
- Dùng
!includeđể tách phần khai báo actor và thành phần dùng chung ra file riêng, mọi sơ đồ nhất quán. - Commit file
.pumlvào Git cạnh code, sinh ảnh trong CI. Tài liệu hết cảnh lệch phiên bản. - Đặt sẵn một file theme cho cả team, đừng để mỗi người một bộ màu.
- Với sơ đồ trên năm mươi phần tử, tách theo ngữ cảnh thay vì phóng to. Tấm A0 in ra chỉ để dán tường cho oai, lúc cần tra thì vẫn phải mở lại file gốc.
Bắt đầu bằng đúng một sequence diagram cho luồng tích hợp gai góc nhất trong dự án. Nếu sau hai tuần bạn vẫn quay lại sửa nó thì công cụ này hợp với bạn.
