企业官网建设流程全解析

1. 先搞清楚mapper接口到底解决什么问题

1.1 传统DAO写法的痛点

在接触MyBatis之前，我相信很多人的DAO层代码都是这么写的：先获取Connection，然后创建PreparedStatement，再手动拼SQL、set参数、遍历ResultSet封装对象，最后还要在一堆finally里关资源。这套流程写一次能忍，写十个表就有想离职的冲动。

等到用了SqlSession之后，情况好了一些，MyBatis帮我们省掉了连接管理、参数设置、结果集映射这些脏活，但新的问题又冒出来：SQL语句以字符串形式散落在Java代码里，比如sqlSession.selectList("com.example.mapper.UserMapper.findAll")，这个字符串一旦写错，编译期完全不报错，运行到那一行才炸。而且IDE的重构功能对这种字符串无能为力，你改了方法名或者XML里的id，Java这边完全感知不到。

我在一个老项目里就见过这种代码，一个查询用户的方法，字符串"userMapper.selectByUsername"在十几个Service里被硬编码，后来某个字段改名，全局替换字符串的时候漏了三个地方，线上直接就503了。所以当MyBatis推出mapper接口这套机制的时候，第一反应是：这才是DAO层该有的样子。

1.2 mapper接口：把SQL调用变成类型安全的方法调用

mapper接口本质上是定义了一组Java方法的契约，每个方法对应XML里的一条SQL语句。调用方不再需要关心SQL语句的id字符串，只需要像调用普通Java方法一样调用接口方法，剩下的交给MyBatis去匹配。

这样做的好处非常直接：

• 编译期就能发现方法名拼写错误、参数类型不匹配的问题
• IDE可以直接跳转到接口方法，再顺着方法找XML，重构的时候能联动
• 业务代码从字符串依赖中解放出来，代码可读性一下子提升一个档次

说白了，mapper接口就是给MyBatis披上了一层"类型安全"的外衣，让SQL调用从散乱的字符串变成了结构化的方法调用。

1.3 接口在整个MyBatis执行链路中的位置

从架构上看，MyBatis的调用链大致是：业务层调用mapper接口方法，MyBatis通过动态代理拦截这个调用，根据方法签名找到对应的MappedStatement（也就是一条SQL的完整定义），然后交给Executor执行，最后把ResultSet映射成Java对象返回。

这个链路里，mapper接口是入口，xml是定义，SqlSession是执行者。三者各司其职。如果你只是会用MyBatis而不理解这个链路，后面遇到"绑定异常""缓存不生效""二级缓存查询到旧数据"这类问题，排查起来会非常痛苦。这个我在第四部分会展开讲。

2. 动手前先定好接口设计规范

2.1 包结构、命名与XML的一一对应关系

创建mapper接口之前，第一步不是写代码，而是定好包结构和命名规范。MyBatis的mapper接口与XML映射文件默认是按"全限定名"匹配的，也就是说，接口的全限定名（包名+类名）必须和XML的namespace保持一致，否则运行期直接报绑定异常。

我常用的规范是这样：

• 接口统一放在xxx.mapper包下，比如com.example.mapper
• 接口命名采用实体名+Mapper，比如UserMapper、OrderMapper
• XML文件与接口同名、同目录存放，比如UserMapper.xml和UserMapper.java放在同一个包下，这样打包的时候不会散掉，IDE也能在接口方法上直接定位到XML中的SQL

有人喜欢把XML放在resources目录下，包路径和接口保持一致，这也是主流做法。关键是namespace必须一模一样，一个字符都不能差。

2.2 接口方法设计的三个黄金约定

结合我多年的实战经验，mapper接口方法设计有三个约定值得遵守：

第一，一个方法对应一条SQL。方法名和XML里的id一一对应，哪怕你只是想查个count，也要单独定义一个方法。不要在同一个方法里根据条件拼接不同SQL，那样会让XML里的 判断变得不可维护。

第二，参数要精简。能用单个参数绝不用多个参数。单个实体参数、单个基本类型参数、Map参数都是好选择。多个参数不是不行，但必须配合@Param注解，否则MyBatis识别不了参数名，这个坑我后面单独讲。

第三，返回值类型要明确。需要返回实体就用实体类型，需要返回列表就用List<实体>，只需要影响行数就返回int。最忌讳的是模糊两可，一会返回List一会返回单个对象，如果SQL实际查出了多行，MyBatis会直接抛TooManyResultsException，这类报错定位起来很费劲。

