Hướng dẫn cú pháp sơ đồ tuần tự Mermaid.js

Sơ đồ tuần tự là gì?

Một Sơ đồ tuần tự là một sơ đồ hành vi thiết yếu sơ đồ UML được thiết kế để trực quan hóa luồng theo thứ tự thời gian của các tin nhắn, lời gọi hàm và dữ liệu truyền tải giữa các thực thể hệ thống khác nhau theo một dòng thời gian tuyến tính. Được công nhận là một loại sơ đồ UML cốt lõi,loại sơ đồ UML, nó mô tả các tương tác tại thời điểm chạy bằng cách xếp các thành phần hệ thống dọc theo trục X như các đường đời dọc và theo dõi các giao tiếp tin nhắn dọc theo trục Y. Bản vẽ này vô cùng quý giá đối với các nhà phát triển khi gỡ lỗi các thao tác trao đổi API phân tán, các đường dẫn điều phối microservice hoặc các luồng xác thực người dùng thời gian thực.

Với Mermaid.js, bạn có thể viết mã cho các quy trình thời gian phức tạp bằng cấu trúc văn bản trực quan. Bộ xử lý tự động xử lý khoảng cách dọc, quản lý căn chỉnh các mũi tên tin nhắn và vẽ các khối kích hoạt tại thời điểm chạy một cách sạch sẽ trên bảng vẽ của bạn.

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ơ đồ tuần tự UML chính xác, dễ đọc, bạn phải thành thạo việc khai báo người tham gia, các biến thể mũi tên tin nhắn, các đường đời rõ ràng và các cấu trúc khối điều kiện.

1. Khai báo người tham gia và người dùng

Bạn khai báo một thực thể hệ thống tiêu chuẩn bằng cách sử dụng từ khóa participant từ khóa. Nếu thực thể đại diện cho người dùng cuối hoặc một người vận hành bên ngoài, hãy sử dụng từ khóa actor để hiển thị biểu tượng hình người đơn giản trên bảng vẽ:

sequenceDiagram
    actor Client
    participant API as Gateway Router

Mẹo chuyên gia: Sử dụng từ khóa as để ánh xạ các tên thành phần dài thành các biệt danh nội bộ ngắn gọn, giúp các đoạn mã tin nhắn của bạn ngắn gọn và dễ đọc.

2. Định dạng mũi tên tin nhắn

Loại đường và đầu mũi tên bạn sử dụng sẽ xác định phong cách giao tiếp giữa các thành phần hệ thống của bạn:

• ->> **Gọi đồng bộ:** Một đường liền với đầu mũi tên đầy. Đại diện cho một yêu cầu chặn, chờ hoàn thành thực thi.
• --> **Đường phản hồi:** Một đường gạch nối với đầu mũi tên hở. Được dùng để trả về dữ liệu hoặc các mã xác nhận.
• -> **Gọi bất đồng bộ:** Một đường liền với đầu mũi tên hở. Chỉ ra một tin nhắn hoặc phát sóng sự kiện không chặn.

sequenceDiagram
    App->>Server: Yêu cầu dữ liệu
    Server-->App: Phản hồi 200 OK

3. Quản lý thanh kích hoạt luồng sống

Để hiển thị chính xác thời điểm một thành phần hệ thống đang thực thi nhiệm vụ hoặc chiếm dụng bộ nhớ luồng, hãy sử dụng lệnhactivate và deactivate để thực hiện. Thay vào đó, bạn có thể thêm dấu cộng (+) hoặc dấu trừ (-) trực tiếp vào mục tiêu tin nhắn như một cách nhanh chóng để hiển thị trực quan:

sequenceDiagram
    Client->>+Server: Xử lý Dữ liệu
    %% Server hiện đang được hiển thị trực quan là hoạt động
    Server-->-Client: Trả về Kết quả

4. Cấu trúc các điều kiện và lựa chọn thay thế (Alt, Opt, Loop)

Để xử lý logic chạy điều kiện nhánh, đánh giá token hoặc thử lại yêu cầu lặp lại, hãy bao bọc các đoạn mã tin nhắn bên trong các khối chuẩn:

• alt / else — Đánh giá các nhánh điều kiện (giống như khối mã if/else).
• opt — Xác định một bước tùy chọn chỉ thực thi khi đáp ứng các tiêu chí cụ thể.
• vòng lặp— Lặp lại một chuỗi thực thi cho đến khi điều kiện được thỏa mãn.

sequenceDiagram
    vòng lặp Mỗi 30 giây
        Client->>Server: Ping nhịp tim
    end

Các thực hành tốt nhất cho các dòng thời gian chuỗi rõ ràng

