jeecgboot/JeecgBoot · error · IllegalArgumentException

类 {ruleClass} 未实现 IFillRuleHandler 接口

Error message

类 {ruleClass} 未实现 IFillRuleHandler 接口

What it means

Thrown by FillRuleUtil.executeRule after successfully loading ruleClass via reflection when the loaded class does not implement org.jeecg.common.handler.IFillRuleHandler. The isAssignableFrom check fails and an IllegalArgumentException is thrown. Note: because the surrounding try-catch swallows all exceptions (e.printStackTrace then returns null), the exception does not propagate — the method silently returns null.

Source

Thrown at jeecg-boot/jeecg-boot-base-core/src/main/java/org/jeecg/common/util/FillRuleUtil.java:87

                        params.put(key, value);
                    }
                }

                if (formData == null) {
                    formData = new JSONObject();
                }
                // 包路径白名单校验，防止任意类加载漏洞
                if (!ruleClass.startsWith("org.jeecg.")) {
                    log.error("检测到非法填值规则类加载尝试: {}", ruleClass);
                    throw new SecurityException("不允许加载非 org.jeecg 包路径下的填值规则类: " + ruleClass);
                }

                // 通过反射执行配置的类里的方法（先加载类并校验接口，再实例化）
                //update-begin---author:scott ---date:20260416  for：【PR#9538】Class.forName使用上下文类加载器，增强部署兼容性-----------
                Class<?> clazz = Class.forName(ruleClass, true, Thread.currentThread().getContextClassLoader());
                //update-end---author:scott ---date:20260416  for：【PR#9538】Class.forName使用上下文类加载器，增强部署兼容性-----------
                if (!IFillRuleHandler.class.isAssignableFrom(clazz)) {
                    throw new IllegalArgumentException("类 " + ruleClass + " 未实现 IFillRuleHandler 接口");
                }
                IFillRuleHandler ruleHandler = (IFillRuleHandler) clazz.getDeclaredConstructor().newInstance();
                return ruleHandler.execute(params, formData);
            } catch (Exception e) {
                e.printStackTrace();
            }
        }
        return null;
    }
}

View on GitHub (pinned to 96fb33f5ec)

Solutions

  1. Make the configured class implement org.jeecg.common.handler.IFillRuleHandler and override execute(JSONObject params, JSONObject formData).
  2. Verify the fully-qualified class name in sys_fill_rule.rule_class matches the actual class and package.
  3. Ensure the class has a public no-arg constructor (getDeclaredConstructor().newInstance() is used).
  4. Because the outer catch swallows this, check application logs for the printed stack trace when executeRule unexpectedly returns null.

Example fix

// before
package org.jeecg.modules.demo;
public class MyRule { // does not implement IFillRuleHandler
    public Object execute() { return "x"; }
}

// after
package org.jeecg.modules.demo;
import org.jeecg.common.handler.IFillRuleHandler;
public class MyRule implements IFillRuleHandler {
    public MyRule() {}
    @Override
    public Object execute(JSONObject params, JSONObject formData) { return "x"; }
}
Defensive patterns

Strategy: try-catch

Validate before calling

Class<?> clazz = Class.forName(ruleClass);
if (!IFillRuleHandler.class.isAssignableFrom(clazz)) {
    throw new IllegalArgumentException(ruleClass + " 未实现 IFillRuleHandler");
}

Type guard

null

Try / catch

// Note: FillRuleUtil.executeRule swallows all exceptions and returns null.
// Check logs for the printed stack trace when the result is unexpectedly null.
Object result = FillRuleUtil.executeRule(ruleCode, formData);
if (result == null) {
    log.warn("填值规则 [{}] 执行失败或未配置，请检查 rule_class 与接口实现", ruleCode);
}

Prevention

When it happens

Trigger: A sys_fill_rule row points rule_class to a valid org.jeecg.* class that exists on the classpath but does not implement IFillRuleHandler; or the class was refactored/renamed and no longer implements the interface.

Common situations: Class name copy-pasted incorrectly into rule_class; the handler class was an early prototype that never implemented the interface; a version upgrade changed the interface or moved it; the configured class is a plain POJO rather than a rule handler.

Related errors

AI-assisted analysis of jeecgboot/JeecgBoot@96fb33f5ec (2026-08-14). Data as JSON: /api/errors/df50e1d03f253449. Report an issue: GitHub.