前端转全栈:一条接口从前端请求到 SQL 完整流程

导读:很多刚接手老项目、前端转后端的同学,面对 web/biz/core/persist/model 多层拆分很容易困惑。本文基于 Maven 多模块工程模拟案例,完整拆解一条查询接口的调用链路,理清 Controller / Manager / Service / Dao / Mapper 各自职责,附带统一返回、全局异常、入参校验补充内容。文中类名、字段、表名全部做脱敏模拟,不包含真实业务项目信息。

目录

  1. 核心一句话总结
  2. 后端分层 ↔ 前端概念类比
  3. 项目模块分工(多模块 Maven 项目)
  4. 接口完整调用链路(案例:学时记录详情接口)
  5. 逐层代码解读
    • 5.1 入口层:web 模块 Controller(接口暴露处)
    • 5.2 业务编排:biz 模块 ManagerImpl
    • 5.3 业务实现:core 模块 ServiceImpl
    • 5.4 DAO 层:persist 模块 DaoImpl(数据组装、对象转换)
    • 5.5 SQL 层:persist Mapper.xml(和数据库交互)
  6. 三种模型:Query / BO / DO 分清
  7. 联调提需求对照表(前端提变更、后端改代码)
  8. 老项目快速定位接口的排查步骤
  9. 高频疑问解答
  10. 扩展补充:统一返回体、全局异常、入参校验(项目标配)

1. 核心一句话总结

一个接口 = 一条函数调用链。

前端发起请求,后端沿着固定分层依次处理,最后访问数据库拿到数据,再按原路封装、返回 JSON 给前端。

2. 后端分层 ↔ 前端概念类比

帮前端 / 新人快速理解各层职责:

表格

后端概念 前端类比 一句话解释
Controller 路由 + 请求处理函数 定义接口地址,接收前端请求、鉴权
Query params / 请求 body 前端传给后端的入参字段
BO response.data 最终返回给前端的业务对象
Manager 页面主业务逻辑 统筹流程、参数校验、数据格式化组装
Service 封装好的通用 api 函数 某一类数据的业务操作封装
Mapper.xml 手写 SQL 语句 和数据库交互,真正执行查询 / 更新
DO 数据库表结构 实体类,和数据库表一一对应
Convert 数据转换工具函数 DO ↔ BO 之间的对象转换

3. 项目模块分工(多模块 Maven 项目)

项目拆成 6 个核心业务模块,各司其职,互不耦合:

表格

模块名 角色 核心职责
demo-web 前台入口 接收前端请求、权限校验、参数接收
demo-biz 业务编排层 流程编排、参数校验、数据格式化组装
demo-core 业务实现层 通用业务逻辑、缓存、规则判断
demo-persist 数据持久层 DAO、Mapper、SQL,直接操作数据库
demo-model 模型定义层 Query 入参、BO 出参,定义接口出入参字段
demo-utils 通用工具箱 日期处理、加密、获取登录用户、公共工具

额外目录说明:

  • application:存放项目运行日志,排查报错优先看这里,业务开发不用改动
  • docs:需求文档、设计文档、接口文档

4. 接口完整调用链路(案例:学时记录详情接口)

接口示例:GET /record/detail?recordId=123

链路顺序:前端请求 → web → biz → core → persist → mapper.xml → 数据库,查到数据后原路逐层返回,最后封装为 JSON 返回前端

  1. web:RecordOperatorController 接收请求,鉴权
  2. biz:RecordManagerImpl 参数校验、时间格式化
  3. core:RecordServiceImpl 业务转发 / 附加规则(缓存、判断等)
  4. persist:RecordDaoImpl 组装查询条件、对象转换
  5. mapper.xml:执行关联 SQL 查询,从数据库取出原始数据

5. 逐层代码解读

5.1 入口层:web 模块 Controller(接口暴露处)

文件路径:demo-web/src/main/java/com/demo/web/controller/operator/RecordOperatorController.java

复制代码
/**
 * 查询学时记录详情(运营端)
 *
 * @param recordId  学时记录主键id
 * @return 统一返回体,data为学时记录详情
 */
