Spring Boot订单地址信息缺失排查：从MyBatis映射到序列化全链路分析

我最近在给“苍穹外卖”这个基于 Spring Boot 的外卖业务项目做 day8 的收尾验证，原计划是打通“新增地址—查询地址—提交订单”的主链路。结果就在订单回显这一步，撞上了很典型的“地址信息缺失”问题：数据库里记录明明完整，接口返回也有数据，页面上的收货人、手机号都在，但详细地址那一栏却空了。

这种问题在业务系统里非常普遍，尤其是“地址”这种复合字段组。它不是语法错误，也不会直接抛异常，通常要顺着调用链一层层排查才能看到根源。这篇文章就把我当天踩坑的完整过程写出来，包括现象定位、Mapper/序列化层面的排查思路、订单快照为什么不推荐只存一个 address_book_id，以及我踩过之后沉淀下来的自检套路。

1. 现象复盘：接口有返回，页面为什么会缺地址

先描述一下当时看到的现象。用户端“地址列表”接口是正常的，consignee、phone、provinceName、cityName、districtName 这些字段都能拿到，但订单确认页展示收货地址时，返回的 JSON 变成了这样：

json复制{
  "id": 1001,
  "addressBookId": 88,
  "consignee": "张三",
  "phone": "13800138000",
  "provinceName": "广东省",
  "cityName": "深圳市",
  "districtName": "南山区",
  "detail": null,
  "isDefault": 0
}

更隐蔽的是另一种“缺失”：整个 detail 字段直接从 JSON 里消失了，而不是值为 null。这两种现象看起来相似，但排查方向完全不一样，后面我会细讲。

1.1 “字段缺失”要先分清两层含义

我习惯把“地址信息缺失”拆成两层来看：

• 第一层：数据库里这个字段本来就是 null，比如 address_book 表的 detail 列没写入，或者写入了但更新时被覆盖掉了。
• 第二层：数据库有值，但到了接口层返回时，字段变成 null，或者字段干脆没出现在 JSON 里。

判断第一层和第二层的方法很简单。先打开数据库客户端，直接执行一层业务里对应的 SQL，看 detail 列到底有没有值。如果数据库里有值，接口返回却没有，那问题就发生在“数据库结果 → Java 对象 → JSON 字符串”这条链路里。

我当时第一反应是先查库。SQL 执行结果里，detail 列的值是完整的，所以数据库层没有问题，需要继续往上层排查。

1.2 为什么地址这种字段组特别容易“缺”

后面做久了会发现，地址信息不是单字段，而是一整组字段。一个典型的地址簿对象包含这些列：

一个对象里 20 多个字段，只要中间某个环节复制对象时漏了一个字段，或者手写 resultMap 时少映射了一个 property，系统不会报错，只会静默地把这个字段变成 null。地址这种“跨多张表做快照”的字段组，尤其容易踩到这种静默缺失。

2. 排查主线：从数据库到 JSON，逐步定位到底是哪一层丢的

遇到字段缺失问题，不要东猜西猜，我的做法是固定一条从底向上的排查链路：先看 SQL 日志，再看 Mapper 映射，再看 service 层日志，最后看 JSON 序列化。因为大部分“查不到值”的场景，根因都集中在某个具体的转换环节。

2.1 第一步看 SQL 日志，确认查询列是否完整

排查前建议先把 MyBatis 的 SQL 日志打开。在 application.yml 里加上：

yaml复制logging:
  level:
    com.example.mapper: debug

com.example.mapper 要替换成你自己项目的 Mapper 包路径。改完配置重启服务，调用一次出问题的接口，在控制台里找到对应的 Preparing 日志。这一步的目的非常明确：确认 MyBatis 真正执行的 SQL 里到底查了哪些列。

如果 SQL 里就压根没有 detail 这个列，比如写成这样：

sql复制SELECT id, consignee, phone, province_name, city_name, district_name
FROM address_book
WHERE id = 88

那问题就很清楚了，是 SQL 查询列不全。补上 detail 就行。

如果 SQL 已经查了 detail，那继续做第二步——查 Java 对象的赋值。

2.2 Mapper 层映射：手写 resultMap 漏字段是最常见的坑

外卖类项目里，很多查询并不是简单的 select *，而是会做多表联查。比如查询订单详情时需要关联地址簿表，把收货字段一起带出来。

