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:
-
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)
-
Tạo sơ đồ đầu tiên của bạn trong một
.mdtệp bằng cú pháp của Mermaid -
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
-
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
-
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à.