@RequestMapping(value = "/record/detail", method = RequestMethod.GET)
@DataPermission(explorer = "RecordDataExplorer", resource = "#recordId", authCode = "302000")
@ResponseBody
public CommonResult getRecordDetail(long recordId, HttpServletRequest request) {
    return recordManager.getRecordDetail4Operator(recordId);
}

要点:

  • 对应前端 axios.get('/record/detail', { params: { recordId } })
  • CommonResult 是统一返回壳子,就是前端熟知的 {code, msg, data}
JavaDoc 规范讲解
复制代码
/**
 * @param recordId  学时记录主键id
 * @return 统一返回体,data为学时记录详情
 */

核心要点:JavaDoc 注释是文档注释,不参与程序运行;主要用途:IDE 鼠标悬停提示、自动生成 API 文档、IDEA 静态检查(参数名不一致标黄警告)

常用标签速查表

表格

标签 写法格式 作用
@param @param 参数名 参数说明 描述入参,参数名必须和方法签名完全一致
@return @return 返回内容说明 描述返回值,不需要写变量名
@throws @throws 异常类名 异常场景说明 声明方法可能抛出的异常
@see @see 类名/方法名 关联参考其他代码
@deprecated @deprecated 说明 + 推荐替代方案 标记接口 / 方法废弃
@since @since 版本号 标记该方法从哪个版本新增
规范约束(重点)
  1. @param 后面第一个单词必须和方法参数名一字不差,大小写也要匹配;参数改名注释不更新,IDEA 黄色告警
  2. @return 不要写变量名,直接描述返回是什么
  3. 一句话简洁描述,不要冗余啰嗦,适合前端、其他开发看接口文档
  4. 多个参数按方法里参数顺序依次写
  5. 类注释放在类上面,方法注释放在方法上面,使用 /** */,单行 // 不属于 JavaDoc,无法生成文档、悬停看不到
自定义数据权限注解

@DataPermission(explorer = "RecordDataExplorer", resource = "#recordId", authCode = "302000")

  1. explorer = "RecordDataExplorer":数据权限解析器
    解析器是一个单独的权限处理类。拿到资源标识(本例就是学时记录 ID)之后,按照项目内部的数据权限规则判断:当前登录用户能不能操作这条数据(比如只能看自己门店、自己区域的学时记录)。

作用:控制【行级数据权限】,有功能权限也不一定能看见别人的数据。

  1. resource = "#recordId":SpEL 表达式
    # 是 SpEL 语法,代表读取当前方法入参 ,这里取方法参数 recordId 的值,作为资源标识传给上面的 RecordDataExplorer 解析器做数据权限校验。

👉 参数名必须和 Controller 方法签名里的参数名完全一致。

如果方法参数改名,这里 SpEL 表达式也要同步修改,否则取不到值。

  1. authCode = "302000":功能权限码
    菜单 / 按钮权限编码。校验逻辑:当前登录账号所属角色,必须提前分配了 302000 这个权限码,才允许进入这个接口。

作用:控制【功能权限】,决定用户有没有入口访问这个接口。

校验顺序

✅ 先校验 authCode 功能权限:没有这个权限码 → 直接拦截,返回无权限

✅ 功能权限通过之后,再解析 SpEL 拿到 resource 的值

✅ 把资源标识交给 explorer 指定的数据权限解析器,做行级数据权限判断

✅ 两层校验全部放行,才进入 Controller 方法执行业务逻辑

接口方法本体,一共三部分:注解、方法签名、方法体
复制代码
@ResponseBody
public CommonResult getRecordDetail(long recordId, HttpServletRequest request) {
    return recordManager.getRecordDetail4Operator(recordId);
}
@ResponseBody

作用:告诉 Spring,该方法的返回值不要当成视图名称去查找页面,而是把对象序列化后,直接写入 HTTP 响应体返回。

  • 类上使用 @RestController:自带这个能力,方法重复添加属于冗余,不报错;
  • 类上只用 @Controller:返回 JSON 必须加它,否则 Spring 会把返回的CommonResult识别成页面名,报页面找不到。

✅ 有 @ResponseBody:Spring 识别为接口,将对象转为 JSON 返回给前端;

❌ 无 @ResponseBody(@Controller):Spring 以为要跳转页面,尝试查找名为 CommonResult 的页面,最终报错。

口诀:不加返回页面,加上返回 JSON 数据

