Biểu đồ dưới dạng mã: Biểu đồ trình tự UML với PlantUML và VPasCode

Một UML biểu đồ trình tự cho thấy cách các thành phần tương tác theo thời gian. Nó hữu ích để tài liệu hóa một kịch bản sử dụng, luồng API, quy trình kinh doanh hoặc kịch bản hệ thống. Thời gian thường di chuyển từ trên xuống dưới; vị trí ngang cho biết ai tham gia, chứ không phải là phép đo chính xác về thời gian trôi qua.

PlantUML cho phép bạn mô tả biểu đồ dưới dạng văn bản. Trình chỉnh sửa VPasCode của Visual Paradigm kết hợp trình chỉnh mã với bản xem trước trực tiếp và hỗ trợ AI để tạo, sửa đổi và sửa mã biểu đồ. Một quy trình làm việc tốt là sử dụng AI để có bản nháp đầu tiên, sau đó tự kiểm tra và tinh chỉnh mã PlantUML.

1. Cấu trúc cơ bản

Một biểu đồ trình tự PlantUML bắt đầu bằng @startuml và kết thúc bằng @enduml. Các thành phần thường được liệt kê trước các thông điệp để bạn có thể kiểm soát tên và thứ tự của chúng.

@startuml
actor Customer
participant Browser
participant "Order API" as API
database "Order DB" as DB

Customer -> Browser: Place order
Browser -> API: POST /orders
API -> DB: Save order
DB --> API: Order ID
API --> Browser: 201 Created
Browser --> Customer: Show confirmation
@enduml

Nhãn hiển thị của người tham gia có thể được đặt trong dấu ngoặc kép, với as để cung cấp một biệt danh ngắn gọn hơn để sử dụng trong các thông báo. Các từ khóa người tham gia phổ biến bao gồm actor, participant, boundary, control, entity, database, và tập hợp. Hãy sử dụng từ khóa truyền đạt tốt nhất vai trò của người tham gia; nó không ép buộc một kiến trúc cụ thể nào.

2. Đọc tin nhắn và thời gian

Mỗi tin nhắn được viết dưới dạng người gửi, một mũi tên, người nhận và một nhãn. Thứ tự của các dòng tin nhắn xác định thứ tự dọc của chúng trong sơ đồ.

• -> là mũi tên tin nhắn liền nét, thường được dùng cho yêu cầu hoặc lời gọi.

• --> là mũi tên nét đứt, thường được dùng cho phản hồi hoặc trả về.

• ->> và -->> sử dụng đầu mũi tên mở trong các kiểu PlantUML phổ biến.

• : văn bản thêm nhãn tin nhắn.

Hãy chọn một quy ước thống nhất cho các lời gọi và phản hồi. Các sơ đồ UML truyền đạt một tương tác; chúng không tự động đảm bảo rằng việc triển khai tuân theo giao thức được mô tả.

3. Kích hoạt và thời gian sống của người tham gia

Các kích hoạt có thể hiển thị khi nào một người tham gia đang thực hiện công việc. Hãy sử dụng kích hoạt và hủy kích hoạt, hoặc ký hiệu tắt ++ và -- trên các mũi tên tin nhắn.

@startuml
actor User
participant "Login API" as API
database Users

User -> API: Gửi thông tin đăng nhập
kích hoạt API
API -> Users: Tìm tài khoản
kích hoạt Users
Users --> API: Bản ghi tài khoản
hủy kích hoạt Users
API --> User: Kết quả đăng nhập
hủy kích hoạt API
@enduml

Các lệnh kích hoạt hữu ích nhất khi chúng làm rõ các lời gọi lồng nhau hoặc trách nhiệm. Tránh thêm chúng một cách máy móc vào mọi tin nhắn nếu điều đó khiến biểu đồ khó đọc hơn.

4. Điều kiện, lựa chọn thay thế và lặp lại

