🚀 Go代碼圖
Go代碼圖是一款強大的Go代碼庫分析工具,它能將代碼轉化為可探索的圖形,藉助模型上下文協議(MCP)使AI助手能夠理解複雜的代碼庫。
🚀 快速開始
藉助MCP快速上手
1. 使用Docker進行設置(推薦)
git clone https://github.com/brutski/go-code-graph.git
cd go-code-graph
make dev-setup
2. 配置Claude桌面端
make generate-mcp-config
將輸出內容複製到Claude桌面端的配置文件中:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%\Claude\claude_desktop_config.json
- Linux:
~/.config/Claude/claude_desktop_config.json
3. 開始與AI一同使用
此時MCP服務器已準備就緒!你的AI助手可以分析任何Go代碼庫。
傳統使用方式(不使用MCP)
make build
./bin/analyze -repo=. -output=graph.json
./bin/server -graph=graph.json -port=8080
./bin/import-neo4j -graph=graph.json -clear
✨ 主要特性
- 🔍 深度代碼分析:從Go抽象語法樹(AST)中提取9種節點類型和12種關係類型。
- 🎨 交互式可視化:Web界面可處理4000多個節點,並支持即時過濾。
- 🧠 基於AI的理解:MCP服務器支持通過自然語言對代碼進行查詢。
- 📊 圖數據庫:集成Neo4j,用於複雜的架構分析。
- 🚀 企業級規模:已在包含97個包和4000多個節點的代碼庫上成功測試。
- ⚡ 語義搜索:可選的嵌入功能,用於增強代碼理解。
📦 安裝指南
藉助MCP快速上手
1. 使用Docker進行設置(推薦)
git clone https://github.com/brutski/go-code-graph.git
cd go-code-graph
make dev-setup
2. 配置Claude桌面端
make generate-mcp-config
將輸出內容複製到Claude桌面端的配置文件中:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%\Claude\claude_desktop_config.json
- Linux:
~/.config/Claude/claude_desktop_config.json
傳統使用方式(不使用MCP)
make build
💻 使用示例
基礎用法
git clone https://github.com/brutski/go-code-graph.git
cd go-code-graph
make dev-setup
make generate-mcp-config
make build
./bin/analyze -repo=. -output=graph.json
./bin/server -graph=graph.json -port=8080
./bin/import-neo4j -graph=graph.json -clear
高級用法
MCP工具和提示
MCP服務器提供了兩種分析代碼庫的方式:
MCP提示(引導式工作流程)
MCP服務器包含15個全面的提示,可引導你完成常見的分析任務。這些提示會明確告知AI助手使用哪些工具以及使用順序,確保遵循最佳實踐並實現全面覆蓋。詳細文檔請參閱 MCP提示指南。
示例提示:
analyze_new_codebase
- 完成初始分析並提供架構概述
assess_code_quality
- 進行全面的質量評估並提供可操作的見解
analyze_change_impact
- 在進行更改之前瞭解影響
debug_execution_flow
- 跟蹤執行路徑以進行調試
plan_refactoring
- 獲取逐步的重構指導
何時使用提示:開始新的分析任務、遵循最佳實踐、確保全面覆蓋。
MCP工具(構建塊)
MCP服務器提供了8個強大的工具,可直接用於代碼庫分析。這些工具是提示所使用的構建塊,但你也可以直接使用它們進行特定查詢和自定義探索:
🔍 analyze_workspace
將Go代碼庫導入並分析到圖數據庫中。
- 何時使用:初始設置或更新代碼庫分析
- 支持:選擇性包含外部依賴項
- 示例用法:
{
"workspacePath": "/path/to/project",
"workspaceName": "my-project",
"incremental": false,
"allowedPackages": [
"github.com/gin-gonic/gin/...",
"github.com/neo4j/neo4j-go-driver/v5"
]
}
💬 natural_query
將自然語言問題轉換為圖查詢。
- 何時使用:探索代碼庫結構和關係
- 示例問題:
- "哪些是最複雜的函數?"
- "哪些結構體的字段最多?"
- "顯示未使用的接口"
- "哪些包依賴於認證模塊?"
- "哪些函數處理錯誤?"
🔗 cypher_query
直接訪問圖數據庫以進行復雜查詢。
- 何時使用:需要進行自定義圖遍歷的高級分析
- 示例用法:查找循環依賴、分析調用鏈、自定義指標
📊 analyze_impact
分析更改某個組件會影響哪些部分。
- 何時使用:在進行重構或重大更改之前
- 示例問題:"如果我更改ProcessOrder函數的簽名,會有什麼影響?"
🎯 find_patterns
檢測代碼庫中的代碼模式和反模式。
- 何時使用:代碼質量評估、查找技術債務
- 模式類型:重複函數、高複雜度、上帝對象、未使用的代碼
🔌 find_implementers
查找實現給定接口的所有類型。
- 何時使用:理解接口使用和多態性
- 示例:"哪些類型實現了io.Writer接口?"
🛤️ trace_call_path
查找兩個函數之間的執行路徑。
- 何時使用:理解組件之間的連接方式
- 示例:"main()函數如何調用SaveToDatabase函數?"
🏗️ detect_architecture
分析架構模式和層次結構。
- 何時使用:理解系統設計和結構
- 分析類型:層檢測、模式識別
何時直接使用工具:特定查詢、交互式探索、自定義分析工作流程。詳細比較請參閱 工具與提示指南。
📚 詳細文檔
如需詳細信息,請參閱文檔目錄:
- 技術架構:系統設計、組件和嵌入
- MCP工具參考:詳細的工具文檔及示例
- MCP提示指南:全面的提示,用於引導式分析
- 工具與提示:何時使用工具和提示
- 實際使用指南:常見工作流程和最佳實踐
- Docker MCP設置:詳細的Docker部署指南
🔧 技術細節
測試和開發
測試腳本
scripts/
目錄包含用於測試和開發的實用腳本:
- test-mcp-tool.sh:使用自定義參數測試單個MCP工具
- test-mcp-tools.sh:對所有MCP工具進行全面測試
- setup-test-workspace.sh:初始化並分析用於測試的工作區
示例用法:
./scripts/test-mcp-tool.sh natural_query go-code-graph '{"question":"What are the most complex functions?"}'
./scripts/test-mcp-tools.sh go-code-graph
./scripts/setup-test-workspace.sh my-project /path/to/project
運行測試
make test
make test-coverage
go test ./internal/analyzer -v
分析外部依賴項
默認情況下,分析器僅包含模塊中的包,以保持圖形的聚焦和可管理性。但是,你可以選擇性地包含外部依賴項,以瞭解代碼與第三方庫的交互方式。
為何包含外部包?
- API使用:確切瞭解如何使用第三方庫
- 集成點:識別與外部代碼的所有接觸點
- 調用鏈:跟蹤包括外部調用在內的完整執行路徑
- 接口實現:查看代碼實現了哪些外部接口
命令行用法
在 analyze
命令中使用 -include-packages
標誌:
./bin/analyze -repo=. -output=graph.json \
-include-packages="github.com/gin-gonic/gin/..."
./bin/analyze -repo=. -output=graph.json \
-include-packages="github.com/gin-gonic/gin,github.com/stretchr/testify/assert"
./bin/analyze -repo=. -output=graph.json \
-include-packages="github.com/sirupsen/logrus,golang.org/x/sync/..."
MCP用法
在使用MCP服務器與AI助手時,在 analyze_workspace
工具中指定外部包:
{
"workspacePath": "/path/to/project",
"workspaceName": "my-project",
"incremental": false,
"allowedPackages": [
"github.com/gin-gonic/gin/...",
"github.com/neo4j/neo4j-go-driver/v5"
]
}
或者直接告知AI助手:
- "分析 /path/to/project 幷包含 github.com/gin-gonic/gin"
- "分析時包含數據庫驅動包"
包模式
- 精確包:
github.com/sirupsen/logrus
- 僅包含此特定包
- 包含子包:
github.com/gin-gonic/gin/...
- 包含包及其所有子包
- 多個包:命令行中使用逗號分隔的列表,MCP中使用數組
示例用例
1. 數據庫驅動分析
./bin/analyze -repo=. -output=db-integration.json \
-include-packages="github.com/lib/pq,database/sql"
2. Web框架集成
./bin/analyze -repo=. -output=web-app.json \
-include-packages="github.com/gin-gonic/gin/...,github.com/gorilla/mux"
3. 內部共享庫
./bin/analyze -repo=. -output=full-analysis.json \
-include-packages="github.com/mycompany/shared-lib/...,github.com/mycompany/common/..."
最佳實踐
- 從小處著手:從最關鍵的依賴項開始
- 使用模式:
...
後綴可有效包含所有子包
- 監控大小:外部包會顯著增加圖形大小
- 關注接口:優先考慮實現了其接口的包
- 供應商目錄:如果使用供應商目錄,可以直接分析
./vendor/...
性能考慮
包含外部包會增加:
- 分析時間(需要解析更多包)
- 內存使用(更多節點和邊)
- 圖形複雜度(需要跟蹤更多關係)
- 可視化性能(需要渲染更多元素)
故障排除
包未找到:
- 確保包在
go.mod
中,或運行 go mod download
- 檢查確切的導入路徑是否與代碼中的一致
- 嘗試使用
go list
驗證包路徑
圖形過大:
- 更有選擇性地包含包
- 儘可能使用特定包而不是
...
- 考慮單獨分析外部包
示例自然語言查詢
向AI助手提出以下問題:
代碼質量
- "哪些是最複雜且需要重構的函數?"
- "查找參數過多的函數"
- "顯示可能存在過多職責的上帝對象"
架構理解
- "支付和訂單服務如何交互?"
- "主要的架構層次有哪些?"
- "哪些包存在循環依賴?"
影響分析
- "如果刪除User結構體,會有什麼影響?"
- "哪些服務依賴於認證模塊?"
- "查找所有調用已棄用API的地方"
代碼模式
- "查找重複的函數實現"
- "哪些接口只有一個實現?"
- "顯示未使用的私有函數"
開發支持
- "理解此服務的主要入口點有哪些?"
- "哪些函數會啟動goroutine?"
- "查找所有錯誤處理模式"
外部依賴項(使用 -include-packages 進行分析時)
- "我們的代碼如何使用wp-golang-packages庫?"
- "我們實現了哪些外部接口?"
- "顯示所有對數據庫驅動的調用"
📄 許可證
本項目採用MIT許可證,詳細信息請參閱 LICENSE 文件。
📦 系統要求
- Docker(用於Neo4j和MCP服務器)
- Go 1.24+(用於本地開發)
- 兼容MCP的客戶端(Claude桌面端或其他MCP客戶端)