隨記

Structurizr DSL 導入指引

導入效應

效應 說明
Architecture as Code 用程式碼定義架構，放入 Git 版控，可 review、可 diff
C4 Model 落地 強制使用 Context/Container/Component 四層視圖描述架構
AI 架構變更追蹤 AI 修改架構時，PR 必須同步更新 DSL，確保架構文件與程式碼同步
自動產生架構圖 從 DSL 自動渲染 Architecture Diagram，不需手繪
團隊溝通一致 架構討論有共同語言，避免口头描述的模糊性
ADR 輔助 架構決策可追溯到 DSL 版本變更歷史

1. 安裝 Structurizr CLI

# macOS
brew install structurizr

# Windows (Chocolatey)
choco install structurizr

# Linux
wget https://github.com/structurizr/cli/releases/latest/download/structurizr-cli.zip
unzip structurizr-cli.zip

2. DSL 語法基礎

2.1 Workspace 定義

workspace "E-Commerce System" {
    model {
        customer = person "Customer" "購買商品的使用者"
        admin = person "Admin" "管理後台的管理員"

        softwareSystem = softwareSystem "E-Commerce Platform" {
            webapp = container "Web App" "React Frontend" "React, TypeScript"
            api = container "API Gateway" "REST API" "Spring Boot"
            orderService = container "Order Service" "處理訂單邏輯" "Spring Boot"
            paymentService = container "Payment Service" "處理付款" "Spring Boot"
            db = container "Database" "資料儲存" "PostgreSQL"
            redis = container "Cache" "快取" "Redis"
        }

        customer -> webapp "瀏覽商品"
        webapp -> api "API 呼叫"
        api -> orderService "建立訂單"
        api -> paymentService "處理付款"
        orderService -> db "讀寫訂單"
        paymentService -> db "讀寫付款"
        api -> redis "快取"
    }

    views {
        systemContext softwareSystem "SystemContext" {
            include *
            autolayout lr
        }

        container softwareSystem "Containers" {
            include *
            autolayout lr
        }

        styles {
            element "Person" {
                shape Person
            }
            element "Database" {
                shape Cylinder
            }
        }
    }
}

2.2 模組化 DSL

// workspace.dsl
workspace {
    model {
        !include models/people.dsl
        !include models/software-systems.dsl
        !include models/relationships.dsl
    }
    views {
        !include views/context.dsl
        !include views/container.dsl
    }
}

3. CI 整合

3.1 驗證 DSL

structurizr validate workspace.dsl

3.2 渲染架構圖

# 產生 PNG
structurizr export -f png workspace.dsl

# 產生 PlantUML
structurizr export -f plantuml workspace.dsl

# 產生 Mermaid
structurizr export -f mermaid workspace.dsl

3.3 Azure Pipeline

- stage: ArchitectureValidation
  jobs:
    - job: Structurizr
      steps:
        - script: |
            structurizr validate workspace.dsl
            structurizr export -f png workspace.dsl
          displayName: 'Validate & Export Architecture'
        - task: PublishBuildArtifacts@1
          inputs:
            pathToPublish: '$(Build.SourcesDirectory)/workspace.png'
            artifactName: 'architecture-diagrams'

4. AI PR Check 整合

在 PR Template 加入：

## Architecture Changes
- [ ] 如有架構變更，已更新 `workspace.dsl`
- [ ] `structurizr validate` 通過
- [ ] 架構圖已重新渲染並附加到 PR

GitHub Action / Azure Pipeline 在 PR 時自動檢查：

# 檢查 DSL 是否有變更
- script: |
    git diff --name-only origin/main | grep -q "workspace.dsl" && \
    echo "Architecture changed - validate DSL" && \
    structurizr validate workspace.dsl || \
    echo "No architecture changes"

5. 與 ADR 結合

// 在 DSL 註解標記 ADR
// ADR-001: 使用 Event Driven 架構
// ADR-002: 資料庫選用 PostgreSQL
softwareSystem = softwareSystem "E-Commerce Platform" {
    api = container "API Gateway" "REST API" "Spring Boot"
    // ADR-003: API Gateway 使用 Spring Cloud Gateway
}

6. Best Practices

  • DSL 放在專案根目錄 architecture/ 或 docs/architecture/
  • 使用模組化 !include 管理大型架構
  • 每次架構變更必須更新 DSL
  • 團隊定期做 Architecture Review，以 DSL 為基準
  • 將架構圖嵌入 README 或 Wiki

7. 參考資源