Trước khi đi sâu vào các bố cục kiến trúc cụ thể như mô hình C4 hay dòng thời gian tuần tự, điều quan trọng là phải hiểu các quy tắc nền tảng điều khiểnSổ tay PlantUML. PlantUML dựa vào hệ thống ký hiệu văn bản sạch sẽ, rất trực quan. Một khi bạn hiểu cách động cơ mở tài liệu, đặt tên cho các thành phần cấu trúc và định tuyến các đường nối, việc viết bất kỳ bố cục hệ thống phức tạp nào sẽ trở nên hoàn toàn tự nhiên.
Bài giới thiệu nhanh này bao quát các cơ chế cú pháp cấu trúc toàn cục áp dụng cho hầu hết mọi loại sơ đồ PlantUML bên trong môi trường làm việc VPasCode.
1. Các bao bọc tài liệu bắt buộc
Mỗi khối mã PlantUML phải bắt đầu và kết thúc bằng các thẻ khung rõ ràng. Những thẻ này thông báo cho trình phân tích VPasCode khởi chạy bộ động cơ hiển thị đúng trong khung xem trước của bạn:
@startuml— Dòng chính xác này phải được đặt ở đầu tuyệt đối của tập lệnh của bạn. Không có gì khác được đặt trước nó.@enduml— Dòng chính xác này phải được đặt ở cuối tuyệt đối của tập lệnh của bạn, đánh dấu kết thúc của khối dữ liệu sơ đồ của bạn.
Mọi mã được viết bên ngoài hai dấu hiệu này sẽ bị trình biên dịch bỏ qua an toàn, hoặc có thể gây ra cảnh báo xác thực cú pháp trong bảng chẩn đoán môi trường làm việc của bạn.
2. Khai báo các thành phần: ID so với nhãn hiển thị
Khi mô hình hóa một hệ thống phần mềm, bạn sẽ tạo ra nhiều thành phần cấu trúc khác nhau như thành phần, cơ sở dữ liệu, tác nhân hoặc dịch vụ vi mô. Trong PlantUML, bạn có thể khai báo một thành phần rõ ràng bằng cách xác định loại của nó, một ID ngắn gọn nội bộ và một tên hiển thị thân thiện với người dùng được bao quanh bằng dấu ngoặc kép:
component microservice_id as "API Xử lý thanh toán"
database db_id as "SQL Giao dịch Người dùng"Tại sao đây là một thực hành tốt nhất: Sử dụng một ID nội bộ ngắn gọn, sạch sẽ (nhưmicroservice_id) giúp vẽ các đường quan hệ nhanh hơn rất nhiều về sau. Nếu bạn cần thay đổi nhãn dành cho khách hàng từ “API Xử lý thanh toán” thành “Dịch vụ Thanh toán Toàn cầu”, bạn chỉ cần chỉnh sửa ở một dòng mã duy nhất, thay vì cập nhật hàng chục dòng trên toàn bộ tập lệnh của mình.
3. Thành thạo các mũi tên quan hệ và định tuyến theo hướng
Các kết nối giữa các nút hệ thống được vẽ bằng cách kết hợp các gạch ngang (-) và các dấu ngoặc mũi tên (>). Độ dài của các gạch ngang và việc bao gồm các từ khóa hướng giúp bạn kiểm soát ngầm cách bộ động cơ bố trí tự động thu phóng sơ đồ của bạn:
- Kết nối cơ bản:
A --> Bvẽ một mũi tên hướng chuẩn, chỉ từ thành phần A thẳng đến thành phần B. - Đường nối phụ thuộc điểm chấm: Thay thế các gạch ngang bằng dấu chấm sẽ tạo thành đường nét đứt, đây là tiêu chuẩn ngành để chỉ các phụ thuộc bất đồng bộ hoặc lời gọi mạng:
A ..> B. - Cưỡng chế định hướng bố cục: Mặc dù bộ động lực bố cục tự động cách đều các hộp, bạn có thể trực tiếp điều chỉnh định hướng bằng cách chèn từ khóa hướng ngay trong chuỗi mũi tên:
A -up-> B(Cưỡng chế B được hiển thị phía trên A)A -down-> B(Cưỡng chế B được hiển thị phía dưới A)A -left-> B(Cưỡng chế B được hiển thị bên trái A)A -right-> B(Cưỡng chế B được hiển thị bên phải A)
4. Thêm ngữ cảnh trực tiếp: Nhãn và chú thích mã
Tài liệu rõ ràng phụ thuộc rất nhiều vào việc đặt ngữ cảnh phù hợp xung quanh các dòng hình ảnh và đoạn mã văn bản của bạn:
Đánh nhãn các đường kết nối
Bạn có thể thêm văn bản giải thích trực tiếp vào bất kỳ đường kết nối nào bằng cách thêm dấu hai chấm (“:) ngay sau khi ánh xạ mối quan hệ của bạn:
client_id --> api_id : "HTTPS POST /v1/checkout"Viết chú thích mã
Nếu bạn muốn để lại một ghi chú hành chính, ghi nhận thiết kế hoặc giải thích kiến trúc bên trong tệp kịch bản của bạn mà không hiển thị hộp hình ảnh nào trên bảng vẽ, hãy sử dụng ký tự dấu ngoặc đơn (“'). Điều này thông báo cho bộ xử lý bỏ qua việc phân tích toàn bộ dòng đó:
' TODO: Chúng ta cần cập nhật hộp biên này một khi quá trình di dời DevOps hoàn tất
[Monolith cũ] --> [Microservice mới]Bây giờ bạn đã quen thuộc với các bao bọc cú pháp toàn cục, khai báo thành phần và các tham số mũi tên định hướng của PlantUML, bạn hoàn toàn sẵn sàng để bắt đầu xây dựng các hình dạng hệ thống nâng cao. Tiến tới trang tiếp theo để mở khóa bộ sưu tập của chúng tôi vềSơ đồ kiến trúc & Thiết kế cấp cao!