• Giữ các đường sống không bị rối:Tránh liệt kê hàng chục sinh thể vi mô dọc theo trục X. Nếu một quy trình tương tác với các lớp trợ giúp nhỏ, hãy trừu tượng chúng phía sau ranh giới hệ thống cấp cao như[Auth Worker] hoặc [Cache Pool].
• Gắn nhãn mã trạng thái một cách rõ ràng: Khi viết các phản hồi trả về (-->), đừng chỉ viết “Trả về Dữ liệu”. Gắn nhãn cho đường đi bằng các mã trạng thái HTTP rõ ràng hoặc loại sự kiện (ví dụ như"201 Tạo thành công (JWT Token)") để cung cấp cho các kỹ sư bối cảnh chính xác.
• Thực hiện ghi chú cho các phép tính phức tạp: Sử dụng lệnhNote over, Note left of, hoặc Note right of để ghi chú cho các thao tác không trực quan, như các bước mã hóa nội bộ hoặc băm dữ liệu cơ sở dữ liệu.

Các ví dụ về sơ đồ chuỗi Mermaid.js trong thế giới thực

Ví dụ 1: Luồng trao đổi token OAuth2 bảo mật (Khối kích hoạt và khối thay thế)

Bản thiết kế chức năng này mô phỏng một chuỗi đăng nhập người dùng an toàn. Nó minh họa cách kết hợp các nhân vật con người, các đường sống hệ thống rõ ràng, và các đường đi xác thực phức tạp bằng cách sử dụng khối alt/else.

sequenceDiagram
    actor User as Người dùng cuối
    participant App as Khách hàng ứng dụng di động
    participant Auth as Nhà cung cấp xác thực Auth0

    User->>+App: Nhấn "Đăng nhập bằng OAuth"
    App->>+Auth: Chuyển hướng với client_id & scope
    Auth-->>User: Hiển thị giao diện đăng nhập
    User->>Auth: Gửi thông tin đăng nhập
    
    Auth->>Auth: Xác minh mã băm mật khẩu
    
    alt Thông tin đăng nhập hợp lệ
        Auth-->>App: Chuyển hướng 302 với mã xác thực
        App->>Auth: Trao đổi mã để nhận mã truy cập
        Auth-->>-App: Trả về token JWT (IdToken)
        App-->>User: Hiển thị trang chủ tài khoản người dùng
    else Thông tin đăng nhập không hợp lệ
        Auth-->>App: Trả về lỗi 401 Không được ủy quyền
        App-->>-User: Hiển thị thông báo "Tên người dùng/Mật khẩu không đúng"
    end

Phân tích cú pháp: Dòng thời gian này theo dõi quá trình trao đổi giữa nhiều bên. Các alt / else khối chứa này minh họa rõ ràng các đường đi xác thực nhị phân, đảm bảo các trạng thái lỗi được ghi chép đầy đủ cùng với đường đi thành công.

Ví dụ 2: Thanh toán kho hàng đơn hàng phân tán (Quy trình song song và Ghi chú)

Bản thiết kế hệ thống nâng cao này mô tả đường dẫn thanh toán thương mại điện tử doanh nghiệp. Nó sử dụng các khối song song (par) để hiển thị các trình tự gửi API đồng thời và xử lý các ghi chú khóa cơ sở dữ liệu trên toàn bộ kiến trúc.

sequenceDiagram
    participant Web as Giao diện người dùng web
    participant Ord as Bộ điều phối đơn hàng
    participant Inv as Dịch vụ kho hàng
    participant Pay as Cổng thanh toán

    Web->>+Ord: Gửi yêu cầu thanh toán
    Note over Ord: Xác minh khả năng tồn kho sản phẩm
    
    par Gửi các lời gọi API đồng thời
        Ord->>+Inv: Khóa các sản phẩm kho
        Inv-->-Ord: Kho hàng đã được giữ (Tồn kho bị khóa)
    and
        Ord->>+Pay: Xác nhận thanh toán thẻ tín dụng
        Pay-->-Ord: Ghi nhận thành công (Giao dịch đã được thanh toán)
    end
    
    opt Quy trình phân bổ thất bại
        Note right of Ord: Thực hiện saga hoàn tác nếu bất kỳ lời gọi nào thất bại
    end
    
    Ord-->-Web: 200 Thành công - Đã xác nhận thanh toán

Phân tích cú pháp: Khối par / and khối chứa này hướng dẫn động cơ nhóm các thao tác song song lại với nhau, ghi lại các thao tác nền đồng thời. Các thẻ Note over và Note right of sẽ chèn các giải thích kỹ thuật tại thời điểm chạy trực tiếp vào lưới bảng vẽ, giúp các đội hiểu rõ các giao dịch nền như khóa dữ liệu và saga hoàn tác mà không làm rối các mũi tên tin nhắn chính.