NVARCHAR2乱码主因是客户端解码链断裂：JDBC需设defaultNChar=true且用setNString()/n'xxx'插入，NLS_LANG对Java无效，JVM编码须为UTF-8。
nvarchar2 乱码不是字段类型问题，而是客户端解码链断裂——nls_lang 和 jdbc 连接层字符集没对齐，导致 unicode 字节被当成本地编码解析。
Java 不读 NLS_LANG，设了也白设
Oracle JDBC 驱动（ojdbc8+）完全忽略 NLS_LANG 环境变量。你把它设成 AMERICAN_AMERICA.AL32UTF8 或 AMERICAN_AMERICA.ZHS16GBK，JDBC 启动时根本不会看一眼。
- 错误做法：在 Linux
~/.bashrc里export NLS_LANG=...，然后跑 Java 程序——毫无效果 - 正确路径：JDBC 字符集协商靠 JVM 编码 + 驱动行为 + 服务端
NLS_NCHAR_CHARACTERSET三者联动 - 验证方式：运行
System.getProperty("file.encoding")，如果不是UTF-8，说明 JVM 层就已错位
NVARCHAR2 必须配 defaultNChar=true
NVARCHAR2 存的是国家字符集（NLS_NCHAR_CHARACTERSET，通常是 AL16UTF16），但 JDBC 默认用 VARCHAR2 的逻辑处理它——不加参数就会走隐式转换，把 UTF-16 字节当 ISO-8859-1 解，一个中文变三个 ?。
- 必须在 JDBC URL 末尾加上：
?oracle.jdbc.defaultNChar=true - 这个参数强制驱动对
NVARCHAR2/NCHAR列使用 Unicode 语义读写，绕过本地字符集干扰 - 不加它，
rs.getString("col_nvarchar2")返回的字串大概率是乱码，即使数据库存得完全正确
连接 URL 里别塞 MySQL 风格参数
像 characterEncoding=UTF-8、useUnicode=true 这类参数是 MySQL JDBC 驱动的，Oracle ojdbc 完全不识别——加了不仅无效，还可能触发警告日志，误导排查方向。
分析 Java Spring Boot 后端 Controller 代码，自动生成 Markdown 格式的接口文档。当用户说“生成 Java 接口文档”、“生成 API 文档”、“从 Spring 代码生成文档”时触发。
- 错误示例：
jdbc:oracle:thin:@localhost:1521:orcl?characterEncoding=UTF-8 - 正确示例：
jdbc:oracle:thin:@localhost:1521:orcl?oracle.jdbc.defaultNChar=true - 如果要用连接池（如 HikariCP），在
connectionInitSql中加ALTER SESSION SET NLS_LANGUAGE='AMERICAN'可防会话级 NLS 干扰，但不是解决NVARCHAR2乱码的核心
插入 NVARCHAR2 时必须用 n'xxx' 前缀或 setNString()
即使连接配置全对，SQL 文本里的中文字符串仍受客户端编码影响。普通单引号字符串 '张三' 会被按 JVM 默认编码（如 GBK）传给 Oracle，再由服务端转成 UTF-16，中间一环出错就入库即乱。
- 安全写法一（JDBC）：
ps.setNString(1, "张三")—— 显式走 Unicode 路径 - 安全写法二（SQL）：
INSERT INTO t VALUES (n'张三')——n前缀告诉 Oracle 这是国家字符集字面量 - 绝对避免：
ps.setString(1, "张三")写入NVARCHAR2字段，尤其当 JVM 编码 ≠ UTF-8 时，等于主动引入二次转码
真正容易被忽略的是：NVARCHAR2 乱码往往在查询时才暴露，但根子在插入那一刻就埋下了——setString() 写进去的字节流已经错了，后面怎么查都是徒劳。先盯住插入路径，再看查询表现。
Java免费学习笔记：立即使用
解锁 Java 大师之旅：从入门到精通的终极指南
