Java/后端
DevAtlas 后端数据访问与 REST 分页链路理解
本文整理 DevAtlas 当前后端中 DTO、Controller、Service、Mapper、MyBatis-Plus、XML 动态 SQL、参数绑定、分页查询、结果映射和安全边界等核心概念,帮助理解一次 REST 请求如何从前端进入系统、查询数据库并返回统一 JSON。
目录
- 1. 当前整体请求链路
- 2. Controller 与 REST 参数
- 3. DTO 的定位与作用
- 4. Service 与业务规则
- 5. Mapper 与 MyBatis-Plus
- 6. 参数绑定与 SQL 安全
- 7. XML 动态 SQL
- 8. 分页插件
- 9. 标签查询与 N+1
- 10. 结果映射
- 11. LambdaQueryWrapper
- 12. 工程原则与整体模型
1. 当前整体请求链路
以请求为例:
GET /api/v1/knowledge-items?page=1&size=10&tagId=2
完整链路:
浏览器
-> Spring Boot 内置服务器
-> DispatcherServlet
-> KnowledgeItemController
-> 参数类型转换与校验
-> KnowledgeItemService
-> KnowledgeItemMapper
-> MyBatis-Plus 分页插件
-> KnowledgeItemMapper.xml
-> MySQL
-> Projection 查询结果
-> Service 组装 DTO
-> ApiResponse 统一包装
-> Jackson 序列化 JSON
-> 返回浏览器
| 对象 | 职责 |
|---|---|
| Controller | HTTP 接入层 |
| Service | 业务逻辑层 |
| Mapper | 数据访问层 |
| Entity | 数据库表模型 |
| Projection | 某条 SQL 的查询结果模型 |
| DTO | 接口数据传输模型 |
| ApiResponse | 统一响应包装 |
2. Controller 与 REST 参数
2.1 路径映射
@RequestMapping("/api/v1/knowledge-items")
@GetMapping
对应:
GET /api/v1/knowledge-items
@GetMapping("/{id}")
对应:
GET /api/v1/knowledge-items/{id}
Spring 根据 HTTP 方法和路径,把请求交给匹配的 Controller 方法。
Controller 负责:
- 声明 REST 路径。
- 接收请求参数。
- 触发参数校验。
- 调用 Service。
- 获取
traceId。 - 返回统一响应体。
Controller 不负责写 SQL、处理复杂业务规则或直接返回数据库 Entity。
2.2 三种请求参数
查询参数:
GET /api/v1/knowledge-items?page=1&size=10
对应:
@RequestParam long page
路径参数:
GET /api/v1/knowledge-items/1
对应:
@PathVariable Long id
请求体:
POST /api/v1/knowledge-items
{"title":"Java 注解","content":"..."}
对应:
@RequestBody KnowledgeItemCreateRequest request
2.3 类型转换与校验
URL 参数首先是字符串:
"1" -> long page
"10" -> long size
处理顺序:
URL 字符串
-> Spring 类型转换
-> Jakarta Validation 校验
-> Controller 方法
例如:
@Min(1)
@Max(50)
long size
@Min、@Max 来自 jakarta.validation.constraints,不是 Lombok。Lombok 负责生成 Getter、Setter 和构造器;Validation 负责校验输入。
3. DTO 的定位与作用
DTO 是 Data Transfer Object,即数据传输对象。它不是严格意义上的独立 MVC 层,而是业务处理和接口传输之间的数据边界对象。
数据库 Entity
-> Service 处理和转换
-> DTO
-> Controller 返回
-> ApiResponse
-> JSON
Entity 表示数据库表结构,DTO 表示接口输入或输出结构,Projection 表示某条 SQL 的查询结果。
DTO 可以:
- 过滤数据库内部字段。
- 防止敏感字段被返回。
- 组合多张表的数据。
- 转换字段格式。
- 区分列表和详情结构。
- 稳定前后端接口契约。
建议区分:
Request DTO:前端提交给后端
Response DTO:后端返回给前端
列表接口使用摘要 DTO,不读取 MEDIUMTEXT content;详情接口才返回正文。这样可以减少数据库读取、网络传输和 JSON 响应体大小。
4. Service 与业务规则
Service 负责组织业务流程、调用 Mapper、处理规则、组装 DTO 和抛出业务异常。
公开内容查询要求:
status = PUBLISHED
visibility = PUBLIC
只有已发布且公开的内容才能被公开接口读取。
查询不到内容时:
throw new BusinessException(ErrorCode.KNOWLEDGE_ITEM_NOT_FOUND);
异常传播链:
Service 抛出异常
-> Controller 不捕获
-> GlobalExceptionHandler 捕获
-> 返回统一 404 JSON
Controller 不需要为每个方法重复编写 try-catch。
5. Mapper 与 MyBatis-Plus
public interface KnowledgeItemMapper
extends BaseMapper<KnowledgeItem> {
}
BaseMapper<T> 是 MyBatis-Plus 提供的通用数据库访问接口,提供:
selectById(id)
selectList(wrapper)
selectOne(wrapper)
selectCount(wrapper)
insert(entity)
updateById(entity)
deleteById(id)
如果新增非继承方法:
IPage<KnowledgeItemListRow> selectPublicPage(...);
就必须在 XML 中实现对应 SQL。
绑定关系:
KnowledgeItemMapper.java
<-> KnowledgeItemMapper.xml
<-> MySQL
XML 的 namespace 对应 Mapper 接口全限定名,select id 对应 Java 方法名。SQL 与 Java 分离,有利于阅读、维护和后续 SQL 优化。
6. 参数绑定与 SQL 安全
6.1 @Param
List<KnowledgeItemTagRow> selectTagsByItemIds(
@Param("itemIds") Collection<Long> itemIds);
@Param("itemIds") 为参数提供明确名称,MyBatis 可以按名称绑定实际值:
itemIds -> 实际的 Collection 对象
XML:
<foreach collection="itemIds" ...>
多个参数时:
@Param("keyword") String keyword
@Param("contentType") String contentType
@Param("tagId") Long tagId
对应:
#{keyword}
#{contentType}
#{tagId}
6.2 #{} 与 ${}
AND item.title LIKE CONCAT('%', #{keyword}, '%')
#{} 会生成 JDBC 预编译参数,用户输入作为参数值传给数据库,不直接拼接进 SQL。
ORDER BY ${sortColumn}
${} 是字符串替换,会把内容直接拼进 SQL,不能直接接收用户输入,否则可能导致 SQL 注入。
#{} 适合绑定普通值,但不能直接绑定表名、列名和排序字段。动态列名必须经过后端白名单映射。
7. XML 动态 SQL
<if test="keyword != null and keyword != ''">
AND item.title LIKE CONCAT('%', #{keyword}, '%')
</if>
表示有关键词时才添加标题筛选。
类型筛选:
<if test="contentType != null and contentType != ''">
AND item.content_type = #{contentType}
</if>
标签筛选:
<if test="tagId != null">
AND EXISTS (
SELECT 1
FROM knowledge_item_tag AS item_tag
WHERE item_tag.item_id = item.id
AND item_tag.tag_id = #{tagId}
)
</if>
8. 分页插件
项目使用:
mybatis-plus-jsqlparser:3.5.17
PaginationInnerInterceptor
Page
IPage
配置:
PaginationInnerInterceptor pagination =
new PaginationInnerInterceptor(DbType.MYSQL);
Service 创建分页对象:
Page<KnowledgeItemListRow> page =
new Page<>(pageNumber, pageSize);
分页通常执行两类 SQL:
SELECT COUNT(*) FROM knowledge_item WHERE ...;
得到总记录数和总页数;然后执行:
SELECT ...
FROM knowledge_item
WHERE ...
ORDER BY published_at DESC, id DESC
LIMIT ?, ?;
分页偏移量:
offset = (page - 1) * size
当前项目限制:
page >= 1
1 <= size <= 50
增加 id DESC 是为了在发布时间相同时保持稳定排序。
9. 标签查询与 N+1
低效方式:
查询 10 篇文章
-> 每篇文章单独查询标签
-> 可能执行 11 次 SQL
当前方式:
查询 10 篇文章
-> 收集 10 个 itemId
-> 一次 IN 查询全部标签
-> Java 按 itemId 分组
这样大约只需要两次 SQL,避免 N+1 查询。
Collection、List 和 Set 的关系:
Collection:接口
List:接口,继承 Collection,有顺序、允许重复
Set:接口,继承 Collection,通常不允许重复
因此参数使用:
Collection<Long> itemIds
表示方法只需要一组 ID,而不关心调用方具体传入 List 还是 Set。
10. 结果映射
MyBatis 结果映射流程:
数据库结果集
-> 根据 resultType 或 resultMap 创建 Java 对象
-> 匹配列名和属性名
-> 设置字段
-> 返回对象
例如:
item.content_type AS contentType
映射到:
private String contentType;
当前三类对象:
Entity:完整数据库表模型
Projection:某条 SQL 的查询结果模型
DTO:对外接口数据模型
完整过程:
MySQL
-> KnowledgeItemListRow
-> KnowledgeItemSummaryResponse
-> PageResponse
-> ApiResponse
-> JSON
11. LambdaQueryWrapper
LambdaQueryWrapper 是 MyBatis-Plus 提供的条件构造器:
LambdaQueryWrapper<KnowledgeItem> query =
new LambdaQueryWrapper<KnowledgeItem>()
.eq(KnowledgeItem::getId, id)
.eq(KnowledgeItem::getStatus, "PUBLISHED")
.eq(KnowledgeItem::getVisibility, "PUBLIC");
它不是数据库,也不是直接执行 SQL 的对象,而是:
Java 查询条件
-> MyBatis-Plus 构造 SQL
-> 参数绑定
-> 执行数据库查询
大致生成:
WHERE id = ?
AND status = ?
AND visibility = ?
适用边界:
简单单表条件查询:LambdaQueryWrapper
复杂分页、多表关联、性能敏感 SQL:Mapper + XML
12. 工程原则与整体模型
当前项目已经建立以下原则:
Entity 不直接对外返回:Entity -> DTO -> JSON
Controller 不写业务规则:Controller -> Service
Mapper 不处理 HTTP:Mapper 只负责数据库访问
复杂 SQL 与 Java 分离:复杂查询放 XML
普通用户输入不直接拼接 SQL:优先使用 #{参数}
列表与详情分离:列表摘要、详情正文
避免 N+1:批量查询关联数据
公开范围由 Service 控制:PUBLISHED + PUBLIC
当前后端整体模型:
HTTP 请求
-> 参数绑定和校验
-> Controller
-> Service 业务规则
-> Mapper
-> MyBatis-Plus 或 XML
-> MySQL
-> Entity / Projection
-> Service 组装 DTO
-> ApiResponse
-> Jackson
-> JSON
这是 DevAtlas 后续继续扩展登录、收藏、笔记、权限、Redis、OpenSearch 和 RAG 功能的基础链路。