Diagrams as code

Công cụ kéo-thả như draw.io hay Visio dễ dùng và cho ra hình đẹp. Nhưng khi sơ đồ cần sống lâu cùng dự án, chúng lộ điểm yếu - đúng nỗi lo "lạc hậu" ta gặp ở mức Component.

• ▸Tách rời code: sơ đồ là một file ảnh nằm đâu đó, dễ quên cập nhật khi hệ thống đổi.
• ▸Khó review: một ảnh PNG không "diff" được; người review không thấy đổi gì.
• ▸Lặp công: cùng một phần tử xuất hiện ở nhiều bức; đổi một chỗ phải sửa tay nhiều bức.

Diagrams as code đảo ngược cách làm: bạn MÔ TẢ mô hình bằng văn bản, rồi để công cụ tự vẽ ra sơ đồ. Vì giờ sơ đồ là text, nó hưởng mọi thứ tốt đẹp của code.

• ▸Version cùng Git: sơ đồ đổi theo từng commit, có lịch sử rõ ràng.
• ▸Review qua Pull Request: người khác xem diff text và góp ý ngay.
• ▸Một model, nhiều view: mô tả phần tử một lần, sinh ra nhiều sơ đồ luôn khớp nhau.
• ▸Tự canh bố cục: khỏi mất công kéo từng hộp cho thẳng hàng.

Thật ra, chính các sơ đồ trong khoá này cũng là "diagrams as code" - chúng được sinh ra từ dữ liệu (không vẽ tay), nên luôn nhất quán. Ví dụ một sơ đồ Container do code dựng:

Structurizr do chính Simon Brown (cha đẻ C4) làm ra, sinh đúng cho C4. Điểm mạnh: bạn dựng một model, rồi định nghĩa nhiều view từ model đó.

workspace {
  model {
    khachHang = person "Khách hàng"
    nganHang = softwareSystem "Ngân Hàng Số" {
      web = container "Web App" "React"
      api = container "API Application" "Java/Spring"
      db = container "Cơ sở dữ liệu" "Oracle"
    }
    khachHang -> web "Dùng [HTTPS]"
    web -> api "Goi [JSON/HTTPS]"
    api -> db "Doc/ghi [SQL]"
  }
  views {
    systemContext nganHang {
      include *
      autolayout lr
    }
    container nganHang {
      include *
      autolayout lr
    }
  }
}

• ▸Khối model khai báo phần tử & quan hệ MỘT lần.
• ▸Khối views sinh ra hai sơ đồ (systemContext và container) từ cùng model đó.
• ▸Đổi tên một container? Sửa một dòng, cả hai sơ đồ cập nhật theo.

Hai lựa chọn phổ biến khác mô tả TỪNG sơ đồ một (không có khái niệm model dùng chung), nhưng rất tiện và nhiều nơi hỗ trợ sẵn.

@startuml
!include https://raw.githubusercontent.com/plantuml-stdlib/C4-PlantUML/master/C4_Container.puml

Person(khachHang, "Khách hàng")
System_Boundary(nganHang, "Ngân Hàng Số") {
  Container(web, "Web App", "React")
  Container(api, "API Application", "Java/Spring")
  ContainerDb(db, "Co so du lieu", "Oracle")
}

Rel(khachHang, web, "Dung", "HTTPS")
Rel(web, api, "Goi", "JSON/HTTPS")
Rel(api, db, "Doc/ghi", "SQL")
@enduml

C4Context
  title System Context - Ngan Hang So
  Person(khachHang, "Khách hàng", "Giao dịch trực tuyến")
  System(nganHang, "Ngân Hàng Số", "Ngân hàng online")
  System_Ext(core, "Core Banking", "Tài khoản & giao dịch")
  Rel(khachHang, nganHang, "Dùng", "HTTPS")
  Rel(nganHang, core, "Lấy số dư", "XML/HTTPS")

Giờ bạn tạo được sơ đồ vừa đẹp vừa luôn khớp hệ thống. Còn một kỹ năng nữa quyết định sơ đồ có thực sự hữu ích: trình bày đúng mức cho đúng người.