AI vẽ sơ đồ kiến trúc từ mã nguồn tốt nhất khi bạn bắt nó vẽ bằng chữ, cụ thể là cú pháp sơ đồ dạng văn bản như Mermaid, thay vì vẽ hình. Sơ đồ dạng chữ lưu được ngay trong kho mã, sửa bằng trình soạn thảo, xem khác biệt giữa hai phiên bản như mọi tệp khác, và nhiều nền tảng quản lý mã hiện nay hiển thị được nó thành hình. Quan trọng hơn, bạn đọc được từng mũi tên AI vẽ và đối chiếu với mã thật.
Bài này hướng dẫn ba loại sơ đồ hữu ích nhất khi tiếp quản dự án cũ: sơ đồ thành phần, sơ đồ tuần tự cho một luồng, và sơ đồ quan hệ giữa các bảng dữ liệu. Kèm theo là cách hỏi AI và cách kiểm từng sơ đồ trước khi đưa vào tài liệu.
Vì sao sơ đồ dạng chữ hợp với AI và với mã cũ
Mô hình ngôn ngữ làm việc với văn bản, nên sinh ra một đoạn cú pháp sơ đồ là việc nó làm tự nhiên. Mermaid là một ngôn ngữ mô tả sơ đồ bằng văn bản, mã nguồn mở, hỗ trợ sơ đồ luồng, sơ đồ tuần tự, sơ đồ lớp, sơ đồ quan hệ thực thể và một số loại khác. Ngoài Mermaid còn có PlantUML và Graphviz với cách viết riêng. Bài này dùng Mermaid làm ví dụ vì cú pháp ngắn và phổ biến; việc nền tảng nào hiển thị được loại sơ đồ nào thì bạn kiểm trong tài liệu hiện hành của nền tảng đó.
Với mã cũ, lợi ích lớn nhất của sơ đồ dạng chữ là nó sống cùng mã. Sơ đồ vẽ bằng công cụ kéo thả thường nằm trong một tệp hình ảnh hay một tài khoản riêng của ai đó, sau một năm không ai cập nhật và không ai tìm thấy. Sơ đồ dạng chữ nằm trong thư mục tài liệu, sửa trong cùng yêu cầu gộp mã với thay đổi liên quan, người rà mã nhìn thấy nó thay đổi. Khi cần cập nhật, bạn đưa sơ đồ cũ cùng phần mã mới cho AI và yêu cầu sửa đúng chỗ thay đổi.
Sơ đồ thành phần: nhìn cả hệ thống trong một trang
Đây là sơ đồ nên vẽ đầu tiên. Nó trả lời câu hỏi hệ thống gồm những khối nào và khối nào gọi khối nào. Quy trình gợi ý:
- Đưa AI danh sách thư mục, tệp khai báo phụ thuộc và tệp cấu hình chính, như khi đọc dự án lạ.
- Yêu cầu: Vẽ sơ đồ thành phần bằng Mermaid kiểu flowchart, tối đa mười hai khối, gồm cả dịch vụ bên ngoài như cơ sở dữ liệu, máy chủ thư, cổng thanh toán. Mỗi mũi tên ghi động từ ngắn. Sau sơ đồ, liệt kê căn cứ của từng mũi tên: tệp và dòng.
- Dán đoạn cú pháp nhận được vào một trình xem Mermaid để xem hình. Nếu hình báo lỗi cú pháp, đưa thông báo lỗi lại cho AI sửa; lỗi hay gặp là ký tự đặc biệt trong nhãn chưa được đặt trong ngoặc kép.
- Kiểm từng mũi tên theo danh sách căn cứ. Mũi tên nào không có căn cứ hoặc căn cứ sai thì xoá.
- Đặt tệp sơ đồ vào thư mục tài liệu, kèm ngày vẽ và phạm vi đã kiểm.
Giới hạn mười hai khối là có chủ ý. Sơ đồ có ba mươi khối thì không ai đọc, và AI dễ tự bịa mối nối để lấp chỗ trống. Nếu hệ thống lớn, vẽ một sơ đồ tổng mười khối, rồi mỗi khối quan trọng có một sơ đồ con riêng. Cách chia tầng như vậy gần với ý tưởng của mô hình C4 mà Simon Brown đề xuất: đi từ bức tranh tổng thể xuống dần từng tầng chi tiết.
Sơ đồ tuần tự: một luồng, nhiều bên tham gia
Sơ đồ tuần tự cho thấy các bên gọi nhau theo thứ tự thời gian trong một luồng cụ thể: trình duyệt, máy chủ web, cơ sở dữ liệu, dịch vụ bên ngoài. Nó hợp nhất với những luồng có nhiều bước qua lại như thanh toán, đăng nhập một lần, gửi thông báo qua hàng đợi. Nếu bạn đã lần theo luồng chạy của một tính năng và có bảng các chặng, việc chuyển bảng đó thành sơ đồ tuần tự gần như là việc dịch máy móc, AI làm rất nhanh và ít sai.
Câu hỏi mẫu: Dựa trên bảng các chặng sau, vẽ sơ đồ tuần tự Mermaid. Các bên tham gia: Trình duyệt, Máy chủ web, Cơ sở dữ liệu, Máy chủ thư. Thể hiện rõ chỗ nào chạy đồng bộ, chỗ nào ghi vào hàng đợi để tác vụ nền xử lý sau. Không thêm bước nào không có trong bảng.
Cụm "không thêm bước nào không có trong bảng" quan trọng. Nếu không dặn, AI có xu hướng vẽ luồng theo hình mẫu sách giáo khoa, thêm bước kiểm tra quyền, bước ghi nhật ký mà hệ thống của bạn thật ra không có. Sơ đồ đẹp mà sai là thứ nguy hiểm, vì nó trông như tài liệu chính thức.
Sơ đồ quan hệ bảng: khi cơ sở dữ liệu không có khoá ngoại
Cơ sở dữ liệu của nhiều dự án cũ không khai báo khoá ngoại, quan hệ giữa các bảng chỉ nằm trong mã. AI giúp suy ra quan hệ từ hai nguồn, và mỗi nguồn có độ tin cậy khác nhau.
| Nguồn suy luận | AI suy ra được gì | Độ tin cậy |
|---|---|---|
| Lệnh tạo bảng có khoá ngoại khai báo | Quan hệ chính xác, kiểu một nhiều | Cao |
| Tên cột theo quy ước, ví dụ cột kết thúc bằng _id | Cột này có thể trỏ tới bảng cùng tên | Trung bình, tên có thể lừa |
| Câu JOIN trong mã | Hai bảng thật sự được nối qua cột nào | Khá cao nếu câu đó còn được gọi |
| Câu truy vấn đếm trên dữ liệu thử | Quan hệ một một hay một nhiều trên thực tế | Cao, nhưng phải chạy thật |
Khi yêu cầu AI vẽ sơ đồ quan hệ thực thể bằng Mermaid, bắt nó ghi nguồn của mỗi quan hệ ngay trong nhãn hoặc trong danh sách đi kèm. Quan hệ chỉ suy từ tên cột nên vẽ khác kiểu hoặc ghi chú "chưa xác nhận", tới khi bạn tìm được câu JOIN hoặc chạy truy vấn kiểm.
Chỉ đưa cho AI cấu trúc bảng, tức lệnh tạo bảng, không đưa dữ liệu thật. Lấy cấu trúc từ cơ sở dữ liệu thử hoặc bản sao đã xoá dữ liệu. Danh mục này có bài riêng đi sâu hơn về việc tìm hiểu một cơ sở dữ liệu cũ không tài liệu.
Kiểm sơ đồ: năm lỗi AI hay mắc
Mũi tên ngược chiều. AI vẽ khối A gọi khối B trong khi thật ra B gọi A qua một hàm gọi lại. Kiểm bằng cách tìm lời gọi trong mã của chính khối ở đầu mũi tên.
Khối không tồn tại. Một tầng bộ nhớ đệm hay một dịch vụ hàng đợi được vẽ vào vì "dự án loại này thường có". Hỏi căn cứ, không có thì xoá.
Gộp hai thứ khác nhau. Hai thư mục cùng tên ở hai nơi bị vẽ thành một khối. Với dự án cũ có bản sao mã, đây là lỗi rất hay gặp.
Thiếu điểm vào phụ. Tác vụ định kỳ, tập lệnh nhập dữ liệu, trang quản trị riêng thường bị bỏ sót vì không nằm trong luồng web chính. Hỏi riêng một câu về các điểm vào ngoài web.
Sơ đồ đúng nhưng lỗi thời. Vẽ từ một nhánh git cũ hoặc từ thư mục chưa cập nhật. Ghi rõ commit hoặc ngày vẽ ngay trong tệp sơ đồ để người đọc biết nó phản ánh thời điểm nào.
Kết hợp công cụ phân tích tĩnh để AI không phải đoán
AI đọc mã để suy ra ai gọi ai, nhưng có những công cụ làm việc đó một cách máy móc và đầy đủ hơn: chúng quét toàn bộ câu lệnh nạp mô-đun và xuất ra đồ thị phụ thuộc. Với JavaScript có các công cụ như madge, với Python có pydeps, với PHP có deptrac để kiểm ranh giới giữa các tầng. Tên và tính năng có thể thay đổi theo thời gian, bạn kiểm trang chính thức của từng công cụ trước khi cài. Nhiều công cụ loại này xuất được kết quả ở dạng văn bản hoặc định dạng DOT của Graphviz.
Cách kết hợp hiệu quả là để công cụ tĩnh làm phần đếm, AI làm phần diễn giải. Bạn chạy công cụ, lấy danh sách cạnh phụ thuộc dạng văn bản, đưa cho AI cùng yêu cầu: Đây là danh sách phụ thuộc giữa các mô-đun, mỗi dòng là một cạnh. Gom thành tối đa mười nhóm, vẽ sơ đồ Mermaid giữa các nhóm, chỉ ra các vòng phụ thuộc và mô-đun bị phụ thuộc nhiều nhất. Lúc này AI không còn phải đoán mũi tên, nó chỉ sắp xếp và đặt tên cho dữ liệu có thật.
Hạn chế cần biết: công cụ tĩnh không thấy lời gọi động, nạp tệp bằng đường dẫn ghép chuỗi, hay giao tiếp qua mạng giữa hai dịch vụ. Các vòng phụ thuộc nó phát hiện thì thường đáng tin, và đó là thông tin quý khi bạn chuẩn bị tách nhỏ một hệ thống cũ.
Giữ sơ đồ sống cùng dự án
Sơ đồ chỉ có giá trị nếu nó còn đúng. Cách đơn giản để giữ đúng là gắn việc cập nhật sơ đồ vào quy trình rà mã: yêu cầu gộp mã nào thêm khối mới, thêm dịch vụ bên ngoài hay đổi luồng chính thì phải sửa sơ đồ trong cùng lần gộp. Người rà mã chỉ cần hỏi một câu. Vì sơ đồ là văn bản, thay đổi hiện ra rõ ràng trong phần so sánh khác biệt.
Bạn cũng có thể giao cho trợ lý AI việc soát định kỳ: đưa sơ đồ hiện có cùng danh sách thư mục và tệp khai báo mới nhất, hỏi chỗ nào trong sơ đồ không còn khớp. Đây là việc AI làm khá tốt vì nó chỉ phải so hai thứ cụ thể, không phải sáng tác. Với người mới vào nhóm, một sơ đồ thành phần và ba sơ đồ tuần tự cho ba luồng quan trọng nhất thường rút ngắn rõ rệt thời gian làm quen, nhiều hơn bất kỳ tài liệu văn xuôi dài nào.
Câu hỏi thường gặp
Mermaid là gì và có cần cài đặt không?
Mermaid là ngôn ngữ mô tả sơ đồ bằng văn bản, mã nguồn mở, viết bằng JavaScript. Nhiều nền tảng quản lý mã và trình soạn thảo hiển thị trực tiếp, hoặc qua tiện ích mở rộng. Bạn kiểm tài liệu của nền tảng đang dùng để biết có hỗ trợ sẵn không.
AI có tự đọc kho mã rồi vẽ sơ đồ được không?
Tác tử AI có quyền đọc kho mã làm được việc này và nhanh. Nhưng vẫn yêu cầu nó liệt kê căn cứ cho từng mũi tên, vì sơ đồ nó vẽ dựa trên những tệp nó kịp đọc, có thể thiếu điểm vào phụ hoặc lời gọi động.
Nên dùng Mermaid, PlantUML hay Graphviz?
Cả ba đều mô tả sơ đồ bằng văn bản. Mermaid cú pháp ngắn và được nhiều nền tảng hiển thị sẵn. PlantUML mạnh về sơ đồ UML chi tiết nhưng thường cần môi trường chạy riêng. Graphviz hợp với đồ thị nhiều nút tự sắp xếp. Chọn cái nhóm bạn xem được dễ nhất.
Sơ đồ nên chi tiết tới mức nào?
Đủ để một người mới hiểu hệ thống trong mười phút. Sơ đồ tổng không quá mười, mười hai khối. Chi tiết hơn thì tách sơ đồ con. Sơ đồ quá chi tiết sẽ lỗi thời nhanh và không ai cập nhật.
Có nên vẽ sơ đồ lớp cho toàn bộ mã hướng đối tượng cũ?
Thường không đáng. Sơ đồ lớp toàn bộ dự án rất rối và ít người đọc. Vẽ sơ đồ lớp cho một vùng cụ thể khi bạn chuẩn bị tái cấu trúc vùng đó thì hữu ích hơn nhiều.