如何在Java中适配Oracle VARCHAR2(4000 BYTE)字符串限制？

算力阿峰

2026-6-17

Oracle VARCHAR2(4000 CHAR) 存储JSON时的长度溢出问题

我们在Oracle数据库中用VARCHAR2(4000 CHAR)列存储JSON数据，目的是避免CLOB带来的性能损耗。但发现4000 CHAR实际上受限于4000 BYTE——这是字符串列的硬限制，哪怕用NVARCHAR2也无法突破。

于是我们在Java端把字符串拆成4000字节的块，用String#getBytes(StandardCharsets.UTF_8).length计算字符串在数据库中的实际长度，但这个方法不可靠，Oracle偶尔还是会抛出错误：

ORA-12899: Wert zu groß für Spalte
"OUR_DATABASE"."HISTORICAL_DATASETS"."JSON1" (aktuell: 4006, maximal: 4000)

通过查询SELECT parameter, value FROM nls_database_parameters WHERE parameter LIKE 'NLS_CHARACTERSET'，确认Oracle使用的字符集是AL32UTF8。

我忽略了什么？除编码本身外是否存在额外开销？

编辑1：使用的拆分方法及相关代码

字符串拆分方法

public static List<String> split(String input, int size, boolean inBytes, Charset charset) {
    List<String>  parts   = new ArrayList<>();
    StringBuilder segment = new StringBuilder();
    int           length  = 0;

    for (int i = 0; i < input.length(); i++) {
        String c = input.substring(i, i+1); // charAt(i);

        // 字符实际占用的字节数取决于编码！
        int realLength = inBytes ? c.getBytes(charset).length : 1;

        if (realLength > size) throw new IllegalArgumentException("参数<size>必须至少能容纳单个字符！当前设置的" +
                                                                  size + "字节无法容纳需要" + realLength + "字节的字符。");

        // 如果当前长度超过限制，保存当前片段
        if (length + realLength > size) {
            parts.add(segment.toString());
            segment   = new StringBuilder();
            length = 0;
        }

        segment.append(c);
        length += realLength;
    }

    // 添加最后一段（如果有剩余）
    if (segment.length() > 0) {
        parts.add(segment.toString());
    }

    return parts;
}

实体类Setter方法

public void setJson(@NotNull String json) {
     if (json.getBytes(StandardCharsets.UTF_8).length > 5 * MAX_VARCHAR) {
        this.jsonShort1 = null;
        this.jsonShort2 = null;
        this.jsonShort3 = null;
        this.jsonShort4 = null;
        this.jsonShort5 = null;
        this.jsonLong   = json;
    }
    else {
        List<String> split = StringUtils.split(json, MAX_VARCHAR, true, StandardCharsets.UTF_8);
        this.jsonShort1 = split.size() > 0 ? split.get(0) : null;
        this.jsonShort2 = split.size() > 1 ? split.get(1) : null;
        this.jsonShort3 = split.size() > 2 ? split.get(2) : null;
        this.jsonShort4 = split.size() > 3 ? split.get(3) : null;
        this.jsonShort5 = split.size() > 4 ? split.get(4) : null;
        this.jsonLong   = null;
    }
}

实体类字段定义

@Lob                          private String jsonLong;
@Column(length = MAX_VARCHAR) private String jsonShort1;
@Column(length = MAX_VARCHAR) private String jsonShort2;
@Column(length = MAX_VARCHAR) private String jsonShort3;
@Column(length = MAX_VARCHAR) private String jsonShort4;
@Column(length = MAX_VARCHAR) private String jsonShort5;

编辑2：CLOB与VARCHAR性能对比测试

测试基于本地Docker Oracle数据库和JBoss EAP：

测试API代码

package my.test;

import my.model.HistoricalDataset;
import my.utils.LoremIpsum;

import javax.inject.Inject;
import javax.persistence.EntityManager;
import javax.transaction.Transactional;
import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import java.util.List;

@Path("/A1E-16094")
public class A1E_16094 {

    @Inject private EntityManager em;

    @GET
    @Path("/generate")
    @Produces("text/plain")
    @Transactional
    public String generate() {
        long max = 0;
        for (int i = 0; i < 50000; i++) {
            String string = LoremIpsum.getWords(2000);
            this.em.persist(HistoricalDataset.useVARCHAR(string));
            this.em.persist(HistoricalDataset.useCLOB(string));
            max = Math.max(max, string.length());
        }
        return "2x 50000次EntityManager#persist()，字符串最长为" + max + "字符，分别存储为VARCHAR + CLOB\n";
    }