在这种场景下，很多同学会手写 resultMap。问题是，MyBatis 对 resultMap 的配置非常宽容，你少写一个 <result> 映射，它不会报任何错误，只会默默地把那个字段留成 null。

举个例子，下面这段 resultMap 就漏掉了 detail：

xml复制<resultMap id="OrderAddressResultMap" type="com.example.vo.OrderAddressVO">
    <id property="orderId" column="order_id" />
    <result property="consignee" column="consignee" />
    <result property="phone" column="phone" />
    <result property="provinceName" column="province_name" />
    <!-- 漏了 detail 字段映射 -->
</resultMap>

注意，查询 SQL 里如果写了 detail，但 resultMap 没有对应的 <result property="detail" ...>，最终返回的 VO 里 detail 就是 null。修复方法就是补上：

xml复制<result property="detail" column="detail" />

但更推荐的做法是，如果不是必须做字段裁剪或动态映射，优先使用 resultType 配合数据库下划线列名转驼峰映射。在 application.yml 里开启：

yaml复制mybatis:
  configuration:
    map-underscore-to-camel-case: true

开启之后，province_name 可以自动映射到 provinceName 属性，少写大量 resultMap，也少一个潜在漏字段的坑。当然，resultType 自动映射也不是完全没有坑，比如如果 SQL 里用了别名，别名和实体的实际属性名对不上，一样会映射成 null。

2.3 service 层打印返回对象，判断是对象丢了还是 JSON 丢了

SQL 没问题、Mapper 映射看起来也没问题时，我会在 service 方法返回前加一行日志，把完整的返回对象打出来：

java复制log.info("queryAddress result = {}", JSON.toJSONString(result));

这里我刻意用 JSON.toJSONString() 而不是直接 log.info("{}", result)。原因是直接打印对象会触发 toString()，但某些自定义实体类没有重写 toString()，或者 MyBatis 的延迟加载代理类会干扰输出，容易让人误判。

如果日志里打出的 JSON 已经有 detail 字段且值完整，而接口返回给前端的 JSON 里 detail 缺失，那问题就出在 Controller 层或序列化层。

2.4 序列化阶段：对象有值，不代表前端接口一定有值

对象有值但接口 JSON 没字段，最常见的有这么几种：

第一，VO 里字段加了 @JsonIgnore 注解，这个字段直接不参与序列化。很多项目里实体和 VO 是复用的，原本在某个场景下不想暴露某字段，就加了 @JsonIgnore，后面换了个场景要返回这个字段，自然就丢了。

第二，字段名的 getter 写得有问题。Java 序列化框架默认走的是 getter 方法，如果字段叫 isDefault，有些框架会优先找 isDefault()，如果实体类里把 getter 写成 getIsDefault()，不同的 JSON 库解析出来结果也不一样，字段名可能就变成了 isDefault 或者直接丢了。

第三，开启了类似 @JsonInclude(JsonInclude.Include.NON_NULL) 的全局配置。这种配置会让所有值为 null 的字段直接不出现在 JSON 里。如果前端依赖某个字段是否存在来做判断，那“字段缺失”和“字段为 null”在用户体验上是一样的。

排查序列化问题最快的方式，就是在 Controller 返回前手动做一次序列化：

java复制String json = JSON.toJSONString(result);
log.info("controller return json = {}", json);

和接口实际返回的响应体对比，如果手动序列化和接口返回不一致，那就是 MVC 的序列化配置做了额外处理。

3. 写入侧的坑：下单时只存了 address_book_id，没做地址快照

前两节讲的都是“查询链路”上的缺失，实际业务里还有一类更隐蔽的“地址信息缺失”——订单表里那只存了一个 address_book_id，并没有把收货人姓名、手机号、完整地址保存下来，等订单列表接口要靠关联查询去补地址时，一旦地址簿被删掉或修改，历史订单的地址信息就彻底断了。

这也是我在做苍穹外卖 day8 下单流程时踩到的坑，每天订单产生的“地址快照”没有落库，导致查询订单详情时地址信息缺失。

3.1 为什么订单里不能只存一个 address_book_id

外卖项目的订单表，一般会包含一批冗余的收货信息字段，比如 consignee（收货人）、phone（手机号）、address（收货地址）。我见过一些新手设计表时，觉得订单表放一个 address_book_id 关联地址簿表，查询时 JOIN 一下就能拿到全部地址字段，没必要冗余存储。

