JDBI 中如何为特定字段注册自定义列映射器

在数据库开发中，我们经常会遇到需要将数据库中的原始数据类型转换为应用程序中更合适的类型的情况。JDBI 作为一个强大的 Java 数据库访问工具，提供了灵活的列映射机制来实现这种转换。本文将介绍如何在 JDBI 中为特定字段注册自定义列映射器，而不是全局注册。

问题背景

假设我们有一个数据库表，其中某个字段以逗号分隔的字符串形式存储了一个字符串列表（TEXT 类型），而不是使用 SQL 数组类型。我们需要将这个字段从 String 类型映射到 List<String> 类型。如果简单地创建一个全局的 ColumnMapper<List<String>>，它会应用于所有 List<String> 类型的字段，这显然不是我们想要的结果。

解决方案：使用限定类型

JDBI 提供了"限定类型"（Qualified Types）的功能，允许我们为特定字段注册自定义的列映射器。以下是实现步骤：

1. 创建自定义注解

首先，我们需要定义一个注解来标记需要特殊处理的字段：

import java.lang.annotation.*;

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.FIELD)
public @interface CommaSeparatedList {
}

2. 实现列映射器工厂

接下来，我们创建一个列映射器工厂，它将为带有我们自定义注解的字段提供特定的映射器：

import org.jdbi.v3.core.mapper.ColumnMapper;
import org.jdbi.v3.core.mapper.ColumnMapperFactory;

public class CommaSeparatedListMapperFactory implements ColumnMapperFactory {
    @Override
    public ColumnMapper<?> build(Type type, ConfigRegistry config) {
        if (type instanceof ParameterizedType) {
            ParameterizedType pt = (ParameterizedType) type;
            if (pt.getRawType() == List.class 
                && pt.getActualTypeArguments()[0] == String.class) {
                return (rs, col, ctx) -> 
                    Arrays.asList(rs.getString(col).split(","));
            }
        }
        return null;
    }
}

3. 注册映射器工厂

在使用 JDBI 时，我们需要注册这个工厂：

jdbi.registerColumnMapper(new CommaSeparatedListMapperFactory());

4. 在数据类中使用

最后，在我们的数据类中，我们可以这样使用：

public class User {
    @CommaSeparatedList
    private List<String> emails;
    
    // 其他字段和getter/setter
}

高级用法：更精确的控制

如果需要更精确的控制，我们可以结合 JDBI 的 @MapWith 注解和限定类型来实现：

1. 首先定义一个更具体的列映射器：

public class CommaSeparatedListMapper implements ColumnMapper<List<String>> {
    @Override
    public List<String> map(ResultSet rs, int columnNumber, StatementContext ctx) {
        String value = rs.getString(columnNumber);
        return Arrays.asList(value.split(","));
    }
}

2. 然后在数据类中使用：

public class User {
    @MapWith(CommaSeparatedListMapper.class)
    private List<String> emails;
}

总结

通过使用 JDBI 的限定类型功能，我们可以为特定字段注册自定义的列映射器，而不影响其他同类型的字段。这种方法特别适用于处理数据库中的非标准数据格式，或者需要特殊转换逻辑的字段。相比全局注册映射器，这种方式更加灵活和安全，避免了意外影响其他字段的风险。

在实际应用中，开发者可以根据具体需求选择简单注解方式还是更复杂的工厂模式，JDBI 提供了足够的灵活性来满足各种场景的需求。