Oracle数据库字符集必须为AL32UTF8或ZHS16GBK等支持中文的编码,若实例使用US7ASCII等不支持中文的字符集,则需重建数据库;同时需使用ojdbc8+驱动、干净URL、-Dfile.encoding=UTF-8和-Doracle.jdbc.defaultNChar=true等配置确保全链路UTF-8。

确认数据库服务端字符集是否支持中文
插入前先查清源头:如果 Oracle 实例本身用的是 US7ASCII 或 WE8ISO8859P1,那任何客户端配置都救不了——它根本存不下中文。执行以下 SQL 验证:
SELECT value FROM nls_database_parameters WHERE parameter = 'NLS_CHARACTERSET';
合法返回值应为 AL32UTF8(推荐)、ZHS16GBK 等;若不是,说明问题在建库阶段,需重建或导出导入。
ojdbc8+ 驱动 + URL 去掉 MySQL 风格参数
老项目常用 ojdbc6,但它对 UTF-8 传输支持不完整:setString() 可能静默截断,getString() 可能错解字节。必须升级到 ojdbc8(Oracle 12c+)或 ojdbc11(21c+),Maven 坐标用 com.oracle.database.jdbc:ojdbc8。
URL 中禁止出现 characterEncoding、useUnicode、encoding 等参数——Oracle JDBC 官方驱动完全不识别它们,加了不仅无效,还会触发 WARN 日志干扰排查。
立即学习“Java免费学习笔记(深入)”;
干净的 URL 示例:
jdbc:oracle:thin:@//db-host:1521/orclpdb
- 别写成
jdbc:oracle:thin:@db-host:1521:orcl?characterEncoding=UTF-8 - 也别拼
&useUnicode=true—— 这是 MySQL 的逻辑,Oracle 不吃这套
JVM 启动参数和驱动行为必须协同
即使 URL 干净、驱动新版,JVM 默认编码不对,照样乱码。关键两点缺一不可:
使用Atmosphere构建通过WebSocket、SSE、gRPC、WebTransport、MCP、A2A和AG-UI流传输的JVM代理网关,并带有治理钩子。
-
-Dfile.encoding=UTF-8:确保String.getBytes()、new String(byte[])等操作走 UTF-8 -
-Doracle.jdbc.defaultNChar=true:强制驱动对VARCHAR2列启用 Unicode 语义读写,绕过NLS_LANG干扰
如果用 HikariCP 等连接池,建议加初始化 SQL 避免会话级 NLS 污染:
connectionInitSql=ALTER SESSION SET NLS_LANGUAGE='AMERICAN' NLS_TERRITORY='AMERICA'
注意:不要手动在 PreparedStatement 里做 new String(str.getBytes("ISO-8859-1"), "UTF-8") 这类转码——这是二次编码,会让乱码更严重。只要上述配置到位,直接 ps.setString(1, "中文") 即可。
验证字节流是否真按 UTF-8 流转
别只看 SELECT 返回是不是“看起来像中文”。有些场景下显示正常只是巧合(比如字段值恰好能被错误编码映射成可显字符)。真正要验证的是底层字节:
执行 Oracle SQL:
SELECT DUMP('你好', 1016) FROM DUAL;
正确结果应为 TYP=1 LEN=6: 60,0,4f,60,0,4f(UTF-8 十六进制)。如果看到 TYP=1 LEN=2: c4,e3,说明驱动正用 GBK 解码,链路已断。
最容易被忽略的点:Java 源文件本身没保存为 UTF-8。IDE 里检查单个文件编码(不是项目默认编码),否则 "中文" 字面量从编译起就错了。

















