今天排查一个线上工单业务反馈某个列表接口里“员工编号”不对数据库里查出来明明是000123接口返回却成了123左侧的零不见了。我用 MySQL 命令行客户端反复确认数据没问题又去翻了 Mapper 里的 SQL也没发现任何异常最后一路追到 JDBC 驱动的取值逻辑才确定这是典型的UNSIGNED ZEROFILL列在 Java/MyBatis 链路读取时左侧零丢失的问题。这篇文章就是这次完整排查和修复的记录。我会从根因拆解开始把“为什么数据库客户端显示正常、JDBC 返回却丢零”讲清楚然后给出一个基于 MyBatis 自定义TypeHandler的通用修复方案附带完整代码、XML 配置和踩坑清单。如果你是在 Java 项目里用 MyBatis MySQL并且遇到过零填充字段查询结果不对、又不想到处改 SQL 的处境这篇笔记可以直接参考复现。1. 问题现象与根因分析1.1 场景还原从一条建表语句说起这类问题最早一般出现在表结构设计阶段。工号、流水号、会员编号这类字段业务上往往要求定长展示比如统一六位、不足左边补零。很多老项目会直接写成下面这样CREATE TABLE employee ( id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY, employee_code INT UNSIGNED ZEROFILL NOT NULL DEFAULT 0 COMMENT 工号显示宽度6位 ) ENGINEInnoDB DEFAULT CHARSETutf8mb4;注意employee_code的类型是INT UNSIGNED ZEROFILL并没有显式指定显示宽度。MySQL 对整数类型的默认显示宽度INT一般是 10或者 11视版本和有无符号而定。很多项目的 DDL 会写成INT(6) UNSIGNED ZEROFILL效果类似。插入一行测试数据INSERT INTO employee (employee_code) VALUES (123);然后直接在 MySQL 命令行查询mysql SELECT employee_code FROM employee; -------------- | employee_code | -------------- | 000123 | --------------数据库客户端展示是000123没有任何毛病。但同一时刻项目里通过 MyBatis 查出来的实体对象employeeCode属性值却是123。如果你在 Mapper XML 里写的只是最简单的select *没有任何特殊处理那丢零几乎必然发生。很多人第一反应是“我 SQL 写错了”或者“MyBatis 映射有问题”其实这两个方向都不对。问题发生在更底层。1.2 ZEROFILL 的真实本质显示层属性不是存储层数据要理解为什么左侧零会丢得先搞清楚UNSIGNED ZEROFILL在 MySQL 里到底做了什么。ZEROFILL并不是把数字转成字符串存进数据库。它只是给列附加了一个“展示时自动补零”的元数据属性当查询结果返回给客户端时MySQL 服务端会参考这个列定义的显示宽度在输出阶段把数值左侧填充0到指定宽度。真正落盘存储的始终是数值类型本身123在 InnoDB 里就是数字123不是字符串000123。这个设计其实和很多业务直觉相反。数据库不是帮你把数据格式化了再存进去它只是在你查询展示的时候“尽量”帮你格式化一下。所以“数据库客户端看到的 000123”和“应用读到 123”并不矛盾——前者是 MySQL 客户端协议层面的展示加工后者才是数据本来的样子。1.3 丢零的根因在 JDBC 驱动不在 MyBatis顺着上面这个逻辑往下走问题就很清晰了MySQL 命令行客户端收到服务端返回的文本协议结果时会根据列元数据里的ZEROFILL属性做补零展示所以你看到了000123。MySQL 的 JDBC 驱动Connector/J在读取结果集时关注的是数值本身。它对employee_code列返回的是Integer/Long类型的数值123并不会像命令行客户端那样主动套用“左侧补零到显示宽度”的展示逻辑。MyBatis 只是一个 ORM 映射框架它的职责是把你 SQL 执行完得到的ResultSet里的值搬运到 Java 对象的属性上。驱动给它的值是123它自然就给你赋123。所以链路是这样的MySQL 服务端 - JDBC 驱动 - MyBatis - Java 对象 ↑ 问题发生在这驱动没有把 ZEROFILL 元数据转成补零效果既然问题定位在驱动层那么修复思路也就清晰了要么在 SQL 阶段就把数值转成补零后的字符串要么在映射阶段拦截处理。在 MyBatis 项目里后者是更优雅、更通用的做法。2. 修复方案拆解与选型2.1 方案 ASQL 层用 LPAD 临时补零最直观的办法是在查询 SQL 里手动处理SELECT employee_id, LPAD(employee_code, 6, 0) AS employee_code FROM employee;如果你只需要救一次急这个方案没问题。但它有两个明显的坑侵入性太强。项目里所有涉及这个字段的查询 SQL 都要改一遍漏掉一个就又是一次线上事故。而且后面接手的人如果不知道这个约定直接在 SQL 里用这个字段做条件可能又会踩一遍。约束了字段的使用方式。一旦在 SQL 里变成LPAD(employee_code, 6, 0)这个表达式返回的就是字符串。如果你拿它去WHERE条件里比较MySQL 可能会走隐式转换索引失效或者结果不符合预期排查起来更绕。适合临时救急不适合做通用修复。2.2 方案 B把数据库字段改成 VARCHAR既然数字类型展示效果不好控制有人会想到直接把employee_code改成VARCHAR(6)插入时自己拼好000123再存。这个方案在新建表的时候可以考虑但对于已有的存量表我不建议随便改。原因有三点存储语义变了。原来按数值类型设计可以享受数值计算、范围比较、排序的便利改成字符串后ORDER BY变成字典序MAX(employee_code)也会得到奇怪结果。存量数据要刷。改字段类型不是改个 DDL 就结束线上几百万行数据的VARCHAR化需要评估长度、字符集、索引重建成本。补零逻辑从数据库下沉到了应用层。如果应用层忘了补零数据直接就错了比展示层丢零更严重。除非业务上这个字段本来就该是字符串编号否则别为了显示问题去动存储结构。2.3 方案 CVO/DTO 层统一格式化也就是在接口返回值组装的时候对employeeCode做一个String.format(%06d, code)之类的处理。这个方案治标不治本属于“展示层兜底”。它的主要问题在于每个需要这个字段的接口都可能单独写一遍格式化代码很难收敛。而且如果某个内部服务直接消费实体对象不经过 VO格式化又失效了。如果只是前端展示问题临时这么处理可以但作为一个系统性缺陷的修复还是不够干净。2.4 方案 DMyBatis 自定义 TypeHandler 拦截映射最终我选择的是在 MyBatis 映射层写一个自定义TypeHandler专门处理这类零填充字段。它的核心思路是让这个字段在 Java 对象里以String类型存在通过TypeHandler读取结果集时根据列元数据里的“显示宽度”做左侧补零。这样所有查询入口只要在resultMap里配置了该字段的typeHandler返回结果就自动带零不需要改任何 SQL。写入的时候也由TypeHandler统一处理保证应用层拿到的是补零字符串写回数据库时又能正确转成数值。修复逻辑收拢在一个类里团队其他人不需要知道底层发生了什么看到 POJO 属性类型是String自然就知道这个字段是定长字符串语义。三种主要方案对比对比维度SQL 层 LPAD改字段为 VARCHAR自定义 TypeHandler侵入性修改所有 SQL容易遗漏需要 DDL 和数据迁移只需配置 resultMap查询 SQL 不变索引/排序影响可能引发隐式转换问题排序变成字典序不影响数据库侧行为可复用性每个查询单独写一次性改造一个 Handler 全局复用存量改造风险低高低边界情况处理宽度写死容易出错应用层补零逻辑要自己维护可从列元数据读取宽度自动适配3. 基于自定义 TypeHandler 的完整修复实现3.1 总体设计思路自定义TypeHandler的职责分成两块读从ResultSet里拿到原始数值获取当前列在 JDBC 元数据里的显示宽度把数值转成左侧补零的字符串返回给 MyBatis 映射到 POJO 属性。写把 POJO 里补零后的字符串转回数值类型再写进PreparedStatement避免数据库把000123当成字符串处理。读是核心写是容易遗漏的坑。很多网上示例只处理了读结果项目里一执行INSERT/UPDATE就报Data truncation或者数据写进去跟预期不符就是因为没处理写方向。3.2 TypeHandler 核心代码package com.example.mybatis.handler; import org.apache.ibatis.type.JdbcType; import org.apache.ibatis.type.TypeHandler; import java.sql.PreparedStatement; import java.sql.ResultSet; import java.sql.SQLException; import java.util.Objects; /** * 处理 MySQL UNSIGNED ZEROFILL 列读取时左侧零丢失的问题。 * * 读写约定 * - Java 侧统一使用 String 接收补零后的值例如 000123 * - 写库时自动转回数值类型避免数据库隐式转换造成意外行为。 */ public class ZeroFillTypeHandler implements TypeHandlerString { /** * 写入参数。 */ Override public void setParameter(PreparedStatement ps, int i, String parameter, JdbcType jdbcType) throws SQLException { if (parameter null) { ps.setNull(i, java.sql.Types.INTEGER); return; } // 补零字符串先转成长整型防止超范围再按数值类型写回 ps.setLong(i, Long.parseLong(parameter.trim())); } /** * 读取结果集根据列显示宽度对数值左侧补零。 */ Override public String getResult(ResultSet rs, String columnName) throws SQLException { Object rawValue rs.getObject(columnName); if (rawValue null) { return null; } int displayWidth getColumnDisplayWidth(rs, columnName); return leftPadZero(rawValue.toString(), displayWidth); } Override public String getResult(ResultSet rs, int columnIndex) throws SQLException { Object rawValue rs.getObject(columnIndex); if (rawValue null) { return null; } int displayWidth getColumnDisplayWidth(rs, columnIndex); return leftPadZero(rawValue.toString(), displayWidth); } Override public String getResult(java.sql.CallableStatement cs, int columnIndex) throws SQLException { Object rawValue cs.getObject(columnIndex); if (rawValue null) { return null; } int displayWidth getColumnDisplayWidth(cs, columnIndex); return leftPadZero(rawValue.toString(), displayWidth); } private int getColumnDisplayWidth(ResultSet rs, String columnName) throws SQLException { // 通过列名找索引再去元数据里拿显示宽度 int columnIndex rs.findColumn(columnName); return getColumnDisplayWidth(rs, columnIndex); } private int getColumnDisplayWidth(ResultSet rs, int columnIndex) throws SQLException { int displayWidth rs.getMetaData().getColumnDisplaySize(columnIndex); // 个别驱动对 ZEROFILL 列可能取不到预期宽度兜底为原字符串长度 return Math.max(displayWidth, 0); } private String leftPadZero(String source, int displayWidth) { if (displayWidth 0) { return source; } int sourceLength source.length(); if (sourceLength displayWidth) { // 数值实际位数超过显示宽度时按真实位数返回不能截断 return source; } StringBuilder sb new StringBuilder(displayWidth); for (int i 0; i displayWidth - sourceLength; i) { sb.append(0); } sb.append(source); return sb.toString(); } }这段代码里几个关键点需要单独说明为什么要用rs.getObject()而不是rs.getString()或rs.getInt()getObject()是 JDBC 驱动基于列类型返回最自然类型的通用方法。对于INT UNSIGNED ZEROFILL列驱动一般返回Integer或Long转成字符串时就是基础的十进制数字不会夹带二进制协议的干扰。getString()在大多数场景也可以用但遇到一些特殊配置或列类型时行为不如getObject()稳定。实际项目里我用getObject()后踩的坑明显更少。为什么读取宽度要用rs.getMetaData().getColumnDisplaySize()这是 JDBC 规范里专门为“展示层宽度”设计的元数据接口。MySQLConnector/J在解析服务端返回的列信息时会把ZEROFILL列的显示宽度暴露在这个字段里。比如INT(6) UNSIGNED ZEROFILL这里通常能取到6默认宽度的INT UNSIGNED一般是10左右。用它来做补零依据比在代码里硬编码宽度要通用得多。为什么源码里没有做全局缓存getColumnDisplaySize()每次调用都会经过 JDBC 驱动的元数据查询有人会觉得性能有损耗想用static Map缓存起来。我在实际使用中不建议这么做原因有两个一是ResultSetMetaData的getColumnDisplaySize()开销远没有想象中那么大一次查询里也就调一次二是如果同一个TypeHandler实例被多个表、多个不同宽度的列共用你很难保证缓存的 key 不会冲突。为了省这点性能去引入状态划不来。3.3 在 MyBatis XML 中接入 resultMap有了TypeHandler接着在 Mapper XML 里配置resultMap?xml version1.0 encodingUTF-8? !DOCTYPE mapper PUBLIC -//mybatis.org//DTD Mapper 3.0//EN http://mybatis.org/dtd/mybatis-3-mapper.dtd mapper namespacecom.example.mapper.EmployeeMapper resultMap idEmployeeResultMap typecom.example.entity.Employee id columnid propertyid/ result columnemployee_code propertyemployeeCode typeHandlercom.example.mybatis.handler.ZeroFillTypeHandler/ /resultMap select idfindById resultMapEmployeeResultMap SELECT id, employee_code FROM employee WHERE id #{id} /select /mapper这里有一个容易踩的坑typeHandler配置在result标签上后这个字段的映射就完全由 Handler 接管了。如果 POJO 的employeeCode还是Integer类型MyBatis 在把String结果赋值给Integer属性的过程中可能报类型转换异常或者拿到000123后自动丢零。所以 POJO 里的对应属性必须声明为Stringpublic class Employee { private Integer id; private String employeeCode; // getter/setter 省略 }3.4 注解方式的使用如果你项目里偏好注解 SQL可以这样配置Select(SELECT id, employee_code FROM employee WHERE id #{id}) Results(id employeeResultMap, value { Result(id true, column id, property id), Result(column employee_code, property employeeCode, typeHandler ZeroFillTypeHandler.class) }) Employee findById(Param(id) Integer id);效果和 XML 配置一样。不过我个人还是建议复杂查询尽量用 XMLresultMap可读性和维护性都更好。3.5 MyBatis-Plus 场景下的接入如果你的项目用的是 MyBatis-Plus可以直接在实体类字段上标注TableName(employee) public class Employee { TableId(type IdType.AUTO) private Integer id; TableField(value employee_code, typeHandler ZeroFillTypeHandler.class) private String employeeCode; }不过 MyBatis-Plus 的typeHandler并不是所有内置方法都默认生效尤其是你自己写Wrapper查询时它只对自动生成的select列起作用。这一点我后面在踩坑清单里会再展开。4. 实操过程与验证细节4.1 动手前先确认问题真的在驱动层我在修复之前先做了一组对照验证避免改了半天根本不是这个原因。第一步用命令行客户端执行查询确认数据展示是补零的mysql SELECT employee_code FROM employee WHERE id 1; -------------- | employee_code | -------------- | 000123 | --------------第二步在 Java 代码里直接写一个最简单的 JDBC 查询不经过 MyBatistry (Connection conn DriverManager.getConnection(url, user, password)) { try (PreparedStatement ps conn.prepareStatement(SELECT employee_code FROM employee WHERE id 1)) { try (ResultSet rs ps.executeQuery()) { if (rs.next()) { System.out.println(JDBC result: rs.getObject(employee_code)); System.out.println(DisplaySize: rs.getMetaData().getColumnDisplaySize(1)); } } } }运行结果是我预期中的JDBC result: 123 DisplaySize: 6getObject()拿到的是123而getMetaData().getColumnDisplaySize(1)返回的是6。这组数据很关键它证明了两件事丢零发生在 JDBC 驱动层跟 MyBatis 无关驱动其实知道这个列的显示宽度只是没有帮你应用补零逻辑。有了这两个证据修复方案就完全清晰了在读取阶段拿到DisplaySize 6把123补成000123。4.2 完整 Demo 验证 TypeHandler 效果为了确认 Handler 的真实效果我搭了一个最小可复现的工程包含下面几个文件。建表 SQL 和测试数据CREATE TABLE employee ( id INT UNSIGNED AUTO_INCREMENT PRIMARY KEY, employee_code INT(6) UNSIGNED ZEROFILL NOT NULL DEFAULT 0, name VARCHAR(50) DEFAULT NULL ) ENGINEInnoDB DEFAULT CHARSETutf8mb4; INSERT INTO employee (employee_code, name) VALUES (123, 张三); INSERT INTO employee (employee_code, name) VALUES (456, 李四); INSERT INTO employee (employee_code, name) VALUES (99999999, 王五);注意我故意插入了一条99999999超过显示宽度6用来验证 Handler 不会把超宽数值截断。Mapper 接口public interface EmployeeMapper { ListEmployee listAll(); }XMLselect idlistAll resultMapEmployeeResultMap SELECT id, employee_code, name FROM employee /select测试运行后Mapper 返回的ListEmployee里employeeCode的值分别是张三 | 000123 李四 | 000456 王五 | 99999999这个结果完全符合预期。特别是99999999没有被截断成999999说明代码里判断sourceLength displayWidth时直接返回原始值的分支是对的。这个场景很多人在写死LPAD(employee_code, 6, 0)的方案里遇到过数据一旦超过宽度LPAD不会截断但后面接一些字符串处理时很容易因为长度假设错误而出 bug。4.3 写方向为什么 setParameter 要做数值回退我在 3.2 的代码里特意把setParameter写成了ps.setLong(i, Long.parseLong(parameter.trim()))而不是直接ps.setString(i, parameter)。原因很简单数据库列的类型是INT UNSIGNED如果你用setString传000123MySQL 在服务器端也会尝试把字符串转成数值结果还是123不会报错但这个过程属于隐式类型转换属于无奈兜底。一旦传入的字符串不是纯数字或者宽度超过数值类型的精度JDBC 驱动就可能抛异常。在项目里大概率会有这样的更新场景前端提交一个000123字符串后端直接用 MyBatis 的updateById写库。如果 Handler 不处理写方向那么000123转成字符串写进去数据库存的还是123展示层再读出来依然是000123看起来好像没问题。但你要小心如果字段是DECIMAL(10,0) UNSIGNED ZEROFILL000123转DECIMAL时可能产生精度相关的坑。更稳妥的写法是在setParameter里先trim()再用Long.parseLong或BigDecimal转成数值最后按数值类型设置参数。这样写库路径完全可控不依赖数据库端的隐式转换。4.4 与分页插件、多表查询的兼容情况这个 Handler 在单表查询场景我已经验证过是没问题的。那么分页插件、多表 JOIN 呢分页插件以常用的 PageHelper 为例它的原理是拦截 SQL改写成分页 SQL 并执行COUNT查询。分页 SQL 走的是同一个resultMap所以TypeHandler照样生效。COUNT 查询不返回业务字段不涉及这个 Handler不会产生副作用。多表 JOIN如果SELECT里同时查了a.employee_code和b.employee_code并且两个列的显示宽度不同ResultSet里它们是两个独立的列各自的ColumnDisplaySize不同Handler 会根据各自列的元数据分别补零。这里的关键是resultMap里要写清楚每个列对应的property别把两个列映射到同一个属性上。动态 SQL动态拼接的查询条件中如果用到这个字段比如where employee_code #{employeeCode}由于 Handler 只作用于结果集映射不作用于参数绑定所以不会改变 SQL 里的值。这一点其实是好事因为数据库里存的是数值123你传000123进去MySQL 隐式转成123再比较没问题。但我建议参数绑定保持传原始值别刻意传补零后的值。5. 常见问题与避坑指南我把自己实际踩过、以及在同事代码 review 里见过的问题整理成了一张速查表。问题现象根本原因处理建议配置 Handler 后查询报类型转换异常POJO 属性还是 IntegerHandler 返回 String把对应实体属性改成 StringINSERT 时数据长度报错或写入异常setParameter 直接用 setString 传补零字符串使用 setLong / setBigDecimal 写数值用该字段做 WHERE 条件时索引失效SQL 里对列做了 LPAD 或 CASTWHERE 条件保持原始数值比较展示补零交给 Handler查询结果超过显示宽度时被截断补零逻辑里没判断 sourceLength width按 3.2 代码逻辑超宽直接返回原值前端拿到的是数字JSON 里不带零Jackson 把 String 序列化成字符串但如果用 Integer 接收就没法带零实体属性用 String前端展示按字符串处理命令行显示正常Java 侧丢零JDBC 驱动不应用 ZEROFILL 展示属性用现成 TypeHandler 修复不要认为是 SQL 写错某些接口正常某些接口丢零有的查询没走配置了 Handler 的 resultMap统一所有返回该字段的 SQL 都指定同一个 resultMapsql_mode 中包含 NO_ZEROFILL该模式会让 ZEROFILL 失效命令行也不补零先检查 sql_mode否则修了半天还是看不到零多表 JOIN 时两个零填充字段显示宽度不一致不同列的 DisplaySize 不同resultMap 分别映射不同的 propertyHandler 自动适配逐个挑几个重点展开一下。关于 sql_mode 的检查这是我踩过最隐蔽的坑。项目某个测试环境的sql_mode被调整过里面加了NO_ZEROFILL导致我一开始复现问题时命令行客户端查出来也是123一度以为不是这个问题。后来把sql_mode还原后客户端立刻显示000123。所以如果你发现数据库客户端也不补零先别怀疑 Handler优先查环境变量SELECT sql_mode;关于 WHERE 条件的隐式转换假设你在 XML 里写了WHERE employee_code #{employeeCode}而employeeCode传的是前端过来的000123如果employee_code是数值列MySQL 会把000123转成数字123再比较能查到数据。如果你把employee_code改成了字符串列或者 SQL 里用了LPAD(employee_code, 6, 0) 000123那就是字符串比较000123 000123也能查到但索引大概率失效。所以我的建议是条件比较永远用数值展示补零永远用 Handler。别把两个场景混在一起。关于 JSON 序列化实体里employeeCode是StringJackson 默认序列化结果是000123带引号。如果前端接口文档里写的是字符串类型那没问题。但如果你原来定义的是Integer前端已经在按数字处理突然改成字符串可能引发前端类型判断报错。这种属于接口兼容性变更需要在发布前同步告知调用方。可以在 VO 层单独处理但实体层面改了类型就要一起评估影响。关于 MyBatis-Plus 的 Wrapper 查询我前面提到TableField(typeHandler ...)并不是所有内置查询都自动生效。MyBatis-Plus 的selectById、selectList这些自动生成的 SQL会带上typeHandler没问题。但如果你用QueryWrapper的select方法指定了部分列或者用了自定义 SQL可能不会触发实体上的 Handler。最可靠的验证方式是实际跑一个接口看返回值别想当然。关于宽度不一致的问题生产环境经常出现这种情况历史表字段是INT(6)新表字段是INT(8)两边的employee_code语义一样但显示宽度不同。Handler 最大的好处就是自动读取每张表实际的显示宽度新表老表都能适配。这比在 SQL 里写死一个宽度要健壮得多。6. 修复之后的小结与个人体会这次修复完成之后我又顺手把项目里其他几个类似的ZEROFILL字段都梳理了一遍统一换成这个 Handler。差不多一年的时间里没有再出现过“数据库展示有零、接口返回没零”的工单。我个人在实际操作中的体会是遇到这类问题先不要急着在 SQL 里补LPAD也别想着改表结构优先考虑在 ORM 映射层做一个统一拦截。因为ZEROFILL本质是一个“展示属性”它最适合被处理的层级恰恰就是结果映射层。MyBatis 的TypeHandler就是这个位置最趁手的工具。最后再分享一个小技巧如果你要修的不是INT而是DECIMAL类型的零填充列Handler 的核心逻辑不需要变但getObject()返回的可能是BigDecimaltoString()之后补零同样有效。唯一要注意的是Decimal可能有小数位左侧补零和右侧小数位要分开处理。这个场景我实际项目里用的不多需要的朋友可以在这个代码基础上自己扩展一下思路是完全一样的。