方法签名拆解
复制代码
public CommonResult getRecordDetail(long recordId, HttpServletRequest request)

表格

组成部分 说明
public 必须是 public。权限拦截器只拦截 Controller 的 public 方法,非 public 的话权限注解不生效。
CommonResult 项目统一返回体,前端拿到的 JSON 大致是 {code, msg, data},详情放在 data 里。
getRecordDetail Java 方法名;接口路径由 @RequestMapping 控制,二者没有强制绑定关系。
long recordId 请求参数,学时记录的主键。没有加 @RequestParam,Spring 按参数名自动匹配 ?recordId=123
HttpServletRequest request Servlet 原生请求对象;本方法体内没有使用,一般是历史遗留代码,安全删除不影响接口功能。
方法体
复制代码
return recordManager.getRecordDetail4Operator(recordId);
  • recordManager:类里注入的 biz 层对象,Controller 不自己查库,直接转交;Controller 遵循原则:不写业务、不查数据库,只转发调用。
  • getRecordDetail4Operator:后缀4Operator代表运营端版本查询。

同一条学时记录,驾校端、学员端、运营端会分开提供方法,用来控制返回字段、数据脱敏、可见范围差异。

  • 下层方法返回已经组装好的 CommonResult,Controller 直接原样返回,不再做额外封装处理。
整条请求执行时序(重点)
  1. 前端发起 GET 请求:/record/detail?recordId=123
  2. 权限切面优先拦截 :执行@DataPermission校验,先校验功能权限码,再解析 SpEL 拿到recordId,交给数据权限解析器做行级权限判断;校验失败直接返回无权限,不会进入方法。
  3. 权限校验通过后,SpringMVC 进行参数绑定:把 URL 里的字符串"123"转换成long类型。
  4. 调用 biz 层 recordManager.getRecordDetail4Operator(recordId)。
  5. 下层链路执行完成,返回CommonResult。
  6. @ResponseBody 将返回对象序列化为 JSON,写入响应返回给前端。
Controller 层设计思想

这个接口的 Controller 非常薄,只负责三件事:接收参数、转发调用、返回结果 ,不嵌入业务逻辑。

好处:

  • 权限、入参绑定、序列化交给框架和注解;
  • 业务逻辑收敛在 biz 层,新增终端(学员端、驾校端)可以复用底层 Service,只新增 Manager 方法;
  • 接口变更时,Controller 代码稳定,不容易改动。
常见踩坑小结
  1. 把long和Long混用,不清楚不传参数会报 400;
  2. 误以为方法名就是接口地址,修改方法名以为接口地址跟着变;
  3. @RestController类上重复写大量@ResponseBody;
  4. 在 Controller 里面写大量格式化、判断逻辑,破坏分层。

5.2 业务编排:biz 模块 ManagerImpl

这是 biz 层运营端【学时记录详情】的编排代码,Controller 转发请求后,真正的业务编排就在这里。整体固定流程:参数校验 → 调用下层获取原始数据 → 展示字段格式化 → 封装统一结果返回

文件路径:demo-biz/src/main/java/com/demo/biz/record/impl/RecordManagerImpl.java

复制代码
public CommonResult getRecordDetail4Operator(Long recordId) {
    Precondition.checkNotNull(recordId != 0, "学时记录ID不能为空");
    RecordDetailBO ret = recordService.getRecordDetail4Operator(recordId);
    if (ret != null) {
        ret.setBeginTime(DateUtil.getFormatDateString(ret.getBeginTime()));
        ret.setEndTime(DateUtil.getFormatDateString(ret.getEndTime()));
    }
    return CommonResult.success(ret);
}
方法签名
复制代码
public CommonResult getRecordDetail4Operator(Long recordId)
  • 和 Controller 的 long recordId 不一样:这里使用包装类型 Long,允许值为 null。
  • 返回值:项目统一响应体 CommonResult。
  • long:框架接收 http 参数,强制必填,不传直接 400;不能为 null
  • Long:内部方法,调用来源不固定,语法上允许 null,校验逻辑交给代码自己控制
第一步:参数校验
复制代码
Precondition.checkNotNull(recordId != 0, "学时记录ID不能为空");

Precondition 是项目自研断言工具,参考 Guava 风格。

