故障排除
当生成文件缺失或 route/type 缺失时，依次检查设置和支持代码的形状。
确认顺序
• 检查 @Profile("local") 是否包含在实际执行的配置文件中。
• 确保 runner.start() 在本地控制台中没有抛出异常。
• 检查 rootPath、routerPackage、entityPackage、handlerOutputDir 在点/斜杠转换后是否位于正确的位置。
• 确保生成的源目录包含在 IDE 和构建工具的源集内。
• 将外部公共模块类型添加到反编译的 jar 类或源类路径中。
• 确保 RouterFunction 支持流式路由/嵌套和处理方法引用的形式。
点路径与斜杠路径
配置在多个路径输入中将 . 规范化为 /。可以混合使用包字符串和文件系统路径，但需要确认将完整输出路径如 src.main.java.com.example... 与仅输入 com.example... 包的设置之间的差异。
复现路径配置
import com.byeolnaerim.watch.route.HandlerGenerator;
var handlerConfig = HandlerGenerator.Config.builder()
.rootPath("src/main/java")
.routerPackage("com.example.web.router")
.handlerPackage("com.example.web.handler")
.handlerOutputDir("src/main/java/com/example/web/handler")
.build();
System.out.println(handlerConfig.routerDir());
// src/main/java/com/example/web/router/在项目根目录运行，确认输出的 routerDir 包含路由源文件。若在 routerPackage 中包含 src/main/java，路径会重复。将此配置传入 runner 的 handlerConfig，然后按 Quick Start 使用 local profile 运行。handlerPackage 是 Java 包名，handlerOutputDir 是实际输出目录。
test -d src/main/java/com/example/web/router
find src/main/java/com/example/web/handler -name '*.java'
# Quick Start swaggerOutputFile:
test -s src/main/resources/static/swagger.json若路径正确却没有输出，先检查 runner.start() 的第一个异常。用一个包含 handler::method 引用的最小路由复现，确认生成文件后再加入原有路由。不能仅因 swagger.json 存在就认为正确：请将 paths 中的请求路径和 HTTP method 与实际响应契约进行核对。
无限重生
Swagger 写入器仅在内容更改时写入文件。即使如此，如果发生重复生成，请检查输出文件是否包含在 watchDirectory 中，格式化程序或其他监视器是否持续更改生成的源。