←AI 实践笔记
Lesson 0012 · 约 10 分钟

一次查询的
五个文件

你截图里 OrderMapper.xml 第 201–211 行那段「是否一键完结」筛选,是我(agent)写的。要读懂它,得看一条请求经过的五个文件:Controller、Mapper 接口、Mapper XML、DTO、VO。

一句话分工:Controller 是「门牌号」,把网址接进来;Mapper 接口说「有这个查询」,XML 写「具体怎么查」;DTO 装「查什么条件」,VO 装「查回来什么」。

后半课讲服务端说「agent 的 SQL 瞎写」到底指什么、改了什么。

先看东西在哪:一次「订单列表」请求

后台点开订单列表并勾「是否一键完结=否」,请求走过这些文件。上面一排你在 Lesson 0002 走过;这一课看最左边的门和最右边那两个,外加两个「搭车」的文件。

OrderController 收请求 OrderServiceImpl 业务逻辑 OrderMapper.java 接口 · 只有声明 OrderMapper.xml SQL 本体 MySQL vcm_order 等表 同名对上 OrderDTO · 条件 oneClickFinish = 0 带进去 OrderPageVO · 结果 每行一个,含 oneClickFinish 带出来

图上没有关系的:DTO 和 VO 彼此不认识——一个只管进、一个只管出。它俩字段长得像(都有 oneClickFinish),是因为都继承了 Order 实体,不是因为互相拷贝。

先看门:Controller 把网址接进来

在后台打开订单列表,浏览器 F12 → Network 里能看到这条请求:

GET /api/vcm-order/v1/order/page?oneClickFinish=0&current=1&size=20

这串地址拆成三段,每段对应一个地方(前端写法见 vcm-web/src/api/orderManager/order.js 第 4 行):

地址片段
谁认它
在哪看
/api/vcm-order
网关:转给 vcm-order 服务
决定 Jenkins 构建哪个服务(Lesson 0005)
/v1/order
类上的 @RequestMapping("/v1/order")
OrderController.java 第 47 行
/page
方法上的 @GetMapping("/page")
同文件第 71 行(你截图里那段)
@GetMapping("/page")
public ApiResult<IPage<OrderPageVO>> page(OrderDTO order, Query query) {
    IPage<OrderPageVO> pages = orderService.selectOrderPage(Condition.getPage(query), order);
    return ApiResult.data(pages);
}

Controller 自己几乎不干活:收参数 → 转给 Service → 把结果包一层 ApiResult(就是你在 Network 里看到的 {"code":200,"data":…})还回去。业务判断都在 Service 里,SQL 都在 XML 里。

参数怎么进 DTO:两种门

查询 · 列表页
操作 · 一键完结
注解
@GetMapping("/page")
@PostMapping("/one-click-finish")(第 395 行)
参数写法
page(OrderDTO order, …)
DTO 前没有注解
oneClickFinish(@Valid @RequestBody OrderOneClickFinishDTO dto)
值从哪来
网址 ? 后面的 oneClickFinish=0,按名字填进 DTO 同名字段
请求体里的 JSON {"orderIds":[…],"reason":"…"}
Network 里看
Payload → Query String Parameters
Payload → Request Payload

依据:Spring 官方说明,没加注解的对象参数按 @ModelAttribute 处理(从网址参数按名字绑定);@RequestBody 则是把「HTTP 请求体」转换成参数类型(Spring MVC · Method Arguments)。@Valid 表示进门前先校验 DTO 上标的规则(这个 DTO 上标了「订单ID不能为空」「异常原因不能为空」),不过就直接退回。

对你有用的一点:前端传的名字和 DTO 字段名差一个字母(比如传了 oneclickFinish),不会报错,DTO 里那格就是空的——于是 XML 的 <if test="… != null"> 整段跳过,表现为「筛选没生效、返回全部」。和 VO 静默丢列是同一类病:按名字对,对不上就当没有。

Retrieval Practice · 1 / 4

Network 里看到 POST /api/vcm-order/v1/order/one-click-finish 。接收这个请求的方法写在哪个文件?

再看里面:Mapper 那四个文件,各一句话

全部是当前分支 v2.2.5鼎流优车合约运力一键完结 上的真实行号,在 IDEA 里按 ⇧⇧ 搜文件名就能对照。

OrderMapper.java
接口,只有一行声明,没有方法体(第 40 行):
List<OrderPageVO> selectOrderPage(IPage page, @Param("order") OrderDTO order);
和 Lesson 0001 的接口一样,它只说「能做什么」。区别是:它的实现不是某个 Impl 类,是一段 XML。
OrderMapper.xml
SQL 本体。靠两处「同名」和接口对上:
<mapper namespace="com.hdcloud.vcm.order.mapper.OrderMapper">   ← 第 3 行,= 接口全名
  <select id="selectOrderPage"                                   ← 第 568 行,= 方法名
          resultType="com.hdcloud.vcm.order.vo.OrderPageVO">      ← 结果装进哪个类
