CodeGraph 框架路由解析：从 URL 模式到 Handler 的 route 节点与 references 边

本文以 CodeGraph 官方文档《Framework Routes》为主体，系统讲解 CodeGraph 如何自动识别 Web 框架的路由声明，把它们转换成图中的 route 节点，并通过 references 边绑定到实际的 handler 类或函数。读完本文，你将了解覆盖 18 类框架的路由识别形态、detect → extract → resolve 的完整管线在源码中的具体实现，以及 route 节点被查询与验证的方式——这一切都是自动完成的，无需任何配置。

CodeGraph 对路由处理的核心机制可以概括为一句话：识别 Web 框架的路由文件，发出 route 节点，并用 references 边将其链接到提供该路由的 handler 类或函数；这样，查询某个视图或控制器的调用方（callers）时，绑定它的 URL 模式就会随之浮现。对 Agent 来说，这意味着回答"这个接口暴露在哪个 URL 上""改这个 handler 会影响哪些端点"这类问题时，不需要再靠 grep 路由表来拼凑答案。

支持的框架与识别形态

官方文档给出了 CodeGraph 可识别的完整框架清单。下表完整继承自 framework-routes.md，每一行的"识别形态"都能在对应的框架解析器源码中找到正则或扫描逻辑：

框架	识别的形态
Django	urls.py 中的 path()、re_path()、url()、include()（含 CBV 的 .as_view()、点分路径）
Flask	@app.route('/path', methods=[...])、blueprint 路由
FastAPI	@app.get(...)、@router.post(...)，覆盖所有标准 HTTP 方法
Express	带中间件链的 app.get(...)、router.post(...)
NestJS	@Controller + @Get/@Post/...、GraphQL 的 @Resolver + @Query/@Mutation、@MessagePattern/@EventPattern、@SubscribeMessage
Laravel	Route::get()、Route::resource()、Controller@action、元组语法
Drupal	*.routing.yml 路由（_controller、_form、实体 handler）；.module/.theme/.install/.inc 中的 hook_* 实现
Rails	get '/x', to: 'users#index'、hash-rocket => 语法
Spring	方法上的 @GetMapping、@PostMapping、@RequestMapping
Play	conf/routes 中的 GET/POST/… 动词路由 → Controller.method action（Scala + Java）
Gin / chi / gorilla / mux	r.GET(...)、router.HandleFunc(...)
Axum / actix / Rocket	.route("/x", get(handler))
ASP.NET	action 方法上的 [HttpGet("/x")] 特性
Vapor	app.get("x", use: handler)
React Router / SvelteKit	路由组件节点
Vue Router / Nuxt	pages/ 文件式路由、server/api/ 端点、路由中间件
Astro	src/pages/ 文件式路由（.astro 页面 + .ts 端点，含 [param]/[...rest] 语法）

这些解析器统一注册在框架解析器注册表中：src/resolution/frameworks/index.ts 的 FRAMEWORK_RESOLVERS 数组按 PHP、JavaScript/TypeScript、Python、Ruby、Java、Go、Rust、C#、Swift 等语言分组登记了 laravelResolver、drupalResolver、expressResolver、nestjsResolver、reactResolver、vueResolver、astroResolver、djangoResolver、flaskResolver、fastapiResolver、railsResolver、springResolver、goResolver、rustResolver、aspnetResolver、vaporResolver 等条目。注册表同时提供 getFrameworkResolver(name) 按名查找、detectFrameworks(context) 项目级探测、以及 registerFrameworkResolver() 供扩展注册的入口。

三段式管线：detect、extract、resolve

route 能力来自 src/resolution/types.ts 中 FrameworkResolver 接口定义的三个关键成员，这也是理解所有框架解析器行为的钥匙：

1. detect(context) —— 项目级框架探测，启动时调用一次，决定该项目启用哪些框架解析器。
2. extract?(filePath, content) —— 从单个文件中提取框架专属的节点与引用，返回 FrameworkExtractionResult（即 { nodes, references }），"框架专属节点（如 routes）"与"框架专属未解析引用（如 route → handler）"都在这里产出。
3. resolve(ref, context) —— 把 extract 产出的未解析引用落图：引用的常规解析管线会把框架自己的 resolve() 作为其中一种策略尝试；接口注释明确写道："Unresolved references flow into the normal resolution pipeline; the framework's own resolve() is one of the strategies tried."

此外还有两个值得注意的可选钩子：

