Java/后端

DevAtlas 后端数据访问与 REST 分页链路理解

本文整理 DevAtlas 当前后端中 DTO、Controller、Service、Mapper、MyBatis-Plus、XML 动态 SQL、参数绑定、分页查询、结果映射和安全边界等核心概念,帮助理解一次 REST 请求如何从前端进入系统、查询数据库并返回统一 JSON。

目录

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
  -> 返回浏览器
对象职责
ControllerHTTP 接入层
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 功能的基础链路。