这个设计在第一次下单时没问题，但业务跑一段时间就会出问题。比如用户修改了地址簿里的手机号，历史订单里的收货人联系方式也会跟着变，这就违反了下单记录应当保留“当时”收货信息的快照需求。甚至用户把地址簿某条记录删了，关联查询直接查不到数据，订单详情里的地址区域就变成了空白。

所以订单表里必须冗余一份地址快照字段，存下单那一刻的收货人、手机号和完整地址。不要省这几个字段。

3.2 BeanUtils.copyProperties 的 null 覆盖问题

做下单功能时，很多同学会这样写业务代码：

java复制AddressBook addressBook = addressBookMapper.getById(addressBookId);

Order order = new Order();
BeanUtils.copyProperties(addressBook, order);
order.setAddressBookId(addressBook.getId());
// ... 省略其他订单字段设置
orderMapper.insert(order);

第一眼看没什么问题，但这里有个足够让人崩溃的细节。

BeanUtils.copyProperties(source, target) 这个方法的作用是把 source 里的属性值复制到 target 里同名的属性上。如果 source 里某个字段为 null，它也会把 target 里的对应字段覆盖成 null。

地址簿对象 AddressBook 和订单对象 Order 之间有一部分字段名是相同的，比如 phone、consignee。但 AddressBook 里没有订单需要的 orderNumber、status、amount 等字段，而这些字段你在 BeanUtils.copyProperties 之前可能已经 set 到 Order 对象里了。

如果 AddressBook 里恰好有个字段值也是 null，并且和 Order 里某个已经赋值过的字段同名，那这个字段就会被覆盖成 null。

我的建议是，像这种“两个对象只有部分字段语义相同、整体结构差异很大”的场景，不要用 BeanUtils.copyProperties 偷懒，老老实实显式赋值：

java复制Order order = new Order();
order.setAddressBookId(addressBook.getId());
order.setConsignee(addressBook.getConsignee());
order.setPhone(addressBook.getPhone());
order.setAddress(buildFullAddress(addressBook));
order.setOrderNumber(orderNumber);
order.setStatus(OrderStatus.PENDING_PAYMENT);
order.setAmount(computedAmount);

显式赋值的代码虽然看起来啰嗦，但可读性非常强，谁漏了字段一眼就能看出来。用 BeanUtils.copyProperties 图省事，最后在 20 多个字段里找 null，反而更浪费时间。

3.3 地址快照不是直接把 detail 塞进去就完了

还有一个非常典型的“信息缺失”是语义层面的缺失。有人把 address_book 表里的 detail 字段直接存进订单的 address 字段里，但 detail 在地址簿表里的含义通常只是“详细地址”，比如“科技园南路 88 号”，并不包含省市区信息。

如果订单详情页要展示完整收货地址，只把 detail 存进去，前端展示时就会变成没有省市区的一行小字，看起来像“省份没了、城市没了、区也没了”。这和我文章开头说的“地址信息缺失”现象几乎一模一样。

正确的做法是，把省市区名称和详细地址拼接成完整地址后再落库：

java复制public static String buildFullAddress(AddressBook addressBook) {
    StringBuilder sb = new StringBuilder();
    sb.append(nullToEmpty(addressBook.getProvinceName()));
    sb.append(nullToEmpty(addressBook.getCityName()));
    sb.append(nullToEmpty(addressBook.getDistrictName()));
    sb.append(nullToEmpty(addressBook.getDetail()));
    return sb.toString();
}

private static String nullToEmpty(String str) {
    return str == null ? "" : str;
}

注意，这里的 provinceName、cityName、districtName 任何一个为空时，不要直接拼一个 "null" 字符串进去，否则数据库里存的就是“广东省null南山区科技园南路 88 号”这种脏数据。所以这里我用了一个 nullToEmpty 的方法做兜底。

4. 高频根因对照表：不同“缺失”现象对应不同解决路径

排查了一天之后，我把这次遇到的“地址信息缺失”按阶段和现象整理成了一个对照表。后面再遇到同类问题，我会先按这张表快速定级，而不是一头扎进代码里翻。

这个表稍微展开一下，对应到实际代码里是这些特点：

