ShardingSphere 算法表达式为何必须声明为 public？

Question

在使用 ShardingSphere 配置分片算法时，若通过 SPI 或表达式方式自定义分片策略，常遇到“算法类未生效”问题。排查发现，尽管类已正确实现 `StandardShardingAlgorithm` 接口并配置到 YAML 中，但运行时报 `ClassNotFoundException` 或实例化失败。根本原因在于：ShardingSphere 通过反射机制加载和调用分片算法类，而 Java 反射仅能访问 public 修饰的类和构造方法。因此，即使逻辑正确，非 public 类会被类加载器忽略，导致无法实例化。故必须将分片算法类声明为 public，确保被框架正常加载与执行。

Answer 1

1. 问题背景与常见现象

在使用 ShardingSphere 进行数据库分片配置时，开发者常通过 SPI（Service Provider Interface）或表达式方式实现自定义分片策略。典型场景包括按用户 ID、时间字段等进行水平分库分表。然而，即便算法类已正确实现 StandardShardingAlgorithm 接口，并在 YAML 配置文件中注册，运行时仍可能出现以下异常：

• java.lang.ClassNotFoundException: com.example.MyShardingAlgorithm
• Cannot instantiate interface org.apache.shardingsphere.sharding.api.sharding.standard.StandardShardingAlgorithm
• No public constructor found for class com.example.MyShardingAlgorithm

此类错误往往让开发者误以为是类路径或配置格式问题，实则根源在于 Java 反射机制的访问控制限制。

2. 深层技术原理分析

ShardingSphere 在启动过程中，依赖 Java 的反射机制动态加载用户自定义的分片算法类。该过程主要由 JavaSPIRegistryService 或 YamlRuleConfigurationLoader 完成，其核心流程如下：

1. 解析 YAML 中的 algorithmClassName 或 SPI 配置文件中的全限定类名
2. 通过 Class.forName(className) 加载类
3. 调用 clazz.newInstance() 或构造函数实例化对象

根据 JVM 规范，Class.forName() 能够加载类，但仅当目标类及其默认构造方法为 public 时，才能成功实例化。若算法类声明为 protected、包私有（default）或私有内部类，则会抛出实例化异常。

3. 典型错误代码示例

// ❌ 错误示例：非 public 类
class UserModShardingAlgorithm implements StandardShardingAlgorithm<String> {
    @Override
    public String doSharding(Collection<String> availableTargetNames, PreciseShardingValue<String> shardingValue) {
        int mod = Math.abs(shardingValue.getValue().hashCode() % availableTargetNames.size());
        return availableTargetNames.stream().filter(name -> name.endsWith(String.valueOf(mod))).findFirst().orElse(null);
    }

    @Override
    public void init(ShardingAlgorithmConfiguration shardingAlgorithmConfig) {}

    @Override
    public String getType() {
        return "USER_ID_MOD";
    }
}

上述代码在编译期无任何问题，但在运行时将因无法被反射实例化而导致分片策略“未生效”。

4. 正确实现方式与规范建议

检查项	推荐值	说明
类访问修饰符	public	确保类可被外部类加载器访问
构造方法	public 无参构造	反射实例化依赖默认构造函数
实现接口	StandardShardingAlgorithm<T>	泛型类型需与分片值匹配
SPI 配置	META-INF/services/org.apache.shardingsphere.sharding.spi.ShardingAlgorithm	文件内容为全限定类名

5. 完整正确实现示例

// ✅ 正确实例：public 类 + public 构造
public class UserModShardingAlgorithm implements StandardShardingAlgorithm<String> {

    public UserModShardingAlgorithm() {} // 显式声明 public 构造函数

    @Override
    public String doSharding(Collection<String> availableTargetNames, PreciseShardingValue<String> shardingValue) {
        int mod = Math.abs(shardingValue.getValue().hashCode() % availableTargetNames.size());
        return availableTargetNames.stream()
            .filter(name -> name.endsWith(String.valueOf(mod)))
            .findFirst()
            .orElseThrow(() -> new IllegalArgumentException("No matching data source for " + shardingValue.getValue()));
    }

    @Override
    public void init(Properties props) {
        // 可选初始化逻辑
    }

    @Override
    public String getType() {
        return "USER_ID_MOD";
    }
}

6. 配置文件与 SPI 注册方式对比

graph TD
    A[自定义分片算法类] --> B{注册方式}
    B --> C[SPI 方式]
    B --> D[YAML 表达式方式]
    C --> E[META-INF/services/...]
    C --> F[自动发现，无需配置类名]
    D --> G[sharding-algorithm-name: userModAlgorithm]
    D --> H[algorithm-class-name: com.example.UserModShardingAlgorithm]
    style A fill:#f9f,stroke:#333
    style C,D fill:#bbf,stroke:#333,color:#fff

7. 排查流程图

graph LR
    Start[应用启动失败] --> Check1{是否报 ClassNotFoundException?}
    Check1 -- 是 --> Fix1[检查类路径与包名拼写]
    Check1 -- 否 --> Check2{是否报 InstantiationException?}
    Check2 -- 是 --> Fix2[确认类和构造函数为 public]
    Check2 -- 否 --> Check3{算法逻辑未执行?}
    Check3 -- 是 --> Fix3[验证 YAML/SPI 配置一致性]
    Fix1 --> End[重启验证]
    Fix2 --> End
    Fix3 --> End

8. 扩展思考：框架设计与反射安全

此问题揭示了现代 Java 框架对反射机制的高度依赖。Spring、MyBatis、Dubbo 等均存在类似约束。从架构角度看，应建立团队编码规范，强制要求所有 SPI 扩展点实现类必须声明为 public。同时，可通过静态代码检查工具（如 SonarQube）添加规则检测非 public 扩展类，提前拦截潜在故障。

9. 常见误区与最佳实践总结

• 误区一：认为只要实现接口即可，忽略访问修饰符
• 误区二：使用 private 内部类封装算法逻辑，导致无法加载
• 误区三：仅测试编译通过，未验证运行时加载
• 最佳实践：统一将分片算法置于独立模块，命名以 ShardingAlgorithm 结尾，便于管理
• 建议启用日志调试：-Dorg.slf4j.simpleLogger.defaultLogLevel=debug 查看类加载过程
• 利用 IDE 插件自动提示 SPI 配置缺失
• 结合单元测试模拟 Class.forName().newInstance() 验证可实例化性
• 在 CI 流程中加入字节码扫描步骤，确保所有扩展点合规
• 文档化所有自定义算法，注明适用场景与分片键
• 定期审查算法性能，避免热点分片