注意:方法名虽然叫 checkNotNull,但入参是布尔表达式。逻辑为:表达式结果为 false 时,抛出业务异常,携带提示文案 。

隐患:如果传入 null,执行 recordId !=0 会触发空指针;上游 Controller 是 long 类型,天然不会传 null。

第二步:调用下层获取业务数据
复制代码
RecordDetailBO ret = recordService.getRecordDetail4Operator(recordId);
  • recordService:core 层业务服务对象,数据库查询逻辑下沉在 core + persist 层。
  • 返回 RecordDetailBO:业务对象,存放学时记录原始字段(开始时间、结束时间、学员、教练、照片等)。
  • Manager 层不关心 SQL、不关心多表关联,只负责接收下层返回好的 BO。
第三步:前端展示字段格式化
复制代码
if (ret != null) {
    ret.setBeginTime(DateUtil.getFormatDateString(ret.getBeginTime()));
    ret.setEndTime(DateUtil.getFormatDateString(ret.getEndTime()));
}
  • 先判断 ret != null,避免查不到记录的时候出现空指针。
  • DateUtil.getFormatDateString():统一把时间转为项目约定字符串格式(一般为 yyyy-MM-dd HH:mm:ss)。
  • 这是典型的面向前端展示的格式化逻辑:数据库存储 Date / 时间戳,对外返回格式化字符串;放在 biz 层,保证运营端接口时间格式统一。core 层只负责吐出原始时间,不关心展示格式。
第四步:封装并返回统一结果
复制代码
return CommonResult.success(ret);

调用成功静态方法,包装为 {code:成功码, msg:"操作成功", data: ret}。

注意:查不到数据(ret=null)时,依旧返回成功状态码,data 为 null。前端需要自行判断 data 是否为空。

分层定位 & biz 层职责总结
复制代码
Controller (web)  ↓ 只负责接收请求、权限校验、转发
Manager (biz)     ←【当前代码位置】
                  · 参数合法性校验
                  · 调用Service获取数据
                  · 前端展示字段格式化(时间、文本)
                  · 组装 CommonResult 返回体
                  ↓
Service (core)    ↓ 核心业务规则
Mapper (persist)  ↓ SQL、数据库查询

biz 层不是底层业务规则的最终实现者,它的核心定位是对外接口编排层:控制入参校验门槛、统一对外字段格式、决定接口返回结构。同一个底层数据,不同终端(运营 / 驾校 / 学员)的差异化处理,都放在这一层。


5.3 业务实现:core 模块 ServiceImpl

文件路径:demo-core/src/main/java/com/demo/core/record/impl/RecordServiceImpl.java

这是 core 层的 Service 实现,属于整条链路里最薄的一层,职责很单纯:把请求透传给持久层 Dao。

复制代码
/**
 * @param recordId
 * @return
 */
@Override
public RecordDetailBO getRecordDetail4Operator(Long recordId) {
    RecordDetailBO ret = recordDao.getRecordDetail4Operator(recordId);
    return ret;
}
JavaDoc 注释
复制代码
/**
 * @param recordId
 * @return
 */

属于占位注释,缺少描述文本。规范写法需要补充参数、返回值说明,前面已经讲过 JavaDoc 的规范。

@Override

@Override 是一个编译期注解 ,只在写代码、编译的时候生效,它不改变运行结果,作用是让编译器帮你把关。

含义:标记这个方法,是重写 / 实现父类或者接口里的方法。

两个核心作用

  1. 让编译器帮你检查签名是否匹配
    它告诉编译器:我打算实现 RecordService 接口里的这个方法。
  • 如果你不小心写错方法名、参数类型、返回值;或者接口改了方法,实现类没同步改 → 直接编译报错,标红提示
  • 如果不加 @Override:写错之后,编译器不会报错,它会认为你新增了一个全新的重载方法,程序运行的时候,接口调用找不到实现,容易出现隐蔽 bug
  1. 提升代码可读性,给阅读者提示
    别人看到 @Override,一眼就能明白:这个方法不是凭空新增的业务方法,是来自接口 / 父类的约定方法 ,是接口规范的一部分。
    项目 core 层统一是 接口 + Impl 的写法,所有实现方法都加上这个注解,代码结构一目了然。

一句话总结

@Override 本身不改变代码运行逻辑,它就是给编译器的一个核对暗号,防止方法签名写错;同时给阅读代码的人做标记。

