本文详解如何在 jdbi 3 中通过自定义 `argumentfactory`（而非仅限 `abstractargumentfactory`）统一处理多种 java 类型到 jdbc 参数的映射，提升 sql 绑定灵活性与代码复用性。
在 JDBI 3 中，AbstractArgumentFactory
ArgumentFactory 接口仅定义一个核心方法：
Optional<Argument> build(Type type, Object value, ConfigRegistry config);
该方法接收运行时类型信息 type（可为 Class> 或泛型 ParameterizedType）、待绑定的 value 及配置注册表，要求返回 Optional
✅ 关键原则：JDBI 按注册顺序遍历所有 ArgumentFactory，首个返回非空 Optional 的工厂即被采用。因此，多类型工厂应合理安排注册优先级，避免宽泛匹配（如 Object.class）过早截断流程。
示例：支持 UUID 与自定义 Id 的统一工厂
以下是一个生产就绪的多类型工厂示例，同时处理 UUID 和泛型标识符 Id
本系统经过多次升级改造，系统内核经过多次优化组合，已经具备相对比较方便快捷的个性化定制的特性，用户部署完毕以后，按照自己的运营要求，可实现快速定制会费管理，支持在线缴费和退费功能财富中心，管理会员的诚信度数据单客户多用户登录管理全部信息支持审批和排名不同的会员级别有不同的信息发布权限企业站单独生成，企业自主决定更新企业站信息留言、询价、报价统一管理，分系统查看分类信息参数化管理，支持多样分类信息，
public class MultiTypeArgumentFactory implements ArgumentFactory.Preparable {
@Override
public Optional<Function<Object, Argument>> prepare(Type type, ConfigRegistry config) {
// 支持 UUID
if (type == UUID.class) {
return Optional.of(this::uuidToArgument);
}
// 支持 Id<T>（需检查是否为参数化类型且原始类为 Id）
if (type instanceof ParameterizedType pt &&
pt.getRawType() instanceof Class<?> raw && raw == Id.class) {
return Optional.of(this::idToArgument);
}
return Optional.empty();
}
private Argument uuidToArgument(Object value) {
if (value == null) {
return (pos, stmt, ctx) -> stmt.setNull(pos, Types.VARCHAR);
}
return (pos, stmt, ctx) -> stmt.setString(pos, value.toString());
}
private Argument idToArgument(Object value) {
if (value == null) {
return (pos, stmt, ctx) -> stmt.setNull(pos, Types.BIGINT);
}
try {
// 假设 Id<T> 提供 longValue() 方法（如 Id<Long>）
Long id = (Long) value.getClass().getMethod("longValue").invoke(value);
return (pos, stmt, ctx) -> stmt.setLong(pos, id);
} catch (Exception e) {
throw new IllegalArgumentException("Unsupported Id type: " + value.getClass(), e);
}
}
}注册与使用
将工厂注册至 JDBI 实例（通常在初始化阶段）：
Jdbi jdbi = Jdbi.create(dataSource); jdbi.registerArgument(new MultiTypeArgumentFactory()); // 注意：此处传入实例，非类 // 或使用扩展方式（若启用 jdbi3-sqlobject） jdbi.installPlugin(new SqlObjectPlugin());
随后即可在 SQL 对象中直接使用：
@SqlUpdate("INSERT INTO users (id, name) VALUES (:userId, :name)")
void insertUser(@Bind("userId") Id<Long> userId, @Bind("name") String name);
@SqlUpdate("INSERT INTO events (uuid, payload) VALUES (:uuid, :payload)")
void insertEvent(@Bind("uuid") UUID uuid, @Bind("payload") String payload);注意事项与最佳实践
- 避免类型误判：使用 instanceof 或 Class.isAssignableFrom() 时需注意装箱/泛型擦除问题；推荐优先使用 Type 参数（尤其是 ParameterizedType）进行精确匹配。
- 性能考量：prepare() 方法在首次绑定同类型时调用，返回的 Function 会被缓存复用，因此复杂逻辑应尽量放在 prepare() 中，而非 build() 内。
- 空值处理：务必显式处理 value == null 场景，调用 statement.setNull(position, sqlType) 并指定正确的 JDBC 类型（如 Types.VARCHAR、Types.BIGINT），否则可能触发 NullPointerException 或类型不匹配异常。
- 错误隔离：单个 ArgumentFactory 的异常不应影响其他类型绑定，建议在 build() 或 prepare() 中捕获并记录具体失败原因，便于调试。
通过直接实现 ArgumentFactory，你不仅能突破 AbstractArgumentFactory 的单类型限制，还能构建高内聚、可扩展的参数绑定体系——这是构建健壮 JDBI 数据访问层的关键能力之一。
