故障排除
當生成檔案不存在或 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 中，或格式化器或其他監視器是否不斷更改生成的源。