口诀:加了就校验,写错直接红;不加不校验,坑藏在运行。

方法签名
复制代码
public RecordDetailBO getRecordDetail4Operator(Long recordId)
  • 入参 Long recordId:学时记录主键,包装类型,允许 null;
  • 返回 RecordDetailBO:原始业务 BO 对象,上层 Manager 获取到之后,再做时间格式化等展示处理;
  • 方法名携带 4Operator,和上层 Manager 保持一致,这条查询链路一直延续到 DAO。代表运营端独立查询分支,SQL 查询字段、关联表,和驾校端、学员端查询链路做隔离。
方法体
复制代码
RecordDetailBO ret = recordDao.getRecordDetail4Operator(recordId);
return ret;
  • recordDao:persist 持久层对象,SQL 查询逻辑封装在 Dao 和 Mapper 里面;
  • 先赋值给临时变量 ret 再 return,逻辑等价于直接 return recordDao.getRecordDetail4Operator(recordId);;
  • 临时变量本身不参与业务计算,一般是为了调试时方便在此行打断点查看返回结果。
思考:为什么要保留这一层?

当前方法没有任何业务判断,只是单纯透传调用,但分层规范要求 Manager 不能直接依赖 Dao。

预留价值:

  1. 后续新增业务规则(数据过滤、字段脱敏、缓存逻辑等),有统一的位置扩展;
  2. 多个 Manager 需要复用这条查询能力时,统一调用 Service,避免重复开发 Dao 调用代码。
完整链路汇总
复制代码
Controller   getRecordDetail(long)           接收参数 + 权限校验
    ↓
Manager      getRecordDetail4Operator(Long)  参数校验 + 时间格式化 + 包装 CommonResult
    ↓
Service      getRecordDetail4Operator(Long)  透传调用(当前代码)
    ↓
DAO          getRecordDetail4Operator(Long)  调用Mapper,执行SQL查询

如果想要看实际查询的表、字段、关联逻辑,可以继续往下看 persist 层的 Dao 和 Mapper XML 文件。

小结

core 层 Service 在这里是一个轻量中转层,不做展示格式化、不组装返回体,只负责向下调用持久层,向上返回原始 BO。


5.4 DAO 层:persist 模块 DaoImpl(数据组装、对象转换)

文件路径:demo-persist/src/main/java/com/demo/persist/record/impl/RecordDaoImpl.java

这是 persist 层 DAO 的实现代码,链路里真正组装查询条件、调用 MyBatis、做 DO 和 BO 转换的地方。

复制代码
@Override
public RecordDetailBO getRecordDetail4Operator(Long recordId) {
    // 构造查询对象
    RecordDO search = new RecordDO();
    search.setRecordId(recordId);
    // 调用Mapper查库
    RecordDetailDO recordDetailDO = recordMapper.getRecordDetail4Operator(search);
    // DO转BO并返回
    return RecordConvert.toRecordDetailBO(recordDetailDO);
}
@Override

说明该方法实现的是 DAO 接口里的同名方法。前面介绍过:编译期校验,保证方法签名和接口定义保持一致,签名不一致直接编译报错。

构造查询对象
复制代码
RecordDO search = new RecordDO();
search.setRecordId(recordId);

RecordDO 即 Data Object,持久层对象,字段和数据库表一一对应。

这里仅填充主键 recordId,其余字段默认是 null,它的定位是查询条件载体。

为什么不直接传 Long 主键给 Mapper?

Mapper 方法入参统一接收 DO 对象,方便后续扩展:XML 中可以搭配 <if test="schoolCode != null"> 动态拼接条件,后续新增过滤字段时,不需要改动 Mapper 方法签名。

调用 Mapper 查库
复制代码
RecordDetailDO recordDetailDO = recordMapper.getRecordDetail4Operator(search);

recordMapper 是 MyBatis 的 Mapper 接口,和 XML 文件一一对应,方法名匹配 XML 中 select 标签的 id。

返回 RecordDetailDO:详情 DO,一般是多表联查的宽表数据,相比基础 RecordDO 字段更多,包含学员姓名、教练信息、照片等扩展字段。

这一行才是真正发起数据库查询的地方。

