MySQL 数据截断错误 #22001：原因分析与解决方案

1. 错误现象

系统在更新用户头像时抛出以下异常：

复制代码

org.springframework.dao.DataIntegrityViolationException: 
### Error updating database.  Cause: com.mysql.cj.jdbc.exceptions.MysqlDataTruncation: Data truncation: #22001
...
SQL: update sys_user set avatar = ? where user_name = ?

核心信息是 MysqlDataTruncation，错误码 #22001，对应 SQLSTATE 字符串数据右截断，即"数据过长，无法写入目标列"。Spring 框架将该异常封装为 DataIntegrityViolationException。

2. 错误码 #22001 的含义

在 MySQL 中，22001 表示字符串截断警告或错误。官方文档将其描述为：

Data too long for column 'column_name'

当插入或更新的字符串值长度超过列定义的最大长度（如 VARCHAR(255)）时，数据库在严格 SQL 模式（STRICT_TRANS_TABLES）下会拒绝写入并抛出错误。如果未启用严格模式，数据会被静默截断并产生警告，可能导致数据丢失。

3. 常见触发场景

本错误出现在 avatar 字段上，通常由以下原因导致：

存储 Base64 编码的图片 ：将图像直接转为 Base64 字符串存入数据库。一张 100KB 的图片经 Base64 编码后长度约 13 万字符，远超过 VARCHAR(255) 的容量。
存储过长的 URL：某些头像 URL 包含大量参数和签名，长度可能超出预设值。
列定义长度不足 ：表结构设计中未充分考虑实际数据的长度分布，默认使用了较小的 VARCHAR 长度。

4. 定位方法

4.1 查看表结构

执行以下命令确认字段类型和长度：

sql 复制代码

DESC sys_user;

如果 avatar 定义为 varchar(255) 或类似短长度类型，即可初步判断原因。

4.2 输出待写入数据的长度

在应用代码中临时记录数据长度，例如：

java 复制代码

String avatarData = getUserAvatarData();
logger.debug("avatar data length: {}", avatarData.length());

通过比较该长度与列定义的最大长度，可以确认是否是数据过长导致。

4.3 检查 SQL 模式

sql 复制代码

SELECT @@sql_mode;

若结果中包含 STRICT_TRANS_TABLES，则写入超长数据时会直接报错；否则可能只产生警告并截断。

5. 解决方案

根据业务需求选择合适的方案。

5.1 扩大列长度（适用于暂时存储 Base64 的场景）

若业务当前必须将头像 Base64 字符串存入数据库，可将列类型改为能容纳更大文本的类型，例如：

sql 复制代码

ALTER TABLE sys_user MODIFY COLUMN avatar MEDIUMTEXT;

各文本类型的存储容量：

TEXT：最大 65,535 字节（约 64KB）
MEDIUMTEXT：最大 16,777,215 字节（约 16MB）
LONGTEXT：最大 4,294,967,295 字节（约 4GB）

通常 MEDIUMTEXT 已能覆盖绝大多数 Base64 头像。需要注意，将大文本存储在数据库主表中会影响查询性能，应避免在频繁查询中使用 SELECT *。

5.2 存储文件路径或 URL（推荐方式）

更合理的设计是：数据库仅存储头像文件的访问路径，文件本身交由对象存储或专用文件系统管理。

实施步骤：

修改表结构，将 avatar 字段调整为存储 URL 的长度：

sql 复制代码

ALTER TABLE sys_user MODIFY COLUMN avatar VARCHAR(500) DEFAULT NULL COMMENT '头像URL';

修改应用逻辑：接收头像文件后，将其上传至对象存储服务（如 OSS、MinIO），获得可访问的 URL，然后将该 URL 写入数据库。

更新对应代码：

java 复制代码

String avatarUrl = uploadToOss(file);
user.setAvatar(avatarUrl);
sysUserMapper.updateUserAvatar(user);

该方案的优点：

数据库字段长度固定且较小，不会出现截断风险。
图片可独立进行 CDN 加速和访问控制。
数据库体积受控，备份和恢复效率更高。

5.3 应用层限制图片大小（辅助措施）

如果确需保存 Base64 数据，可在存入前对图片进行压缩和尺寸控制，以减小字符串长度。例如使用 Thumbnails 库：

java 复制代码

byte[] compressed = Thumbnails.of(inputStream)
    .size(128, 128)
    .outputQuality(0.5)
    .asByteArray();
String base64 = Base64.getEncoder().encodeToString(compressed);

此方法只能减小数据量，仍建议结合 5.1 方案扩大列长度，并为未来数据增长留出余量。

6. 预防措施

数据库设计规范

避免在常规业务表中使用大文本类型存储文件内容。如需存储长文本，可考虑垂直拆分到独立表，减少对主表查询的影响。

应用层校验

在数据写入前增加长度校验，提供明确的业务错误提示：

java 复制代码

if (avatar != null && avatar.length() > 500) {
    throw new BusinessException("头像地址长度超出限制");
}

严格 SQL 模式

生产环境建议启用 STRICT_TRANS_TABLES，让异常尽早暴露，避免数据静默丢失。
监控与日志

对 DataIntegrityViolationException 进行监控告警，并记录完整的数据长度和表信息，便于快速定位。

7. 总结

Data truncation: #22001 错误的直接原因是写入数据长度超过列定义上限，但更深层次的问题在于数据库字段设计未能与数据类型相匹配。将非结构化大文本（如 Base64 图片）存入数据库会带来性能和维护负担，推荐采用"数据库存储路径 + 对象存储保存文件"的架构。在无法改变存储方式的情况下，应合理选择 TEXT/MEDIUMTEXT 类型并配合应用层校验，确保数据完整性和系统稳定。

愿你我都能在各自的领域里不断成长，勇敢追求梦想，同时也保持对世界的好奇与善意!