Hướng dẫn cú pháp sơ đồ trạng thái Mermaid.js

Sơ đồ trạng thái là gì?

Một Sơ đồ trạng thái (cũng được gọi là sơ đồ trạng thái) là một sơ đồ hành vi sơ đồ UML mô hình hóa vòng đời hữu hạn của một đối tượng hoặc hệ thống con duy nhất. Được công nhận là một loại sơ đồ UML cốt lõi, loại sơ đồ UML, nó minh họa các điều kiện rời rạc (trạng thái) mà một thực thể có thể chiếm giữ, các sự kiện bên ngoài hoặc kích hoạt gây ra sự chuyển đổi giữa các điều kiện đó (chuyển tiếp), và các nhánh quy tắc điều kiện thay đổi các con đường thực thi. Việc ánh xạ này là thiết yếu để theo dõi vòng đời đối tượng phức tạp, chẳng hạn như tiến trình của một đơn hàng từ thực hiện đến giao hàng, chuỗi thời gian hết hạn phiên người dùng, hoặc vòng lặp công tắc phần cứng nhúng.

Với Mermaid.js, bạn có thể định nghĩa các máy trạng thái phản ứng của mình bằng sơ đồ khai báo, dựa trên văn bản. Bộ xử lý cú pháp tự động tính toán khoảng cách bố cục tối ưu, xử lý các mũi tên vòng lặp đệ quy, và điều chỉnh biên giới chứa trạng thái một cách mượt mà.

Hướng dẫn cú pháp cốt lõi: Các thành phần và cấu trúc

Để thiết kế một sơ đồ trạng thái UML chính xác, tuân thủ chuẩn trong Mermaid, bạn phải thành thạo các dấu hiệu vào/ra, chuỗi chuyển tiếp, nhúng hợp thành và các khối lựa chọn điều kiện.

1. Xác định trạng thái vào, ra và trạng thái chuẩn

Bạn khởi tạo bảng trạng thái trên dòng đầu tiên bằng cách sử dụng từ khóa stateDiagram-v2 từ khóa. Vòng đời yêu cầu các điểm bắt đầu và kết thúc rõ ràng, được biểu diễn bằng ký hiệu hình tròn đầy ([*]):

• Trạng thái ban đầu (vào): [*] --> TênTrạngThái (Đánh dấu nơi vòng đời bắt đầu).
• Trạng thái kết thúc (ra): TênTrạngThái --> [*] (Đánh dấu nơi vòng đời kết thúc).

stateDiagram-v2
    [*] --> NgưngChờ
    NgưngChờ --> [*]

2. Cấu hình các bộ kích hoạt chuyển tiếp và nhãn sự kiện

Để ánh xạ một thay đổi trạng thái, kết nối các token trạng thái đã định nghĩa của bạn bằng một đường mũi tên tiêu chuẩn (“-->). Để ghi chú chính xác sự kiện, phản hồi API hoặc nhấp chuột nút gây ra chuyển tiếp này, thêm dấu hai chấm (“:) theo sau là chuỗi văn bản mô tả của bạn:

stateDiagram-v2
    Active --> Suspended : PaymentFailed
    Suspended --> Active : InvoiceSettled

3. Triển khai các khối lựa chọn điều kiện

Để xử lý các vòng lặp đánh giá nhánh, sử dụng<<choice>>kiểu dáng. Điều này tạo ra một hình thoi rõ ràng trên bảng vẽ, chia một đường chuyển tiếp đầu vào duy nhất thành nhiều đường chuyển tiếp đầu ra khác nhau dựa trên các kiểm tra logic tại thời điểm chạy:

stateDiagram-v2
    state check_status <<choice>>
    [*] --> check_status
    check_status --> PremiumUser : if balance >= 100
    check_status --> StandardUser : if balance < 100

4. Cấu trúc các trạng thái hợp (lồng ghép)

Khi mô hình hóa một hệ thống phức tạp, một trạng thái cấp cao duy nhất có thể chứa vòng đời nội bộ độc lập của chính nó. Bạn có thể tạo bố cục trạng thái con lồng ghép bằng cách xác định một trạng thái cha theo sau là một khối thân được bao quanh bởi dấu ngoặc nhọn:

stateDiagram-v2
    state OrderProcessing {
        [*] --> Packaging
        Packaging --> Labeling
    }

