MyBatis-Plus中使用PostgreSQL的UUID类型主键问题解析

2025-05-13 05:00:10作者：伍霜盼Ellen

问题背景

在使用MyBatis-Plus框架与PostgreSQL数据库结合开发时，经常会遇到需要使用UUID作为主键类型的情况。然而，在实际应用中，开发者可能会遇到类型转换错误，特别是当数据库字段定义为UUID类型而Java代码中尝试使用字符串形式传递时的兼容性问题。

问题现象

当开发者尝试在实体类中使用UUID作为主键类型，并通过TypeHandler进行类型转换时，可能会遇到类似以下的错误信息：

ERROR: column "id" is of type uuid but expression is of type character varying

这表明PostgreSQL数据库期望接收一个UUID类型的值，但实际接收到的是一个字符串类型的值。

问题根源分析

主键注解使用不当：在MyBatis-Plus中，主键字段应该使用@TableId注解，而不是@TableField注解。@TableField的typeHandler属性对主键字段无效。
类型转换机制不匹配：PostgreSQL的JDBC驱动对UUID类型有特殊处理要求，直接使用字符串形式传递会导致类型不匹配。
TypeHandler实现问题：自定义的UUIDTypeHandler可能没有正确处理PostgreSQL特有的UUID类型转换方式。

解决方案

方案一：使用MyBatis-Plus内置的UUID类型处理器

MyBatis-Plus已经提供了对UUID类型的支持，可以直接使用：

@TableId(type = IdType.ASSIGN_UUID)
private UUID id;

这种方式会自动处理UUID的生成和类型转换，是最简单的解决方案。

方案二：正确实现自定义TypeHandler

如果需要自定义UUID处理逻辑，应该确保TypeHandler正确处理PostgreSQL的UUID类型：

@MappedJdbcTypes(JdbcType.OTHER)
@MappedTypes(UUID.class)
public class PgUUIDTypeHandler extends BaseTypeHandler<UUID> {
    
    @Override
    public void setNonNullParameter(PreparedStatement ps, int i, 
                                  UUID parameter, JdbcType jdbcType) throws SQLException {
        ps.setObject(i, parameter);
    }

    @Override
    public UUID getNullableResult(ResultSet rs, String columnName) throws SQLException {
        return (UUID) rs.getObject(columnName);
    }

    @Override
    public UUID getNullableResult(ResultSet rs, int columnIndex) throws SQLException {
        return (UUID) rs.getObject(columnIndex);
    }

    @Override
    public UUID getNullableResult(CallableStatement cs, int columnIndex) throws SQLException {
        return (UUID) cs.getObject(columnIndex);
    }
}

方案三：全局配置TypeHandler

在MyBatis配置中全局注册UUID类型处理器：

mybatis-plus:
  type-handlers-package: com.example.handler

或者在配置类中显式注册：

@Configuration
public class MybatisPlusConfig {
    
    @Bean
    public MybatisPlusInterceptor mybatisPlusInterceptor() {
        MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
        // 添加其他拦截器
        return interceptor;
    }
    
    @Bean
    public ConfigurationCustomizer configurationCustomizer() {
        return configuration -> {
            configuration.getTypeHandlerRegistry().register(UUID.class, new PgUUIDTypeHandler());
        };
    }
}