当 MapStruct 调用 @Named 标注的 dataToBase64 方法处理可能为 null 的 byte[] 字段时，因未做空值校验直接传入 Base64.getEncoder().encodeToString(null)，触发 JDK 底层 NPE；需在自定义映射方法中显式处理 null 输入。
当 mapstruct 调用 `@named` 标注的 `datatobase64` 方法处理可能为 null 的 `byte[]` 字段时，因未做空值校验直接传入 `base64.getencoder().encodetostring(null)`，触发 jdk 底层 npe；需在自定义映射方法中显式处理 null 输入。
在使用 MapStruct 进行对象转换时，若通过 qualifiedByName 引用自定义映射方法（如将 byte[] 转为 Base64 字符串），必须确保该方法能安全处理 null 输入——因为源字段（如 loadedImage.data 或 resultImage.data）在业务逻辑中完全可能为 null。而 Base64.getEncoder().encodeToString(byte[]) 是 JDK 内部严格非空校验的方法，传入 null 会立即抛出 NullPointerException，错误栈明确指向 src is null。
以下是推荐的三种稳健实现方式，按不同业务语义选择：
✅ 方案一：空转空字符串（适合前端需要默认占位的场景）
@Named("dataToBase64")
default String dataToBase64(byte[] data) {
if (data == null) {
return "";
}
return Base64.getEncoder().encodeToString(data);
}✅ 方案二：空转 null（保持语义一致性，推荐多数后端场景）
@Named("dataToBase64")
default String dataToBase64(byte[] data) {
if (data == null) {
return null;
}
return Base64.getEncoder().encodeToString(data);
}✅ 方案三：返回 Optional（函数式风格，增强调用方空值感知）
@Named("dataToBase64")
default Optional<String> dataToBase64(byte[] data) {
return Optional.ofNullable(data)
.map(Base64.getEncoder()::encodeToString);
}⚠️ 注意：若采用此方案，目标字段类型需同步改为 Optional
此外，还需检查 Task 实体中 loadedImage 和 resultImage 对象本身是否为 null —— 若其为 null，则 loadedImage.data 会触发更早的 NPE（NullPointerException: Cannot read field "data" because "loadedImage" is null）。此时应在 @Mapping 中添加 nullValueMappingStrategy = NullValueMappingStrategy.RETURN_NULL 或使用 @BeanMapping(nullValuePropertyMappingStrategy = NullValuePropertyMappingStrategy.IGNORE) 控制嵌套属性访问行为，或在 dataToBase64 前增加对象判空（如 if (loadedImage != null) { ... }）。
总结：MapStruct 的 @Named 方法本质是普通 Java 方法，不自动规避空值风险。所有外部依赖（如 Base64、Objects.requireNonNull、第三方序列化工具等）都必须由开发者主动防御性编程。将 null 检查作为自定义映射方法的第一行逻辑，是保障映射健壮性的关键实践。
