ORA-12899「值太大」錯誤解析：中文字串長度陷阱與解決方案

Hibernate 寫入 Oracle 時拋出 ORA-12899: value too large for column，明明已用 substring(0,512) 截斷，卻提示實際長度 521 超過上限 512。根因在於「字元數」與「位元組數」的單位差異。

一、錯誤現場

ORA-12899: 列 "ITS"."VIO_BUSINESS_RESPONSE_I"."RESPONSE" 的值太大
(實際值: 521, 最大值: 512)

欄位定義：VARCHAR2(512)（預設 byte 語意）。

程式碼：str.substring(0, 512) 按字元截取。

二、根因分析

• Oracle VARCHAR2(n) 預設以位元組為單位。
• 中文字元在 UTF-8/AL32UTF8 編碼下佔 3 位元組。
• Java substring 按字元計數，512 個中文字元 = 1,536 位元組，遠超 512 位元組上限。
• 錯誤訊息「實際值: 521」代表實際位元組長度。

三、解決方案

方案一：預留緩衝，縮減截取長度（快速修復）

// 粗略估算：中文佔 3 bytes，預留餘量
str.substring(0, 400)  // 400 * 3 = 1200 bytes，仍可能超過，視實際比例調整

缺點：無法精確控制，純英文時浪費空間。

方案二：先編碼再按位元組截取（精確控制）

// Java 端處理
String encoded = URLEncoder.encode(str, "UTF-8");  // 中文變 %E4%B8%AD 等 9 字元
// 或直接取位元組陣列
byte[] bytes = str.getBytes("UTF-8");
if (bytes.length > 512) {
    bytes = Arrays.copyOf(bytes, 512);
}
String safeStr = new String(bytes, "UTF-8");  // 注意：截斷可能產生半個中文導致解碼錯誤，建議用 CharsetDecoder

更穩健的做法：使用 CharsetDecoder 或 ByteBuffer 精確截取完整字元。

方案三：資料庫欄位改用 CHAR 語意（架構層面）

ALTER TABLE VIO_BUSINESS_RESPONSE_I 
MODIFY RESPONSE VARCHAR2(512 CHAR);

優點：應用端按字元截取即可，無需擔心位元組轉換。
缺點：需評估現有資料遷移影響，且最大字元數仍受 4000 位元組硬性限制（MAX_STRING_SIZE=STANDARD 時）。

四、最佳實務建議

1. 新系統建表預設使用 VARCHAR2(n CHAR)，消除單位混淆。
2. 應用層統一封裝 safeSubstring(str, maxBytes, charset) 工具方法。
3. 啟用資料庫約束 CHECK (LENGTHB(col) <= 512) 防呆。
4. 測試案例覆蓋：純中文、中英混雜、特殊字元、超長邊界。

五、快速對照表