2.3 提前规划SQL操作：从接口方法到XML声明的映射关系

写接口的时候，心里就要对每条SQL有数。我的做法是先列出这个实体需要的全部数据库操作，再逐一定义接口方法，最后一次性写XML。比如User实体，通常需要这些方法：

• int insertUser(User user)新增
• int deleteById(Integer id)按主键删除
• int updateUser(User user)更新
• User findById(Integer id)按主键查询
• List<User> findAll()查询全部
• long countUser()统计总数

每个方法名在XML里的id就是方法名本身，不需要前缀。记住一个原则：接口里的方法名、参数、返回值三者合起来，就是XML里那条SQL的"签名"。只有三者都匹配，MyBatis才能把调用正确翻译成SQL执行。

3. 完整实操：创建UserMapper接口

3.1 准备依赖与基础配置

实操之前，先确认工程里已经引入了MyBatis的核心依赖。如果是一个普通Maven项目，pom.xml里要加上：

<dependency> <groupId>org.mybatis</groupId> <artifactId>mybatis</artifactId> <version>3.5.16</version> </dependency>

如果是Spring Boot项目，建议用mybatis-spring-boot-starter，版本选择2.3.x之后基本稳定。这里我不展开Spring整合的细节，先讲纯MyBatis环境下的玩法，因为把底层机制搞明白，后面接入Spring就是一行注解的事。

然后准备一个最基础的mybatis-config.xml：

<?xml version="1.0" encoding="UTF-8" ?> <!DOCTYPE configuration PUBLIC "-//mybatis.org//DTD Config 3.0//EN" "https://mybatis.org/dtd/mybatis-3-config.dtd"> <configuration> <environments default="development"> <environment id="development"> <transactionManager type="JDBC"/> <dataSource type="POOLED"> <property name="driver" value="com.mysql.cj.jdbc.Driver"/> <property name="url" value="jdbc:mysql://localhost:3306/test"/> <property name="username" value="root"/> <property name="password" value="123456"/> </dataSource> </environment> </environments> </configuration>

这段配置先不注册mapper，注册方式我放在3.4节单独比较。

3.2 定义User实体与UserMapper接口

先准备一个简单的实体类User：

