Hướng dẫn cú pháp sơ đồ luồng Mermaid.js

Sơ đồ luồng là gì?

Một Sơ đồ luồnglà một bản đồ hành vi nền tảng, giúp trực quan hóa quy trình vận hành từng bước, quy trình thuật toán hoặc logic kinh doanh tuần tự. Bằng cách biểu diễn các hành động hệ thống dưới dạng các hình học riêng biệt và vẽ luồng điều khiển bằng các mũi tên hướng, sơ đồ luồng giúp các kỹ sư phần mềm và kiến trúc sư hệ thống dễ dàng theo dõi các đường đi thực thi điều kiện, tách biệt các khối điểm lỗi duy nhất, và phân tích các vòng lặp logic hệ thống trước khi viết mã backend thực tế.

Với Mermaid.js, bạn không cần mất hàng giờ kéo thả các hộp, điều chỉnh chi tiết các đường lưới hay tính toán lại các biến khoảng cách lề. Bộ động lực bố cục sẽ tính toán tọa độ các nút một cách động từ các đoạn mã khai báo thô của bạn, giúp bạn tập trung hoàn toàn vào logic cốt lõi của hệ thống.

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ơ đồ luồng tinh tế, dễ đọc cao trong Mermaid, bạn phải thành thạo các chỉ báo hướng khung, các bao bọc hình học cho nút, các biến dây nối và các cấu trúc đồ thị con.

1. Thiết lập hướng khung

Hướng của sơ đồ luồng của bạn được xác định trực tiếp ở dòng đầu tiên thông qua cặp từ khóa được áp dụng cho graph hoặc flowchartbọc. Bạn có thể kiểm soát hướng mở rộng hình ảnh của bố cục bằng bốn khóa định hướng chính:

• flowchart TD (Từ trên xuống dưới / Hướng thẳng đứng)
• flowchart BU (Từ dưới lên trên)
• flowchart LR (Từ trái sang phải / Hướng nằm ngang)
• flowchart RL (Từ phải sang trái)

2. Tùy chỉnh hình học nút (hình dạng)

Mặc định, một khai báo ID đơn giản sẽ hiển thị dưới dạng hộp chữ nhật sắc nét. Để làm cho sơ đồ của bạn dễ đọc hơn, hãy sử dụng các dấu ngoặc bao bọc chuyên biệt của Mermaid để đưa ngay lập tức ngữ cảnh hình ảnh vào các bước quy trình khác nhau. Mỗi khối khai báo phải được đi trước bởi một ký hiệu bố cục định hướng để được phân tích đúng cách:

• Cạnh tròn: id(Văn bản) — Đại diện cho một bước xử lý chung.
• Hình dạng sân vận động/Vỏ thuốc: id([Văn bản]) — Biểu tượng tiêu chuẩn cho các mốc giới hạn bắt đầu và kết thúc.
• Thủ tục con/Quy trình được định nghĩa trước: id[[Văn bản]] — Đại diện cho một thủ tục hệ thống được đóng gói hoặc mã kịch bản lớp bên ngoài.
• Hình trụ/Cơ sở dữ liệu: id[(Văn bản)] — Đại diện cho tính bền vững cơ sở dữ liệu, bộ nhớ đệm hoặc kho dữ liệu.
• Hình thoi/Chim tháp quyết định: id{Văn bản} — Đại diện cho các công tắc điều kiện, nhánh if/else hoặc các điểm đánh giá.
• Hình bình hành: id[/Văn bản/] hoặc id[Văn bản] — Vẽ các biên giới xiên để đại diện cho dữ liệu đầu vào/đầu ra (I/O) rõ ràng.

biểu đồ luồng TD
    start_node([Bắt đầu thực thi])
    query_db[(Thực thể PostgreSQL)]
    validate_check{Được ủy quyền chưa?}

3. Quy tắc nối dây và nhãn nhúng

Bạn có thể điều chỉnh các đường nối để biểu diễn các mối quan hệ cấu trúc khác nhau và các phong cách giao tiếp. Để giữ cho biểu đồ của bạn gọn gàng, hãy chèn các nhãn mô tả trực tiếp lên các đường nối:

biểu đồ luồng TD
    %% Mũi tên nối tiêu chuẩn với nhãn văn bản
    A --> |"Dữ liệu JSON"| B

    %% Đường chấm chấm/đồng bộ với nhãn văn bản
    B -.-> |"Sự kiện bất đồng bộ"| C

    %% Đường đậm với nhãn văn bản
    C ==> |"Ghi dữ liệu quan trọng"| D

4. Cách ly theo mô-đun thông qua các đồ thị con

Để thiết lập các biên giới mạng sạch sẽ, nhóm các dịch vụ vi mô hoặc tách biệt trách nhiệm của nhóm, hãy nhóm các phần tử của bạn bên trong các bao bọc cấu trúcđồ thị con bao bọc. Bạn định nghĩa một đồ thị con bằng cách gán cho nó một ID nội bộ, một tiêu đề hiển thị tùy chọn, và đóng nó bằng mộtkết thúcnhãn:

biểu đồ luồng TD
    subgraph auth_sub["Biên giới bảo mật"]
        gateway[API Gateway] --> auth_worker(Trình xác thực token)
    end

Các thực hành tốt nhất cho sơ đồ luồng sạch

• Tách rời bố cục theo chiều ngang: Đối với các luồng kỹ thuật dài và nhiều bước, hãy chọn một biểu đồ luồng LRhướng. Điều này mở rộng tốt hơn nhiều trên các màn hình rộng tiêu chuẩn ở chế độ nằm ngang so với bố cục dọc dài.
• Tách biệt các vòng lặp phức tạp: Nếu một quy trình có vòng lặp lặp lại nặng, hãy đánh dấu rõ ràng kết nối ngược (ví dụ như retry --> |"Thử lại lần nữa"| start) để ngăn người đọc nhầm lẫn vòng lặp với đường đi thông thường.
• Tránh trộn lẫn các loại sơ đồ: Duy trì sử dụng biểu đồ luồng từ khóa thay vì graphcờ khi vẽ bản đồ phức tạp. Bộ xử lý biểu đồ luồngsử dụng thuật toán bố cục cập nhật hỗ trợ các kết hợp mũi tên nâng cao và định tuyến đường đi sạch hơn.

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

Ví dụ 1: Mạng thu thập dữ liệu dựa trên sự kiện của microservice (kiến trúc trái sang phải)

Bản thiết kế chức năng này mô hình hóa một dịch vụ thu thập dữ liệu web telemetry. Nó minh họa cách kết hợp đầu vào dữ liệu, hình thoi quyết định và các hình dạng cơ sở dữ liệu đám mây trên một mặt phẳng ngang rõ ràng.

biểu đồ luồng LR
    %% Xác định các nút thành phần với hình dạng hình học rõ ràng
    init([Webhook được kích hoạt]) --> input_io[/Chụp yêu cầu HTTP/]
    input_io --> auth_check{Xác thực token}
    
    auth_check --> |"Token không hợp lệ"| err_stop([Trả về 401 Không được ủy quyền])
    auth_check --> |"JWT hợp lệ"| write_queue[[Đăng tải lên hàng đợi Kafka]]
    
    write_queue --> worker_proc(Quá trình tiêu thụ)
    worker_proc --> db_store[(Cụm TimescaleDB)]
    db_store --> term([Luồng đã kết thúc])

    %% Ghi đè phong cách tùy chỉnh nhanh
    style auth_check fill:#fff3cd,stroke:#ffc107,stroke-width:2px
    style err_stop fill:#f8d7da,stroke:#dc3545,stroke-width:1px

Phân tích cú pháp: Sơ đồ này chảy trơn tru từ trái sang phải. Bước xác thực sử dụng hình thoi quyết định màu vàng (auth_check{Xác thực Token}), giúp chia tách đường thực thi một cách rõ ràng thành hai kết quả khác nhau. Các kho lưu trữ dữ liệu được nhận diện ngay lập tức nhờ hình trụ cơ sở dữ liệu tùy chỉnh ([(Cluster TimescaleDB)]) và các đầu vào hình thang.

Ví dụ 2: Bộ động cơ đăng ký người dùng đa tầng doanh nghiệp (Thẳng đứng với các sơ đồ con lồng ghép)

Bản thiết kế doanh nghiệp nâng cao này mô tả đường dẫn đăng ký ứng dụng. Nó sắp xếp các bước theo chiều dọc qua ba sơ đồ con cấu trúc riêng biệt để đại diện cho các lớp kiến trúc khác nhau.

flowchart TD
    subgraph Client_Tier["Lớp giao diện người dùng trình bày"]
        app[UI Ứng dụng di động]
        web[Frontend SPA Web]
    end

    subgraph Service_Tier["Bộ định tuyến cổng cốt lõi"]
        proxy[[Ngược proxy Nginx Ingress]]
        auth_svc(Worker Dịch vụ Xác thực)
    end

    subgraph Persistence_Tier["Trung tâm dữ liệu được bảo mật"]
        main_db[(Cơ sở dữ liệu chính Tài khoản người dùng)]
        cache_node[(Bộ đệm phiên Redis)]
    end

    %% Xác định các đường truyền thông giữa các lớp hệ thống con
    app -- "Yêu cầu HTTPS" --> proxy
    web -- "Yêu cầu HTTPS" --> proxy
    
    proxy --> |"Định tuyến /v1/auth"| auth_svc
    
    auth_svc --> |"Xác minh Phiên"| cache_node
    auth_svc --> |"Ghi tài khoản"| main_db

Phân tích cú pháp: Chỉ báo định hướng từ trên xuống (flowchart TD), buộc động cơ bố cục xếp các thành phần một cách sạch sẽ từ trên xuống dưới. Các khối giới hạn nhóm các thành phần liên quan vào các lớp riêng biệt (Khách hàng, Dịch vụ và Dữ liệu), mang lại cho kiến trúc tổng thể cảm giác trực quan và có cấu trúc cao.