Sử dụng các khối kết hợp để thể hiện luồng điều khiển. Từ khóa fragment bắt đầu khối, else phân tách các lựa chọn thay thế khi phù hợp, và end đóng khối lại. Các điều kiện bảo vệ được đặt trong dấu ngoặc vuông.

Các đường dẫn thay thế: alt và else

@startuml
actor User
participant "Login API" as API
database Users

User -> API: Gửi tên người dùng và mật khẩu
API -> Users: Kiểm tra thông tin xác thực
Users --> API: Kết quả khớp

alt [thông tin xác thực hợp lệ]
  API --> User: Trả về mã thông báo phiên
else [thông tin xác thực không hợp lệ]
  API --> User: Trả về lỗi xác thực
end
@enduml

alt là phù hợp khi các đường dẫn loại trừ lẫn nhau. Hãy sử dụng nhãn làm rõ các điều kiện.

Hành vi tùy chọn: opt

@startuml
actor Customer
participant Checkout
participant "Email Service" as Email

Customer -> Checkout: Hoàn tất mua hàng
Checkout --> Customer: Xác nhận đơn hàng

opt [khách hàng đã đăng ký nhận email]
  Checkout -> Email: Gửi biên lai
  Email --> Checkout: Đã chấp nhận
end
@enduml

Lặp lại: vòng lặp

@startuml
participant "Batch Job" as Job
participant "Payment API" as API

loop [cho mỗi thanh toán đang chờ]
  Job -> API: Gửi thanh toán
  API --> Job: Kết quả thanh toán
end
@enduml

Đặt hành động lặp lại bên trong khối và nêu rõ điều kiện hoặc phạm vi của vòng lặp.

5. Tương tác song song và nhóm

Sử dụng par khi các tương tác xảy ra đồng thời hoặc thứ tự của chúng không quan trọng. Sử dụng group để gắn nhãn cho một tập hợp các thông báo mà không ngụ ý một cấu trúc luồng điều khiển cụ thể.

@startuml
participant "Dịch vụ Đơn hàng" as Orders
participant "Dịch vụ Kho" as Inventory
participant "Dịch vụ Thông báo" as Notify

Orders -> Orders: Đơn hàng được chấp nhận

par Trữ hàng
  Orders -> Inventory: Trữ hàng hóa
  Inventory --> Orders: Kết quả đặt chỗ
else Thông báo khách hàng
  Orders -> Notify: Gửi cập nhật đơn hàng
  Notify --> Orders: Đã chấp nhận
end
@enduml

Sử dụng parchỉ khi tính đồng thời có ý nghĩa. Nếu một hành động phải hoàn tất trước khi hành động khác bắt đầu, hãy hiển thị các thông báo theo trình tự thay vì.

6. Ghi chú, tham chiếu và nhóm trực quan

Ghi chú có thể làm rõ các giả định, ràng buộc hoặc quyết định. Một ref đoạn mã có thể hướng người đọc đến một biểu đồ khác hoặc một tương tác được tài liệu hóa riêng biệt.

@startuml
actor Khách hàng
participant "Giao diện Thanh toán" as UI
participant "Dịch vụ Thanh toán" as Pay
participant "Kiểm tra Lừa đảo" as Fraud

Customer -> UI: Thanh toán cho đơn hàng
UI -> Pay: Xác thực thanh toán
Pay -> Fraud: Đánh giá giao dịch

note bên phải của Fraud
  Các quy tắc rủi ro được duy trì
  bên ngoài tương tác này.
end note

Fraud --> Pay: Kết quả rủi ro
Pay --> UI: Kết quả xác thực
UI --> Customer: Hiển thị kết quả
@enduml

Ghi chú nên bổ sung ngữ cảnh thay vì lặp lại nhãn thông báo. Nếu biểu đồ trở nên quá tải, hãy chia nó thành các kịch bản tập trung và sử dụng các tham chiếu hoặc liên kết tài liệu để kết nối chúng.