    @GET
    @Path("/loadVARCHAR")
    @Produces("text/plain")
    public String loadVARCHAR() {
        List<HistoricalDataset> datasets = this.em.createQuery("from HistoricalDataset where uuidTable = 'VARCHAR'",
                                                               HistoricalDataset.class).getResultList();
        return datasets.size() + "条VARCHAR类型数据加载完成\n";
    }

    @GET
    @Path("/loadCLOB")
    @Produces("text/plain")
    public String loadCLOB() {
        List<HistoricalDataset> datasets = this.em.createQuery("from HistoricalDataset where uuidTable = 'CLOB'",
                                                               HistoricalDataset.class).getResultList();
        return datasets.size() + "条CLOB类型数据加载完成\n";
    }

    @GET
    @Path("/delete")
    @Produces("text/plain")
    @Transactional
    public String delete() {
        int count = this.em.createQuery("delete from HistoricalDataset where uuidTable in ('CLOB', 'VARCHAR')")
                .executeUpdate();
        return count + "条VARCHAR + CLOB类型数据已删除\n";
    }
}

测试结果

daniel@McPherson:./jboss-eap-7.4 $ curl -s -w "耗时: %{time_total}s\n" http://localhost:8080/webapp/rest/A1E-16094/generate
2x 50000次EntityManager#persist()，字符串最长为12452字符，分别存储为VARCHAR + CLOB
耗时: 97.379629s
daniel@McPherson:./jboss-eap-7.4 $ curl -s -w "耗时: %{time_total}s\n" http://localhost:8080/webapp/rest/A1E-16094/loadVARCHAR
50000条VARCHAR类型数据加载完成
耗时: 7.544128s
daniel@McPherson:./jboss-eap-7.4 $ curl -s -w "耗时: %{time_total}s\n" http://localhost:8080/webapp/rest/A1E-16094/loadCLOB
50000条CLOB类型数据加载完成
耗时: 43.838948s
daniel@McPherson:./jboss-eap-7.4 $ curl -s -w "耗时: %{time_total}s\n" http://localhost:8080/webapp/rest/A1E-16094/delete
100000条VARCHAR + CLOB类型数据已删除
耗时: 30.284013s
daniel@McPherson:./jboss-eap-7.4 $

问题解决思路

核心原因：Unicode代理对拆分错误

你的拆分逻辑用String.substring(i, i+1)处理字符，但对于Unicode代理对（比如Emoji、部分生僻汉字，这类字符由两个Java 16位字符组成），会拆分出无效的半段字符。转成UTF-8时，这个无效片段会被替换成3字节的占位符�，导致计算的字节数比实际完整字符的字节数少，最终拆分后的片段总字节数超过4000，触发Oracle错误。

修复方案：正确处理完整Unicode字符

修改拆分逻辑，用Unicode码点识别完整字符，避免拆分代理对：

public static List<String> split(String input, int maxBytes, Charset charset) {
    List<String> parts = new ArrayList<>();
    StringBuilder segment = new StringBuilder();
    int currentBytes = 0;

    int i = 0;
    while (i < input.length()) {
        int codePoint = input.codePointAt(i);
        String charStr = new String(Character.toChars(codePoint));
        int charBytes = charStr.getBytes(charset).length;

        if (charBytes > maxBytes) {
            throw new IllegalArgumentException("单个字符需要" + charBytes + "字节，超过最大限制" + maxBytes + "字节");
        }

        if (currentBytes + charBytes > maxBytes) {
            parts.add(segment.toString());
            segment = new StringBuilder();
            currentBytes = 0;
        }

        segment.append(charStr);
        currentBytes += charBytes;
        i += Character.charCount(codePoint);
    }

    if (segment.length() > 0) {
        parts.add(segment.toString());
    }

    return parts;
}

额外优化：扩展Oracle VARCHAR2长度（12c+）

如果使用Oracle 12c及以上版本，可以将VARCHAR2最大长度扩展到32767字节，减少拆分次数甚至无需拆分：

关闭数据库
启动到升级模式：startup upgrade
执行：ALTER SYSTEM SET MAX_STRING_SIZE=EXTENDED;
运行脚本：@?/rdbms/admin/utl32k.sql
关闭并重启数据库

内容的提问来源于stack exchange，提问作者Daniel Bleisteiner

如何在Java中适配Oracle VARCHAR2(4000 BYTE)字符串限制？

编辑1：使用的拆分方法及相关代码 #

字符串拆分方法 #

实体类Setter方法 #

实体类字段定义 #

编辑2：CLOB与VARCHAR性能对比测试 #

测试API代码 #

测试结果 #

问题解决思路 #

核心原因：Unicode代理对拆分错误 #

修复方案：正确处理完整Unicode字符 #

额外优化：扩展Oracle VARCHAR2长度（12c+） #