DO 转 BO
复制代码
return RecordConvert.toRecordDetailBO(recordDetailDO);

RecordConvert 是对象转换器,项目大多使用 MapStruct 自动生成,也有手写静态转换方法。

作用:把持久层 DO 转换成 core 层使用的 BO,隔离数据库表结构和业务对象 。

哪怕两边字段看起来差不多,这个转换也很有价值:数据库新增字段不会直接污染上层业务;BO 里可以增加业务计算字段,不影响数据库表结构。

在整条链路中的位置
复制代码
Controller   接收入参、权限校验
    ↓
Manager      参数校验、时间格式化、包装 CommonResult
    ↓
Service      简单透传(core层)
    ↓
DAO          ←【当前代码】组装查询DO、调用Mapper、DO转BO
    ↓
Mapper.xml   编写SQL,和数据库交互
设计要点

三层模型分工明确

  • DO:映射数据库表结构,只允许在 persist 层流转;
  • BO:业务对象,供给 core、biz 层使用,承载业务数据;
  • VO / Query:web 层专用,接收前端请求或者组装返回给前端的数据。

查询统一使用 DO 作为条件载体

现在只用到主键,但是统一入参为 DO,适配 MyBatis 动态 SQL,方便后续追加数据权限、多条件过滤。

小结

DAO 层职责:组装查询条件、调用 MyBatis 执行 SQL、完成 DO 到 BO 的转换,向上返回干净的业务 BO 对象,不做业务校验和展示格式化。


5.5 SQL 层:persist Mapper.xml(和数据库交互)

文件路径:demo-persist/src/main/resources/mapper/RecordMapper.xml

复制代码
<select id="getRecordDetail4Operator"
        parameterType="com.demo.persist.record.DO.RecordDO"
        resultMap="recordDetail">
    <![CDATA[select a.record_id,a.log_code,a.sim,a.class_id,a.student_id,bs.student_name,a.student_photo,bs.phone,bs.id_card,bs.sc_id,
            a.teacher_id,a.teacher_name,a.teacher_phone,a.org_code,a.org_name,
            a.device_id,a.car_id,a.card_no,a.subject_code,a.subject_type,a.train_car_type,a.stage,a.train_item,
            a.study_time,a.begin_time,a.end_time,a.appoint_begin_time,a.appoint_end_time,a.appoint_id,
            a.total_study_min,a.real_min,a.valid_min,a.invalid_min,a.mileage,a.max_speed,a.min_speed,a.avg_speed,
            a.teacher_comment,a.remark,a.audit_state,a.is_upload,a.check_state,a.check_remark,a.gmt_create,a.gmt_modify,
            b.gmt_trigger as nextAuditTime,b.remark as nextAuditReason,
            tcrb.manual_mark, tcrp.picture as cheatPic, tcrp.gps as cheatGps, tcrp.cheat_detail
            from train_record a
            inner join base_student bs on bs.student_id = a.student_id
            left join train_record_invalid b on b.record_id = a.record_id and b.max_times > 0
            left join train_record_bind tcrb on a.record_id = tcrb.record_id
            left join train_record_predict tcrp on tcrb.predict_id = tcrp.id
             ]]>
    <where>
        <if test="recordId != null and recordId != 0">
            a.record_id = #{recordId}
        </if>
        <if test="sim != null and sim != 0">
            and a.sim = #{sim}
        </if>
        <if test="classId != null and classId != '' ">
            and a.class_id = #{classId}
        </if>
    </where>
    limit 1
</select>
标签头部属性
复制代码
<select id="getRecordDetail4Operator"
        parameterType="com.demo.persist.record.DO.RecordDO"
        resultMap="recordDetail">
  • id="getRecordDetail4Operator":和 Mapper 接口里的方法名一一对应,MyBatis 靠这个匹配;也就是前面一路传下来、带4Operator运营端专用的查询。
  • parameterType:入参类型,就是我们前面组装的查询载体 RecordDO,MyBatis 会从这个 DO 对象里读取属性,填充#{xxx}。
  • resultMap="recordDetail":指定结果映射。SQL 查出来的数据库列名,按照这个 resultMap 的规则,映射到 RecordDetailDO 的字段上,解决下划线转驼峰、字段别名映射问题。