7. Tạo và tinh chỉnh biểu đồ trong VPasCode

VPasCode hỗ trợ chỉnh sửa PlantUML với hiển thị trực tiếp, cũng như tạo biểu đồ hỗ trợ bởi AI, chỉnh sửa mã và sửa lỗi cú pháp. Giao diện chính xác và tính khả dụng của các tính năng có thể thay đổi, nhưng quy trình chung là:

1. Mở VPasCode và chọn hoặc nhập PlantUML.

2. Mô tả tương tác, hoặc dán bản nháp PlantUML vào trình soạn thảo.

3. Kiểm tra bản xem trước đã được hiển thị khi bạn tinh chỉnh mã nguồn.

4. Yêu cầu AI thực hiện một thay đổi cụ thể, chẳng hạn như “thêm một đường dẫn sử dụng thông tin đăng nhập không hợp lệ bằng “alt.”

5. Xem lại mã và biểu đồ kết quả để đảm bảo cả về cú pháp và tính đúng đắn của hệ thống.

6. Xuất hoặc chia sẻ biểu đồ hoàn chỉnh bằng các tùy chọn có sẵn trong trình soạn thảo.

Một câu lệnh hữu ích cung cấp cho AI loại biểu đồ, các vai trò, ranh giới hệ thống, đường dẫn thành công chính, các đường dẫn thay thế quan trọng và mức độ chi tiết. Ví dụ:

Tạo biểu đồ trình tự PlantUML cho việc khách hàng đăng nhập vào ứng dụng web. Bao gồm Trình duyệt, API Đăng nhập, Nhà cung cấp Danh tính và Cơ sở dữ liệu Người dùng. Hiển thị đường dẫn đăng nhập thành công và một phương án thay thế cho mật khẩu không hợp lệ. Sử dụng nhãn ngắn gọn và không tự tạo các dịch vụ ngoài những dịch vụ này.

Xem mã được tạo ra như một bản nháp. Kiểm tra xem các đối tượng tham gia, mũi tên, điều kiện và đường dẫn lỗi có phản ánh đúng hệ thống thực tế hay không—chứ không chỉ là một luồng có vẻ hợp lý.

8. Một ví dụ chi tiết hơn: thanh toán với lỗi thanh toán

Ví dụ này kết hợp các biệt danh đối tượng tham gia, các kích hoạt và một đường dẫn thay thế.

@startuml
title Thanh toán và Xác thực Thanh toán

actor Khách hàng
boundary "Giao diện Thanh toán" as UI
control "Dịch vụ Đơn hàng" as Orders
participant "Cổng thanh toán" as Pay
database "Cơ sở dữ liệu Đơn hàng" as DB

Khách hàng -> UI: Gửi yêu cầu thanh toán
UI -> Orders: Tạo đơn hàng tạm
activate Orders

Orders -> DB: Lưu đơn hàng tạm
DB --> Orders: Mã đơn hàng

Orders -> Pay: Xác thực thanh toán
activate Pay

alt [thanh toán được chấp nhận]
  Pay --> Orders: Mã xác thực
deactivate Pay

  Orders -> DB: Đánh dấu đơn hàng đã xác nhận
  DB --> Orders: Đã cập nhật
  Orders --> UI: Đơn hàng đã xác nhận
  UI --> Khách hàng: Hiển thị xác nhận
else [thanh toán bị từ chối]
  Pay --> Orders: Lý do từ chối
deactivate Pay

  Orders -> DB: Đánh dấu đơn hàng thất bại
  DB --> Orders: Đã cập nhật
  Orders --> UI: Thanh toán bị từ chối
  UI --> Khách hàng: Hiển thị tùy chọn thử lại
end

deactivate Orders
@enduml

Hãy kiểm tra xem thứ tự trong sơ đồ có khớp với hành vi thực tế hay không. Ví dụ, nếu hệ thống chỉ lưu đơn hàng sau khi xác thực thành công, hãy di chuyển các thông báo cơ sở dữ liệu để phù hợp với thiết kế đó.