Các thực hành tốt nhất cho bố cục máy trạng thái sạch sẽ

• Giữ các token trạng thái ngắn gọn: Sử dụng các chuỗi văn bản CamelCase ngắn gọn cho các token trạng thái nội bộ của bạn (ví dụ,AwaitingRefund). Nếu bạn cần một tiêu đề mô tả dài trên bảng vẽ, hãy sử dụngstate "Khối văn bản mô tả" như Token cú pháp để tạo một biệt danh rõ ràng.
• Thiết lập một điểm vào duy nhất: Luôn bắt đầu sơ đồ của bạn từ một điểm duy nhất [*] nút. Việc có nhiều điểm khởi đầu có thể gây nhầm lẫn cho người dùng khi cố gắng theo dõi đường dẫn khởi tạo gốc của hệ thống.
• Luôn sử dụng stateDiagram-v2: Luôn chọn stateDiagram-v2 từ khóa thay vì stateDiagram cờ. Bộ xử lý hiển thị v2 sử dụng thuật toán bố cục được cập nhật, mang lại định tuyến đường nét sạch sẽ hơn và căn chỉnh hộp lồng nhau tốt hơn.

Các ví dụ sơ đồ trạng thái Mermaid.js trong thế giới thực

Ví dụ 1: Chu kỳ vòng đời giao dịch ví kỹ thuật số (nhánh lựa chọn và vòng lặp lỗi)

Bản thiết kế chức năng này mô phỏng chu kỳ vòng đời của một giao dịch thanh toán kỹ thuật số, cho thấy cách giao dịch di chuyển từ điểm gửi ban đầu thông qua nhánh kiểm tra gian lận đến các trạng thái sổ cái cuối cùng.

stateDiagram-v2
    state fraud_check <<choice>>

    [*] --> TransSubmitted
    TransSubmitted --> fraud_check : ExecuteRiskAssessment

    fraud_check --> TransApproved : Điểm rủi ro Thấp
    fraud_check --> TransFlagged : Điểm rủi ro Cao
    
    TransFlagged --> TransApproved : Ghi đè thủ công của quản lý
    TransFlagged --> TransDeclined : Hết thời gian bảo mật
    
    TransApproved --> SettlementPending : Ghi vào sổ cái
    SettlementPending --> TransCompleted : Thành công thanh toán ngân hàng
    
    TransDeclined --> [*]
    TransCompleted --> [*]

Phân tích cú pháp: Quy trình này sử dụng một <<choice>> khối để đánh giá điểm an toàn ngay từ đầu. Giao dịch chuyển tiếp theo các hành trình riêng biệt dựa trên các điểm số này, với tên sự kiện rõ ràng (như ExecuteRiskAssessment) được ghi chú trực tiếp trên các mũi tên chuyển tiếp.

Ví dụ 2: Dòng chảy hoàn thành đơn hàng thương mại điện tử (hệ thống lồng ghép phức hợp)

Bản thiết kế doanh nghiệp nâng cao này mô tả toàn bộ chu kỳ vòng đời vận chuyển và quản lý đơn hàng, sử dụng các khối hợp thành lồng ghép để hiển thị các thao tác nội bộ đang diễn ra trong giai đoạn hoàn thành.

stateDiagram-v2
    [*] --> OrderPlaced
    
    OrderPlaced --> InFulfillment : Thanh toán đã được thu
    
    state InFulfillment {
        [*] --> ItemPicking
        ItemPicking --> QualityAudit : Đã lấy lô hàng
        QualityAudit --> SecureBoxPacking : Kiểm tra đạt
        SecureBoxPacking --> CarrierManifest Generated : Đã in nhãn
    }
    
    InFulfillment --> Shipped : Giao tiếp với hãng vận chuyển
    Shipped --> Delivered : Xác nhận đang giao hàng
    
    Delivered --> [*]

Phân tích cú pháp: Bằng cách bao bọc các bước bên trong state InFulfillment {...} khối thân, bạn tạo ra một ranh giới cấu trúc rõ ràng trên bảng vẽ. Bộ xử lý coi khối này là một trạng thái cha hợp nhất duy nhất khi hiển thị các bước công việc nội bộ theo thứ tự, giúp việc điều hướng các vòng đời phức tạp nhiều lớp trở nên dễ dàng hơn.