Understand-Anything Spring Boot 知识图谱分析附录：文件角色、边规则与分层映射详解

Understand-Anything Spring Boot 知识图谱分析附录文件角色、边规则与分层映射详解【免费下载链接】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本文围绕 Understand-Anything 插件中的 Spring Boot 框架附录framework addendum展开。它不是独立提示词而是在/understand分析流程检测到 Spring Boot 项目时被注入到 file-analyzer 与 architecture-analyzer 提示词中的领域知识层。读完本文你将完整掌握该附录定义的文件角色表、四类边edge识别规则、七层架构映射和 languageLesson 知识点并理解它与框架检测机制、提示词注入流程、层检测器之间的真实调用关系。一、框架附录是什么注入机制与触发时机spring.md 的开头声明了它的定位Injected into file-analyzer and architecture-analyzer prompts when Spring Boot is detected. Do NOT use as a standalone prompt — always appended to the base prompt template.也就是说这份附录是一份“领域知识补丁”它不单独驱动任何分析而是叠加大纲式的基线规则base prompt之上让通用代码分析器具备 Spring Boot 特有的语义理解能力。注入流程从检测到拼接在 SKILL.md 的 Phase 4ARCHITECTURE中组合提示词模板的构建顺序被明确定义为四步使用 architecture-analyzer.md 作为基础模板语言上下文注入对 Phase 1 检测到的每种语言读取./languages/language-id.md并追加在## Language Context标题下框架附录注入对 Phase 1 检测到的每种框架如Django、Spring Boot读取./frameworks/framework-id-lowercase.md例如./frameworks/spring.md并整体追加在语言上下文之后文件不存在时静默跳过输出语言注入若目标输出语言非英语再追加./locales/language-code.md的语言规范。这些frameworks/目录就位于 SKILL.md 同级目录下。Spring Boot 场景下实际生效的三份注入材料是语言侧的 java.mdjava/kotlin被检测到时框架侧的 spring.md 本身以及按需的 locale 文件。file-analyzer 的分析批次Phase 2同样会携带这些框架上下文使逐文件产出的节点标签tags与语义边与架构分层Phase 4使用同一套 Spring 语义保证图内部一致性。二、Spring Boot 是如何被检测到的附录的触发前提是“检测到 Spring Boot”。这个检测由 core 包的框架注册表完成配置源头是 spring.tsexport const springConfig { id: spring, displayName: Spring Boot, languages: [java, kotlin], detectionKeywords: [ spring-boot, spring-boot-starter, spring-web, spring-data, org.springframework, ], manifestFiles: [pom.xml, build.gradle, build.gradle.kts], promptSnippetPath: ./frameworks/spring.md, entryPoints: [**/Application.java, **/App.java], layerHints: { controller: api, service: service, repository: data, model: data, entity: data, config: config, dto: types, security: middleware, }, } satisfies FrameworkConfig;各字段的作用可以结合 framework-registry.ts 中的detectFrameworks实现来理解manifestFiles只检查 Maven/Gradle 三种构建清单文件pom.xml、build.gradle、build.gradle.kts。按文件名基名匹配支持带目录前缀的路径key.endsWith(/ manifestFile)。detectionKeywords对清单内容做小写化后的子串匹配命中spring-boot、spring-web、org.springframework等任一关键词即判定为 Spring Boot 项目。从源码结构看这是纯字符串匹配而非依赖解析因此 Gradle 中任意位置出现的org.springframework.*依赖坐标都能触发检测。promptSnippetPath指向./frameworks/spring.md即本文主角。core 包的配置模式测试config-schema.test.ts明确要求每个框架必须提供非空的promptSnippetPath并有测试断言“每个框架都有非空 promptSnippetPath”保证附录文件不会漏配。entryPoints**/Application.java、**/App.java被标记为项目入口点候选。这与 SKILL.md Phase 0 的入口点探测src/main/java/**/Application.java以及 architecture-analyzer 目录模式表中“名为Application.java的文件归入entry”的规则互相印证。layerHints把 Spring 常见包名后缀直接映射到层 ID例如controller → api、repository → data、security → middleware。这是比目录模式匹配更贴近 Spring 惯例的先验知识。框架注册表整体行为在 framework-registry.test.ts 中有系统验证检测大小写不敏感Django4.2与django4.2均可命中、多清单命中同一框架时去重、createDefault()注册 10 个内置框架且java语言下至少能取到 1 个框架即 Spring Boot。springConfig 通过 frameworks/index.ts 导出并进入builtinFrameworkConfigs。三、标准文件角色表Canonical File Roles附录的第一张表定义了 Spring Boot 项目中的文件命名惯例到图谱节点角色的映射是 file-analyzer 打标签和 architecture-analyzer 分层的直接依据。完整继承如下File / PatternRoleTags*Application.java,*Application.kt应用入口——含main()方法的SpringBootApplication类entry-point,config*Controller.java,*RestController.javaREST 控制器——处理 HTTP 请求委托给服务api-handler*Service.java服务接口——定义业务操作契约service*ServiceImpl.java服务实现——包含业务逻辑service*Repository.javaSpring Data 仓储——继承 JpaRepository/CrudRepository 的数据访问接口data-model*Entity.javaJPA 实体——通过Entity注解映射数据库表data-model*DTO.java,*Request.java,*Response.java数据传输对象——请求/响应载荷type-definition*Config.java,*Configuration.java配置类——ConfigurationBean、安全配置、Web 配置config*Filter.javaServlet 过滤器——在请求到达控制器之前拦截middleware*Interceptor.java处理器拦截器——控制器方法的前置/后置处理middleware*Advice.java,*ExceptionHandler.java控制器增强——全局异常处理与响应包装middleware*Mapper.java对象映射器——Entity 与 DTO 互转MapStruct、ModelMapperutilityapplication.yml,application.properties应用配置——profile、数据源、服务器设置config*Test.java,*Tests.java,*IT.java单元测试、集成测试test这些标签并非孤立存在而是 file-analyzer.md 标签词表中entry-point、api-handler、data-model、middleware、service、type-definition、utility、test等通用标签在 Spring 语境下的具体化规则。例如通用规则已经约定“文件名匹配*Test.java→test标签”而附录进一步补充了*IT.java集成测试这一 Java 特有惯例并明确了 Controller/Service/Repository 三类命名各自的语义分工。四、四类关键边规则Edge Patterns附录的第二部分告诉 file-analyzer在 Spring Boot 项目中哪些源码结构应当转化为知识图谱的边。这是把“Java 注解语义”翻译成“图拓扑”的核心规则。1. Autowired 依赖注入 →depends_on边Autowired injection— 当类通过Autowired、构造器注入或Inject注入依赖时从消费方consumer指向被注入 Bean 创建depends_on边。现代 Spring 中构造器注入优先且最常见。从源码结构看depends_on在 file-analyzer 的边类型表中定义权重为0.6、方向forward语义是“比 imports 更宽的运行期依赖”。Spring 的依赖注入正是这种非 import 依赖Bean 之间可能通过 XML、Bean方法或容器装配连接import语句未必完整反映真实依赖关系因此用depends_on而非imports表达注入关系是刻意的语义选择。2. Controller → Service → Repository 调用链 →depends_on边Controller-Service-Repository chain— 标准调用链是RestController→Service→Repository。沿这条链创建depends_on边以呈现分层架构。这条规则保证图谱能显式呈现 Spring 的经典三层调用骨架与第七节layer:api/layer:service/layer:data的分层结果相互对应——分层是静态归属边是动态关系两者叠加才能完整表达“层间依赖方向”。3. Entity 关联注解 → 实体间depends_on边Entity relationships— 当实体定义OneToMany、ManyToOne、OneToOne、ManyToMany注解时在实体类之间创建depends_on边并在描述中说明关系类型与方向。要求“描述中标明关系类型与方向”意味着边不只是一个连接符还携带OneToMany一对多这类领域语义为后续在仪表盘里回答“订单和用户是什么关系”这类问题提供依据。4. Configuration Bean 定义 →configures边Configuration bean definitions— 当Configuration类定义Bean方法时从配置类指向其产生的类型创建configures边。这些 Bean 在全应用中可被注入。configures同样是权重0.6的边类型在 file-analyzer 的非代码边表中用于“配置文件影响代码模块”这里被泛化到“配置类装配 Bean”。这条规则把 Spring IoC 容器的装配语义映射成了图上的“谁生产谁”关系。五、七层架构映射Architectural Layers附录的第三张表规定检测到对应文件模式时把节点归入下列层。完整继承如下Layer IDLayer NameWhat Goes Herelayer:apiAPI Layer*Controller.java、REST 端点、API 文档layer:serviceService Layer*Service.java、*ServiceImpl.java、业务逻辑layer:dataData Layer*Repository.java、*Entity.java、JPA 映射、数据库迁移layer:typesTypes Layer*DTO.java、*Request.java、*Response.java、共享值对象layer:configConfig Layer*Configuration.java、application.yml、安全配置、*Application.javalayer:middlewareMiddleware Layer*Filter.java、*Interceptor.java、*Advice.java、安全过滤器layer:testTest Layer*Test.java、*Tests.java、*IT.java、测试配置这份层表的 ID 命名layer:kebab-case与 architecture-analyzer.md 输出规范完全一致——后者要求每个层对象包含id、name、description、nodeIds四个必填字段ID 遵循layer:api、layer:service等格式。附录相当于为 Spring Boot 项目给出了这 3–10 层选择中的“参考答案”architecture-analyzer 的 Phase 2 语义指派会优先采用它与目录结构、导入方向等结构证据一致的层划分。两处实现细节进一步佐证了这套映射的落地位置目录模式表architecture-analyzer 的结构化分析脚本要求对目录名做模式匹配其中包含大量 Java/Spring 专属条目src/main/java → service、src/test/java → test、dto/request/response → types、entity → controller → api原文中entity归data、controller归api。附录的层表与这些模式互补目录模式看路径附录看文件名后缀两者交叉验证。启发式层检测器core 包的 layer-detector.ts 内置了一份LAYER_PATTERNS兜底映射如routes/controller/handler/endpoint/api → API Layer、middleware/interceptor/guard/filter/pipe → Middleware Layer当 LLM 层识别不可用时按目录段启发式归属未匹配的落入Core层。Spring 项目的controller/、service/、repository/、entity/包名恰好都能被这套模式捕获说明提示词附录与确定性回退逻辑在层命名上保持了对齐。六、languageLesson五个应写入图谱的知识点附录最后一节要求把以下 Spring 标志性模式捕获进languageLesson字段——该字段在知识图谱 schema 中是 tour 步骤的可选字符串字段见 schema.ts 的languageLesson: z.string().optional()在 dashboard 的 LearnPanel 中渲染给用户。这五条知识点定义了 Spring 项目的“教学内容下限”构造器注入优先Constructor InjectionSpring 偏爱构造器注入而非字段注入字段上的Autowired——它让依赖显式化、支持不可变性、并简化测试。分层架构Controller → Service → RepositorySpring Boot 应用遵循严格的分层模式控制器处理 HTTP服务承载业务逻辑仓储管理持久化。Spring Security 过滤器链安全被实现为一条 Servlet 过滤器链——SecurityFilterChainBean 配置认证、授权、CORS 与 CSRF 防护。JPA 实体生命周期实体经历 transient、managed、detached、removed 等状态迁移——理解该生命周期是追踪持久层数据流的前提。AOP 处理横切关注点Aspect类通过Before、After、Around通知在连接点织入行为——用于日志、事务Transactional与缓存Cacheable。从 tour-builder.md 的规范看languageLesson只在“真正有教育价值”时添加附录的这五条因此同时充当了 tour 生成阶段的知识点清单。dashboard 的 knowledge-graph.json 示例中已存在多条languageLesson实例可对照理解其呈现效果。七、小结附录在整条流水线中的位置把源码证据串起来这份 Spring 附录的完整生命周期是检测Phase 1 扫描得到pom.xml/build.gradle内容FrameworkRegistry.detectFrameworks按关键词命中spring配置framework-registry.ts注入Phase 2file-analyzer 批次与 Phase 4architecture-analyzer按 SKILL.md 的拼接规则把 spring.md 全文追加进提示词产出file-analyzer 依文件角色表打标签、依四类边规则生成depends_on/configures边architecture-analyzer 依七层表把节点归入layer:api…layer:test并与 springConfig 的layerHints、layer-detector 的目录模式互为印证呈现知识点落入 tour 的languageLesson最终经 dashboard 的 LearnPanel 渲染为可交互的学习内容。对使用者而言这意味着对一个 Spring Boot 项目运行/understand后生成的knowledge-graph.json会天然带有 Spring 语义Bean 装配关系、Controller-Service-Repository 分层骨架、实体关联方向都能直接查询若图里缺少某类边或层归属不符预期可以回到本文的三张表逐一核对文件命名是否命中了*Controller.java、*ServiceImpl.java等约定模式——这是该附录发挥作用的前提。【免费下载链接】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），仅供参考