Cách vẽ sơ đồ kiến trúc phần mềm (2022)

 (terrastruct.com)
3 điểm bởi GN⁺ 2023-10-28 | 1 bình luận | Chia sẻ qua WhatsApp
  • Một sơ đồ kiến trúc tốt giúp việc truyền đạt ý tưởng và cộng tác được duy trì lâu dài nhờ mức độ trừu tượng phù hợp, tính cập nhật và loại bỏ sự mơ hồ, hơn là nhờ trang trí
  • Nguyên tắc cơ bản là giảm thiểu khoảng cách lân cận, tức đặt các phần tử có liên kết gần nhau; sơ đồ càng lớn thì càng cần lặp lại việc xóa và vẽ lại
  • Tính đối xứng không chỉ tạo ấn tượng đẹp mắt, mà còn tăng cường truyền đạt ý nghĩa, chẳng hạn bằng cách đặt đầu vào và đầu ra ở hai phía khác nhau
  • Duy trì căn giữa các hình khối giúp cả những khái niệm phức tạp trông bớt rối hơn, và khi thêm phần tử mới, bố cục tổng thể không bị xáo trộn
  • Nhóm container có nhãn giúp nhìn ra ngay các phân tách môi trường như AWS và Azure, các lớp trừu tượng như implementation của ReaderWriter, hoặc các nhóm đối tượng liên quan như Cores

Điều kiện của một sơ đồ bền vững theo thời gian

  • Một sơ đồ tốt không bị xóa đi sau khi cuộc họp kết thúc, mà tiếp tục được dùng làm điểm tham chiếu cho các thảo luận và câu hỏi sau đó
  • Các sơ đồ được sử dụng lâu dài có một vài điều kiện chung
    • Các phần tử phải ở đúng mức độ trừu tượng
    • Phải được duy trì ở trạng thái cập nhật
    • Không được có sự mơ hồ
  • Cùng một thực thể và quan hệ có thể được vẽ theo nhiều cách, nhưng có bố cục giúp cộng tác trong suốt thời gian dự án, còn có bố cục sẽ biến mất khi cuộc họp kết thúc
  • Vẻ đẹp được nói đến ở đây không phải là trang trí như đổ bóng hay bo góc, mà là vẻ đẹp chức năng giúp truyền đạt suy nghĩ hiệu quả

Nguyên tắc tạo bố cục dễ đọc

  • Giảm thiểu khoảng cách lân cận

    • Về cơ bản, các node được kết nối với nhau nên được vẽ gần nhau
    • Với sơ đồ nhỏ thì điều này dễ, nhưng khi sơ đồ lớn hơn và các kết nối mới được thêm vào, thuộc tính này rất dễ bị phá vỡ
    • Giống như khi phát hiện edge case trong code thì sửa phần liên quan, hoặc khi phát hiện mục bị thiếu trong tài liệu thì chỉnh lại câu chữ, sơ đồ dùng cho tài liệu cũng cần được xóa và vẽ lại khi cần
    • Trong bối cảnh phỏng vấn, chi phí vẽ lại có thể là gánh nặng, nhưng nếu là tài liệu để nhiều người hoặc nhiều nhóm sử dụng, việc chỉnh sửa lặp lại sẽ dẫn đến một sơ đồ tốt hơn

  • Tìm tính đối xứng

    • Tính đối xứng đóng góp lớn vào ấn tượng thẩm mỹ của sơ đồ, và não người có xu hướng ưa thích sự đối xứng thị giác, như với khuôn mặt
    • Ngay cả khi mọi node đều ở gần hàng xóm của mình nhất có thể, nếu thiếu đối xứng thì sơ đồ vẫn có thể trông hơi lệch
    • Một phiên bản cân đối hơn có thể trông đẹp hơn, dù khoảng cách lân cận của một số node tăng lên một chút
    • Cách đặt đầu vào ở một phía và đầu ra ở phía còn lại vừa tạo tính đối xứng, vừa củng cố ý nghĩa của sơ đồ

  • Căn giữa

    • Căn chỉnh là một yếu tố lớn giúp sơ đồ trông gọn gàng
    • Sơ đồ gọn gàng làm khái niệm trở nên rõ ràng hơn, còn sơ đồ lộn xộn khiến khái niệm trông phức tạp hơn
    • Nếu ngay từ đầu đặt các hình khối ngẫu nhiên trên một canvas trống, các bố cục về sau cũng dễ tiếp tục mang tính ngẫu nhiên
    • Căn chỉnh chỉ có ý nghĩa giữa hai hình khối trở lên, nên nếu duy trì căn chỉnh mỗi khi thêm phần tử mới, sơ đồ sẽ tự nhiên trở nên gọn gàng
    • Sự đối xứng thường tạo ra căn chỉnh, nhưng không phải lúc nào cũng vậy

  • Sử dụng nhóm container

    • Chia sơ đồ thành nhiều vùng có nhãn giúp người xem hiểu cấu trúc dễ hơn
    • Container có thể bổ sung các thông tin sau cho sơ đồ
      • Thêm ngữ cảnh, như “các service này nằm trên AWS, còn các service này nằm trên Azure”
      • Thể hiện trừu tượng, như “tất cả những thành phần này đều là implementation của ReaderWriter”
      • Nhóm các đối tượng liên quan, như gom core 1, 2, 3, 4 vào container “Cores”

