{"record":{"id":"4218c763e960eb2f","repo":"YunaiV/yudao-cloud","slug":"iputils","errorCode":null,"errorMessage":"IPUtils 初始化失败","messagePattern":"IPUtils 初始化失败","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"yudao-framework/yudao-spring-boot-starter-biz-ip/src/main/java/cn/iocoder/yudao/framework/ip/core/utils/IPUtils.java","lineNumber":40,"sourceCode":"     * IP 查询器，启动加载到内存中\n     */\n    private static Searcher SEARCHER;\n\n    static {\n        init();\n    }\n\n    /**\n     * 初始化\n     */\n    private static void init() {\n        try {\n            long now = System.currentTimeMillis();\n            byte[] bytes = ResourceUtil.readBytes(\"ip2region.xdb\");\n            SEARCHER = Searcher.newWithBuffer(bytes);\n            log.info(\"启动加载 IPUtils 成功，耗时 ({}) 毫秒\", System.currentTimeMillis() - now);\n        } catch (Exception e) {\n            throw new RuntimeException(\"IPUtils 初始化失败\", e);\n        }\n    }\n\n    /**\n     * 查询 IP 对应的地区编号\n     *\n     * @param ip IP 地址，格式为 127.0.0.1\n     * @return 地区id\n     */\n    @SneakyThrows\n    public static Integer getAreaId(String ip) {\n        return Integer.parseInt(SEARCHER.search(ip.trim()));\n    }\n\n    /**\n     * 查询 IP 对应的地区编号\n     *\n     * @param ip IP 地址的时间戳，格式参考{@link Searcher#checkIP(String)} 的返回","sourceCodeStart":22,"sourceCodeEnd":58,"githubUrl":"https://github.com/YunaiV/yudao-cloud/blob/477be9dd49ab7223a972a6abdff0684d6423dec3/yudao-framework/yudao-spring-boot-starter-biz-ip/src/main/java/cn/iocoder/yudao/framework/ip/core/utils/IPUtils.java#L22-L58","documentation":"IPUtils statically loads the ip2region.xdb binary from the classpath and wraps any failure (missing file, unreadable bytes, Searcher build error) in RuntimeException('IPUtils 初始化失败'). The class initializes on first use, so the error surfaces far from the configuration cause.","triggerScenarios":"Class load triggered by first getAreaId()/search call when ip2region.xdb is absent from src/main/resources or was excluded from the packaged artifact; or the file is truncated/corrupt so Searcher.newWithBuffer throws.","commonSituations":"Resource excluded by build filters; large xdb stripped by git-lfs not being pulled before build; jar repackaging tools dropping binary resources; CI builds that skip copying resources.","solutions":["Confirm ip2region.xdb exists in src/main/resources and appears in the built jar (jar tf app.jar | grep xdb).","If git-lfs is used, run git lfs pull before building.","Verify file size/integrity (compare checksum with the upstream ip2region release).","Read getCause() to distinguish missing resource from corrupt content."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"if (IPUtils.class.getResource(\"/ip2region.xdb\") == null) {\n    throw new IllegalStateException(\"ip2region.xdb missing from classpath — check build resources\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    Integer areaId = IPUtils.getAreaId(ip);\n} catch (ExceptionInInitializerError e) {\n    log.error(\"IP region lookup disabled; init failed: {}\", e.getCause().getCause());\n    return null; // graceful degradation for optional geo feature\n}","preventionTips":["Keep ip2region.xdb under src/main/resources and assert its presence at startup","git lfs pull before building if the xdb is lfs-tracked"],"tags":["yudao","initialization","classpath","resource","ip2region","ip"],"backgroundTag":null,"analyzedSha":"477be9dd49ab7223a972a6abdff0684d6423dec3","analyzedAt":"2026-08-14T13:35:31.121Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}