Vượt qua hình ảnh tĩnh: Giải phóng sức mạnh của sơ đồ dưới dạng mã với Mermaid và công cụ AI

Khủng hoảng về tài liệu

Mọi đội kỹ thuật đều biết nỗi đau này. Bạn dành hàng tuần để thiết kế một kiến trúc vi dịch vụ tuyệt đẹp, tỉ mỉ tạo ra các sơ đồ Visio gây ấn tượng với các bên liên quan. Sáu tháng sau, hệ thống đã thay đổi—các dịch vụ mới được thêm vào, cơ sở dữ liệu được di chuyển, các điểm cuối API bị loại bỏ—nhưng sơ đồ vẫn đóng băng trong thời gian. Đó là một di tích. Thậm chí là một lời nói dối.

Đây là “sự mục nát của tài liệu” (doc-rot), và đó là kẻ giết người thầm lặng đối với năng suất kỹ thuật. Khi sơ đồ nói dối, các nhà phát triển sẽ bỏ qua chúng. Khi các nhà phát triển bỏ qua tài liệu, kiến thức bộ tộc sẽ thống trị. Khi người duy nhất hiểu hệ thống rời đi, bạn sẽ còn lại một cơ sở mã phức tạp và không có bản đồ.

Sơ đồ dưới dạng mã (DaC) là giải pháp. Và cốt lõi của nó là Mermaid, công cụ tạo sơ đồ dựa trên JavaScript biến văn bản thuần túy thành hình ảnh đẹp mắt.

Triết lý cốt lõi: Đối xử với sơ đồ như phần mềm

Sự thay đổi cơ bản của Sơ đồ dưới dạng mã là đối xử với sơ đồ của bạn với cùng sự nghiêm ngặt như mã ứng dụng của bạn. Điều này có nghĩa là:

1. Kiểm soát phiên bản là tiêu chuẩn

Khi sơ đồ của bạn là một .mermaid file, nó tồn tại trong kho lưu trữ Git của bạn bên cạnh mã nguồn. Mọi thay đổi đều được theo dõi. Bạn có thể git blame để xem ai đã thêm dịch vụ mới đó, git diff để xem xét các thay đổi trước khi hợp nhất, và quay lại bất kỳ trạng thái nào trước đó.

gitGraph
    commit id: "Kiến trúc ban đầu"
    commit id: "Thêm dịch vụ người dùng"
    branch feature/order-service
    commit id: "Dịch vụ đơn hàng v1"
    commit id: "Thêm cổng thanh toán"
    checkout main
    merge feature/order-service
    commit id: "Cập nhật cổng API"

Ví dụ: Trực quan hóa lịch sử Git của chính sơ đồ của bạn bằng cú pháp Git Graph của Mermaid

2. Đánh giá mã cho sơ đồ

Yêu cầu kéo (pull requests) không còn chỉ dành cho mã nữa. Khi một nhà phát triển đề xuất một dịch vụ mới hoặc thay đổi luồng dữ liệu, thay đổi đó sẽ xuất hiện dưới dạng diff dễ đọc trong PR. Người xem xét có thể bình luận trực tiếp vào sơ đồ, đảm bảo các quyết định kiến trúc được thảo luận và phê duyệt trước khi được hợp nhất.

3. Tích hợp vào quy trình CI/CD

Sơ đồ của bạn có thể được tự động tạo và xác thực trong quy trình của bạn. Hãy tưởng tượng một hành động GitHub thực hiện:

• Biến đổi tất cả các sơ đồ Mermaid thành PNG/SVG

• Tải chúng lên trang tài liệu của bạn

• Báo lỗi xây dựng nếu phát hiện cú pháp Mermaid không hợp lệ

flowchart LR
    A[Phát triển viên đẩy mã] --> B[CI Pipeline chạy]
    B --> C[Chạy kiểm thử]
    B --> D[Hiển thị biểu đồ Mermaid]
    D --> E{Cú pháp hợp lệ?}
    E -->|Có| F[Đẩy lên tài liệu]
    E -->|Không| G[Phát sinh lỗi xây dựng & Thông báo cho nhóm]
    F --> H[Triển khai ứng dụng]
    G --> I[Phát triển viên sửa cú pháp]
    I --> A