CDATA 包裹 SQL 文本。作用:防止 SQL 里面 <、& 这类符号被 XML 解析器当成 XML 标签语法报错。写复杂 SQL 建议包上。

select 字段与表关联
复制代码
from train_record a
inner join base_student bs on bs.student_id = a.student_id
left join train_record_invalid b on b.record_id = a.record_id and b.max_times > 0
left join train_record_bind tcrb on a.record_id = tcrb.record_id
left join train_record_predict tcrp on tcrb.predict_id = tcrp.id
  • train_record a:主表,学时记录主表;
  • inner join base_student bs:内连接学员表,必须匹配到学员数据才会返回这条记录,拿学员姓名、手机号、身份证号等信息;
  • left join train_record_invalid b:左连接异常复核表,查下一次复核时间、复核原因;匹配不到时,这部分字段为 null;
  • left join train_record_bind tcrb、left join train_record_predict tcrp:左连接标记表、AI 判作弊预测表,拿到人工标记、照片作弊、GPS 作弊、作弊详情;没有作弊数据,这部分字段是 null。

这就是前面说的:RecordDetailDO 是一张宽表结果,多表合并后的汇总数据。

别名 as xxx:比如 b.gmt_trigger as nextAuditTime,给数据库列起别名,交给 resultMap 映射。

+ 动态条件(MyBatis 核心)
复制代码
<where>
    <if test="recordId != null and recordId != 0">
        a.record_id = #{recordId}
    </if>
    <if test="sim != null and sim != 0">
        and a.sim = #{sim}
    </if>
    <if test="classId != null and classId != '' ">
        and a.class_id = #{classId}
    </if>
</where>

<where> 标签自带特性:自动去掉条件里多余开头的 and。

<if test="...">:条件判断,只有 DO 里面对应字段满足条件,这段 SQL 才拼进去,动态 SQL 。

当前接口场景,我们只塞了 recordId,最终拼接条件:a.record_id = #{recordId}。

这也解释了为什么 DAO 层入参统一用 DO:后续支持 sim、classId 多条件查询,不用改 Mapper 方法。

limit 1

只返回匹配的第一条记录。

业务约定:record_id 是主键,最多只有一条;加上 limit 1 是保险优化,数据库查到第一条就停止扫描,提升性能。

这条 SQL 是运营端版本的特点

对比驾校端 SQL:

这条 SQL没有加 org_code = #{orgCode} 的过滤条件 ,运营账号有权限查任意驾校的记录;驾校端的查询 SQL 一般会强制带上机构编码过滤,做数据隔离。这就是 4Operator 链路的差异点。

在整条链路里的位置
复制代码
Controller   接收入参、权限校验
    ↓
Manager      参数校验、时间格式化、包装 CommonResult
    ↓
Service      透传调用
    ↓
DAO          组装查询DO、调用Mapper、DO转BO
    ↓
Mapper XML   ←【当前代码】动态SQL、多表联查、查询数据库
小结

这份 XML 是运营端学时记录详情的查询 SQL:以内连接学员表、左连接复核和 AI 作弊相关表组装宽表数据;支持主键、sim 卡、班级号多条件动态查询;limit 1 保证只返回单条记录;查询结果映射到 RecordDetailDO,向上交给 DAO 层做 DO 转 BO。

6. 三种对象:Query / BO / DO 分清

都定义在 model 模块,是前后端对接的核心:

表格

对象 作用 存放位置 前端是否关心
Query 接收前端入参 demo-model/.../query ✅ 关心,决定前端能传哪些字段
BO 返回给前端的业务数据 demo-model/... 对应业务包 ✅ 关心,决定接口返回字段
DO 映射数据库表实体 persist 层 DO 包 ❌ 前端不需要感知

小技巧:前后端联调,想看接口出入参,优先去 model 模块找 Query 和 BO

7. 联调提需求对照表(前端提变更、后端改代码)

表格

前端需求 需要改动的地方 沟通话术参考
返回结果新增一个展示字段 mapper 加查询列 + resultMap + DO + BO 详情接口 data 里,新增返回 xxx 字段
列表增加筛选条件 Query 新增字段 + mapper.xml where 增加 if 条件 列表接口支持按 xxx 条件筛选
时间 / 金额展示格式修改 biz 层 Manager 格式化代码 该字段返回格式调整为 xxx
新增角色开放接口权限 web 层 Controller 权限注解 这个接口开放给 xxx 角色访问