public class User { private Integer id; private String username; private String email; // 必须提供无参构造器和getter/setter public User() {} public Integer getId() { return id; } public void setId(Integer id) { this.id = id; } public String getUsername() { return username; } public void setUsername(String username) { this.username = username; } public String getEmail() { return email; } public void setEmail(String email) { this.email = email; } }

然后是本节的主角——UserMapper接口：

package com.example.mapper; import com.example.entity.User; import java.util.List; public interface UserMapper { int insertUser(User user); int deleteById(Integer id); int updateUser(User user); User findById(Integer id); List<User> findAll(); long countUser(); }

这里有个细节：接口里不需要写任何实现，也不需要extends任何父接口。方法名、参数类型、返回值类型在写的时候就要想清楚，因为它们直接决定了XML里SQL怎么配。

3.3 编写UserMapper.xml并完成绑定

接口写完之后，创建UserMapper.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.mapper.UserMapper"> <insert id="insertUser" parameterType="com.example.entity.User" useGeneratedKeys="true" keyProperty="id"> INSERT INTO t_user(username, email) VALUES (#{username}, #{email}) </insert> <delete id="deleteById" parameterType="integer"> DELETE FROM t_user WHERE id = #{id} </delete> <update id="updateUser" parameterType="com.example.entity.User"> UPDATE t_user SET username = #{username}, email = #{email} WHERE id = #{id} </update> <select id="findById" parameterType="integer" resultType="com.example.entity.User"> SELECT id, username, email FROM t_user WHERE id = #{id} </select> <select id="findAll" resultType="com.example.entity.User"> SELECT id, username, email FROM t_user </select> <select id="countUser" resultType="long"> SELECT COUNT(*) FROM t_user </select> </mapper>

几个关键点单独说一下：

namespace必须是com.example.mapper.UserMapper（接口全限定名），这是绑定的第一道保险。

id必须与接口方法名完全一致，包括大小写。deleteById少写一个大写B，运行期就会报Invalid bound statement。

parameterType和resultType可以不写得那么全，MyBatis会根据方法签名自动推断，但显式写出来有两个好处：一是别人看XML的时候不用翻接口，二是MyBatis省去推断开销。我个人习惯是都写上，尤其在团队协作项目里，XML本身就承担着一部分文档职责。

这里特别要说说#{}和${}的区别。#{}是预编译参数占位符，MyBatis会把它转成?，由JDBC的PreparedStatement来处理，可以防止SQL注入。${}是字符串直接替换，虽然有动态列名之类的场景要用，但平时写SQL一律用#{}，这是底线。

3.4 注册mapper的三种方式对比

XML写完之后，还需要在mybatis-config.xml里把mapper告诉MyBatis。有三种注册方式：

<!-- 方式一：用resource指定XML位置，最常用 --> <mappers> <mapper resource="com/example/mapper/UserMapper.xml"/> </mappers> <!-- 方式二：直接用接口类注册，要求XML与接口同包同名 --> <mappers> <mapper class="com.example.mapper.UserMapper"/> </mappers> <!-- 方式三：包扫描批量注册，推荐 --> <mappers> <package name="com.example.mapper"/> </mappers>

我强烈推荐方式三。项目里的mapper接口一多，方式一和方式二会让配置文件膨胀到没法看。而且package扫描能保证新增接口零配置，只要XML位置放对了，启动即生效。

通过SqlSessionFactoryBuilder.build()读取配置，然后：

String resource = "mybatis-config.xml"; InputStream inputStream = Resources.getResourceAsStream(resource); SqlSessionFactory sqlSessionFactory = new SqlSessionFactoryBuilder().build(inputStream); try (SqlSession sqlSession = sqlSessionFactory.openSession()) { UserMapper userMapper = sqlSession.getMapper(UserMapper.class); User user = userMapper.findById(1); System.out.println(user.getUsername()); }

这一步跑通了，说明从接口到XML的整个绑定链路没有问题。

4. mapper接口背后到底怎么工作的

4.1 getMapper返回的其实是一个动态代理

很多第一次接触mapper接口的人都会疑惑：明明是一个没有实现类的接口，为什么sqlSession.getMapper(UserMapper.class)召唤出来的东西能直接调用方法？

答案就是JDK动态代理。

SqlSession.getMapper()内部会去MapperRegistry里查找这个接口对应的MapperProxyFactory，然后调用newInstance()方法，通过JDK Proxy生成一个代理对象。这个代理对象实现了UserMapper接口，但方法体是空的——真正的逻辑都在MapperProxy的invoke()拦截器里。

我用一个生活化的类比来解释：你去4S店买车，接待你的不是生产厂商，而是销售顾问。你提出需求（调用接口方法），销售顾问帮你联系后方的各个部门（SqlSession、Executor、StatementHandler），最后把车交给你（返回结果）。你根本不需要知道厂商内部有多少条流水线。

4.2 从接口方法到SQL执行的完整调用链

代理对象调用接口方法后，MapperProxy.invoke()会做几件事：

第一步，判断是不是Object自带的方法，比如toString()、hashCode()、equals()，如果是就直接走原逻辑，不进SQL流程。

第二步，根据方法生成或者从缓存中取出一个MapperMethod对象。这个对象维护了两个关键信息：SqlCommand（记录这条SQL的id和类型）和MethodSignature（记录方法返回类型、参数类型、@Param注解信息）。

第三步，MapperMethod.execute()根据SQL类型（INSERT、UPDATE、DELETE、SELECT）调用对应的SqlSession方法，比如sqlSession.selectOne()、sqlSession.insert()。这里有个细节：如果方法返回值是List，MyBatis会调用selectList()，所以XML里的resultType不需要写成java.util.List，只需要写List里的元素类型。

第四步，SqlSession把执行委托给Executor，Executor再通过StatementHandler拼装JDBC的PreparedStatement，设置参数，执行SQL，最后通过ResultSetHandler把结果集映射成Java对象。

这个调用链实际上解释了MyBatis面试题里特别爱问的MapperMethod和MapperProxy的关系。我把热点关键词整理成一个速记：

4.3 缓存与mapper接口的关系

前面聊到缓存热搜词，我说一下缓存和mapper接口的关系，因为很多人在这里栽过跟头。

MyBatis的一级缓存默认是开启的，作用范围是SqlSession。同一个SqlSession内执行两次相同的查询，第二次会直接命中缓存，不开数据库查询。一级缓存的key由statementId、SQL、参数等组成，statementId其实就是"接口全限定名+方法名"。

二级缓存的作用范围是namespace，也就是一个mapper接口对应的XML。开启方式是在Mapper.xml里加<cache/>标签。加了之后，多个SqlSession共享这个XML对应的缓存数据。注意，二级缓存是事务级的，只有SqlSession提交或关闭之后，缓存数据才会被写入，所以如果你查询后一直不提交，缓存不会生效。

二级缓存的坑在于：如果一个UserMapper的XML开启了<cache/>，另一个订单Mapper的XML通过关联查询也查了user表数据，这时User表数据在UserMapper的缓存里更新了，订单Mapper的缓存却不知道，就会出现"缓存查到旧数据"的问题。所以在设计缓存时，要么严格控制缓存粒度，要么直接用Redis这类分布式缓存替代。

5. 常见问题排查与避坑

5.1 Invalid bound statement (not found)排查

这是所有初次搭建mapper接口的人必遇的报错，报错信息大概是：

org.apache.ibatis.binding.BindingException: Invalid bound statement (not found): com.example.mapper.UserMapper.findById

排查顺序固定看四个地方：

第一，接口全限定名和XML的namespace是否完全一致。最常见的是复制代码时包名写错，或者XML放在了resources目录且目录结构没有对齐。

第二，XML里的id是否等于接口方法名。注意是严格等于，连大小写都要一致。

第三，XML文件是否真的被MyBatis扫描到。用<package name="xx.mapper"/>扫描时，要求接口和XML同包同名。很多Maven项目的问题出在XML放在了src/main/java下，但构建时没有把XML文件纳入classpath，导致运行时找不到。

第四，检查是否注册了该mapper。如果前面三种方式都没注册，MyBatis根本不知道有这个接口。

我提供一个终极排查思路：先写一个test，手动加载mybatis-config.xml，打印sqlSession.getConfiguration().getMappedStatementNames()，看里面有没有你要的statement。如果集合里有，说明绑定成功，问题在调用侧；如果集合里没有，说明XML没被加载或者namespace不一致，按上面四点逐项查。

5.2 参数绑定问题与@Param

接口方法如果是多参数，比如：

List<User> findByNameAndEmail(String username, String email);

对应的XML如果写成#{username}、#{email}，运行时会报错：

org.apache.ibatis.binding.BindingException: Parameter 'username' not found. Available parameters are [arg1, arg0, param1, param2]

原因是MyBatis在Java编译默认不保留参数名的情况下，拿不到真实的参数名。它只能用arg0/arg1或者param1/param2来占位。解决办法有两个：

第一种，写法上直接用paramN引用：

<select id="findByNameAndEmail" resultType="com.example.entity.User"> SELECT * FROM t_user WHERE username = #{param1} AND email = #{param2} </select>

第二种，加@Param注解：

List<User> findByNameAndEmail(@Param("username") String username, @Param("email") String email);

<select id="findByNameAndEmail" resultType="com.example.entity.User"> SELECT * FROM t_user WHERE username = #{username} AND email = #{email} </select>

我强烈建议用第二种，语义清晰，可读性好。param1、param2这种写法一旦方法参数调整，SQL就废了。

另外提一个Java 8+的特性：如果在pom.xml的maven-compiler-plugin里配置<parameters>true</parameters>，编译时会把参数名写进字节码，MyBatis就能直接识别方法参数名。但这个依赖编译配置，项目成员换机器或者IDE设置不一致时很容易出问题，所以最稳妥的还是加@Param，别把命运交给编译参数。

5.3 返回值类型采坑记录

接口方法返回类型和XML的resultType不匹配，也会引发诡异问题。

比如方法定义的是List<User> findAll()，XML里resultType却不小心写成了java.lang.String，MyBatis在映射结果集的时候会尝试把每个字段映射成String，轻则类型转换异常，重则数据直接错乱。

还有一种常见错误：方法返回单个User，但SQL查出了多条记录。MyBatis会抛TooManyResultsException。这类问题往往是业务上查询条件没写全，不是配置问题，但排查时容易被误导到绑定层去。

我自己常用的约定是：

• 查询单条记录：返回实体类型
• 查询多条记录：返回List<实体>
• 统计条数：返回long或int
• 更新操作：返回int表示受影响行数

这些约定配合XML里的resultType，基本能规避大部分类型坑。

5.4 常见问题速查表

6. 整合进Spring后还要注意什么

6.1 @MapperScan与@Mapper的区别

文章开头我提过，这里再展开一点。纯MyBatis环境需要手动拿SqlSession来getMapper，但在Spring Boot项目里，通常只需要在配置类上加@MapperScan("com.example.mapper")，或者在每个Mapper接口上标@Mapper。两者作用基本都是让Spring容器扫描到这些接口，然后通过MapperFactoryBean为每个接口生成代理对象注册成Bean。

区别在于粒度：

• @Mapper作用于单个接口，适合mapper数量少、不需要统一扫描路径的场景
• @MapperScan作用于一个包，批量处理，适合典型的项目分割模式

使用@MapperScan时要注意basePackages别写错了根包，否则包下接口扫描不到。而且Spring Boot启动时如果扫描到的接口没有对应XML，也会报绑定异常，排查思路和5.1一样。

在Spring项目中，还有一个我见过很多次的坑：事务和内缓存一起用时，如果Service方法被@Transactional包裹，同一个事务里的两次相同查询会命中一级缓存，这是正常的。但如果MyBatis的openSession和Spring事务没有绑定在同一个线程上，一级缓存可能"看似失效"，每次查询都有新的SqlSession。这个问题普遍是mybatis-spring版本配置不当导致，升级到版本库里近期版本一般能解决。

6.2 建议的源码阅读路径

如果你想深入理解mapper接口的工作原理，最好不要只停留在使用层面。我推荐一条阅读路径，都是我实际看过之后觉得收益很大的：

第一站，看org.apache.ibatis.binding.MapperRegistry。进入源码后先找addMapper()方法，理解接口是如何注册进Configuration的。核心逻辑是判断这个接口是不是接口、有没有被重复注册，然后创建MapperProxyFactory放入knownMappers。

第二站，看MapperProxyFactory和MapperProxy。这里能看到JDK动态代理的具体应用：Proxy.newProxyInstance()创建代理类，invoke方法里如何从MapperMethod的缓存中取方法。

第三站，看MapperMethod。重点关注execute()方法里的switch分支，看它是如何根据SQL类型选择SqlSession对应方法的。这个类还包含ParamNameResolver对参数的解析，理解了它，就知道@Param是怎么生效的。

第四站，看XmlConfigBuilder和XMLMapperBuilder。这里就是热搜词里提到的xmlconfigbuilser工作流程的核心。MyBatis启动时，SqlSessionFactoryBuilder调用XMLConfigBuilder解析mybatis-config.xml，碰到<mappers>标签时，再创建XMLMapperBuilder挨个解析mapper XML文件，把每个<select>/<insert>解析成MappedStatement注册进Configuration。理解了这一层，你就知道为什么XML加载失败会直接影响到接口绑定。

五站走完，你对MyBatis的理解会完全不一样，至少面试中被问到"mapper接口的实现原理""MyBatis初始化流程"这类问题，你能讲出真正的代码细节，而不是停留在概念层面。

6.3 接口设计的一些额外建议

最后分享几点我在实际项目中的习惯。首先，mapper接口尽量保持"瘦"，一个接口对应当前业务实体的基础CRUD就够了，不要什么SQL都往里塞。我见过有人把统计、报表、跨表查询全部堆在一个Mapper里，最后接口上百个方法，XML几千行，维护成本直接失控。拆分原则很简单：一个实体一个基础Mapper，复杂查询按业务模块单独建Mapper接口。

其次，接口方法命名要统一动词。查询用find开头，新增用insert，更新用update，删除用delete，统计用count。团队统一这个规范后，看代码时不用进XML就能猜个大概。

最后，XML里SQL的写法也有讲究。多条件查询建议在SQL里写好<where>标签，配合<if>动态判断。排序字段如果要动态传入，一定用${}并做白名单校验。分组统计、联表查询这些复杂场景，优先保证SQL的可读性，宁愿多写几行也不要写成一行长串。SQL语句格式清晰，不仅是给自己看，也是给后来接手的人看，这比任何文档都重要。

这个系列走到这里，mapper接口创建已经全部完成。但MyBatis的核心还有很多值得挖的地方，比如缓存策略、TypeHandler自定义、插件拦截器、分布查询优化，每块内容都能单独成篇。后续我会挑几个项目里真正用得多的场景继续写，有需要的读者可以先动手把这一篇的UserMapper完整跑通，再结合源码看一遍，感受会很不一样。