Java 后端 / 知识点

Spring Boot 开发速查手册

手册条目

配置 Mapper 接口并执行 XML 或注解 SQL。

使用 MyBatis

用于在 Spring Boot 中定义 Mapper 接口并执行注解 SQL 或 XML SQL。最小可用链路是:数据源配置正确、Mapper 被扫描、SQL 与返回类型匹配,然后通过接口方法完成查询或写入。

最小配置

以下示例假定项目已引入 mybatis-spring-boot-starter 和 MySQL 驱动,数据库中存在 sys_user 表。生产环境建议由 Flyway 或 Liquibase 管理表结构,不要依赖应用启动时自动建表。

yaml
spring:
  datasource:
    url: jdbc:mysql://127.0.0.1:3306/demo?useUnicode=true&characterEncoding=utf8&serverTimezone=Asia/Shanghai
    username: demo
    password: <PASSWORD>
    driver-class-name: com.mysql.cj.jdbc.Driver

mybatis:
  mapper-locations: classpath*:mapper/**/*.xml
  configuration:
    map-underscore-to-camel-case: true

生效结果:Spring Boot 创建数据源,MyBatis 加载 mapper 目录下的 XML,并可把 user_name 映射为 userName。密码应改为环境变量或密钥配置,不能提交到仓库。

注解 SQL

适合字段少、SQL 简短且不需要动态 SQL 的场景。Mapper 可用 @Mapper 标记;项目中有多个 Mapper 时,也可以由启动类统一使用 @MapperScan。

java
package com.example.demo.user;

import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Param;
import org.apache.ibatis.annotations.Select;

@Mapper
public interface UserMapper {

    @Select("""
        SELECT id, user_name
        FROM sys_user
        WHERE id = #{id}
        """)
    User findById(@Param("id") Long id);

    record User(Long id, String userName) {
    }
}

这里使用 #{id} 进行预编译参数绑定;查询无记录时,findById 返回 null。

高频使用

把 Mapper 注入 Spring 管理的 Service,并在业务层处理未查询到记录的情况。

java
package com.example.demo.user;

import org.springframework.stereotype.Service;

@Service
public class UserService {

    private final UserMapper userMapper;

    public UserService(UserMapper userMapper) {
        this.userMapper = userMapper;
    }

    public UserMapper.User getRequiredUser(long id) {
        UserMapper.User user = userMapper.findById(id);
        if (user == null) {
            throw new IllegalArgumentException("user not found: " + id);
        }
        return user;
    }
}

预期结果:

text
getRequiredUser(1) -> User[id=1, userName=alice]
getRequiredUser(999) -> IllegalArgumentException: user not found: 999

实际 ID 和用户名取决于数据库数据。

XML SQL

动态条件、批量操作、复杂关联或需要集中维护的 SQL 更适合 XML。namespace 必须与 Mapper 接口全限定名一致,语句 id 必须与方法名一致。

xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE mapper
    PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN"
    "https://mybatis.org/dtd/mybatis-3-mapper.dtd">
<mapper namespace="com.example.demo.user.UserXmlMapper">

    <select id="findByName" resultType="com.example.demo.user.UserXmlMapper$User">
        SELECT id, user_name
        FROM sys_user
        WHERE user_name = #{name}
        LIMIT 1
    </select>
</mapper>
java
package com.example.demo.user;

import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Param;

@Mapper
public interface UserXmlMapper {

    User findByName(@Param("name") String name);

    record User(Long id, String userName) {
    }
}

预期结果:

text
findByName("alice") -> User[id=1, userName=alice]

启动或调用时报 Invalid bound statement 时,优先检查 XML 路径、namespace、语句 id 和 Mapper 方法名是否一一对应。

高频排障

  • Invalid bound statement:检查 mapper-locations 是否覆盖 XML 文件,以及 namespace、id 是否匹配。
  • 参数找不到:多参数方法显式添加 @Param,SQL 中使用相同名称。
  • 字段为 null:检查列名、别名、map-underscore-to-camel-case 和 Java 属性名;复杂映射使用 resultMap。
  • 事务未生效:写操作放在 Spring 管理的 Service 中,并从外部 Bean 调用带 @Transactional 的公开方法;同类自调用不会经过事务代理。

风险与边界

不要把外部输入直接放进 ${value}。它会把文本原样拼入 SQL,可能导致 SQL 注入或语法破坏;优先使用 #{value} 参数绑定。表名、排序字段等确实无法参数化的位置,必须先映射到后端白名单,再使用 ${}。

批量查询如果没有分页、上限或有效条件,可能占满连接和堆内存。生产环境应设置合理返回上限、建立匹配索引,并在上线前检查实际执行计划。

目录与阅读设置

记录一个想法

Spring Boot 开发速查手册

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通