Understand-Anything 的 Gin 框架分析附录为 Go/Gin 项目生成高质量知识图谱的完整规则集【免费下载链接】Understand-AnythingGraphs that teach graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.项目地址: https://gitcode.com/GitHub_Trending/un/Understand-AnythingUnderstand-Anything 的/understand技能在分析 Go 项目时会依据go.mod自动检测 Gin 框架并把一份名为gin.md的“框架附录”注入到 file-analyzer 与 architecture-analyzer 两个分析子代理的提示词中。本文完整解读这份附录——它定义了 Gin 项目的规范文件角色与标签体系、四类图边edge识别模式、七层架构划分以及应写入languageLesson的六个 Go/Gin 惯用法——并结合插件核心包的检测注册源码FrameworkRegistry、ginConfig说明这些规则是如何被触发、注入和验证的帮助你在自己的 Gin 项目中理解并复核自动生成的knowledge-graph.json。一、定位一份被注入的“附加规则”而非独立提示词gin.md 开头就明确了自身的使用约束Injected into file-analyzer and architecture-analyzer prompts when Gin is detected. Do NOT use as a standalone prompt — always appended to the base prompt template.也就是说它不是一份可以单独执行的提示词而是在检测到 Gin 时追加到基础提示词模板之后的补充规则用于在通用分析规则之上叠加 Gin 的目录惯例与语义模式。1.1 Gin 是如何被检测到的框架检测由核心包中的FrameworkRegistry完成。Gin 的检测配置定义在 gin.tsexport const ginConfig { id: gin, displayName: Gin, languages: [go], detectionKeywords: [github.com/gin-gonic/gin], manifestFiles: [go.mod], promptSnippetPath: ./frameworks/gin.md, entryPoints: [main.go, cmd/server/main.go], layerHints: { handlers: api, routes: api, models: data, middleware: middleware, services: service, repository: data, }, } satisfies FrameworkConfig;从源码结构看检测逻辑位于 framework-registry.ts 的detectFrameworks方法它接收“文件名 → 文件内容”的映射对每个已注册框架按manifestFiles在映射中查找go.mod支持 basename 匹配与路径/go.mod结尾匹配将内容转小写后逐个匹配detectionKeywords只要go.mod中出现github.com/gin-gonic/gin即判定项目使用 Gin。该匹配不区分大小写且对同一框架去重detected集合保证多个清单文件命中时只返回一次。promptSnippetPath: ./frameworks/gin.md这一字段把检测结果与本文档关联起来扫描阶段输出框架名后主流程按./frameworks/framework-id-lowercase.md的规则读取附录文件gin正好是小写 id。SKILL.md 在 Phase 4ARCHITECTURE中描述了这一注入流程对 Phase 1 检测到的每个框架读取frameworks/目录下对应文件将全文追加在语言上下文languages/language-id.mdGin 项目对应go.md之后若文件不存在则静默跳过。附录中的全部规则下文第二至四节正是随这一步进入 architecture-analyzer 的提示词同理它也被注入 file-analyzer 的提示词指导节点标签与图边的生成。ginConfig中还包含两个辅助字段可视为附录规则的机器可读映射entryPoints: [main.go, cmd/server/main.go]—— 与附录中main.go/cmd/*.go作为entry-point的角色约定一致layerHints—— 目录名到层的提示handlers→api、models/repository→data等与附录的“Architectural Layers”表格相互印证。Gin 是内置 10 个框架配置之一全部注册入口见 frameworks/index.ts 的builtinFrameworkConfigs数组。测试用例 framework-registry.test.ts 断言了createDefault()恰好注册 10 个框架且 Go 语言至少关联 1 个框架即 Gin覆盖了检测大小写不敏感、无匹配返回空数组、多清单去重等行为。二、规范文件角色Canonical File Roles 与标签约定附录的第一张表规定了分析 Gin 项目时“什么文件扮演什么角色”以及应赋予节点的标签tags。完整继承如下13 条文件模式文件 / 模式角色标签main.go应用入口 —— 初始化 Gin 引擎、注册路由、启动服务器entry-point、configcmd/*.go、cmd/**/*.goCLI 入口 —— 多命令项目中的多个二进制entry-point、confighandlers/*.go、handler/*.goHTTP 处理器 —— 使用gin.Context处理请求api-handlercontrollers/*.go、controller/*.go控制器 —— HTTP 处理器的另一种命名api-handlerroutes/*.go、router/*.go路由定义 —— 注册端点与路由组routing、configmodels/*.go、model/*.go数据模型 —— 映射到数据库表的 struct 定义data-modelmiddleware/*.go中间件函数 —— 认证、日志、CORS、限流middlewareservices/*.go、service/*.go业务逻辑 —— 与 HTTP 层解耦的领域操作servicerepository/*.go、repo/*.go数据访问层 —— 数据库查询与持久化逻辑data-model、serviceconfig/*.go、config.go应用配置 —— 环境加载、基于 struct 的配置configdto/*.go数据传输对象 —— 请求与响应 structtype-definitionutils/*.go、pkg/*.go共享工具包utility*_test.go单元与集成测试test这些标签并非附录自创而是 file-analyzer 标签词表的一部分。file-analyzer.md 中列出的代码文件候选标签正是entry-point、utility、api-handler、data-model、test、config、middleware、service、type-definition等并要求每个节点赋予 3–5 个小写连字符标签。附录的价值在于把标签选择从“LLM 自由裁量”收窄为“按目录惯例查表”例如cmd/下的main.go在 file-analyzer 的通用规则里本就被判定为entry-point“Namedmain.goincmd/directory entry-point(Go binary)”附录进一步要求它同时带config标签因为它还承担“初始化引擎、注册路由”的配置职责。对节点 ID 的约束同样来自 file-analyzerGin 项目中这些文件生成的节点将使用file:handlers/user.go、function:handlers/user.go:CreateUser、class:models/user.go:User这类严格前缀格式*_test.go与生产文件之间应生成tested_by边方向统一为production → test由合并脚本merge-batch-graphs.py规范化。三、四类图边模式Route Group、Handler→Service、Service→Repository、Middleware Chaining附录的第二部分定义了 Gin 项目特有的四条“边模式”edge patterns即 file-analyzer 在语义分析阶段应主动识别的跨文件关系。逐条说明如下并补充各边类型在 file-analyzer.md 边类型表中的标准权重3.1 Route group registration ——configures边当r.Group(/api)创建路由组并注册处理器时从路由定义文件到每个处理器创建configures边。路由组按前缀组织端点并共享中间件。边类型configures依赖类权重 0.6语义routes/或router/下的文件“配置”了它挂载的每个 handler。例如file:routes/v1.go→file:handlers/user.go。注意这不同于结构性的imports边权重 0.7由扫描器预解析的batchImportData逐条 1:1 发射configures表达的是“路由文件把某处理器挂到某前缀下”这一框架级语义。3.2 Handler-to-service calls ——depends_on边当 handler 函数调用 service 方法时从 handler 到 service 创建depends_on边表示 HTTP 处理与业务逻辑的分离。边类型depends_on依赖类权重 0.6file-analyzer 定义为“比 imports 更宽泛的运行期依赖”语义handlers/user.go→services/user_service.go。这条边是理解 Gin 分层架构的关键沿它向下即可追溯“请求进来到业务逻辑”的调用链。3.3 Service-to-repository calls ——depends_on边当 service 调用 repository 方法做数据访问时从 service 到 repository 创建depends_on边表示数据访问抽象。语义services/user_service.go→repository/user_repo.go。与上一条边串起来图上一眼可见handlers → services → repository的三层数据流这正是 Gin 社区最常见的分层写法。3.4 Middleware chaining —— middleware 边当r.Use(middleware)或路由组应用中间件时从 router 或 group 到中间件函数创建 middleware 边。中间件按注册顺序执行。边类型middleware行为类边见 SKILL.md 末尾的 KnowledgeGraph Schema 参考Behavioral 类包含calls、subscribes、publishes、middleware语义file:main.go或file:routes/v1.go→file:middleware/auth.go。它把“认证/日志/CORS 中间件挂在哪条路由链上”这一信息显式化配合附录 languageLesson 中“中间件按注册顺序执行”的说明可以在图谱中还原 Gin 的中间件链。这四类模式与核心 schema 是闭环的边类型表共 26 种configures、depends_on、middleware均在其中且权重约定固定depends_on/configures为 0.6middleware走默认 0.5保证了不同分析者产出的图可以统一比较与合并。四、Gin 架构七层Architectural Layers 与检测佐证附录的第三张表规定了 Gin 项目节点应被划分的架构层。完整继承如下7 层层 ID层名放入哪些内容layer:apiAPI 层handlers/、controllers/、HTTP 处理器函数layer:data数据层models/、repository/、数据库访问、迁移layer:service服务层services/、业务逻辑layer:middleware中间件层middleware/、认证、日志、限流layer:config配置层main.go、routes/、config/、环境配置layer:utility工具层utils/、pkg/、共享辅助包layer:test测试层*_test.go、测试 fixture、测试辅助代码这张表与两个上游机制严格对齐层 ID 格式architecture-analyzer.md 要求层 ID 统一使用layer:kebab-case格式其中明确列出的可选值就包含layer:api、layer:service、layer:data、layer:middleware、layer:utility、layer:config、layer:test——与附录七层一一对应因此附录给出的不是“建议命名”而是可直接落地的合法 ID。目录模式先验architecture-analyzer 的 Phase 1 结构分析脚本会做“Directory Pattern Matching”其内置模式表中handlers、routes、controllers归为apimiddleware归为middlewareservices归为servicemodels/repository归为datapkg归为utilitycmd归为entry。附录的七层表相当于把这个通用先验实例化为 Gin 方言例如handlers/与handler/单复数都算repo/与repository/都算再叠加ginConfig.layerHints的机器可读映射。层划分结果最终写入$UA_DIR/intermediate/layers.json并经过 SKILL.md Phase 4 的规范化步骤解包 envelope、nodes→nodeIds字段改名、缺失 ID 合成layer:kebab-case-name、裸路径转file:前缀、剔除悬空引用后进入最终knowledge-graph.json。每个文件节点必须恰好属于一层所有nodeIds之和必须等于文件节点总数——这是 architecture-analyzer.md 的硬性约束附录的七层设计API/数据/服务/中间件/配置/工具/测试正是让典型 Gin 项目能够无遗漏地完成这次全量划分的依据。五、languageLesson 六模式写进知识图谱的 Go/Gin 惯用法附录的最后一节要求把以下六个模式捕获进 tour 步骤的languageLesson字段SKILL.md Phase 5 规定tour[*].languageLesson是允许保留的可选字符串字段。这六条是帮助读者真正读懂 Gin 代码的教学要点逐条说明带gin.Context的处理器函数每个 Gin handler 都接收*gin.Context参数——它提供请求解析c.Bind、c.Param、c.Query、响应写出c.JSON、c.HTML与控制流c.Abort、c.Next。基于c.Next()的中间件链中间件调用c.Next()把控制权交给链上下一个 handler——c.Next()之前的代码在 handler 前执行pre-handler之后的代码在 handler 后执行post-handler。面向模块化 API 的路由分组r.Group(/v1)创建可拥有独立中间件栈的模块化子路由——在组级别实现版本管理与访问控制。构造函数式依赖注入无框架 DIGo 没有 DI 框架——依赖通过构造函数参数传入如NewUserHandler(userService)并存储为 struct 字段。面向可测试性的接口驱动设计service 与 repository 以接口定义——handler 依赖接口从而可在测试中使用 mock 实现。基于gin.Error的错误处理Gin 通过c.Error(err)收集错误——中间件可在 handler 执行后检查c.Errors实现集中式错误日志与响应格式化。其中第 2 条与第 6 条共同解释了 Gin 中间件的“双向”模型c.Next()之前的逻辑在请求阶段运行之后的逻辑含检查c.Errors在响应阶段运行——这正是第四节 middleware 边在图中值得单列一类的语义基础。第 4、5 条则解释了为什么 Gin 项目的depends_on边handler→service→repository是可靠的架构信号依赖显式穿过构造函数与接口边界而非全局变量。六、端到端流程与验证从检测注入到图谱校验把上述证据串起来一个 Gin 项目运行/understand时与本文档相关的完整链路是Phase 1 SCANproject-scanner 扫描文件、检测语言与框架go.mod中出现github.com/gin-gonic/gin时FrameworkRegistry.detectFrameworks命中ginConfig。Phase 2 ANALYZEfile-analyzer 子代理在基础提示词上收到gin.md附录连同go.md语言上下文按“规范文件角色”打标签、按“四类边模式”生成configures/depends_on/middleware边imports 边仍由预解析的batchImportData1:1 发射*_test.go产生tested_by边。Phase 4 ARCHITECTUREarchitecture-analyzer 收到同一附录按七层表把每个文件节点划入layer:api/layer:data/layer:service/layer:middleware/layer:config/layer:utility/layer:test。Phase 5 TOURtour-builder 产出带可选languageLesson的学习步骤六个 Gin 惯用法即在此落位。Phase 6/7 REVIEW SAVE图经确定性校验或--review的 LLM 复核后写入$UA_DIR/knowledge-graph.json数据目录为.ua/遗留项目保留.understand-anything/dashboard 随后基于它提供探索界面。仓库中的测试为这条链路提供了可直接运行的验证点framework-registry.test.tsdetectFrameworks的大小写不敏感匹配、空清单返回空数组、多清单命中去重、createDefault()注册全部 10 个内置框架且 Go 语言至少含 1 个Ginconfig-schema.test.tsFrameworkConfigSchema要求每个框架的promptSnippetPath非空——这从 schema 层面保证了像gin.md这样的附录路径不会缺失每个被检测到的框架都一定能找到可注入的补充规则文件。七、使用与适用前提适用对象任意被 Understand-Anything 插件分析的 Go 项目。当且仅当go.mod内容匹配github.com/gin-gonic/gin不区分大小写时本附录才会被注入纯标准库或其他框架如 Echo、Chi项目不会触发 Gin 规则promptSnippetPath对应的文件也不会被读取。运行方式在 Gin 项目根目录执行/understand首次运行需 Node.js ≥ 22 与 pnpm ≥ 10 构建核心包增量更新时 Phase 4 会在全量合并节点集上重跑架构分析层划分随之保持一致注入既有层定义以维持命名稳定。规则边界附录中的目录模式handlers/、services/、repository/等是约定而非强制——Gin 项目完全可以采用不同的目录组织此时 file-analyzer 仍依赖目录先验 文件摘要/标签做兜底判断附录的作用是提升“社区主流布局”下图谱的标签、边与层的一致性。参考文件附录本体 gin.md、检测配置 gin.ts、注册与检测 framework-registry.ts、注入流程 SKILL.md、节点/边规则 file-analyzer.md 与 architecture-analyzer.md、层 ID 与目录模式表见 architecture-analyzer 的 Phase 1/“Layer ID Format” 章节。【免费下载链接】Understand-AnythingGraphs that teach graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.项目地址: https://gitcode.com/GitHub_Trending/un/Understand-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考