Ví dụ: Quy trình CI/CD để xác thực và triển khai biểu đồ

Mermaid trong thực tế: Các ví dụ thực tế

Hãy cùng khám phá các loại biểu đồ mà Mermaid hỗ trợ thông qua các ví dụ thực tế và thiết thực.

Ví dụ 1: Kiến trúc vi dịch vụ (Sơ đồ luồng)

Đây là trường hợp sử dụng phổ biến nhất—trực quan hóa cách các dịch vụ của bạn giao tiếp với nhau.

flowchart TB
    subgraph "Lớp khách hàng"
        MobileApp[Ứng dụng di động]
        WebApp[Ứng dụng web]
    end

    subgraph "API Gateway"
        Gateway[Cổng API]
    end

    subgraph "Vi dịch vụ"
        UserSvc[Dịch vụ người dùng]
        OrderSvc[Dịch vụ đơn hàng]
        ProductSvc[Dịch vụ sản phẩm]
        PaymentSvc[Dịch vụ thanh toán]
    end

    subgraph "Lớp dữ liệu"
        UserDB[(Cơ sở dữ liệu người dùng)]
        OrderDB[(Cơ sở dữ liệu đơn hàng)]
        ProductDB[(Cơ sở dữ liệu sản phẩm)]
        Redis[(Bộ nhớ đệm Redis)]
    end

    subgraph "Dịch vụ bên ngoài"
        Stripe[Thanh toán Stripe]
        EmailAPI[API Email]
    end

    MobileApp --> Gateway
    WebApp --> Gateway
    Gateway --> UserSvc
    Gateway --> OrderSvc
    Gateway --> ProductSvc
    Gateway --> PaymentSvc

    UserSvc --> UserDB
    UserSvc --> Redis
    OrderSvc --> OrderDB
    OrderSvc --> Redis
    ProductSvc --> ProductDB
    ProductSvc --> Redis

    PaymentSvc --> Stripe
    OrderSvc --> EmailAPI
    PaymentSvc --> EmailAPI

Ví dụ: Kiến trúc vi dịch vụ hoàn chỉnh với bộ nhớ đệm, cơ sở dữ liệu và các phụ thuộc bên ngoài

Ví dụ 2: Luồng xác thực người dùng (Biểu đồ trình tự)

Biểu đồ trình tự rất hoàn hảo để tài liệu hóa các tương tác phức tạp giữa các dịch vụ.

sequenceDiagram
    autonumber
    participant Người dùng
    participant Giao diện trước
    participant AuthSvc as Dịch vụ xác thực
    participant UserDB as Cơ sở dữ liệu người dùng
    participant Cache as Bộ nhớ đệm Redis
    participant EmailSvc as Dịch vụ Email

    Người dùng->>Giao diện trước: Nhập thông tin đăng nhập
    Giao diện trước->>AuthSvc: POST /login (email, mật khẩu)
    AuthSvc->>UserDB: Truy vấn người dùng theo email
    UserDB-->>AuthSvc: Trả về mật khẩu đã mã hóa & dữ liệu người dùng
    AuthSvc->>AuthSvc: Xác thực mật khẩu bằng bcrypt
    
    alt Thông tin hợp lệ
        AuthSvc->>AuthSvc: Tạo mã JWT
        AuthSvc->>Cache: Lưu phiên (khóa: user_id, thời hạn: 1 giờ)
        AuthSvc-->>Giao diện trước: 200 OK + mã JWT
        Giao diện trước-->>Người dùng: Chuyển hướng đến bảng điều khiển
    else Thông tin không hợp lệ
        AuthSvc->>EmailSvc: Kích hoạt cảnh báo đăng nhập thất bại
        AuthSvc-->>Giao diện trước: 401 Không được phép
        Giao diện trước-->>Người dùng: Hiển thị thông báo lỗi
    end
    
    Ghi chú trên AuthSvc,EmailSvc: Sau 5 lần thử thất bại, khóa tài khoản trong 15 phút