MyBatis 官方原话:映射器 XML 会「直接映射到在命名空间中同名的映射器类」,并把 select 语句「匹配到对应名称、参数和返回类型的方法」(MyBatis 入门)。所以在 IDEA 里,从接口方法点左边的小鸟图标就能跳到 XML。
OrderDTO.java
进去的:查询条件。第 353 行 private Integer oneClickFinish;。接口参数上写了 @Param("order"),所以 XML 里用 order.oneClickFinish 取它——前缀 order. 就是这个名字。
OrderPageVO.java
出来的:每一行结果。第 68 行 private Integer oneClickFinish;。SQL 查出列 one_click_finish,MyBatis-Plus 默认「下划线转驼峰」自动装进 oneClickFinish(MyBatis-Plus 配置 · mapUnderscoreToCamelCase,默认 true)。

对照截图:条件是怎么走进 SQL 的

前端传 oneClickFinish=0 → 落进 OrderDTO → XML 第 202 行开始判断:

<if test="order.oneClickFinish != null">          ← 没传就整段跳过,不筛
  <choose>
    <when test="order.oneClickFinish == 1">
      and b.one_click_finish = 1
    </when>
    <otherwise>                                     ← 传 0 走这里
      and (b.one_click_finish = 0 or b.one_click_finish is null)
    </otherwise>
  </choose>
</if>

<if> / <choose> 就是 XML 版的 if-else(Lesson 0007 的括号规则这里换成了标签)。b. 是表别名,指 vcm_order_detail——别名在哪定义?在别处的 left join vcm_order_detail b。记住这一点,后半课要用。

为什么「否」要带 or is null:这列是 v2.2.5 才加的,老订单那一格是空的,不是 0。

Retrieval Practice · 2 / 4

测试反馈:勾「一键完结=否」,老订单一条都查不出来。你先打开哪个文件看?

Retrieval Practice · 3 / 4

SQL 里 select 了 b.one_click_finish,但忘了给 OrderPageVO 加字段。上线后会怎样?

「agent 的 SQL 瞎写」指的是什么

最具体的一次在 v2.2.3(来源单号)。我写的列表 SQL 里有 15 处这种写法,评审打回,提交 80279abeb 统一改掉。评审原话记在提交信息里:「每行执行一次,WHERE 中的 or (子查询) = ? 还会让索引失效」。

改前 · 相关子查询
改后 · join 取列
取列
(select waybill_source_no from vcm_order_waybill x where x.id = s.waybill_id)
w.waybill_source_no
外加一行 left join vcm_order_waybill w on w.id = s.waybill_id
数据库在干嘛
列表 1 万行,就跑去运单表单独查 1 万次
两张表按运单 id 一次对齐,然后逐行读
放在筛选里
or (select …) = ?:数据库没法用索引,只能逐行算完再比
or w.waybill_source_no = ?:普通列比较

改法带出的新义务:改后写的是 w.,那每个用到这段 SQL 的查询都得有 join … w。上面那个筛选片段 whereCondiSql 被 6 个查询共用,其中 3 个原本没 join 运单表——所以那次提交还给 allInfoSql、三方分页、状态计数各补了一行 join。漏补一个,XML 校验不报错,运行时才报「Unknown column w.xxx」。

评审打回过的另外三类

都已写进 wanghuo-java-coding 的「铁律七」,下次 agent 改 SQL 时会自检。你只需记住它们各自的症状,用来提问:

大 IN
先把几万个订单 id 取出来,再 where order_id in (几万个)。9-21 订单导出 504 就是它——公司公共库打 SQL 日志时逐个替换参数,参数越多越慢,3.8 万个参数花了 115 秒。症状:少量正常,量大突然超时。
SQL 里 join 字典表
「货物类型 1 → 冷藏」这种翻译,SQL 只出 1,翻译交给 Java 调字典服务。9-10 首版直接 join vcm_dict_biz 被打回。
同类列两种口径
v2.2.2 承运商运费列用了 carrier_name is null,其它承运商列都用 freight_settle_object = 3。两种看着都对,但组长要求同一类列同一个判断。

共同点:结果都对,错在「怎么查」。测试环境数据少,结果对就过了;问题要么在评审被看出来,要么在线上数据量上来后才暴露。所以服务端说「瞎写」,指的是没按数据量和项目惯例写,不是逻辑错。

Retrieval Practice · 4 / 4

把共享片段 whereCondiSql 里的子查询改成 w.waybill_source_no 之后,还必须做什么?

落到你能做的动作

下次评审或测试说 SQL 有问题,拿这三句问研发(或问我),不用看懂 SQL 本身:

  1. 「这个片段被几个查询 include 了?每个都有对应的 join 吗?」——对应 w. / b. 的别名问题。
  2. 「select 加的列,VO 里加字段了吗?」——对应静默丢列。
  3. 「生产最大量级下,这条 SQL 的参数有多少个?」——对应大 IN。

接着读什么

主源:MyBatis 官方中文 · 入门,读「探究已映射的 SQL 语句」一节(约 5 分钟),接口和 XML 如何对上就在那里。再往下读 XML 映射器 的 resultType 与 <sql> 两小节。

速查卡:Mapper / XML / DTO / VO 速查。

有不清楚的直接问我。这一课刻意没讲:Controller 上的 @ApiLog / @ApiOperation 是干嘛的、为什么有的 Mapper 没有 XML 也能查(MyBatis-Plus 的 BaseMapper 自带增删改查)、resultMap 手动映射、<foreach> 拼 IN、怎么用 EXPLAIN 自己看 SQL 走没走索引。想学哪个,说一声。