{"record":{"id":"60554acbd5666934","repo":"dromara/Sa-Token","slug":"10003","errorCode":"10003","errorMessage":"未实现具体的 json 转换器","messagePattern":"未实现具体的 json 转换器","errorType":"exception","errorClass":"NotImplException","httpStatus":null,"severity":"error","filePath":"sa-token-core/src/main/java/cn/dev33/satoken/json/SaJsonTemplateDefaultImpl.java","lineNumber":37,"sourceCode":"import cn.dev33.satoken.exception.NotImplException;\n\nimport java.util.Map;\n\n/**\n * JSON 转换器，默认实现类\n *\n * <p> 如果代码断点走到了此默认实现类，说明框架没有注入有效的 JSON 转换器，需要开发者自行实现并注入 </p>\n *\n * @author click33\n * @since 1.30.0\n */\npublic class SaJsonTemplateDefaultImpl implements SaJsonTemplate {\n\n\tpublic static final String ERROR_MESSAGE = \"未实现具体的 json 转换器\";\n\n\t@Override\n\tpublic String objectToJson(Object obj) {\n\t\tthrow new NotImplException(ERROR_MESSAGE).setCode(SaErrorCode.CODE_10003);\n\t}\n\n\t@Override\n\tpublic Object jsonToObject(String jsonStr) {\n\t\tthrow new NotImplException(ERROR_MESSAGE).setCode(SaErrorCode.CODE_10003);\n\t}\n\n\t@Override\n\tpublic <T> T jsonToObject(String jsonStr, Class<T> type) {\n\t\tthrow new NotImplException(ERROR_MESSAGE).setCode(SaErrorCode.CODE_10003);\n\t}\n\n\t@Override\n\tpublic Map<String, Object> jsonToMap(String jsonStr) {\n\t\tthrow new NotImplException(ERROR_MESSAGE).setCode(SaErrorCode.CODE_10003);\n\t}\n\t\n}","sourceCodeStart":19,"sourceCodeEnd":55,"githubUrl":"https://github.com/dromara/Sa-Token/blob/ac2c7f6e94a78573cf0bcb932dd8b04e68fad189/sa-token-core/src/main/java/cn/dev33/satoken/json/SaJsonTemplateDefaultImpl.java#L19-L55","documentation":"NotImplException (code 10003) thrown by SaJsonTemplateDefaultImpl.objectToJson(). Sa-Token core ships only this do-nothing default JSON template; actual serialization is provided by integration jars (sa-token-json-jackson, sa-token-json-gson, sa-token-json-fastjson, etc.). Hitting it means no real JSON converter was injected, so any framework feature that serializes to JSON (e.g. storing objects in session, sa-token's own JSON persistence) fails.","triggerScenarios":"SaManager.getSaJsonTemplate() returns the default impl and application code — or sa-token internals — calls objectToJson(obj). Typical when the project depends on sa-token-core alone, or the JSON integration jar was excluded, and the plugin/SPI loader never registered a real SaJsonTemplate.","commonSituations":"Using sa-token-core without any sa-token-json-* dependency; excluding the json integration via Maven exclusions while pulling sa-token-spring-boot-starter transitively; a custom SaJsonTemplate registered after first use; classpath conflicts where the SPI file for the json plugin is missing.","solutions":["Add a JSON integration dependency, e.g. <dependency><groupId>cn.dev33</groupId><artifactId>sa-token-json-jackson</artifactId><version>${sa-token.version}</version></dependency> (or gson/fastjson2 variant)","If you intentionally have no integration jar, implement SaJsonTemplate yourself and inject: SaManager.setSaJsonTemplate(new MyJsonTemplate()) early at startup","Verify only one sa-token-json-* jar is on the classpath and its version matches the core version"],"exampleFix":"// before: only sa-token-core on classpath\n// SaManager.getSaJsonTemplate().objectToJson(obj) -> NotImplException 10003\n\n// after (pom.xml)\n<dependency>\n  <groupId>cn.dev33</groupId>\n  <artifactId>sa-token-json-jackson</artifactId>\n  <version>1.44.0</version>\n</dependency>","handlingStrategy":"validation","validationCode":"if (SaManager.getSaJsonTemplate() instanceof SaJsonTemplateDefaultImpl) {\n    // no real JSON converter injected; add sa-token-json-* dependency before using JSON features\n}","typeGuard":"boolean hasRealJsonTemplate() {\n    return !(SaManager.getSaJsonTemplate() instanceof cn.dev33.satoken.json.SaJsonTemplateDefaultImpl);\n}","tryCatchPattern":"try {\n    SaManager.getSaJsonTemplate().objectToJson(obj);\n} catch (NotImplException e) {\n    if (e.getCode() == SaErrorCode.CODE_10003) { /* inject a SaJsonTemplate and retry once */ }\n    throw e;\n}","preventionTips":["Always pair sa-token-core with a sa-token-json-* integration at the same version","Assert at startup that SaManager.getSaJsonTemplate() is not the default impl","When shading, preserve META-INF/services entries from integration jars"],"tags":["json","dependency","diy-template","sa-token"],"backgroundTag":null,"analyzedSha":"ac2c7f6e94a78573cf0bcb932dd8b04e68fad189","analyzedAt":"2026-08-14T14:36:10.271Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}