• claimsReference?(name)：让某个引用名称绕过"无同名节点即丢弃"的预过滤。接口注释举例：Django 的 self._iterable_class(...) 是属性而非声明符号，必须靠这个钩子才能到达 resolve()。Laravel 用同一机制认领 Controller@method 形式的引用（见下文 PHP 一节）。
• postExtract?(context)：跨文件收尾遍，用于"符号的最终形态依赖兄弟文件"的框架，例如 NestJS 的 RouterModule.register([...]) 会为声明在别处的控制器补上路由前缀。实现必须保留节点 id 以维持既有边，且应保持 qualifiedName 幂等。

extract 的挂载点在主抽取流程中。src/extraction/tree-sitter.ts 的 extractFromSource() 函数头注释说明：当传入 frameworkNames 时，与文件名、文件语言匹配的框架专属提取器会在 tree-sitter 解析遍之后运行，其 nodes/references/errors 合并进返回结果。也就是说 route 节点与普通函数/类节点共享同一份图数据，且随索引/同步自动刷新——这正是文档所说"框架文件被识别后，其路由会在下一次索引或同步后出现在图中"的机制来源。

各框架解析器的实现细节

Python 系：Django、Flask、FastAPI

三个解析器同源于 src/resolution/frameworks/python.ts。

**项目探测（detect）**各不相同，可以理解为每个框架的"指纹"：

