写入可为空ARRAY类型列NULL值时，Dataflow Spanner API抛出IllegalStateException

这个问题我之前帮不少开发者排查过，本质是Spanner的Java客户端对NULL数组值的处理有特殊要求——你不能直接把null传给常规的数组Value构造方法，否则会触发内部的非空检查，就出现了你看到的IllegalStateException: Illegal call to getter of null value错误。

核心原因 #

Spanner的Value.array()、Value.stringArray()这类方法，设计上要求传入的数组参数必须是非空的，哪怕目标列是允许NULL的ARRAY类型也不行。如果直接传null，方法内部会尝试调用null值的getter方法，触发Guava的Preconditions非空校验，导致报错。

解决方案 #

这里有两种可靠的处理方式：

1. 用Value.nullValue()构造NULL数组值

当你需要写入NULL到ARRAY列时，直接调用Value.nullValue()并指定对应的数组类型即可，比如：

// 针对STRING类型的ARRAY列
Value nullArrayValue = Value.nullValue(Type.array(Type.string()));

// 如果是INT64类型的ARRAY列，就改成：
// Value nullArrayValue = Value.nullValue(Type.array(Type.int64()));

这个方法会生成一个合法的代表NULL的Value对象，完全符合Spanner的要求。

2. 在Dataflow转换逻辑中添加判空分支

在构建Spanner Mutation之前，先判断你的业务数据中的数组是否为NULL，分情况处理：

// 假设你的业务数据对象是dataRecord，getTags()返回可能为null的String数组
String[] tags = dataRecord.getTags();
Value tagsValue;

if (tags == null) {
    tagsValue = Value.nullValue(Type.array(Type.string()));
} else {
    tagsValue = Value.stringArray(tags);
}

// 构建插入/更新Mutation
Mutation mutation = Mutation.newInsertBuilder("your_table_name")
    .set("id").to(dataRecord.getId())
    .set("tags").to(tagsValue) // 传入处理后的Value
    .build();

这样就能完美避开空值校验的问题，顺利将NULL写入到Spanner的可为空ARRAY列中。

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