Ví dụ: Luồng xác thực chi tiết hiển thị các đường dẫn thành công và thất bại, bao gồm các tác dụng phụ như bộ nhớ đệm và cảnh báo

Ví dụ 3: Cơ sở hạ tầng đám mây trên AWS (Biểu đồ lớp)

Biểu đồ lớp không chỉ dành cho mã—chúng có thể mô hình hóa các tài nguyên đám mây và mối quan hệ giữa chúng.

classDiagram
    class VPC {
        +string cidr_block
        +string region
        +createSubnet()
        +deleteSubnet()
    }

    class Subnet {
        +string availability_zone
        +string cidr_block
        +boolean is_public
        +attachRouteTable()
    }

    class EC2Instance {
        +string instance_type
        +string ami_id
        +int storage_gb
        +start()
        +stop()
        +reboot()
    }

    class RDSDatabase {
        +string engine
        +string version
        +int storage_gb
        +boolean multi_az
        +takeSnapshot()
        +restoreFromSnapshot()
    }

    class S3Bucket {
        +string bucket_name
        +string region
        +boolean versioning_enabled
        +uploadFile()
        +downloadFile()
    }

    class IAMRole {
        +string role_name
        +string policy_document
        +attachPolicy()
        +detachPolicy()
    }

    VPC "1" --> "*" Subnet
    Subnet "1" --> "*" EC2Instance
    Subnet "1" --> "0..1" RDSDatabase
    VPC "1" --> "0..*" S3Bucket
    EC2Instance --> IAMRole
    RDSDatabase --> IAMRole

Ví dụ: Mô hình hóa cơ sở hạ tầng AWS dưới dạng các lớp với thuộc tính và phương thức, hữu ích cho việc tài liệu hóa và lập kế hoạch Cơ sở hạ tầng dưới dạng Mã

Ví dụ 4: Xử lý đơn hàng Thương mại điện tử (Biểu đồ trạng thái)

Biểu đồ trạng thái xuất sắc trong việc hiển thị cách các thực thể chuyển đổi qua các trạng thái khác nhau.

stateDiagram-v2
    [*] --> Giỏ hàng: Người dùng thêm sản phẩm
    Giỏ hàng --> Thanh toán: Người dùng chuyển đến trang thanh toán
    
    Thanh toán --> Chờ thanh toán: Người dùng gửi đơn hàng
    Chờ thanh toán --> Đang xử lý thanh toán: Khởi tạo cổng thanh toán
    
    Đang xử lý thanh toán --> Đã thanh toán: Thanh toán thành công
    Đang xử lý thanh toán --> Thanh toán thất bại: Thanh toán bị từ chối
    
    Thanh toán thất bại --> Thanh toán: Người dùng thử lại thanh toán
    Thanh toán thất bại --> [*]: Người dùng bỏ giỏ hàng
    
    Đã thanh toán --> Đơn hàng xác nhận: Gửi email xác nhận
    Đơn hàng xác nhận --> Đang chuẩn bị: Phân công cho kho
    
    Đang chuẩn bị --> Đã giao hàng: Giao cho đơn vị vận chuyển
    Đã giao hàng --> Đang vận chuyển: Đơn vị vận chuyển nhận hàng
    
    Đang vận chuyển --> Đã giao: Giao hàng thành công
    Đã giao --> Nhắc đánh giá: Yêu cầu người dùng đánh giá
    
    Nhắc đánh giá --> [*]: Người dùng gửi đánh giá
    Đã giao --> Yêu cầu hoàn tiền: Người dùng khởi tạo yêu cầu hoàn tiền
    
    Yêu cầu hoàn tiền --> Hoàn tiền được phê duyệt: Bộ phận hỗ trợ phê duyệt
    Hoàn tiền được phê duyệt --> Đã xử lý hoàn tiền: Tiền được hoàn lại
    Đã xử lý hoàn tiền --> [*]: Đơn hàng đóng
    
    state "Kiểm tra gian lận rủi ro cao" as Kiểm tra gian lận {
        [*] --> Kiểm tra điểm
        Kiểm tra điểm --> Rủi ro thấp: Điểm < 50
        Kiểm tra điểm --> Rủi ro cao: Điểm >= 50
        Rủi ro cao --> Xem xét thủ công: Đánh dấu cho nhóm
        Xem xét thủ công --> Rủi ro thấp: Phê duyệt
        Xem xét thủ công --> Thanh toán thất bại: Từ chối
    }
    
    Chờ thanh toán --> Kiểm tra gian lận: Kích hoạt đánh giá rủi ro
    Kiểm tra gian lận --> Đang xử lý thanh toán: Rủi ro thấp

