本文详解 @Formula 注解在 Spring Batch 场景下的典型误用与修复方案，重点解决因错误 SQL 表达式导致的 syntax error at or near "select" 异常，并提供安全、可维护的数据库函数调用实践。
本文详解 `@formula` 注解在 spring batch 场景下的典型误用与修复方案，重点解决因错误 sql 表达式导致的 `syntax error at or near "select"` 异常，并提供安全、可维护的数据库函数调用实践。
在基于 Spring Batch 的批处理流程中，若需在实体加载时动态计算或派生字段（例如通过数据库自定义函数解密敏感字段），开发者常倾向使用 Hibernate 的 @Formula 注解。然而，一个常见误区是直接在 @Formula 中编写完整 SQL 子查询（如 @Formula("select get_data(cardNo)")），这会导致 Hibernate 在生成主查询时拼接出非法 SQL，最终抛出类似 ERROR: syntax error at or near "select" 的 PSQLException ——正如日志中 Position: 100 所示，Hibernate 将 select get_data(...) 错误地作为字段表达式嵌入 SELECT 列表，而非子查询上下文。
根本原因在于：@Formula 不接受完整 SQL 语句，它仅接受一个可被直接嵌入 SELECT 子句的 SQL 表达式（即无需 SELECT 关键字）。正确的写法应省略 SELECT，并确保引用的列名与数据库物理列名严格一致（注意大小写和下划线命名）。
✅ 正确做法如下：
@Entity
@Table(name = "swt_dx_file_eod")
@Data
public class TransactionFileEod {
// ... 其他字段保持不变
// ✅ 修正：移除 'select'，且 column 名必须与 DB 实际列名一致（此处为 'crd_no'，非 'cardNo'）
@Formula("get_data(crd_no)")
private String decryptedCardNo;
// ... 其余字段
}⚠️ 关键注意事项：
-
列名必须真实存在：
get_data(crd_no)中的crd_no是数据库表swt_dx_file_eod中实际的列名（见@Column(name = "crd_no")），而非 Java 字段名cardNo。若误写为get_data(cardNo)，Hibernate 会尝试解析为别名或未知标识符，同样引发异常。 -
函数需在数据库中已定义且权限充足：确保
get_data()是 PostgreSQL 中已创建的STABLE或IMMUTABLE函数，且连接用户具有执行权限。 -
仅用于只读场景：
@Formula字段由 Hibernate 在SELECT时自动填充，不可用于INSERT/UPDATE。因此它天然适用于“第二步读取时解密”的需求，但绝不应在RepositoryItemWriter写入时依赖该字段值——因为写入操作不会触发@Formula计算，且该字段也不会被持久化。 -
性能考量：每个
@Formula字段都会增加单条 SQL 的复杂度。若批量加载大量记录，建议评估函数执行开销；必要时可改用@SqlResultSetMapping+ 原生查询，或在 Service 层批量调用函数。
此外，为增强可读性与类型安全，推荐将 @Formula 字段设为 transient 并添加 @JsonIgnore（若涉及 JSON 序列化），避免意外序列化或混淆：
@Formula("get_data(crd_no)")
@JsonIgnore
private String decryptedCardNo;总结：@Formula 是实现数据库端动态字段的强大工具，但其本质是 SQL 表达式注入点，而非独立查询入口。遵循“无 SELECT、列名精准、只读使用”三原则，即可在 Spring Batch 的 RepositoryItemReader 中安全启用数据库函数，彻底规避语法异常，同时保持批处理流程的清晰与健壮。
