如何在 Hibernate JDBC 日志中排除 BLOB 二进制参数?
结论
Hibernate 6.5.x 没有按 JDBC 类型关闭参数绑定日志的原生配置项。如果要保留其他参数的日志,可以分两步处理:
- 覆盖
byte[]的extractLoggableRepresentation(),避免 Hibernate 把附件内容展开成字符串。 - 如果还需要隐藏整条 BLOB 参数绑定记录,再通过日志后端过滤。
保存附件时遇到性能问题,建议先做第一步。只过滤最终的日志行,仍可能产生生成二进制字符串的开销。
为什么调整 BasicBinder 的日志级别没有效果
Hibernate 6 的参数绑定日志统一使用这个类别:
org.hibernate.orm.jdbc.bind=trace
BLOB、字符串、数值等参数都写入这个类别,无法通过 logger 层级分别控制。JdbcBindingLogging 根据 JDBC 类型码生成类型名称,再输出绑定记录。Hibernate 6.5 日志实现
Hibernate 6.5 中的 BasicBinder 类是:
org.hibernate.type.descriptor.jdbc.BasicBinder
旧配置中的 org.hibernate.type.descriptor.sql.BasicBinder 不适用于这里。按 VarbinaryJdbcType 类名调整日志级别,同样无法关闭统一类别中的二进制参数日志。
第一步:让 byte[] 只输出长度
Hibernate 6.5 的 PrimitiveByteArrayJavaType 提供了 extractLoggableRepresentation(byte[]) 方法。继承这个类,只覆盖日志表示方法,就能保留原有的类型转换和比较逻辑。Hibernate 6.5 API
package com.example.persistence;
import org.hibernate.type.descriptor.java.PrimitiveByteArrayJavaType;
public class BinarySummaryJavaType extends PrimitiveByteArrayJavaType {
@Override
public String extractLoggableRepresentation(byte[] value) {
return value == null
? "null"
: "<binary, " + value.length + " bytes>";
}
}
然后在附件属性上指定这个 Java 类型描述符。以下示例假设实体采用字段访问,且附件原本就通过 @Lob 映射:
import jakarta.persistence.Lob;
import org.hibernate.annotations.JavaType;
@Lob
@JavaType(BinarySummaryJavaType.class)
private byte[] attachment;
如果原属性没有 @Lob,只添加 @JavaType,保留已有的数据库映射。采用属性访问时,把注解放在相应的 getter 上。@JavaType 用于指定属性使用的 Java 类型描述符。注解说明
日志级别保持原样:
org.hibernate.SQL=debug
org.hibernate.orm.jdbc.bind=trace
附件值在日志中会显示为类似内容:
binding parameter (3:BLOB) <- [<binary, 18432 bytes>]
这样会保留参数位置、类型和长度,也不影响其他属性的参数日志。即使返回空字符串,也只是把日志中的值留空,整条绑定记录仍会输出。
这个方法只控制日志中的值如何显示。不要为了隐藏日志而修改 unwrap()、wrap() 或实际的 JDBC 绑定逻辑。
第二步:需要时过滤整条二进制绑定日志
如果需要隐藏所有 BLOB 绑定记录,可以在日志后端添加过滤器。下面使用 Logback;Log4j 2 等后端需要使用各自的过滤机制。
创建一个只处理 Hibernate 参数绑定日志的过滤器:
package com.example.logging;
import java.util.regex.Pattern;
import ch.qos.logback.classic.spi.ILoggingEvent;
import ch.qos.logback.core.filter.Filter;
import ch.qos.logback.core.spi.FilterReply;
public class BinaryBindingFilter extends Filter<ILoggingEvent> {
private static final String BIND_LOGGER =
"org.hibernate.orm.jdbc.bind";
private static final Pattern BINARY_BINDING = Pattern.compile(
"^binding parameter \\([^:]*:"
+ "(?:BLOB|BINARY|VARBINARY|LONGVARBINARY)"
+ "\\) <- \\["
);
@Override
public FilterReply decide(ILoggingEvent event) {
if (!BIND_LOGGER.equals(event.getLoggerName())) {
return FilterReply.NEUTRAL;
}
String message = event.getFormattedMessage();
if (message != null
&& BINARY_BINDING.matcher(message).find()) {
return FilterReply.DENY;
}
return FilterReply.NEUTRAL;
}
}
将过滤器添加到接收这些日志的 appender 中:
<configuration>
<appender name="CONSOLE"
class="ch.qos.logback.core.ConsoleAppender">
<filter class="com.example.logging.BinaryBindingFilter"/>
<encoder>
<pattern>%d %-5level %logger - %msg%n</pattern>
</encoder>
</appender>
<logger name="org.hibernate.SQL" level="DEBUG"/>
<logger name="org.hibernate.orm.jdbc.bind" level="TRACE"/>
<root level="INFO">
<appender-ref ref="CONSOLE"/>
</root>
</configuration>
如果已有 Logback 配置,在相应的 appender 中加入 <filter> 即可。控制台和文件都接收绑定日志时,两处都要配置。Logback 的普通过滤器只作用于所属 appender:返回 DENY 会丢弃记录,返回 NEUTRAL 则继续后续判断。Logback 过滤器说明
这个规则会过滤常见的 BLOB、BINARY、VARBINARY 和 LONGVARBINARY 绑定记录,也包括这些类型的 null 记录。如果只想排除 BLOB,把正则中的类型列表改为 BLOB。
使用时需要注意什么
上面的过滤器会读取格式化后的消息,此时展开 byte[] 的开销已经产生。因此,单独使用过滤器无法消除这部分开销,需要配合第一步,才能同时避免附件内容展开和日志行输出。
BinarySummaryJavaType 处理的是 Java 类型 byte[],不会自动覆盖所有 JDBC BLOB 映射。如果有多个附件属性,需要分别应用它。如果希望统一处理默认的 byte[] 映射,可以通过 TypeContributor 注册类型描述符。Hibernate 6.5 支持通过 ServiceLoader 加载这个扩展。TypeContributor API
过滤规则依赖 Hibernate 6.5 的日志文本格式。升级 Hibernate 或使用其他二进制 JDBC 类型时,需要核对实际输出并调整规则。验证时,除了确认普通参数仍正常记录、附件内容没有展开,还要检查文件保存后能否正确读取。
如果关闭绑定日志后耗时明显下降,可以优先排查日志路径,但这不足以说明全部耗时都来自字节数组转换。修改后应重新测量保存耗时,日志输出设备和 appender 配置也可能影响结果。
备注:内容仅供参考。
