很多初学者第一次接触MyBatis时最困惑的一件事就是明明写了一个mapper接口里面全是方法声明没有一行实现代码可项目跑起来之后这些方法却能被正常调用SQL也执行得明明白白。我当年第一次看到这种写法时也愣了半天后来翻源码才搞清楚这背后全是动态代理在干活。这篇文章就把mapper接口的创建这件事从头到尾讲透包括基础写法、参数传递、结果映射以及和XML映射文件之间那层说不清道不明的绑定关系。不管是刚入门的新手还是想系统梳理一遍的老手这篇都值得你花几分钟看看。1. 为什么mapper非得是个接口先看懂MyBatis的动态代理玩法mapper接口不是MyBatis拍脑袋想出来的设计而是整套框架约定优于配置思路的集中体现。很多人在创建mapper接口时只照着模板抄却不知道它为什么长这样遇到问题就懵了。1.1 接口加XML的二元结构从哪里来MyBatis最早是从iBATIS演变过来的。iBATIS时代我们写SQL是写在一个独立的SQL Map配置文件里然后通过一个DAO实现类去调用SqlSession的方法比如sqlSession.selectList(com.xxx.UserMapper.selectAll)。这种写法的缺点是SQL的id是字符串写错了要等运行时报错才知道而且每写一个查询都要手动跟SqlSession的方法打交道代码重复度极高。MyBatis的mapper接口机制本质上是把SQL语句的定位从字符串硬编码变成了接口方法调用。你定义一个接口接口里的方法名对应XML里那条SQL语句的id方法的参数对应SQL语句的参数返回值对应SQL语句的结果映射。框架在启动时把这些对应关系全部解析好注册到Configuration对象里运行时就靠动态代理把接口方法调用翻译成一次SQL执行。我的理解是接口在这里扮演的是一个契约的角色。SQL写在XML里参数和返回值由接口方法声明来约束两者通过namespace和id完成绑定。这样既享受了XML里写SQL的灵活又获得了接口调用的类型安全算是当时Java生态里很巧妙的一种折中。1.2 没有实现类调用时到底发生了什么你说mapper接口没有实现类为什么userMapper.selectById(1)就能执行答案在MapperProxy和MapperMethod这两个类上。项目启动时MyBatis会扫描所有mapper接口把每个接口都注册到MapperRegistry里。注册时做的事情很关键Configuration.addMapper()方法会创建一个MapperProxyFactory这个工厂专门负责为对应接口生成代理对象。当你从SqlSession.getMapper(UserMapper.class)拿到对象时实际拿到的就是MapperProxy动态代理生成的实例。MapperProxy实现了InvocationHandler接口。也就是说任何对UserMapper接口方法的调用最终都会进到MapperProxy.invoke()方法里。这个方法会先把当前被调用的方法封装成一个MapperMethod对象MapperMethod内部有两个核心组件一个是SqlCommand负责从Configuration里找出这条方法对应的SQL语句也就是从XML里解析出来的MappedStatement另一个是MethodSignature负责把方法的参数列表转换成SQL执行时需要的参数对象。这两个信息齐了剩下的就是交给SqlSession去真正执行SQL再把结果封装成方法声明的返回类型返回给调用方。所以你看mapper接口不是没有实现而是实现被MyBatis在运行时替你动态生成了。你定义的是行为契约框架帮你做了落地执行。创建mapper接口时心里装着这条链路后面很多诡异问题都能自己推出来原因。2. 零基础落地创建mapper接口的标准姿势与目录规范前面说了那么多原理现在上手实操。一个标准的mapper接口创建流程其实是固定的跟着步骤走基本不会出大问题。2.1 包结构、命名与项目位置怎么定先明确mapper接口放在哪。常规的Java项目结构里mapper接口一般放在某个包下比如com.example.project.mapper。如果你用的是Spring Boot更常见的做法是放在com.example.project.dao或者com.example.project.mapper然后在启动类上加上MapperScan(com.example.project.mapper)注解让Spring在启动时扫描这些接口并注册为Bean。举个具体的例子假设项目根包是com.example.shop那我可以建这样的结构com.example.shop ├── controller ├── service ├── mapper │ ├── UserMapper.java │ └── OrderMapper.java └── entity ├── User.java └── Order.java命名上我习惯用实体名Mapper比如User实体对应UserMapper接口Order实体对应OrderMapper接口。这样在项目里找文件时非常直观团队协作时别人一眼就能明白哪个接口管哪张表。有一点容易踩坑在Spring Boot项目里如果mapper接口和XML映射文件不在同一个模块或包路径下一定要检查target/classes目录里是否同时打包进去了。很多次线上环境报Invalid bound statement排查到最后发现是打包配置把XML文件漏了。2.2 接口里的方法签名怎么定定义一个mapper接口代码很简单package com.example.shop.mapper; import com.example.shop.entity.User; import org.apache.ibatis.annotations.Param; import java.util.List; public interface UserMapper { User selectById(Param(id) Long id); ListUser selectAll(); int insert(User user); int updateById(User user); int deleteById(Param(id) Long id); }方法签名是定契约的关键。每个方法背后都对应XML里的一条statement方法名、参数、返回值这三个要素必须和XML里的配置一一对应否则启动或调用时会报错。先说方法名。方法名就是SQL语句的id。前面提到过MyBatis把namespace . 方法名作为MappedStatement的唯一标识所以方法名叫selectByIdXML里那条SQL的id就必须是selectById连大小写都要完全一致。这也是初学者最常踩的坑明明XML里写的是selectByID接口方法写的selectById运行时直接抛BindingException。参数这块多个参数时强烈建议加Param注解。后面第4章会详细展开。返回值方面单条数据用实体类比如User多条数据用ListUser。如果只是统计数量可以直接用int或Long。2.3 三步把接口和XML映射文件绑起来接口写完了不算完还要有对应的XML映射文件才能执行SQL。绑定关系靠三样东西namespace、statement id、resultType/resultMap。拿UserMapper.java对应的UserMapper.xml做例子?xml version1.0 encodingUTF-8? !DOCTYPE mapper PUBLIC -//mybatis.org//DTD Mapper 3.0//EN http://mybatis.org/dtd/mybatis-3-mapper.dtd mapper namespacecom.example.shop.mapper.UserMapper select idselectById resultTypecom.example.shop.entity.User SELECT * FROM user WHERE id #{id} /select select idselectAll resultTypecom.example.shop.entity.User SELECT * FROM user /select insert idinsert parameterTypecom.example.shop.entity.User INSERT INTO user (name, age) VALUES (#{name}, #{age}) /insert /mapper第一步namespace必须写接口的全限定名也就是包名加接口名com.example.shop.mapper.UserMapper。这是框架用来找接口的关键。第二步XML里的select、insert、update、delete标签的id属性必须和接口方法名完全一致。MyBatis在解析XML时会把namespace . id作为MappedStatement的key注册到Configuration里调用接口方法时又用同样的组合去找对不上就报错。第三步resultType或者resultMap要正确处理。单表查询且字段名和实体属性名能对得上时用resultType指定实体类全限定名就行。如果有字段名对不上的情况或者多表联查就得配置resultMap。这三步都做对了接口和XML就绑定成功了。在Spring Boot项目里如果XML文件放在src/main/resources/mapper/目录下还需要在application.yml里加上这样的配置mybatis: mapper-locations: classpath:mapper/*.xml否则MyBatis根本找不到XML文件也会报绑定异常。3. mapper接口与XML的绑定细节namespace、id与statement的耦合逻辑前面讲了怎么绑定现在深入一点说说为什么这样绑定。好多老手写代码很溜但是被问到namespace为什么要写全限定名时答不上来。这块卡壳了排查问题时很容易走弯路。3.1 namespace为什么必须写成接口全限定名MyBatis的MapperRegistry在注册mapper接口时是拿着接口的Class对象去Configuration里找MappedStatement的。它的做法是用mapperInterface.getName()拿到接口的全限定名加上方法名拼接成statement的完整id然后去Configuration的mappedStatements集合里查。如果你是拿配置类方式注册的mapper框架只认这个全限定名。再说一个容易忽略的点如果一个namespace下的statement id冲突了MyBatis启动时就直接抛异常。比如两个不同的接口里都有selectAll方法但只要namespace不同com.example.shop.mapper.UserMapper.selectAll和com.example.shop.mapper.OrderMapper.selectAll是两个完全不同的key可以共存。反过来如果同一个namespace下出现两个相同的id启动直接报错。3.2 mapper接口里的方法能不能重载很多从Spring Data JPA转过来的同学会习惯性地在mapper接口里写重载方法比如一个selectByCondition(String name)和一个selectByCondition(String name, Integer age)。这在MyBatis里是大忌。原因其实很简单重载方法的签名不同但方法名相同。MyBatis绑定SQL时只认方法名方法名对应唯一一个statement id也就是说接口里如果存在两个同名方法它们找的是同一个MappedStatement。调用时到底执行哪个完全取决于MapperMethod解析出来的参数和SQL占位符是否匹配这种不确定性就是埋在代码里的炸弹。我在实际项目里遇到过同事这么写selectByCondition(张三)有时候正常有时候参数对不上直接报错排查了半天才发现是重载导致的。正确做法方法名必须唯一。要表达不同的查询语义就起不同的方法名比如selectByName和selectByNameAndAge。这虽然啰嗦但胜在清晰可控。3.3 mapper注册的几种方式与扫描顺序bound statement能不能找到除了接口和XML绑定要正确还取决于mapper有没有被成功注册。注册方式主要有三种。第一种是用Mapper注解标在接口上Spring Boot启动时会自动扫描所有带Mapper注解的接口把它注册成mapper。第二种是在启动类上写MapperScan(com.example.shop.mapper)直接指定扫描包路径这种方式最常用一次扫描多个接口。第三种是纯MyBatis的XML配置方式在mybatis-config.xml里用mappers标签逐个注册mappers mapper resourcemapper/UserMapper.xml/ mapper classcom.example.shop.mapper.UserMapper/ /mappers第三种方式里有个细节如果一个mapper接口既有XML映射文件又通过mapper class...注册MyBatis会同时尝试加载XML和注解里的SQL。如果XML的namespace和接口一致加载XML后还会去解析接口上有没有Select、Insert这类注解SQL两者的statement id可能会冲突后加载的会把先加载的覆盖掉。这个顺序问题在新老版本里的表现还不完全一样所以我的建议是尽量只用一种方式写SQL要么全XML要么全注解别混着用。4. 参数传递把方法入参交给SQL的三种姿势与常见翻车场景mapper接口方法里最灵活也最容易出问题的就是参数。我见过不少因为参数问题导致SQL条件不生效的线上故障这里把常见的传参方式梳理清楚。4.1 单参数、多参数与Param注解的底层逻辑先看单参数的情况。如果接口方法是这样的User selectById(Long id);那XML里直接用#{id}引用就行MyBatis会把单个参数直接传给SQL这里#{id}里的名字其实不重要你写#{value}、#{anything}都能生效。一旦参数超过一个情况就变了User selectByNameAndAge(String name, Integer age);如果XML里写#{name}和#{age}运行时会抛BindingException: Parameter name not found。原因是MyBatis处理多参数时会把参数封装成一个Mapkey默认是param1、param2或者arg0、arg1不同版本略有差异。你直接写#{name}MyBatis在Map里找不到这个key自然就报错。解决办法就是加Param注解User selectByNameAndAge(Param(name) String name, Param(age) Integer age);加了Param之后MyBatis在封装参数Map时会把注解的值作为key#{name}、#{age}就能正确取到值了。这是多参数时最稳妥的写法。4.2 POJO和Map传参的取舍如果参数超过三四个比如一个查询条件有用户名、年龄区间、创建时间区间、状态、分页信息再一个个加Param就不太优雅了。项目里更常见的做法是封装一个查询条件的POJO类。public class UserQuery { private String name; private Integer ageStart; private Integer ageEnd; private Integer status; // getter/setter 省略 }接口方法写成ListUser selectByCondition(UserQuery query);XML里直接用#{name}、#{ageStart}这些属性名引用就行。MyBatis会把POJO的属性自动作为参数Map的key不再需要Param。很多人也喜欢用Map传参ListUser selectByCondition(MapString, Object params);XML里同样是#{xxx}引用。Map传参虽然灵活但有一个明显的缺点类型安全完全丧失。你写params.put(ageStart, 18)如果XML里写的是#{ageStart}两边对不上MyBatis不会在编译期提示任何错误只有运行期拿到null或者直接报类型转换异常时才意识到问题。我个人建议是宁可多写几个POJO类也不要用Map做万能传参对象维护成本真的差很多。4.3 参数为null时SQL条件不生效的排查方向热词里有mybatis条件不生效这是实战里反复出现的问题。最典型的场景用MyBatis做动态SQLXML里写了if test判断但条件就是加不上。比如select idselectByCondition parameterTypecom.example.shop.entity.UserQuery resultTypecom.example.shop.entity.User SELECT * FROM user where if testname ! null and name ! AND name #{name} /if if testageStart ! null AND age gt; #{ageStart} /if /where /select看起来没问题但如果调用时传进来的name是空字符串而非nullname ! 的判断就会生效并加上条件。反过来如果你传的name值是null但if test里写的是name ! null这个条件也会跳过看起来就像条件不生效。还有一个高发场景传参封装成Map时key没放进去或者POJO某个属性没set值MyBatis拿到的是null同样会跳过条件。排查顺序我建议是这样的先确认接口方法有没有加Param多参数不加注解时条件引用肯定会出问题再确认XML里if test的属性和参数对象能对上最后用日志打印出最终执行的SQL一眼就能看出条件到底有没有拼接进去。MyBatis打印SQL可以通过配置文件开启mybatis.configuration.log-impl: org.apache.ibatis.logging.stdout.StdOutImpl这一步能省掉大量猜测时间。5. 返回值设计resultType与resultMap的选择以及字段映射那些事mapper接口方法的返回值类型决定了MyBatis怎么处理查询结果。这一层设计得好业务代码写起来很舒服设计得不好两天两头被数据库字段和Java属性对不上折腾。5.1 单条、多条与DTO返回的注意点返回单条记录时接口方法可以直接返回实体类User selectById(Long id);如果查出的结果有多条但方法返回类型是单个实体MyBatis会从结果集里取第一条返回多的记录被直接忽略而且不会报错MyBatis 3.x早期版本是这样的行为。这个坑非常隐蔽建议查询条件可能命中多条数据时要么用ListUser要么SQL里加limit 1。返回多条记录时用ListUserListUser selectAll();XML只需要配置好resultTypeMyBatis会自动为每条记录创建User对象并填充属性最后包装成List。集合泛型里的类型就是resultType指定的类。还有一种需求是返回部分字段而不是整个实体。比如列表页只需要展示id、name、avatar三个字段。我见过很多初学的人返回Entity然后在Service层再转成VO这种做法不仅浪费字段多了还容易出错。更合理的做法是定义DTO类直接在SQL里select需要的列resultType指向DTOpublic class UserListVO { private Long id; private String name; private String avatar; // getter/setter }接口方法返回ListUserListVOXML里resultType写com.example.shop.vo.UserListVO。这样查询结果直接就是页面需要的数据结构Service层不用再做无意义的转换。5.2 什么时候必须上resultMapresultType的使用前提是SQL查询结果的列名能直接映射到实体类的属性名。如果数据库列名用了下划线风格比如user_name而Java属性是驼峰风格userName直接resultType是映射不上的返回的userName会一直是null。解决这个问题的第一种方案是全局配置下划线转驼峰在application.yml里加一行mybatis: configuration: map-underscore-to-camel-case: true这招能解决大部分常规字段映射问题。但如果遇到列名和属性名彻底对不上的情况或者多表联查返回的字段是拼凑出来的比如SELECT u.name AS userName, o.order_no FROM ...这时就得用resultMap显式定义了resultMap iduserOrderMap typecom.example.shop.vo.UserOrderVO id propertyid columnid/ result propertyuserName columnuser_name/ result propertyorderNo columnorder_no/ /resultMapXML里再把SQL的resultMap设成这个id查询结果的每一列就按你的定义去填充。resultMap还有一个强大之处是支持关联映射比如一对一用association、一对多用collection这个在复杂报表查询里非常实用。不过我个人的建议是resultMap的关联映射尽量少用复杂的查询直接在SQL里join然后映射到DTO反而更好维护。嵌套的resultMap在数据量大的时候性能表现也一般还容易产生N1问题。5.3 主键回填useGeneratedKeys的常见坑执行insert操作后拿到自增主键是很多业务的基本需求。mapper接口方法这样定义int insert(User user);如果直接执行你会发现insert完之后user.getId()还是null。这是因为MyBatis默认不会把数据库生成的主键写回传入的对象。需要在insert标签里加两个属性insert idinsert parameterTypecom.example.shop.entity.User useGeneratedKeystrue keyPropertyid INSERT INTO user (name, age) VALUES (#{name}, #{age}) /insertuseGeneratedKeystrue表示要数据库生成的主键keyPropertyid表示把生成的主键值赋给传入User对象的id属性。这也解释了为什么insert方法的入参用了POJO而不是Param拆开传——主键回填需要操作原始对象你传一个拆散的参数主键回填到哪去这是个非常常见的错误认知我甚至见过有人insert完再select一遍去拿主键甚至是先select max(id)再insert的写法看得人心惊肉跳。有个细节如果表名是复合主键keyProperty可以写逗号分隔的多个属性名比如keyPropertyid,tenantId。这个用到的场景少但真遇到了能省很多事。6. 从源码看mapper接口的无实现真相MapperProxy与注册时机很多人面试时被问到MyBatis的mapper接口原理答不上来。刚才在开头讲过一遍链路这里再用源码视角过一遍把几个关键的类串起来。6.1 Configuration里的MapperRegistry做了什么MyBatis全局配置的核心就是Configuration这个类它内部有一个MapperRegistry类型的成员变量。MapperRegistry里面有这样一个Mapprivate final MapClass?, MapperProxyFactory? knownMappers new HashMap();key是mapper接口的Class对象value是MapperProxyFactory——可以理解成专门为这个接口生产代理对象的工厂。框架在启动时无论你用的是MapperScan扫描注解还是XML里mapper class...最后都会走到MapperRegistry.addMapper(ClassT type)方法。这个方法会做一件事把接口Class和MapperProxyFactory的对应关系塞进knownMappers。注意到这里传入的必须是一个接口如果你传一个普通类进去MyBatis会直接抛异常——这也是开头那句话的来历mapper必须是个接口不是框架矫情是设计时就这么定的。6.2 接口方法调用如何一步步变成SQL执行再从一次完整的调用来看。第一步业务代码执行userMapper.selectById(1)。这个userMapper对象看起来是UserMapper类型实际拿到的MapperProxy代理对象。第二步进入MapperProxy.invoke()方法。这个方法第一步会判断方法是不是Object里的方法比如toString、hashCode、equals如果是就直接调用不再走SQL逻辑。第三步针对真正的业务方法它用MapperMethod做了一次缓存。MapperMethod内部有SqlCommand和MethodSignature。SqlCommand在构造时从Configuration里查了个MappedStatement查找用的key就是mapperInterface.getName() . methodName。这一步又一次验证了前面说的接口全限定名和namespace必须一致方法名和statement id必须一致。第四步MethodSignature把方法入参转换成param对象。这一步会解析有没有Param注解、参数个数、以及是否传入了RowBounds、ResultHandler这类MyBatis内置参数类型。转换完成后SqlSession把MappedStatement和参数对象交给执行器真正的JDBC操作就在这里发生了然后就是数据库驱动干活了。面试时把这一段讲明白基本没有面试官在这块还能问倒你。6.3 与TypeHandler、二级缓存的关联位置创建mapper接口时你可能没意识到方法返回值的类型和入参的类型都会牵扯到TypeHandler和缓存。一个接口方法执行时MyBatis会根据MappedStatement里注册的TypeHandler把Java对象转成JDBC参数查询结果集时又用TypeHandler把JDBC的ResultSet列转成Java对象的属性。你自定义了枚举类型字段就需要在MyBatis配置里注册对应的TypeHandler否则映射时会直接报There is no getter for property named ...或者类型转换失败。二级缓存也是在MappedStatement级别配置的。XML里select标签加上useCachetrue同一个namespace下的查询结果会被缓存起来。这里有个经典坑如果两个mapper接口的namespace不同但操作的是同一张表其中一个做了update操作另一个namespace下的查询缓存不会失效就会出现数据脏读。所以设计mapper接口的粒度时如果表之间有较强的关联操作把它们的mapper放在同一个namespace下也就是同一张表的读写尽量放在同一个mapper接口里缓存问题会少很多。7. 这一路踩过的坑与排错手法绑定异常到数据错乱的排查笔记最后分享一些我在实际项目里遇到的典型问题给准备动手创建mapper接口的同学一个提前预警。这些问题几乎都在生产环境里真实出现过每一个排查起来都让人头秃。7.1 绑定异常排查链路从Invalid bound statement说起Invalid bound statement (not found)恐怕是MyBatis最著名的报错没有之一。它的大意是能找到mapper接口但找不到接口方法对应的SQL语句。排查顺序很重要按这个链路走基本能在五分钟内定位问题。第一步确认XML文件有没有被编译到输出目录。IDEA里Project Structure的Sources标签页如果没把resources目录标记为ResourcesXML文件就不会被拷贝到target/classes下。检查方式很简单直接展开target/classes目录看有没有对应的XML文件。没有的话就是资源目录没配好或者Maven的build配置里漏了resource节点。第二步确认XML里namespace和mapper接口全限定名一致。这一步可以用文本对比直接看绝大多数绑定异常都是namespace漏写或者写错。第三步确认方法名和statement id一致。包括大小写和拼写。IDE里用Ctrl加点击如果跳转不到基本上就是这个问题。第四步验证mapper有没有被正确扫描。如果Spring Boot项目里没有配MapperScan也没有在接口上加Mapper注解即使XML和接口都正确mapper也不会注册进容器调用时同样报绑定异常。同时要确认mybatis.mapper-locations配置指向的路径包含你的XML文件。7.2 参数和映射类报错Parameter not found与ResultMap类型冲突Parameter xxx not found. Available parameters are [arg1, arg0, param1, param2]这个报错是上一章说的多参数问题。看到Available parameters里全是param1这种名字就说明你漏了Param注解。加上注解key就会变成你指定的名字。还有一种很让人困惑的报错写接口方法时ListUser正常把返回类型改成User后数据量一多就出现TooManyResultsException。这种问题不算绑定错误更多是返回类型设计不合理SQL会命中多条而你没加限制。报错信息里其实已经给出了示例代码照着改成List或者加limit 1就行。resultMap相关问题通常表现在接口方法返回值不报错但字段为null。这时候先排查map-underscore-to-camel-case是否开启、resultMap里的column和查询出来的列名是否完全一致、嵌套属性路径是否正确。我一直强调先用日志打印最终SQL再用SQL客户端把查询结果粘贴出来对比这一步能直接排除SQL层面的困惑避免在Java和XML之间来回猜。7.3 动态SQL拼接错误查询结果对不上、数据被误更新最后说一个新手特别容易忽视的隐患XML里用了if动态SQL条件里的判断符号如果写错会造成数据错乱甚至误更新。最常见的错误是把if teststatus ! null写成if teststatus ! null and status ! 当status值是0时0 ! 在OGNL里可能会因为类型转换出现意外结果条件被略过。更新类SQL更危险set标签里的条件判断如果漏了可能把完好字段覆盖成null。这类问题的排查方法还是那句老话开启MyBatis的SQL日志把执行前后的日志对比着看。条件拼接出错时日志里SQL明显少了一段WHERE条件一眼就能看出来。多参数场景下用Param显式命名配合where和set标签能在最大程度上避免动态SQL的边界问题。说实话mapper接口的创建是整个MyBatis框架里最规矩的环节——只要理解了它背后的动态代理机制再把命名惯例如实遵守后面跑起来其实是相当省心的。我个人的建议是最初学习阶段可以在接口方法上把所有Param都写全XML里的namespace、id逐一核对用日志把SQL打印出来过几轮之后自然就形成肌肉记忆了。框架的坑都藏在看不见的约定里而约定一旦吃透它就是效率工具不是拦路虎。