sqlclientinfoexception 是受检异常，因其继承自 sqlexception 且设置客户端信息属显式配置行为，需编译期强制处理；常见于 key 不支持、value 为空/超长或连接状态不合法等可预知场景，可通过 getfailedproperties() 获取失败属性，语义上专指客户端元数据设置失败，不影响后续 sql 执行。
SQLClientInfoException 是 Java JDBC 中的一个受检异常（checked exception），在调用 Connection.setClientInfo() 方法设置客户端连接属性（如应用名、用户 ID、程序版本等）失败时抛出。
为什么是受检异常？
Java 将其设计为受检异常，是因为：
- 设置客户端信息属于显式配置行为，预期开发者应主动处理失败场景
- 失败原因通常是可预知的（如不支持的属性名、值格式非法、数据库驱动未实现该功能），适合编译期强制检查
- 与
SQLException继承关系一致（SQLClientInfoException是其子类），保持 JDBC 异常体系一致性
常见触发场景
以下情况会抛出 SQLClientInfoException：
- 传入的 key 不在数据库驱动支持的客户端信息列表中（如 PostgreSQL 驱动不支持
ApplicationName以外的多数标准 key） - value 为空字符串或 null（部分驱动明确禁止）
- value 超长（例如超过驱动设定的长度限制，常见于 Oracle 或 SQL Server）
- 连接已关闭，或处于只读/事务中等不支持修改 client info 的状态
如何正确处理？
必须用 try-catch 捕获，不能忽略：
try {
connection.setClientInfo("ApplicationName", "MyOrderService");
} catch (SQLClientInfoException e) {
// 记录警告而非中断流程：client info 是辅助信息，非核心功能
logger.warn("Failed to set client info: {}", e.getMessage(), e);
}
建议策略：
- 仅设置关键且广泛支持的属性（如
ApplicationName、ClientUser） - 对非关键属性设置做静默降级（不抛异常中断主逻辑）
- 生产环境可结合
DatabaseMetaData.supportsSetClientInfo()预先判断是否支持
与 SQLException 的区别
它虽继承自 SQLException，但语义更具体：
-
SQLException表示通用 SQL 执行错误（如语法错、超时、约束冲突） -
SQLClientInfoException专指 客户端元数据设置失败，不影响后续 SQL 执行 - 可通过
e.getFailedProperties()获取哪些 key 设置失败，便于调试
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