Các mục tiếp theo trong phần sau

  • Phần 2 sẽ tiếp nối với các chủ đề sau
    • Vẽ đường đi của cạnh
    • Kích thước và vị trí nhãn
    • Màu sắc
    • Biểu tượng

Bài viết liên quan

1 bình luận

 
GN⁺ 2023-10-28
Ý kiến trên Hacker News

  • Tôi rất thích dùng D2 để vẽ sơ đồ. Nó giống mermaid.js nhưng có nhiều tùy chọn định dạng hơn, và cá nhân tôi thấy cú pháp cũng tốt hơn
    Tôi cũng đã viết một bài ngắn về việc này: https://victorbjorklund.com/build-diagrams-as-code-with-d2-d...

    • Tôi thấy sơ đồ không nên đẹp theo kiểu trang trí. Ví dụ, màu sắc không nên được dùng như một lựa chọn thẩm mỹ hay nghệ thuật mà phải phục vụ việc truyền đạt ý nghĩa
      Tôi hiểu rằng một sơ đồ phần mềm xấu xí thì không dễ chịu để nhìn, nhưng việc trang trí nó cũng giống như thêm đường cong vào biểu đồ đường. Trông có thể đẹp hơn về mặt thị giác, nhưng lại cản trở dữ liệu mà bạn muốn truyền tải
    • Tôi đã làm theo ví dụ và thấy nó thực sự ấn tượng, nhưng trái với hướng dẫn thì nó được render từ trên xuống dưới chứ không phải từ trái sang phải
      Tôi render ví dụ đầu tiên x -> y sang SVG rồi chỉ mở riêng SVG đó trong trình duyệt, và đã tìm khắp tài liệu cách căn hướng đầu ra nhưng không thấy
      Vì tài liệu hướng dẫn và kết quả thực tế khác nhau nên tôi đã ngừng dùng nó. Tôi tìm "d2lang connection left to right" và đi đến https://d2lang.com/tour/layouts/, nhưng có vẻ trang đó không được liên kết từ tài liệu tổng quan, nên nếu bổ sung vào thì sẽ hữu ích cho người truy cập
    • https://flowchart.fun/ đã giúp tôi vẽ lưu đồ rất nhanh để hiểu các quy trình hệ thống. Điều tôi thích nhất là nó trực quan và cho phép lặp lại rất nhanh, ngoài ra CSS tùy chỉnh để tạo kiểu cũng khá hữu ích
      Riêng với lưu đồ thì đây là một trong những công cụ sơ đồ dựa trên văn bản dễ và nhanh nhất mà tôi từng dùng
    • D2 có công cụ layout tala rất tốt, nhưng muốn dùng thì phải có giấy phép trả phí. Hai engine còn lại không tốt bằng
    • Tôi thích mermaid và dùng nó thường xuyên, nhưng chắc cũng nên thử D2. Sơ đồ khai báo là một công cụ mạnh để ghi lại suy nghĩ dưới dạng dễ đọc và cho phép quản lý phiên bản như các loại văn bản khác

  • Khi hệ thống bắt đầu thay đổi, sơ đồ đẹp trở nên rất khó duy trì. Hãy tưởng tượng phải thêm một hộp mới vào chính giữa một sơ đồ vốn đã phức tạp, có khi bạn sẽ mất cả tiếng chỉ để sắp lại mọi thứ
    Thời gian của lập trình viên trong thập niên 2020 có lẽ tốt hơn nên được dành cho việc quản lý sơ đồ dưới dạng mã: https://www.ilograph.com/blog/posts/its-time-to-drop-drag-an...

    • Tôi luôn đùa rằng 10% công việc vẽ sơ đồ là tạo sơ đồ thật sự, còn 90% là căn chỉnh mũi tên
      Nhưng có lẽ thật ra đó không phải trò đùa
    • Tôi từng duy trì một mô hình C4 để nhập và hiển thị trong structurizr.com, và thành thật mà nói thì không vui chút nào. Chỉ dùng mã thôi không tạo ra được sự hiểu trực quan và cái nhìn tổng thể mà sơ đồ mang lại, lại còn không có xem trước cục bộ nhanh nên phải đẩy mã lên server
      Tệ hơn nữa là khi thêm một hộp mới, thường tôi phải căn lại toàn bộ mũi tên. Kết quả là sơ đồ không thể được giữ luôn ở trạng thái cập nhật
      Với sequence diagram thì khi dùng plantML tôi thấy tốt hơn. Công việc bản thân nó dễ hơn nên đầu ra của trình thông dịch thường dùng được mà không cần can thiệp thủ công nhiều
    • Bài viết cũng nói đến việc chỉnh sửa sơ đồ rất tốn thời gian. Thực tế đúng là như vậy, và sẽ tốt hơn nếu có thể tuân thủ đúng một schema chuẩn hóa và công cụ có tùy chọn định dạng tự động
    • Khi di chuyển các thành phần và sắp xếp lại, bạn phải học lại toàn bộ sơ đồ. Nếu frobnitz trước giờ luôn ở góc trên bên phải mà đột nhiên bị chuyển sang giữa bên trái vì hợp lý hơn về mặt bố cục, thì có thể điều đó giúp người mới nhìn lần đầu, nhưng với người đã nhìn nó suốt 6 tháng thì nó trông như một thứ hoàn toàn khác
      Nó giống UI xấu vậy. Dù xấu, người dùng vẫn đã quen rồi. Đến lúc bạn “dọn dẹp” nó thì bạn đang phá vỡ mô hình tinh thần của họ và buộc họ phải học lại
    • Việc đầu tư thời gian đó có đáng hay không phụ thuộc vào phạm vi tiếp cận và tuổi thọ của sơ đồ
      Đôi khi đó chỉ là một bản phác thảo để sắp xếp suy nghĩ rồi 20 phút sau sẽ vứt đi
      Nhưng nếu nó là tài liệu tham khảo để onboarding hoặc giải thích hệ thống cho nhóm khác, thì một giờ bỏ ra để làm nó dễ hiểu hơn hoàn toàn có thể mang lại giá trị xứng đáng

  • Tôi dùng yEd để vẽ những thứ như thế này. Bạn có thể làm rối tung các hộp và mũi tên, rồi chỉ cần vài cú nhấp trong menu là nó tự sắp lại
    Dĩ nhiên vẫn phải chấp nhận một số đánh đổi. Hộp lồng trong hộp không phải lúc nào cũng cho kết quả tốt. Nhưng nhìn chung tôi có thể tài liệu hóa nhanh hơn nhiều, và sau vài lần thử bạn sẽ dần cảm được cái gì hoạt động tốt hay không, nên với tôi đó là một sự thỏa hiệp ổn

    • Tôi thắc mắc không biết yEd có dùng miễn phí được không. Bộ SDK yWorks bên dưới có vẻ tốn mức giá 5 chữ số ngay cả khi chỉ một lập trình viên dùng cho một website. Nếu họ đã có khách hàng gần 20 năm thì chắc hẳn đây là một công cụ khá mạnh
    • Tôi cũng dùng y như vậy. Không có lý do gì phải tự tay vẽ
      Chỉ cần trích xuất các quan hệ thành TGF rồi import vào, sau đó áp dụng layout phân cấp
      Định dạng from, to, relation là đủ
    • Tôi dùng OmniGraffle vì những lý do tương tự

  • Việc này có nhiều điểm tương đồng rất mạnh với sơ đồ điện, sơ đồ mạch và các bản vẽ kỹ thuật khác. Không có một cách “đúng” duy nhất
    Cũng như code, khả năng chọn mức trừu tượng và cách biểu đạt phù hợp là yếu tố quyết định giữa một ý tưởng dễ hiểu và một mớ hỗn độn đáng tiếc. Đây không phải vấn đề của vẻ đẹp hay thẩm mỹ, mà là một công cụ đòi hỏi suy nghĩ và nỗ lực chủ động trong thiết kế

    • Giữ cho mức độ trừu tượng được nhất quán đôi khi thực sự rất khó. Đặc biệt với sơ đồ hạ tầng, rất khó cưỡng lại thôi thúc nhồi thêm các mức chi tiết khác nhau
      Sẽ rất hay nếu có một công cụ cho phép dễ dàng phóng to đi sâu vào sơ đồ, kiểu như hoạt ảnh zoom vô hạn

  • Sắp ra mắt https://VisualFlows.io v1.0
    Chỉ trong vài phút đã có thể tạo bản đồ “kiến trúc” dạng hoạt hình cho SaaS của công ty mẹ: https://app.visualsitemaps.com/user_flows/share/e64da8ed-2ef...
    Các tính năng chính gồm Smart Sections, Smart Edges, Smart Node Deletion, chế độ tối/sáng, nhúng, kéo thả ảnh/SVG/GIF, biểu tượng AWS/Windows/Google, và Markdown dự kiến có vào tuần tới
    Tham khảo Smart Sections: https://support.visualsitemaps.com/en/articles/6477269-how-t...

    • Tôi tò mò vì sao nên dùng cái này thay vì https://whimsical.com vốn đã trưởng thành hơn nhưng có cùng gu thẩm mỹ

  • Bài này thực sự rất hay. Dù là vẽ sơ đồ kiến trúc, viết tài liệu hay code, hay làm bất cứ việc gì trong công việc, tôi thường dành chút thời gian để làm cho nó “trông đẹp hơn”
    Khó giải thích vì sao, nhưng tôi biết là sau khi làm vậy thì tôi thấy hài lòng hơn
    Tôi hơi lo đó có thể không phải là cách dùng thời gian hiệu quả nhất, nhưng cũng chưa từng nghe ai bảo đừng làm vậy
    Điều hay ở bài này là nó diễn tả việc tôi vẫn làm theo cảm tính như một phương pháp thực tế để khiến mọi thứ đẹp hơn

    • Tôi cũng vậy. Với tôi, lập trình là một công việc khá mang tính thị giác. Tôi chỉ có thể mô tả nó là “dòng chảy”. Nếu code không có dòng chảy thì tôi không thấy thỏa mãn
      Tôi thấy bối rối khi nhìn những đồng đội dường như không có cảm giác thị giác với code. Họ không chừa dòng trống giữa cuối một hàm và khai báo hàm tiếp theo, hoặc ở phần chữ ký hàm thì lúc viết mỗi tham số trên một dòng, lúc lại nhét nhiều tham số trên cùng một dòng. Với tôi điều đó rất chói mắt, nhưng có vẻ họ không bận tâm
    • Ngay cả khi không chia sẻ với ai, quá trình suy nghĩ về thứ tự các khối và phần tử trên trang tự nó cũng khiến ta nghĩ đến cấu trúc lớn hơn và các phụ thuộc. Cực kỳ hữu ích
    • Tôi cũng có cảm giác tương tự khi làm sơ đồ mạng bằng Visio. Tôi chuyển sang chế độ Steve Jobs và ám ảnh với những chi tiết nhỏ
      Đôi khi tốn thời gian, nhưng tôi cảm thấy như được lấp đầy điều gì đó. Tôi biết mình có phần nào năng khiếu nghệ thuật kỹ thuật, và hồi cấp ba từng muốn trở thành họa viên kỹ thuật
    • Đó là lý do có markup. Nó giúp ta thoát khỏi việc trang trí thiếu năng suất. Dĩ nhiên điều này không áp dụng cho việc viết code
    • “Cuộc thảo luận xoay quanh sơ đồ này. Mọi người vô thức lại gần và nhìn nó. Câu hỏi được trả lời bằng cách chỉ vào sơ đồ. Theo chu kỳ trong ngày, những chiếc ghế quay về phía vật thể trung tâm này, và mọi người đan tay ra sau đầu.”
      Đó chính là mục tiêu của trực quan hóa

  • D2 rất hợp cho việc này. Ở vai trò trước, tôi đã viết một chương trình phân tích tất cả các file serverless.yml để tự động tạo ra một sơ đồ D2 khổng lồ
    Chúng tôi làm microservice trên AWS, và thật tuyệt khi nó tự cập nhật khi hệ thống lớn dần. Tôi cũng làm cho nó có thể tách thành các sơ đồ nhỏ hơn cho từng hệ thống con, chẳng hạn chia theo SNS topic

    • Tôi cũng thích draw.io

  • Tôi không hiểu ví dụ đầu tiên. Tác giả nói về một node không được lên kế hoạch, rồi lại thực sự đặt tên nó là “I was unplanned”, sau đó lại nói “nếu đã lên kế hoạch trước”
    Tôi không hiểu trong ngữ cảnh sơ đồ thì làm sao có thể lên kế hoạch trước cho một thứ không được lên kế hoạch. Không biết ý có phải là nên chừa đủ khoảng trắng quanh mọi node hay không
    Ngoài ra, phương án cải thiện được đề xuất lại khiến “something” và “I was unplanned” trông như dùng cùng một kênh hay cơ chế khi tương tác với “engine”

  • Tôi dùng Miro, và với nội dung cấp cao hoặc phác thảo ý tưởng thì công cụ post-it của nó khá ổn. Nhưng nó không vượt quá được mức trung gian
    Sau khi các component và hệ thống đã được xác định, sẽ có những công cụ phù hợp hơn cho công việc đó

  • Nếu tài liệu dự án ở dạng Markdown, bạn có thể chèn sơ đồ bằng cách thêm khối ```plantuml thay vì dùng một file nhị phân riêng
    Trên GitLab, khi xem file .md trong trình duyệt thì nó được render rất đẹp. GitHub vẫn chưa có tính năng đó