Web 框架路由感知與 AST 剖析 · Codegraph

為什麼要進行 Web 框架感知？

在一般的後端應用程式中，前端 HTTP 請求流（如 GET /orders/123）是如何觸發後端程式碼的？這通常是透過 Web 框架的路由機制（如 Django 的 urls.py、Express 的 app.get()、或者 FastAPI 的 @app.get() 裝飾器）來進行映射。

傳統的靜態分析工具只關心程式語言級別的「類別 (Class) 與方法 (Method) 關係」，卻完全不懂這些「網路路由裝飾器」的語意。當一個前端 SPA 嘗試呼叫一個後端 API 時，AI 助手無法從圖譜中看出 HTTP 路由與實體 Controller 之間的關聯，這形成了「網路調用邊界 (Network Boundary)」的認知盲區。

Codegraph 引入了 框架感知引擎 (Framework-Aware Routing Engine)，專門為解決跨網路邊界的依賴追蹤而生。

框架路由解析原理

Codegraph 的底層解析器包含一組針對 17 種主流 Web 框架的特徵規則庫（Framework Signatures）：

 ┌──────────────────────┐   Decorators    ┌──────────────────────┐
 │   HTTP Request       ├────────────────▶│   FastAPI / Django   │
 │   GET /api/v1/user   │                 │   Framework Engine   │
 └──────────────────────┘                 └──────────┬───────────┘
                                                     │ AST 屬性識別
                                                     ▼
 ┌──────────────────────┐   圖譜綁定邊     ┌──────────────────────┐
 │    Controller.ts     │◀────────────────┤    @app.get() Node   │
 │    getUser() Method  │   ROUTE_LEADS_TO│    (Route Endpoint)  │
 └──────────────────────┘                 └──────────────────────┘

裝飾器屬性識別 (Decorator AST Parsing)：
當 Tree-sitter 解析到特定的語法結構（如 Python 中的 @app.post("/users")），Codegraph 的 AST 分析器會自動提取出該節點的兩個核心屬性：http_method (“POST”) 與 route_path (“/users”)。
控制器綁定 (Controller Binding)：
解析器會定位被該裝飾器修飾的方法（如 def create_user），並在圖譜中自動建立一條 ROUTE_LEADS_TO 的關係邊，將「HTTP 路由節點」與「實體方法節點」強綁定。
路由拓撲樹生成：
對於 Django 這類將路由集中定義在 urls.py 中的框架，Codegraph 會自動追蹤 path('orders/', include('orders.urls')) 的遞歸包含關係，並在圖中生成一顆階層式的「路由樹」，從而將整個 Web API 的曝露面清晰繪出。

支援的 17 種主流 Web 框架

Codegraph 內置了對以下語言與框架路由的開箱即用支援：

Python：FastAPI, Django, Flask, Sanic, Tornado
TypeScript / JavaScript：Express, NestJS, Koa, Fastify, Next.js API Routes
Go：Gin, Echo, Fiber, Chi
Rust：Actix-web, Axum, Rocket

藉由這項感知能力，AI 助手在查詢 codegraph_explore 時，可以穿透 HTTP 邊界，直接指出「前端的 axios 呼叫點是通過哪一個 Web 路由與哪一個後端 Controller 方法進行對接」，實現真正的全棧依賴可視化。