9. Hướng dẫn mô hình hóa thực tiễn

• Giữ cho sơ đồ tập trung.Chỉ hiển thị một kịch bản hoặc một tập hợp các đường dẫn liên quan chặt chẽ. Tách biệt các chi tiết sâu có thể làm phân tâm khỏi tương tác chính.

• Đặt tên cho các thành viên dựa trên trách nhiệm của họ. Ưu tiên các nhãn như “Dịch vụ Đơn hàng” hoặc “Cổng thanh toán” thay vì các nhãn mơ hồ như “Hệ thống.

• “Thể hiện các ranh giới có ý nghĩa.Phân biệt người dùng, khách hàng, dịch vụ nội bộ, cơ sở dữ liệu và các hệ thống bên ngoài khi điều đó giúp người đọc hiểu rõ trách nhiệm.

• Sử dụng các nhãn thông báo rõ ràng. Bao gồm một hoạt động, sự kiện hoặc kết quả quan trọng; tránh các nhãn chỉ đơn thuần ghi “quá trình.”

• Mô hình hóa các đường dẫn lỗi có ý nghĩa.Bao gồm các thời gian chờ, từ chối, thử lại hoặc lỗi xác thực liên quan khi chúng ảnh hưởng đến kịch bản.

• Sử dụng các đoạn mã (fragments) một cách chính xác. alt có nghĩa là các đường dẫn thay thế, opt có nghĩa là hành vi tùy chọn, loop có nghĩa là sự lặp lại, và par có nghĩa là hành vi song song.

• Tránh nhiễu từ các chi tiết triển khai.Đừng vẽ sơ đồ cho mọi phương thức getter, phương thức nội bộ hoặc chi tiết cấp thấp trừ khi khán giả cần nó.

• Giữ cho nguồn mã dễ bảo trì.Sử dụng biệt danh cho các tên dài, đặt tên nhất quán, và chú thích hoặc ghi chú ngắn gọn cho các giả định quan trọng.

10. Các lỗi phổ biến và danh sách kiểm tra rà soát

Nếu sơ đồ không hiển thị được, hãy kiểm tra xem @startuml và @enduml được hiển thị, các khối phân đoạn có các cặp khớp nhau end câu lệnh, các biệt danh được sử dụng nhất quán, và tất cả các điểm cuối thông báo đều tham chiếu đến các đối tượng đã được định nghĩa. Ngoài ra, hãy kiểm tra xem có cú pháp từ một ngôn ngữ sơ đồ khác bị dán nhầm vào mã nguồn PlantUML hay không.

Trước khi chia sẻ, hãy xem xét hai điều sau:

• Cú pháp: Nó có được hiển thị đúng không? Các khối phân đoạn đã được đóng lại chưa? Các đối tượng và biệt danh có nhất quán không?

• Ý nghĩa: Các đối tượng và hướng thông báo có chính xác không? Các đường dẫn lỗi quan trọng đã được bao gồm chưa? Các hệ thống bên ngoài và kho dữ liệu có được biểu diễn chính xác không?

Quy trình làm việc mạnh mẽ nhất sơ đồ dưới dạng mã kết hợp mã nguồn dễ đọc, phản hồi trực quan nhanh chóng và đánh giá theo lĩnh vực. PlantUML cung cấp quyền kiểm soát rõ ràng đối với ký hiệu tương tác, trong khi VPasCode có thể tăng tốc độ soạn thảo và lặp lại; thẩm quyền cuối cùng về độ chính xác của sơ đồ vẫn là hành vi hệ thống mà nó được thiết kế để mô tả.

This post is also available in Deutsch, English, Español, فارسی, Français, Bahasa Indonesia, 日本語, Polski, Portuguese, Ру́сский, 简体中文 and 繁體中文.