• “请求参数缺失”通常不是后端问题，是前端表单和 DTO 的字段命名不一致，后端接收的时候全部是 null。
• “数据库有值、接口返回 null”是最需要按 2.x 那一节流程排查的场景。
• “整个字段消失”多是 JSON 序列化配置导致，和数据库没关系。
• “下单后地址表为 null”属于写入逻辑缺陷，重点看 insert 之前有没有把值 set 进去。
• “更新后字段变 null”，通常是直接把前端提交的部分字段对象整体 updateById，而前端没提交的字段被覆盖掉了。

其中“更新后字段变 null”值得单独提醒一下。地址簿如果采用“先查出来，把允许修改的字段 set 进去，最后执行 update”的方式，就不会出现这个问题。但如果直接拿前端传过来的对象执行 updateById，前端没传的字段就用默认值覆盖了数据库原值，这也是“地址信息缺失”的一个高频原因。

5. Day8 之后我沉淀的自检套路：三招让地址字段缺失问题不过夜

排查地址信息缺失这类问题，最费时间的不是改代码，而是定位阶段在多层链路里反复横跳。后来我给自己定了几条很死板的规矩，按照规矩走，基本能在几分钟内锁定问题方向。

5.1 凡是涉及“地址保存/更新”的接口，必查一条主链路

如果这次改动涉及地址簿的新增、修改、删除，或者订单表里写入地址快照，我不会只看当前接口返回是否正确，而是会完整跑一遍“主链路”：

1. 新增地址：前端传什么字段，后端落库后能否通过接口完整查出。
2. 编辑回显：调用详情接口后，所有地址字段是否都有值。
3. 提交订单：确认订单表中的收货地址快照是否完整。
4. 订单查询：从订单详情接口拿到的 JSON，是否包含所有需要展示的地址字段。

我这次在苍穹外卖 day8 里只测了第 1 步和第 2 步，没走到第 3、4 步，所以线下环境的地址列表看着一切正常，联调时才发现订单里的地址快照根本没存。补了一个“下单后去订单表里核对收货信息”的用例后，这个问题就再没出现过。

5.2 日志只加在关键边界，不要全程铺日志

排查字段问题时，很多人爱在几十个方法里都打上日志，结果刷屏刷得没法看。我的习惯是只在三条边界打必要日志：

• Controller 入参处：确认接口拿到的字段。
• Service 方法返回前：确认 Java 对象经过业务逻辑后字段是否完整。
• Mapper 执行 SQL 处：通过 MyBatis 日志看实际查询的列。

这三条边界的日志，配合数据库客户端手工执行 SQL，基本能覆盖“地址信息缺失”的绝大多数场景。

另外在调试期，我会把打印内容序列化成 JSON。直接打印对象很容易被默认 toString() 误导，特别是在一个对象里嵌套了多个子对象时。序列化成 JSON 后，字段哪个有值哪个没值，一眼就看清了。

5.3 字段多、复制多的地方，优先用构造器或 Builder

我自己每次看到代码里连续三行以上的 bean.setXxx(bean2.getXxx())，就会提醒自己这里存在“漏字段”风险。

地址簿往订单快照赋值、地址簿转 VO、DTO 转实体，这些场景本质上是同一个源头的数据在不同结构之间迁移。与其反复 BeanUtils.copyProperties 或者手写十来行 setter，不如在订单一侧定义自己的构造器或静态工厂方法，把字段对应关系收敛到一处。这样后续改一个字段，只需要在一个地方同步维护。比如：

java复制public static Order fromAddressBook(AddressBook addressBook, String orderNo) {
    Order order = new Order();
    order.setAddressBookId(addressBook.getId());
    order.setConsignee(addressBook.getConsignee());
    order.setPhone(addressBook.getPhone());
    order.setAddress(buildFullAddress(addressBook));
    order.setOrderNumber(orderNo);
    return order;
}

调用方就不需要关心 Order 里有几个地址字段、该怎么取值了。新增字段时，维护工厂方法这一处就行，漏配的概率大大降低。

实际开发里，地址信息缺失很少是“某一个惊天大 Bug”导致的，更多是字段太多、对象转换太随意、查询映射又不严谨，一环扣一环悄悄吞掉了数据。把上面这些环节都过一遍，绝大多数问题都能在十分钟内定位清楚。