{"record":{"id":"821dd88c7505cb00","repo":"dromara/Sa-Token","slug":"12401","errorCode":"12401","errorMessage":"未实现具体路由匹配策略","messagePattern":"未实现具体路由匹配策略","errorType":"exception","errorClass":"NotImplException","httpStatus":null,"severity":"error","filePath":"sa-token-core/src/main/java/cn/dev33/satoken/strategy/SaStrategy.java","lineNumber":184,"sourceCode":"\t/**\n     * 是否自动续期 active-timeout\n     */\n    public SaAutoRenewFunction autoRenew = (stpLogic) -> {\n        return stpLogic.getConfigOrGlobal().getAutoRenew();\n    };\n\n\t/**\n\t * 创建 StpLogic 的算法\n\t */\n\tpublic SaCreateStpLogicFunction createStpLogic = (loginType) -> {\n\t\treturn new StpLogic(loginType);\n\t};\n\n\t/**\n\t * 路由匹配策略\n\t */\n\tpublic SaRouteMatchFunction routeMatcher = (pattern, path) -> {\n\t\tthrow new NotImplException(\"未实现具体路由匹配策略\").setCode(SaErrorCode.CODE_12401);\n\t};\n\n\t/**\n\t * CORS 策略处理函数\n\t */\n\tpublic SaCorsHandleFunction corsHandle = (req, res, sto) -> {\n\n\t};\n\n\n\t// ----------------------- 重写策略 set连缀风格\n\n\t/**\n\t * 重写创建 Token 的策略\n\t *\n\t * @param createToken /\n\t * @return /\n\t */","sourceCodeStart":166,"sourceCodeEnd":202,"githubUrl":"https://github.com/dromara/Sa-Token/blob/ac2c7f6e94a78573cf0bcb932dd8b04e68fad189/sa-token-core/src/main/java/cn/dev33/satoken/strategy/SaStrategy.java#L166-L202","documentation":"sa-token-core ships only a default no-op route matcher that throws NotImplException (code 12401) whenever SaStrategy.routeMatcher is invoked. The library expects the framework integration layer (spring-boot-starter, reactor starter, solon/jfinal/jboot plugins) to replace this strategy at startup with a real implementation such as AntPathMatcher or Spring PathPattern. If you use sa-token-core directly or the integration failed to register, any route-interceptor matching (SaRouter.match, checkPath annotations, SaInterceptor) hits this throw.","triggerScenarios":"Calling SaRouter.match(\"/user/**\") or registering a SaInterceptor with route rules while SaStrategy.instance.routeMatcher was never assigned; depending on sa-token-core alone without a sa-token-starter/sa-token-plugin integration module; manually constructing SaManager components before the Spring/solon context registers SaTokenContextRegister/SaBeanRegister.","commonSituations":"Adding sa-token-core as the only dependency (e.g. in a plain Java or Vert.x/gRPC app with no official plugin); integration auto-configuration not loading because the starter is not on the component-scan path or the context is a non-web @SpringBootApplication; upgrading and accidentally swapping the starter for core.","solutions":["Use the matching integration starter (sa-token-spring-boot-starter, sa-token-reactor-spring-boot-starter, sa-token-solon-plugin, etc.) — its SaTokenContextRegister/SaBeanRegister sets routeMatcher automatically","If no official plugin exists for your framework, assign one yourself at startup: SaStrategy.instance.routeMatcher = (pattern, path) -> AntPathMatcher.INSTANCE.match(pattern, path);","Verify the registration actually ran (debug-print SaStrategy.instance.routeMatcher) and that your auto-configuration is not excluded via spring.autoconfigure.exclude","For Spring 6+, bind it to PathPatternParser: SaStrategy.instance.routeMatcher = new SaPathPatternParser()::match"],"exampleFix":"// before: only sa-token-core on classpath, then\nSaRouter.match(\"/admin/**\", r -> StpUtil.checkRole(\"admin\")); // throws 12401\n\n// after: assign a matcher at app startup\n@Bean\npublic void initSaStrategy() {\n    SaStrategy.instance.routeMatcher = (pattern, path) ->\n        AntPathMatcher.INSTANCE.match(pattern, path);\n}","handlingStrategy":"validation","validationCode":"// before app start, verify the integration set a real matcher\nif (SaStrategy.instance.routeMatcher == null\n        || SaStrategy.instance.routeMatcher.apply(\"/a\", \"/a\") == null) {\n    // default throws NotImplException, so test via exception:\n}\ntry {\n    SaStrategy.instance.routeMatcher.apply(\"/test/**\", \"/test/x\");\n} catch (NotImplException e) {\n    SaStrategy.instance.routeMatcher = (pattern, path)\n        -> AntPathMatcher.INSTANCE.match(pattern, path);\n}","typeGuard":null,"tryCatchPattern":"try {\n    SaRouter.match(\"/admin/**\", r -> StpUtil.checkRole(\"admin\"));\n} catch (NotImplException e) {\n    // config error, not a business condition: fail startup loudly\n    throw new IllegalStateException(\"routeMatcher not installed; add a sa-token starter\", e);\n}","preventionTips":["Always pair sa-token-core with the integration starter for your framework","Run a smoke test at startup that invokes SaStrategy.instance.routeMatcher once","Never swallow NotImplException in request handlers — it signals broken wiring"],"tags":["sa-token","routing","configuration","integration"],"backgroundTag":null,"analyzedSha":"ac2c7f6e94a78573cf0bcb932dd8b04e68fad189","analyzedAt":"2026-08-14T14:36:10.271Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}