为什么@Mapper标在接口而@Service标在实现类？底层机制解析

如果你写 Java 后端的时间稍微长一点大概率产生过这个困惑同样都是“告诉框架这是一个需要管理的组件”为什么Service、Controller总是放在实现类上而Mapper却堂而皇之地放在接口上尤其是当项目里把接口和实现类拆成分层模块时现象就更奇怪了——Service 接口通篇没有实现类却能照常注入Mapper 接口连一个MapperImpl都不存在Spring 启动也能稳稳当当。这套看似矛盾的做法背后涉及 Spring 组件扫描和 MyBatis 动态代理两条完全不同的机制。如果把结论压缩成一句话Mapper标注的是 MyBatis 要为它生成代理对象的“接口”Service/Controller标注的是 Spring 容器要实例化的“具体类”。一个是代理的起点一个是实例化的对象两个框架对注解目标的期待天然就不一样。但这句结论背下来没有用换个场景还是会踩坑。我打算把两边机制拆开讲清楚顺便把项目里常见的几个“接口注解混乱”引发的启动失败和注入问题也一并排掉。1. 先回答最表面的那一层谁在被注册成 Bean要把这个问题理清首先得接受一个事实Service和Mapper虽然长得像“同类注解”但它们服务的框架和生命周期的阶段完全不同。Service属于 Spring 构造型注解它和Component、Controller、Repository是一家人。Spring 在启动时通过ComponentScan扫描类路径找到带这类注解的具体类然后由AutowireCapableBeanFactory反射构造一个实例。这里的关键点是Spring 需要的是一个“能 new 出来的类”。如果一个类没有明确的构造方法、抽象方法占位、或者它干脆是一个接口Spring 的常规路径是无能为力的。Mapper则属于 MyBatis 的注解作用是告诉 MyBatis这个接口需要被扫描并由 MyBatis 在运行时生成一个代理实现。真正的 Bean 并不是接口本身而是MapperFactoryBean创建的 JDK 动态代理对象。也就是说接口在这个机制里不是“待实例化的目标”而是“代理生成的模板”。我把两个注解的关键差异放在一起对比一下看完这个问题基本就通了一半对比维度Service / ControllerMapper出处Spring 框架自身MyBatis 及 MyBatis-Spring 集成标注对象具体实现类接口注册方式组件扫描直接注册类反射实例化扫描接口后注册MapperFactoryBeanBean 本体是动态代理依赖注入时声明的类型实现类本身或它实现的接口接口本身标错位置的后果接口标了通常不会被注册运行期报没有可用 Bean标在实现类上没有意义不会被识别这里要说一个容易被忽略的点Mapper接口在注入时接口类型就是 Bean 的类型。你可以在 Controller 里直接Autowired private UserMapper userMapper;Spring 通过类型匹配到MapperFactoryBean生成的代理当你调用userMapper.selectById时实际上走的是代理对象内部的SqlSession。而Service实现类在注入时Spring 按类型匹配到的通常是实现类本身只不过因为你声明的是接口类型它会把实现类的实例赋上去。这两个机制的分工一旦理清题目里的“为什么”就只剩最后一层窗户纸因为框架要的东西不一样所以注解待的位置自然不一样。2. 从 Spring 的组件扫描看接口上的 Service 为什么默认失灵很多人不服气我偏要在接口上加Service实现类也加了Service项目照样能跑你怎么说能跑是因为脚手架够宽容而不是因为 Spring 真的接纳了接口上的注解。这里得把 Spring 扫描候选组件的流程翻出来看。2.1 Spring 扫描组件时的两层判断逻辑ComponentScan的扫描不是“看一眼有没有注解”就完事它由ClassPathScanningCandidateComponentProvider执行。大致流程是根据配置的包路径遍历 classpath 下所有.class文件生成MetadataReader用 include/exclude 过滤器初步筛选。默认的注解过滤器AnnotationTypeFilter会匹配带有Component及其元注解也就是Service、Controller、Repository的类对初步匹配到的候选对象调用isCandidateComponent(AnnotatedBeanDefinition)做二次校验只有通过二次校验的 BeanDefinition 才会被注册到容器。问题就出在第三步。isCandidateComponent的实际逻辑可以理解成这个类必须是“独立的”顶层类或静态内部类并且它要么是“具体的”普通类要么是“携带Lookup方法的抽象类”。关键词是“具体类”。接口永远不是一个可实例化的具体类它没有构造函数也没有任何方法体Spring 拿它去BeanUtils.instantiateClass根本无从下手。所以接口即便在第二步被注解过滤器匹配到了在第三步也会被直接筛掉压根不会注册成 BeanDefinition。2.2 接口加 Service 后到底会发生什么我实际见过最典型的场景是这样的某同学在 Service 接口上标了Service实现类UserServiceImpl上没标启动时 Spring 报No qualifying bean of type UserService。他当时百思不解觉得注解不是已经标在接口上了吗原因就在这里。接口没有被注册实现类又没有Service容器里完全没有UserService类型对应的 Bean注入自然失败。还有一种更隐蔽的场景接口和实现类都标了Service。这种情况下项目能跑因为实现类被正常扫描注册接口上的Service被静默忽略。但别高兴得太早这种写法最容易埋雷。假设后续有两个实现类比如UserServiceImpl和LdapUserServiceImpl类型匹配时容易产生歧义或者你想在接口上加 JDK 动态代理切面时切点表达式写的接口全限定名结果发现接口根本没有被注册为 BeanAOP 行为整个是错位的。2.3 唯一沾点边的例外Lookup 不是给人这么用的有朋友会问抽象类可以吗确实可以。Spring 的isCandidateComponent里留了一个特殊通道如果一个类是抽象类但只要它包含了标注Lookup的方法Spring 依然会留下它的 BeanDefinition并通过 CGLIB 生成一个子类代理注入。但这是给“抽象类 方法注入”的场景设计的接口完全不适用。接口没有构造器即便是Lookup也救不了它。所以实践结论很干脆Spring 构造型注解的默认工作目标就是具体类接口上加Service属于无效标注。与其跟框架拧着来不如老老实实把Service放在实现类。3. 从 MyBatis 的代理机制看Mapper 为什么必须放在接口上理解了Service那一侧之后再看Mapper就会明白不是 MyBatis 故意玩特立独行而是它的整套设计本来就构建在接口之上。3.1 MapperFactoryBean 是如何“凭空”制造 Bean 的MyBatis 扫描接口后注册的并不是接口本身而是一个MapperFactoryBean。这个工厂 Bean 实现了 Spring 的FactoryBeanT接口当你从容器中获取UserMapper时它会调用getObject()方法最终执行到这样一条链路SqlSessionTemplate.getMapper(UserMapper.class); // 内部进一步调用 Configuration.getMapper // 委托给 MapperRegistry由 MapperProxyFactory 创建动态代理这意味着容器里真正存在的 Bean 是一个 JDK 动态代理它的接口是UserMapper。这个代理在调用方法时会把每个接口方法包装成一个MapperMethod再交给SqlSession去执行真正的 SQL 操作。整个过程中MyBatis 从来不关心你有没有写实现类它只关心能不能从接口拿到足够信息来拼出一个代理。3.2 SQL 与接口方法的绑定关系接口在这里不只是“形状”它还是 SQL 映射的锚点。MyBatis 有两种方式把 SQL 绑到方法上XML 方式mapper命名空间必须等于接口的全限定名statement id等于方法名。比如接口是com.example.mapper.UserMapperXML 里的namespace就得写成一致注解方式在接口方法上直接标Select、Insert、Update、DeleteMyBatis 从注解里提取 SQL。这两种方式都以接口方法作为唯一入参。如果没有接口MyBatis 根本不知道 SQL 应该挂在哪里。这就是Mapper必须待在接口上的根本原因在这个框架里接口就是“实现类”的角色只是这个“实现类”不是手写的而是代理工厂在运行期生成的。3.3 Mapper 和 MapperScan 同时使用的重复注册问题聊到Mapper一定会扯出MapperScan。很多项目会在启动类上加MapperScan(com.example.mapper)又在每个 Mapper 接口上加Mapper结果两边同时扫描导致同一个接口被注册了两份 BeanDefinition。MapperScan通过MapperScannerConfigurer扫描指定包下被Mapper注解标记的接口而 MyBatis-Spring 的自动配置里也有一个AutoConfiguredMapperScannerRegistrar。如果你两个通道都开着就可能出现重复的MapperFactoryBean注册。日志里常见的提示是“Incompatible attribute”——严重时直接启动报错轻微时 Spring 靠 BeanDefinition 覆盖规则取其中一个行为不可控。我平时的做法是在一个项目内明确二选一要么用MapperScan统一扫包接口上不写Mapper要么每个接口加Mapper启动类上不写MapperScan。两者混用短期没事但一旦加了多数据源或者定制 Mapper 插件的场景坑立刻就会出现。4. 接口与实现类分离时注解该怎样分配既然题目提到了分层结构那我重点说说最常见的工程形态Service 拆成接口和实现类Mapper 只保留接口。这种结构下注解的分布其实非常规律。4.1 一个标准分层模块的注解落点我拿一个典型的用户模块举例// Mapper 层只有接口由 MyBatis 动态代理接管 Mapper public interface UserMapper { UserDO selectById(Param(id) Long id); } // Service 层接口只定义业务契约不标注任何构造型注解 public interface UserService { UserDTO getUserById(Long id); } // Service 实现Service 标在具体实现上 Service public class UserServiceImpl implements UserService { private final UserMapper userMapper; public UserServiceImpl(UserMapper userMapper) { this.userMapper userMapper; } Override public UserDTO getUserById(Long id) { UserDO user userMapper.selectById(id); // 业务组装... return userDTO; } }这套结构干净的原因在于接口负责定义契约Mapper负责告诉 MyBatis “给我生成这个接口的代理”Service负责告诉 Spring “这个具体类要被我实例化并管理”。每层干的活不一样注解待的位置也跟着分工。4.2 为什么不在 Service 接口上写 Service 更符合体系有一种反向思潮是所有接口都加Service实现类不加让框架“自动识别”实现类。这种想法源自对注解的误读。Spring 的组件扫描机制面向具体的 class 文件它没有能力也没有义务在接口和实现类之间自动建立“配对关系”。如果一个接口标注了ServiceSpring 要么忽略它要么因为它找不到实现类而报错。你不写Service在接口上反而省去了一层困惑。有人可能会问那接口上是不是永远不该出现构造型注解对常规业务代码是的。接口上出现的应该只有Mapper、FeignClient、Repository这类由专门框架自己识别和消费的注解。Spring 自己的构造型注解统一放实现类。4.3 顺带一提Spring Data JPA 的接口注解为什么能成立说到“接口加注解”很多人会拿 Spring Data JPA 的Repository接口反问为什么 JPA 可以把Repository放在接口上因为 JPA 走的也不是常规组件扫描路径而是EnableJpaRepositories触发的仓库扫描类似 MyBatis 的MapperScan。框架会给每个接口生成一个SimpleJpaRepository代理实现。你看到的“接口被注入了”只是表象真正生效的是仓库代理工厂。所以判断一个接口上的注解是否有效别只看注解本身要看背后有没有对应的代理工厂机制在消费它。没有就白标。5. 接口和实现类注解错位时常见的三个排错现场实际项目里因为这套机制踩坑的案例我见过不少挑三个最典型的说一下排查思路。5.1 接口写 Service实现类没写启动报“No qualifying bean”这是最直白的错误。启动时的异常通常长这样Parameter 0 of constructor in com.example.controller.UserController required a bean of type com.example.service.UserService that could not be found.排查链路很简单先看UserService是不是接口如果接口上写了Service几乎可以断定它被扫描链路过滤掉了再去实现类上看有没有Service或Component确认ComponentScan的包路径覆盖了实现类。这类问题的修复永远是“在实现类上标注构造型注解”而不是“把接口上的注解删掉再等等看”。5.2 Mapper 接口忘记加 Mapper也没有 MapperScan注入时报找不到 Bean这属于 MyBatis 侧的常见遗漏。假设代码是这样的Mapper public interface OrderMapper { }删掉Mapper后如果项目没有MapperScan启动时OrderMapper根本不会出现在容器里注入同样会报找不到 Bean。排查时注意一点有些项目里的MapperScan写在别的配置类上你只盯着启动类看是看不出来的。正确做法是全局搜一下MapperScan确认它的扫描范围是否覆盖了这个接口所在的包。另外如果Mapper和MapperScan同时存在且出现了重复注册相关的启动杂音先决定留哪一个把另一个清掉不要留着隐患然后等某天换多数据源时突然炸。5.3 同一接口出现多个实现类注入提示类型不唯一这个问题和Service的位置关系更大。假设UserService有两个实现类都标了Service注入UserService时会提示No qualifying bean of type UserService available: expected single matching bean but found 2这不是注解位置的问题而是类型匹配产生歧义。解法是在实现类上加Primary或者在注入处用Qualifier指定 bean 名称。但这类歧义在“接口上加 Service 再配多个实现”的组合里特别容易让人晕。因为接口上那个无效Service会让人误以为接口本身是一个 Bean导致排查时跑到错误的思路上。这也侧面说明接口上保留无效注解只会增加维护噪声。6. 我这些年总结的三条判断经验最后分享几条压箱底的判断法则是我在实际项目中反复被教育出来的。第一看注解被谁消费。Component家族注解的作用对象是 Spring 容器容器需要实例化一个具体类所以它应该待在能被 new 出来的类上。Mapper的作用对象是 MyBatis 的接口代理工厂工厂需要接口来生成代理所以它待在接口上。某一个注解有效无效取决于背后有没有框架在消费它而不是它本身叫什么叫什么。第二分层项目的注解分布可以当模板用。Mapper 接口只写MapperService 接口不写任何 Spring 构造型注解ServiceImpl 写ServiceController 写Controller。这套分布配合项目里的分层结构半年后你再回来看代码一眼就能判断出每一层的职责边界。第三遇到接口自动注入却没有任何实现类的现象第一个念头应该是“这里存在代理工厂”而不是“反射黑魔法”。MyBatis 的Mapper、Spring Data JPA 的 Repository、OpenFeign 的 FeignClient都是这个模式。只要你摸清了代理工厂的注册链路这类问题在脑子里立刻就有了排查方向。写到这里基本把两个注解的底层逻辑聊透了。这个题目看起来像个入门问题但能把接口代理和类扫描两条链路分清楚的人在很多复杂场景里反而不容易迷路。最后再提醒一句启动日志里看到No qualifying bean先别急着加Service先想清楚你要注入的东西是应该由容器实例化的类还是应该由代理工厂生成的接口。这个区别就是那层窗户纸。