8. 老项目快速定位接口的排查步骤

  1. 拿到接口路径,全局搜索接口 url,定位 web 模块的 Controller
  2. 看 Controller 调用哪个 Manager 方法
  3. 在 biz 模块找到 ManagerImpl,再顺着方法往下找 Service、Dao
  4. 最后找到 Mapper.xml 查看 SQL

小技巧:同一个业务域,各层包名都带相同标识,检索效率更高

9. 高频疑问解答

Q:为什么拆这么多层,全部写在 Controller 里不行吗?

A:分层解耦。改 SQL 不影响接口、改前端展示格式不碰数据库逻辑,多人并行开发、维护老项目不容易冲突。

Q:接口里接口名和 Impl 有什么区别?

A:不带 Impl 是接口,只定义方法签名;带 Impl 是接口的实现类,真正写业务代码,看逻辑一定要找 Impl 文件。

Q:接口报错,排查顺序是什么?

A:优先查看 application/logs 下异常日志 → 顺着调用链路,从 Controller 逐层向下定位。

10. 扩展补充:统一返回体、全局异常、入参校验(项目标配)

10.1 统一返回体 CommonResult(model 模块)

所有接口统一返回 {code, msg, data},前端不用适配多种返回格式

复制代码
@Data
public class CommonResult<T> {
    private Integer code;
    private String msg;
    private T data;

    public static <T> CommonResult<T> success(T data) {
        CommonResult<T> result = new CommonResult<>();
        result.setCode(200);
        result.setMsg("操作成功");
        result.setData(data);
        return result;
    }

    public static <T> CommonResult<T> fail(Integer code, String msg) {
        CommonResult<T> result = new CommonResult<>();
        result.setCode(code);
        result.setMsg(msg);
        return result;
    }
}

10.2 全局异常捕获 @ControllerAdvice(web 模块)

不用每个接口单独 try-catch,统一拦截异常,包装成 CommonResult 返回

复制代码
@ControllerAdvice
public class GlobalExceptionHandler {

    // 自定义业务异常
    @ExceptionHandler(BizException.class)
    @ResponseBody
    public CommonResult<?> handleBizException(BizException e) {
        return CommonResult.fail(e.getCode(), e.getMessage());
    }

    // 系统未知异常
    @ExceptionHandler(Exception.class)
    @ResponseBody
    public CommonResult<?> handleException(Exception e) {
        log.error("系统异常:", e);
        return CommonResult.fail(500, "服务器内部异常");
    }
}

10.3 Query 入参校验(JSR303,model 模块 Query)

适合 POST 接口复杂参数校验,校验不通过自动返回提示,减少 Manager 里手写 if 判断

复制代码
@Data
public class RecordQuery {
    @NotNull(message = "学时记录ID不能为空")
    private Long recordId;

    @NotBlank(message = "学员姓名不能为空")
    private String studentName;
}

Controller 增加 @Valid 开启校验:

复制代码
@PostMapping("/list")
public CommonResult list(@Valid @RequestBody RecordQuery query){
    return recordManager.list(query);
}
相关推荐
亿元程序员29 分钟前
微信小游戏备案很久?这样操作可以直接发布!
前端
福狼36 分钟前
The Expanse:让风沙成为世界的一部分
前端·three.js
程序员鱼皮41 分钟前
这 3 年 AI Agent 到底进化了啥?万字大白话,一次讲透!
前端·后端·aigc
用户900305093621 小时前
Claude Code平替评测:换掉之前先理清楚这些选型条件
前端
bai2731 小时前
同一个 JSON,Node 读出了三种坏法:Windows 上四种写法的编码实测
前端
ZANE1 小时前
纯前端实现的 .gitignore 生成器技术实现
前端
小y的笔记1 小时前
Vue 3 异步搜索实战:watch、请求取消与竞态控制
前端·javascript
sanxing三省1 小时前
DeepSeek Harness 到底是什么?标题里最重的词其实不是「DeepSeek」
前端·人工智能·deepseek
jianqiang.xue1 小时前
把Agent塞进MCU:工具次数和上下文长度怎么卡
java·前端·网络·单片机·esp32·ai编程