• Django：依次读取 requirements.txt、setup.py、pyproject.toml 是否含 django，最后兜底 fileExists('manage.py')；
• Flask：依赖清单中含 flask；或者在 app|application|main|wsgi|__init__.py 命名的入口文件（最多扫 50 个）中发现 import flask 与 Flask(...) 实例化——注释说明这覆盖 Flask(__name__) 与 app-factory 模式；
• FastAPI：依赖清单含 fastapi，或 app.py/main.py/api.py 中出现 FastAPI(。

Django 路由提取用的核心正则是：

const routeRegex = /\b(path|re_path|url)\s*\(\s*r?'"['"]\s*,\s*([\w.]+(?:\s*\([^)]*\))?)/g;

它捕获三个组：函数名（path/re_path/url）、URL 字符串、handler 表达式（允许一对平衡括号，以容纳 View.as_view() 或 include('x.y')）。匹配后生成 kind: 'route' 的节点，name 即 URL 路径，qualifiedName 为 ${filePath}::route:${urlPath}。handler 表达式交给 resolveHandlerName() 解析：include('module.path') 产出 imports 类型引用（被包含的 URLconf 由此对根 URLconf 记一条依赖）；其余情况先剥掉尾部 .as_view(...) 等调用，取点分名的最后一段作为 references 引用。

此外还有一条专门针对 DRF 的规则：router.register(r'articles', ArticleViewSet) 会产出 name 为 VIEWSET /articles 的 route 节点并引用该 ViewSet 类。源码注释解释了区分逻辑——第一个参数是字符串这一点把它与 admin.site.register(Model, Admin)（首参是类）分开，第二个参数的 View/ViewSet 后缀限定它只匹配 DRF viewset。

Flask 与 FastAPI 共用装饰器提取器 extractDecoratorRoutes()，二者只是正则与分组不同：

• Flask：@(\w+)\.route\(\s*'"'"]+)[\])])?\s*\)，默认方法 GET，方法可从 methods=[...] 列表中取出；
• FastAPI：@(\w+)\.(get|post|put|patch|delete|options|head)\(\s*'"['"]，方法名直接取自装饰器名（注释指出路径可为空字符串，表示挂载在 router/前缀根上）。

handler 的定位逻辑是 findHandler：在装饰器之后寻找下一个 \n\s*(?:async\s+)?def\s+(\w+)，从而兼容装饰器与 def 之间夹着 @login_required 等其它装饰器的情形。route 节点的 name 统一为 `${METHOD} ${routePath || '/'}` 形式，id 为 route:${filePath}:${line}:${method}:${routePath}——文件 + 行号 + 方法 + 路径构成确定性标识，保证增量同步时的幂等。

Flask 还额外覆盖 Flask-RESTful：extractFlaskRestful() 匹配 .add*Resource(Class, '/path', '/path2')，对每个路径产出 name 为 ANY /path 的 route 节点并引用资源类——注释说明 ResourceClass 持有 get/post/... 等动词方法，所以引用落在类上，具体 handler 经类可达。

框架侧 resolve 策略同样值得看：Django 解析器对 *Model、*View/*ViewSet、*Form 三类后缀引用，用 resolveByNameAndKind() 在约定目录（models/、views/、forms/ 等）中优先挑候选，命中则给 0.8 的置信度并以 resolvedBy: 'framework' 记边；FastAPI 对 *_router/router 变量和 Depends(...) 依赖项做同类处理（0.75 置信度）。

JavaScript/TypeScript 系：Express、NestJS 与前端路由

Express（src/resolution/frameworks/express.ts）的 detect 先看 package.json 的 dependencies/devDependencies 是否含 express/fastify/koa/hapi，再兜底扫描路径含 routes/controllers/middleware 的文件内容。提取时只匹配"路由头"：

const head = /\b(app|router)\.(get|post|put|patch|delete|all|use)\s*\(\s*'"['"]\s*,/g;

源码注释解释了为什么刻意不匹配整个调用：handler 常是内联箭头函数，res.json(...)、嵌套 } 会让整调正则失配，导致"内联 handler 路由连不上任何东西"。改为在 use 且路径不以 / 开头时跳过（把 app.use('/api', router) 这类挂载与路由区分开）。resolve 侧则处理中间件名（0.8 置信度）、XxxController.method（0.85）、XxxService/Helper/Utils.method（0.8）三类引用，并用 RESERVED_CALLS 集合把 res.json、req.body 等框架噪音调用排除在路由边之外。

NestJS（src/resolution/frameworks/nestjs.ts）的提取逻辑分四路：

• HTTP 路由：先用 buildClassScopes() 建立类作用域，@Get/@Post/... 装饰器所在行若落在 @Controller 作用域内，则把控制器前缀与方法装饰器路径拼接成完整路径（joinHttpPath(prefix, parseStringArg(hit.args))），handler 取装饰器后第一个方法名；
• GraphQL 操作：@Query/@Mutation/... 只在 @Resolver 作用域内生效——注释点明这是为了与 @Controller 类里同名的 REST 参数装饰器 @Query() 消歧；
• 微服务消息/事件：@MessagePattern/@EventPattern 产出 MESSAGE/EVENT 前缀的 route 节点；
• 路由节点统一经内部 addRoute() 生成，id 为 route:${filePath}:${line}:${method}:${path}。

跨文件的前缀补全（RouterModule.register([...])）则由接口中的 postExtract 钩子承担，见上文管线一节。

前端路由（React Router / SvelteKit / Vue / Nuxt / Astro）的语义不同：它们产出的是"路由组件节点"。测试 tests/frameworks.test.ts 展示了 React 解析器对多种写法的覆盖：

• v6 写法 <Route path="/users" element={<UsersPage/>}/> → route 名 /users，引用 UsersPage；
• v5 写法 <Route exact path="/login" component={Login} />（属性顺序任意）→ route 名 /login，引用 Login；
• <Routes> 容器本身不算路由；
• createBrowserRouter([{ path: "/dashboard", element: <Dashboard /> }, ...]) 对象式路由也能提取；
• 负例同样被测过：next.config.mjs 与 vite.config.ts 不会误报为 Next.js 路由，而真实的 src/pages/about.tsx 会产出 /about。

PHP 系：Laravel 与 Drupal

Laravel（src/resolution/frameworks/laravel.ts）的 detect 极其简单：artisan 文件或 app/Http/Kernel.php 存在即命中。路由提取正则 Route::(get|post|put|patch|delete|options|any)\s*\(\s*'"['"]\s*,\s*([^)]+)\) 捕获方法与 handler 表达式，handler 支持 [Class::class, 'method'] 元组、'Controller@method' 字符串、闭包、Class::class 等形态；Route::resource/apiResource 则产出 name 为 resource:<name> 的节点并引用控制器类。

Controller@action 引用是"名字不指向任何声明符号"的典型，靠 claimsReference(name) 钩子放行（正则 ^[A-Za-z_][\w]*Controller@\w+$），再由 resolve 的 Pattern 4 以 0.9 置信度解析到控制器方法——这是 FrameworkResolver 接口注释中专门点名的场景。文件顶部还导出一份 FACADE_MAPPINGS（Auth → Illuminate\Auth\AuthManager、Route → Illuminate\Routing\Router 等 20 余项），供门面解析复用；而 Auth::user() 这类门面调用本身会被识别为外部代码、返回 null，不在本地图上造虚节点。

Drupal 解析器（src/resolution/frameworks/drupal.ts）按文档所述覆盖 *.routing.yml（_controller、_form、实体 handler）与 hook_* 实现，仓库中另有专项测试 tests/drupal.test.ts 与之对应。

文件式路由：Vue/Nuxt 与 Astro

文件式路由的 route 节点不由语法匹配产生，而是由文件路径本身推导。以 Astro 为例（src/resolution/frameworks/astro.ts 的 extract）：

• 只处理 src/pages/ 下的 .astro/.ts/.js/.mjs 文件（.md/.mdx 页面存在但不作为源码索引）；
• 含下划线前缀路径段的文件被 Astro 排除出路由，解析器同样跳过；pages 目录下误放的 *.config.* 文件永不视为路由；
• 其余文件经 filePathToAstroRoute() 把 blog/index.astro → /blog、[param]/[...rest] 动态段转换为路由名，产出 startLine: 1 的 route 节点。

测试（frameworks.test.ts 中 astroResolver.extract — src/pages file-based routing 一节）确认了 index.astro → /、blog/index.astro → /blog、about.astro → /about 以及 [param]/[...rest] 的转换。

Vue/Nuxt 解析器（src/resolution/frameworks/vue.ts）按文档覆盖 pages/ 文件式路由、server/api/ 端点与路由中间件；detect 先看 package.json 是否含 vue/nuxt/@nuxt/kit，再兜底"是否存在 .vue 文件"。其 resolve 侧还内置了 Vue 3 编译器宏白名单（defineProps、defineEmits 等 7 项，自引用、置信度 1.0）与 Nuxt 自动导入集合（useRoute、navigateTo、useFetch、definePageMeta 等 30 余项），避免这些框架提供的标识符被误当成用户符号去重名匹配。

其它语言

Go（Gin/chi/gorilla/mux 及 GoFrame，src/resolution/frameworks/go.ts 与 goframe.ts）、Rust（Axum/actix/Rocket，rust.ts）、C#（[HttpGet("/x")] 特性，csharp.ts）、Java（Spring 注解 + Play conf/routes，java.ts 与 play.ts）、Swift（Vapor，swift.ts）与 Ruby（Rails，ruby.ts）的解析器均实现了同样的 extract 契约——search_in_files 检索 kind: 'route' 可在每个文件里看到一致的节点构造模式：route: 前缀的确定性 id、filePath::METHOD:path 形式的 qualifiedName、以及指向 handler 的 references 引用。

验证：route 能力如何被测试与查询

测试层。tests/frameworks.test.ts（1800 余行）按框架组织用例：React Router 五种形态、SvelteKit 冒烟、Astro 路径映射等；tests/explore-allocation-1500.test.ts 中还能看到断言 n.kind === 'route' 的用法，说明 route 节点会进入 explore 等上下文分配流程。专项测试还包括 tests/laravel-event-synthesizer.test.ts、tests/gin-middleware-chain.test.ts、tests/goframe.test.ts、tests/drupal.test.ts 等，与文档表格中的框架清单一一对应。

查询层。route 是一等查询目标：MCP 工具定义（src/mcp/tools.ts）把 route 列入可按 kind 过滤的节点类型枚举（'function', 'method', 'class', 'interface', 'type', 'variable', 'route', 'component'）。因此"查询某视图/控制器的调用方 → 浮现绑定它的 URL 模式"在工具层面是：对该 handler 节点取调用方，图中指向它的 route 节点自然出现在结果里；反向地按 kind: route 检索可列出全部端点，再顺着其 references 边定位 handler。

总结：零配置，随索引自动生效

回到文档结论：路由解析是全自动的，没有任何可配置项。项目里只要出现框架特征文件，route 节点就会在下一次索引或同步后进入图。把整条链路串起来看：

1. 探测——detectFrameworks() 对注册表中每个解析器跑 detect(context)，异常会被捕获并视为"未检出"，单个框架的探测失败不影响其它框架；
2. 提取——每个被索引文件走 extractFromSource()：tree-sitter 遍产出符号节点后，命中该语言的框架 extract() 追加 route 节点与 route→handler 引用；
3. 解析——引用进入常规解析管线，框架 resolve() 按后缀/前缀/目录约定策略落边，resolvedBy: 'framework' 标记边来源与置信度；
4. 收尾——需要跨文件信息的框架（如 NestJS 前缀补全）用 postExtract 做幂等修正，id 与 qualifiedName 的保留约束保证既有 route→handler 边不被破坏。

对使用 CodeGraph 的 Agent 而言，这套机制的价值在于把"URL 模式 ↔ handler"这对在静态调用图里天然缺失的关系补了回来：新增端点、排查接口变更影响面、回答"这个 URL 由哪段代码处理"，都可以在图上一跳到达，而不必再退回全文搜索路由文件。