隨記

jQAssistant 導入指引

導入效應

效應 說明
架構可視化 將整個程式碼轉成 Graph Database，用 Cypher 查詢架構違規
循環依賴偵測 透過 Graph 查詢精準找出 Circular Dependency
Forbidden Dependency 定義「哪些 package 不該依賴哪些 package」，違反即報錯
Spring Layer 驗證 自動識別 Spring Bean 類型，驗證 Controller/Service/Repository 分層
Architecture Audit 提供 Dashboard 視覺化架構違規，適合 Architecture Review Meeting
AI 產碼深度檢查 比 ArchUnit 更強的跨模組/跨 API 依賴分析

1. 安裝

1.1 Maven Plugin

<plugin>
    <groupId>org.jqassistant.plugin</groupId>
    <artifactId>jqassistant-maven-plugin</artifactId>
    <version>2.1.1</version>
    <configuration>
        <rulesDirectory>${project.basedir}/src/test/jqassistant</rulesDirectory>
    </configuration>
    <executions>
        <execution>
            <id>default-cli</id>
            <goals>
                <goal>scan</goal>
                <goal>analyze</goal>
            </goals>
        </execution>
    </executions>
</plugin>

1.2 Gradle Plugin

plugins {
    id 'org.jqassistant.plugin' version '2.1.1'
}

jqassistant {
    rules {
        directories = ['src/test/jqassistant']
    }
}

2. 基本使用

2.1 掃描專案

# Maven
mvn jqassistant:scan jqassistant:analyze

# 只掃描
mvn jqassistant:scan

2.2 Cypher 查詢範例

查詢循環依賴

MATCH (a)-[:DEPENDS_ON*2..]->(a)
RETURN DISTINCT a.name, a.fqn

查詢 Forbidden Dependency

MATCH (c:Class)-[:DEPENDS_ON]->(t:Class)
WHERE c.package <> t.package
  AND c.fqn CONTAINS '.controller.'
  AND t.fqn CONTAINS '.repository.'
RETURN c.fqn AS source, t.fqn AS target

驗證 Spring Layer

MATCH (s:SpringService)
RETURN s.fqn

查詢 God Class（方法數過多）

MATCH (c:Class)-[:HAS_METHOD]->(m:Method)
WITH c, count(m) AS methodCount
WHERE methodCount > 30
RETURN c.fqn, methodCount
ORDER BY methodCount DESC

3. Rules 檔案

3.1 建立 rules 規則

在 src/test/jqassistant/ 建立 .xml 規則檔：

<?xml version="1.0" encoding="UTF-8"?>
<jqassistant-rules xmlns="https://www.jqassistant.org/schema/rule">
    <group name="custom-rules">
        <constraint id="custom:NoControllerToRepository">
            <description>Controller 不應直接依賴 Repository</description>
            <cypher>
                MATCH (c:Class)-[:DEPENDS_ON]->(r:Class)
                WHERE c.fqn CONTAINS '.controller.'
                  AND r.fqn CONTAINS '.repository.'
                RETURN c.fqn, r.fqn
            </cypher>
        </constraint>
        <concept id="custom:SpringLayerCheck">
            <description>列出所有 Spring Service</description>
            <cypher>
                MATCH (s:SpringService)
                RETURN s.fqn
            </cypher>
        </concept>
    </group>
</jqassistant-rules>

3.2 Rule 執行

mvn jqassistant:analyze -Djqassistant.group.include=custom-rules

4. CI 整合

# azure-pipelines.yml
- stage: ArchitectureAudit
  jobs:
    - job: jQAssistant
      steps:
        - task: Maven@4
          inputs:
            goals: 'jqassistant:scan jqassistant:analyze'
            options: '-Djqassistant.group.include=custom-rules'
        - task: PublishTestResults@2
          condition: failed()
          inputs:
            testResultsFiles: '**/jqassistant-report.xml'

5. Dashboard

jQAssistant 提供 Neo4j Browser 整合：

# 啟動 Neo4j Browser 查詢
mvn jqassistant:scan
mvn jqassistant:server
# 開啟 http://localhost:7474

6. 與 ArchUnit 差異比較

特性 ArchUnit jQAssistant
執行方式 Unit Test 獨立分析工具
查詢語言 Java API Cypher (Graph Query)
視覺化 無 Neo4j Graph
分析深度 模組內為主 跨模組/跨 API
學習曲線 低 中（需學 Cypher）
CI 整合 簡單 需額外配置

7. 參考資源