Ví dụ: Máy trạng thái đơn hàng thương mại điện tử hoàn chỉnh với trạng thái lồng nhau phát hiện gian lận

Ví dụ 5: Lập kế hoạch Sprint với GitHub Issues (Biểu đồ Git)

Biểu đồ Git có thể biểu diễn các quy trình làm việc vượt ra ngoài chính Git.

gitGraph
    commit id: "Lập kế hoạch Sprint" type: HIGHLIGHT
    
    branch sprint-1
    commit id: "Câu chuyện người dùng #101: Trang đăng nhập"
    commit id: "Câu chuyện người dùng #102: Đăng ký người dùng"
    
    branch bugfix/hotfix
    commit id: "Hotfix: Hết hạn Token xác thực"
    checkout sprint-1
    merge bugfix/hotfix
    
    commit id: "Câu chuyện người dùng #103: Đặt lại mật khẩu"
    
    checkout main
    merge sprint-1 tag: "v1.0.0"
    
    branch sprint-2
    commit id: "Tính năng #201: Giỏ hàng"
    commit id: "Tính năng #202: Quy trình thanh toán"
    
    branch experiment/ai-recommendations
    commit id: "POC: Động cơ đề xuất ML"
    
    checkout sprint-2
    commit id: "Tính năng #203: Lịch sử đơn hàng"
    
    checkout main
    merge sprint-2 tag: "v2.0.0"
    
    commit id: "Ghi chú phát hành: Hoàn thành Sprint 1 & 2"

Ví dụ: Trực quan hóa quản lý dự án, các Sprint và các nhánh tính năng dưới dạng biểu đồ Git

Cuộc cách mạng AI trong vẽ biểu đồ

Bất chấp sự tinh tế của Mermaid, cú pháp có thể là một rào cản. Ai muốn gỡ lỗi một mũi tên bị lệch hoặc một dấu ngoặc bị thiếu khi bạn đang cố gắng tài liệu hóa một hệ thống?

Đây chính là nơi các công cụ được hỗ trợ bởi AI thay đổi mọi thứ.

Tự động sửa lỗi bằng AI

Các công cụ như VPasCode (nền tảng Vẽ biểu đồ dưới dạng mã của Visual Paradigm) và Mermaid Chart đã tích hợp các mô hình AI (như Google Gemini và OpenAI) có thể:

• Tự động phát hiện lỗi cú pháp

• Sửa các biểu đồ bị lỗi chỉ với một cú nhấp chuột

• Đề xuất các cải tiến cho cấu trúc biểu đồ

Hãy cùng xem điều này hoạt động như thế nào:

Mã Mermaid bị lỗi:

flowchart LR
    A[Frontend] --> B(API Gateway
    B --> C[User Service]
    C --> D[(Database
    D --> E[Cache]

Mã đã được AI sửa:

flowchart LR
    A[Frontend] --> B(API Gateway)
    B --> C[User Service]
    C --> D[(Database)]
    D --> E[Cache]

AI nhận diện dấu ngoặc đơn và dấu ngoặc vuông bị thiếu, sau đó sửa chúng ngay lập tức.

Từ ngôn ngữ tự nhiên sang sơ đồ

Có lẽ tính năng mạnh mẽ nhất là tạo sơ đồ từ các mô tả bằng ngôn ngữ tự nhiên. Với các công cụ như OpenDocs (nền tảng tài liệu của VP), bạn chỉ cần mô tả những gì mình muốn:

“Tạo một sơ đồ luồng thể hiện người dùng đăng nhập. Nếu thông tin xác thực hợp lệ, chuyển hướng đến bảng điều khiển. Nếu không hợp lệ, hiển thị lỗi và cho phép 3 lần thử. Sau 3 lần thất bại, khóa tài khoản.”

Mermaid do AI tạo ra:

flowchart TD
    Start([Người dùng thử đăng nhập]) --> EnterCreds[Nhập Email & Mật khẩu]
    EnterCreds --> Validate{Xác thực thông tin}
    Validate -->|Hợp lệ| Dashboard[Chuyển hướng đến bảng điều khiển]
    Validate -->|Không hợp lệ| CheckAttempts{Số lần thử < 3}
    CheckAttempts -->|Có| Increment[Tăng bộ đếm số lần thử]
    Increment --> ShowError[Hiển thị thông báo lỗi]
    ShowError --> EnterCreds
    CheckAttempts -->|Không| LockAccount[Khóa tài khoản trong 15 phút]
    LockAccount --> SendAlert[Gửi email cảnh báo bảo mật]
    SendAlert --> End([Quy trình kết thúc])
    Dashboard --> End

Chuyển đổi giữa các loại sơ đồ

AI cũng có thể chuyển đổi giữa các định dạng sơ đồ khác nhau. Cần chuyển đổi sơ đồ PlantUML sang Mermaid? Các công cụ AI có thể xử lý việc đó:

Đầu vào PlantUML:

@startuml
actor User
participant "Frontend" as FE
participant "Backend" as BE
database "DB" as DB

User -> FE: Click Login
FE -> BE: POST /login
BE -> DB: SELECT user
DB --> BE: user data
BE --> FE: JWT token
FE --> User: Show Dashboard
@enduml

Mermaid đã được AI chuyển đổi:

sequenceDiagram
    actor User
    participant Frontend
    participant Backend
    participant Database
    
    User->>Frontend: Click Login
    Frontend->>Backend: POST /login
    Backend->>Database: SELECT user
    Database-->>Backend: user data
    Backend-->>Frontend: JWT token
    Frontend-->>User: Show Dashboard

Tích hợp trợ lý ảo tương tác

Một số nền tảng hiện nay cung cấp giao diện trợ lý ảo để tạo sơ đồ. Bạn có thể trò chuyện:

Người dùng: “Thêm một dịch vụ mới tên là ‘Dịch vụ Kho’ vào sơ đồ kiến trúc của tôi.”

AI: “Tôi sẽ thêm một Dịch vụ Kho được kết nối với các Dịch vụ Sản phẩm và Đơn hàng hiện có của bạn.”

Sơ đồ được cập nhật tự động

Người dùng: “Thực ra, hãy làm cho nó cũng kết nối với một cơ sở dữ liệu mới tên là ‘InventoryDB’.”

AI: “Xong. Dịch vụ Kho giờ đã kết nối với Dịch vụ Sản phẩm, Dịch vụ Đơn hàng và cơ sở dữ liệu InventoryDB mới.”

Tích hợp Sơ đồ dưới dạng Mã vào Quy trình Làm việc của Bạn

Bước 1: Bắt đầu từ những điều nhỏ bé

Đừng cố gắng vẽ sơ đồ toàn bộ hệ thống của bạn cùng một lúc. Hãy bắt đầu với một thành phần đơn lẻ—có thể là luồng xác thực của bạn hoặc một tính năng mới mà bạn đang xây dựng.

Bước 2: Nhúng vào Tài liệu

Giữ các tệp .mermaid bên cạnh tài liệu của bạn (ví dụ: trong thư mục /docs). Sử dụng các công cụ như mermaid-cli để hiển thị chúng trong quá trình xây dựng.

Bước 3: Tận dụng Động cơ Thống nhất của VPasCode

Nếu bạn làm việc trong một nhóm với sở thích đa dạng, VPasCode là vô giá. Nó hỗ trợ nhiều ngôn ngữ sơ đồ dưới dạng mã trong một nơi:

# Trong VPasCode, bạn có thể kết hợp linh hoạt:
diagrams/
  ├── architecture.mermaid
  ├── deployment.puml      # PlantUML
  ├── database-erd.mermaid
  └── workflow.d2          # Ngôn ngữ D2

Bước 4: Tự động hóa với CI/CD

Thêm một bước vào GitHub Actions hoặc GitLab CI của bạn:

- name: Hiển thị Sơ đồ Mermaid
  run: |
    for file in $(find docs -name "*.mermaid"); do
      npx @mermaid-js/mermaid-cli -i $file -o ${file%.mermaid}.png
    done

- name: Tải lên Trang Tài liệu
  run: |
    aws s3 sync docs/ s3://your-docs-bucket/

Bước 5: Xem xét trong các Yêu cầu Kéo (Pull Requests)

Quy định chính sách rằng mọi thay đổi kiến trúc đều yêu cầu cập nhật sơ đồ. Sử dụng bình luận trong PR để thảo luận các thay đổi trực quan:

Người xem xét: “Cache không lẽ không nên nằm giữa Dịch vụ Đơn hàng và Cơ sở dữ liệu? Hiện tại nó chỉ được gắn với Dịch vụ Người dùng.”

Tác giả: “Phát hiện tốt. Tôi sẽ cập nhật sơ đồ.”

Tác động thực tế: Một nghiên cứu điển hình

Hãy xem xét một công ty khởi nghiệp fintech đã áp dụng Sơ đồ dưới dạng Mã với Mermaid và VPasCode:

• Trước đây: 47 tệp Visio tĩnh, phần lớn đã cũ hơn 6 tháng. Nhân viên mới mất 3 tuần để hiểu kiến trúc.

• Sau khi áp dụng: 12 sơ đồ Mermaid, tất cả được lưu trữ trong Git, được cập nhật cùng mỗi tính năng. Nhân viên mới đã làm việc hiệu quả ngay trong tuần đầu tiên.

CTO của đội nhận xét: “Chúng tôi đã chuyển từ việc sơ đồ chỉ là một ô kiểm tra tuân thủ sang trở thành một phần sống động trong quy trình phát triển của chúng tôi. Khi tranh luận về một kiến trúc mới, chúng tôi mở trình soạn thảo Mermaid và phác thảo nó trực tiếp bằng mã. Đây là một bước ngoặt.”

Tương lai: Tài liệu liên tục

Mục tiêu tối thượng là “tài liệu liên tục”, nơi các sơ đồ được tạo tự động từ cơ sở hạ tầng hoặc mã của bạn. Các công cụ đã bắt đầu xuất hiện có thể:

• Quét các tệp cấu hình Kubernetes và tạo sơ đồ cấu trúc dịch vụ

• Phân tích các tệp OpenAPI/Swagger và tạo sơ đồ luồng API

• Giám sát tài nguyên đám mây của bạn và tự động cập nhật các sơ đồ kiến trúc

Mermaid nằm ở trung tâm của phong trào này, cung cấp một định dạng đơn giản dựa trên văn bản mà máy móc có thể tạo ra và con người có thể hiểu được.

Bắt đầu ngay hôm nay

Sẵn sàng vượt ra ngoài các hình ảnh tĩnh? Đây là kế hoạch hành động của bạn:

1. Cài đặt tiện ích mở rộng Mermaid trong trình phát triển tích hợp (IDE) yêu thích của bạn (VS Code, IntelliJ)

2. Tạo sơ đồ đầu tiên của bạn trong một.md tệp bằng cú pháp của Mermaid

3. Khám phá gói miễn phí của VPasCode để trải nghiệm vẽ sơ đồ với sức mạnh của AI

4. Khởi tạo kho lưu trữ tài liệu sống độngcùng với cơ sở mã của bạn

5. Chia sẻ bài viết này với đội nhóm của bạnvà bắt đầu cuộc trò chuyện

Kiến trúc của bạn xứng đáng hơn một sơ đồ bụi bặm trong một thư mục bị lãng quên. Đã đến lúc coi các sơ đồ của bạn như những tài sản quan trọng mà chúng thực sự là.