导读:很多刚接手老项目、前端转后端的同学,面对
web/biz/core/persist/model多层拆分很容易困惑。本文基于 Maven 多模块工程模拟案例,完整拆解一条查询接口的调用链路,理清 Controller / Manager / Service / Dao / Mapper 各自职责,附带统一返回、全局异常、入参校验补充内容。文中类名、字段、表名全部做脱敏模拟,不包含真实业务项目信息。
目录
- 核心一句话总结
- 后端分层 ↔ 前端概念类比
- 项目模块分工(多模块 Maven 项目)
- 接口完整调用链路(案例:学时记录详情接口)
- 逐层代码解读
- 5.1 入口层:web 模块 Controller(接口暴露处)
- 5.2 业务编排:biz 模块 ManagerImpl
- 5.3 业务实现:core 模块 ServiceImpl
- 5.4 DAO 层:persist 模块 DaoImpl(数据组装、对象转换)
- 5.5 SQL 层:persist Mapper.xml(和数据库交互)
- 三种模型:Query / BO / DO 分清
- 联调提需求对照表(前端提变更、后端改代码)
- 老项目快速定位接口的排查步骤
- 高频疑问解答
- 扩展补充:统一返回体、全局异常、入参校验(项目标配)
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 返回前端
- web:
RecordOperatorController接收请求,鉴权 - biz:
RecordManagerImpl参数校验、时间格式化 - core:
RecordServiceImpl业务转发 / 附加规则(缓存、判断等) - persist:
RecordDaoImpl组装查询条件、对象转换 - 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 版本号 |
标记该方法从哪个版本新增 |
规范约束(重点)
@param后面第一个单词必须和方法参数名一字不差,大小写也要匹配;参数改名注释不更新,IDEA 黄色告警@return不要写变量名,直接描述返回是什么- 一句话简洁描述,不要冗余啰嗦,适合前端、其他开发看接口文档
- 多个参数按方法里参数顺序依次写
- 类注释放在类上面,方法注释放在方法上面,使用
/** */,单行//不属于 JavaDoc,无法生成文档、悬停看不到
自定义数据权限注解
@DataPermission(explorer = "RecordDataExplorer", resource = "#recordId", authCode = "302000")
- explorer = "RecordDataExplorer":数据权限解析器
解析器是一个单独的权限处理类。拿到资源标识(本例就是学时记录 ID)之后,按照项目内部的数据权限规则判断:当前登录用户能不能操作这条数据(比如只能看自己门店、自己区域的学时记录)。
作用:控制【行级数据权限】,有功能权限也不一定能看见别人的数据。
- resource = "#recordId":SpEL 表达式
#是 SpEL 语法,代表读取当前方法入参 ,这里取方法参数recordId的值,作为资源标识传给上面的RecordDataExplorer解析器做数据权限校验。
👉 参数名必须和 Controller 方法签名里的参数名完全一致。
如果方法参数改名,这里 SpEL 表达式也要同步修改,否则取不到值。
- 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 直接原样返回,不再做额外封装处理。
整条请求执行时序(重点)
- 前端发起 GET 请求:
/record/detail?recordId=123 - 权限切面优先拦截 :执行
@DataPermission校验,先校验功能权限码,再解析 SpEL 拿到recordId,交给数据权限解析器做行级权限判断;校验失败直接返回无权限,不会进入方法。 - 权限校验通过后,SpringMVC 进行参数绑定:把 URL 里的字符串
"123"转换成long类型。 - 调用 biz 层
recordManager.getRecordDetail4Operator(recordId)。 - 下层链路执行完成,返回
CommonResult。 @ResponseBody将返回对象序列化为 JSON,写入响应返回给前端。
Controller 层设计思想
这个接口的 Controller 非常薄,只负责三件事:接收参数、转发调用、返回结果 ,不嵌入业务逻辑。
好处:
- 权限、入参绑定、序列化交给框架和注解;
- 业务逻辑收敛在 biz 层,新增终端(学员端、驾校端)可以复用底层 Service,只新增 Manager 方法;
- 接口变更时,Controller 代码稳定,不容易改动。
常见踩坑小结
- 把
long和Long混用,不清楚不传参数会报 400; - 误以为方法名就是接口地址,修改方法名以为接口地址跟着变;
@RestController类上重复写大量@ResponseBody;- 在 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;不能为 nullLong:内部方法,调用来源不固定,语法上允许 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 是一个编译期注解 ,只在写代码、编译的时候生效,它不改变运行结果,作用是让编译器帮你把关。
含义:标记这个方法,是重写 / 实现父类或者接口里的方法。
两个核心作用
- 让编译器帮你检查签名是否匹配
它告诉编译器:我打算实现RecordService接口里的这个方法。
- 如果你不小心写错方法名、参数类型、返回值;或者接口改了方法,实现类没同步改 → 直接编译报错,标红提示
- 如果不加
@Override:写错之后,编译器不会报错,它会认为你新增了一个全新的重载方法,程序运行的时候,接口调用找不到实现,容易出现隐蔽 bug
- 提升代码可读性,给阅读者提示
别人看到@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。
预留价值:
- 后续新增业务规则(数据过滤、字段脱敏、缓存逻辑等),有统一的位置扩展;
- 多个 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. 老项目快速定位接口的排查步骤
- 拿到接口路径,全局搜索接口 url,定位 web 模块的 Controller
- 看 Controller 调用哪个 Manager 方法
- 在 biz 模块找到 ManagerImpl,再顺着方法往下找 Service、Dao
- 最后找到 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);
}