Codemap: bản đồ tương tác một trang cho mọi repo Go

Một công cụ mã nguồn mở mới có tên Codemap cho phép tạo ra bản đồ trực quan cho toàn bộ module Go chỉ trong một trang HTML. Công cụ này hữu ích với những lập trình viên cần làm quen nhanh với một dự án lạ, bởi nó cho thấy mỗi package dựa trên nền tảng nào và các hàm nằm ở đâu.

Một trang HTML, không cần server

Theo mô tả của tác giả trên GitHub, Codemap tạo ra một trang HTML duy nhất mô tả mọi package, những gì nó xây dựng dựa trên trong cùng module, và các hàm trong từng file. Người dùng có thể tìm kiếm trên trang, nhấp vào một package để xem nó dùng gì và bị những gì sử dụng, và với module trên GitHub có thể nhảy thẳng tới dòng chứa hàm. Các file test được loại khỏi bản đồ.

Ví dụ mà tác giả đưa ra là bản đồ của yggstore, gồm 40 package và 1.850 hàm.

Điểm đáng chú ý là kết quả chỉ là một file, không cần dựng server, nên có thể đặt lên bất kỳ website nào.

Cách sử dụng

Trong thư mục của module, với Go 1.24 trở lên, chạy lệnh:

go run github.com/peterretief/codemap@latest -o code-map.html

Sau đó mở file code-map.html bằng trình duyệt. Tham số -root DIR dùng để ánh xạ một thư mục khác.

Codemap cũng tích hợp được vào GitHub Actions:

- uses: actions/checkout@v4
- uses: peterretief/[email protected]
  with:
    output: code-map.html
- uses: actions/upload-artifact@v4
  with:
    name: code-map
    path: code-map.html

Cách đọc bản đồ

Mỗi hàng chỉ xây dựng dựa trên các hàng bên dưới nó, nên phần nền tảng nằm ở dưới cùng và các lệnh (command) của bạn nằm ở trên cùng.

Các ô rộng hơn chứa nhiều hàm hơn, và màu sắc thể hiện thư mục cấp cao nhất. Tiền tố internal/ được lược khỏi tên. Các thư mục vendor, testdata và những thư mục có file go.mod riêng đều bị loại bỏ.

Trang tải phông chữ từ Google Fonts, và sẽ chuyển sang phông chữ hệ thống nếu không tải được.

Góc nhìn

Với các nhóm phát triển Go tại Việt Nam, Codemap giải quyết một vấn đề quen thuộc: tiếp nhận một codebase lớn do người khác viết. Một bản đồ phụ thuộc giữa các package, kèm vị trí hàm, giúp rút ngắn thời gian đọc hiểu và giảm nguy cơ sửa nhầm tầng khi thêm tính năng.

Vì đầu ra chỉ là một file HTML tĩnh, công cụ này có thể đưa vào pipeline CI để mỗi lần build đều sinh ra bản đồ mới, rồi chia sẻ trong nội bộ hoặc gắn vào tài liệu dự án. Cần lưu ý công cụ yêu cầu Go 1.24 trở lên, nên các dự án còn dùng phiên bản cũ hơn sẽ phải cân nhắc khi áp dụng.