Spring Data持久化null字节数组报错问题求助

问题现象 #

使用Spring Boot 3.3.1（依赖spring-boot-starter-parent）时，通过Spring Data JDBC持久化byte[]类型为null的实体到SQL Server，会抛出如下异常：

Caused by: org.springframework.jdbc.UncategorizedSQLException: 
PreparedStatementCallback; uncategorized SQLException for SQL [INSERT INTO "SOME_TABLE" 
("CONTENT") VALUES (?)]; SQL state [S0003]; error code [257]; Implicit conversion from data type nvarchar to varbinary(max) is not allowed. Use the CONVERT function to run this query.
at org.springframework.jdbc.core.JdbcTemplate.translateException(JdbcTemplate.java:1549)
...
Caused by: com.microsoft.sqlserver.jdbc.SQLServerException: Implicit conversion from data type nvarchar to varbinary(max) is not allowed. Use the CONVERT function to run this query.

仅当byte[]字段为null时触发异常，非null或空数组（new byte[]{}）的情况可以正常持久化。Spring Boot 3.2.0版本下无此问题。

复现代码 #

实体类 #

@Table("SOME_TABLE")
public record SomeTable(
    @Id @Column("ID")
    Long id,
    @Column("CONTENT")
    byte[] content
) {
}

Repository接口 #

public interface SomeTableRepository extends CrudRepository<SomeTable, Long> {
}

测试类 #

@DataJdbcTest
@AutoConfigureTestDatabase(replace = AutoConfigureTestDatabase.Replace.NONE)
@EnableJdbcRepositories(considerNestedRepositories = true)
@ContextConfiguration(classes = {
    SomeTableRepository.class
})
@Sql(executionPhase = BEFORE_TEST_METHOD, value = {
    "classpath:0_init.sql",
    "classpath:1_load.sql"
})
@Sql(executionPhase = AFTER_TEST_METHOD, value = "classpath:2_clean.sql")
class ByteTest extends MssqlContainerBaseTest {

  @Autowired
  private SomeTableRepository someTableRepository;

  @Test
  void testByteArrayNotNull() {
      final SomeTable record = new SomeTable(null, "abc".getBytes());
      someTableRepository.save(record);
  }

  @Test
  void testByteArrayNull() {
      final SomeTable record = new SomeTable(null, null);
      someTableRepository.save(record);
  }

  @Test
  void testByteArrayEmpty() {
      final SomeTable record = new SomeTable(null, new byte[]{});
      someTableRepository.save(record);
  }

}

临时方案 #

用空字节数组（new byte[]{}）替代null值，但这不符合业务中对null的语义需求。

正确解决方案 #

方案1：通过@SqlType指定字段SQL类型 #

在byte[]字段上添加@SqlType注解，明确指定对应的SQL Server类型为VARBINARY(MAX)，强制Spring Data JDBC按二进制类型处理该字段，即使值为null：

@Table("SOME_TABLE")
public record SomeTable(
    @Id @Column("ID")
    Long id,
    @Column("CONTENT")
    @SqlType("VARBINARY(MAX)")
    byte[] content
) {
}

方案2：注册自定义类型转换器 #

创建自定义转换器，确保null的byte[]在持久化时被识别为二进制类型：

import org.springframework.core.convert.converter.Converter;
import org.springframework.data.jdbc.core.convert.SqlTypeDescriptor;
import java.sql.Types;

public class NullByteArrayConverter implements Converter<byte[], Object> {
    @Override
    public Object convert(byte[] source) {
        return source; // 直接返回，仅处理类型推断
    }

    @Override
    public SqlTypeDescriptor getSqlTypeDescriptor() {
        return SqlTypeDescriptor.valueOf(Types.VARBINARY);
    }
}

然后注册到Spring Data JDBC的自定义转换配置中：

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.data.jdbc.core.convert.JdbcCustomConversions;
import java.util.List;

@Configuration
public class DataJdbcConfig {
    @Bean
    public JdbcCustomConversions jdbcCustomConversions() {
        return new JdbcCustomConversions(List.of(new NullByteArrayConverter()));
    }
}

原因分析 #

Spring Boot 3.3.1升级了Spring Data JDBC版本，其对null值的类型推断逻辑发生变化：当byte[]为null时，框架未正确识别其对应SQL类型为VARBINARY，而是默认按NVARCHAR处理，导致SQL Server拒绝执行隐式类型转换。通过显式指定SQL类型或自定义转换器，可以强制框架使用正确的类型处理null字节数组。

内容的提问来源于stack exchange，提问作者user2054927