类路径扫描和托管组件

本章中的大多数示例都使用 XML 来指定配置元数据,这些元数据在 Spring 容器中生成每个 BeanDefinition。上一节(基于注解的容器配置)演示了如何通过源代码级注解提供大部分配置元数据。然而,即使在这些示例中,“基础”bean 定义也明确定义在 XML 文件中,而注解仅驱动依赖注入。本节描述了一种通过扫描类路径隐式检测候选组件的选项。候选组件是与过滤条件匹配并在容器中注册了相应 bean 定义的类。这消除了使用 XML 执行 bean 注册的需要。相反,您可以使用注解(例如,@Component)、AspectJ 类型表达式或您自己的自定义过滤条件来选择哪些类在容器中注册了 bean 定义。

您可以使用 Java 而不是 XML 文件来定义 bean。请查看 @Configuration@Bean@Import@DependsOn 注解,以获取如何使用这些功能的示例。

@Component 和更多构造型注解

@Repository 注解是任何扮演存储库(也称为数据访问对象或 DAO)角色或_构造型_的类的标记。此标记的用途之一是异常的自动翻译,如 异常翻译 中所述。

Spring 提供了更多的构造型注解:@Component@Service@Controller@Component 是任何 Spring 管理组件的通用构造型。@Repository@Service@Controller@Component 的特化,用于更具体的用例(分别在持久层、服务层和表示层)。因此,您可以用 @Component 注解您的组件类,但是,通过用 @Repository@Service@Controller 注解它们,您的类更适合由工具处理或与切面关联。例如,这些构造型注解是切入点的理想目标。@Repository@Service@Controller 也可能在 Spring Framework 的未来版本中携带额外的语义。因此,如果您在为服务层选择使用 @Component@Service@Service 显然是更好的选择。同样,如前所述,@Repository 已经作为持久层中自动异常翻译的标记得到支持。

使用元注解和组合注解

Spring 提供的许多注解可以在您自己的代码中用作元注解。元注解是可以应用于另一个注解的注解。例如,前面提到的 @Service 注解被 @Component 元注解,如下例所示:

Java
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Component [id="CO1-1"][id="CO1-1"][id="CO1-1"](1)
public @interface Service {

	// ...
}
<1>  `@Component` 使得 `@Service` 以与 `@Component` 相同的方式处理。
Kotlin
@Target(AnnotationTarget.TYPE)
@Retention(AnnotationRetention.RUNTIME)
@MustBeDocumented
@Component [id="CO2-1"][id="CO1-2"][id="CO2-1"](1)
annotation class Service {

	// ...
}
<1>  `@Component` 使得 `@Service` 以与 `@Component` 相同的方式处理。

您还可以组合元注解来创建“组合注解”。例如,Spring MVC 中的 @RestController 注解由 @Controller@ResponseBody 组成。

此外,组合注解可以选择性地重新声明元注解的属性以允许自定义。当您只想公开元注解属性的一个子集时,这尤其有用。例如,Spring 的 @SessionScope 注解将作用域名称硬编码为 session,但仍然允许自定义 proxyMode。以下清单显示了 SessionScope 注解的定义:

  • Java

  • Kotlin

@Target({ElementType.TYPE, ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Scope(WebApplicationContext.SCOPE_SESSION)
public @interface SessionScope {

	/**
	 * Alias for {@link Scope#proxyMode}.
	 * <p>Defaults to {@link ScopedProxyMode#TARGET_CLASS}.
	 */
	@AliasFor(annotation = Scope.class)
	ScopedProxyMode proxyMode() default ScopedProxyMode.TARGET_CLASS;

}
@Target(AnnotationTarget.TYPE, AnnotationTarget.FUNCTION)
@Retention(AnnotationRetention.RUNTIME)
@MustBeDocumented
@Scope(WebApplicationContext.SCOPE_SESSION)
annotation class SessionScope(
		@get:AliasFor(annotation = Scope::class)
		val proxyMode: ScopedProxyMode = ScopedProxyMode.TARGET_CLASS
)

然后,您可以像以下示例一样使用 @SessionScope 而无需声明 proxyMode

  • Java

  • Kotlin

@Service
@SessionScope
public class SessionScopedService {
	// ...
}
@Service
@SessionScope
class SessionScopedService {
	// ...
}

您还可以覆盖 proxyMode 的值,如下例所示:

  • Java

  • Kotlin

@Service
@SessionScope(proxyMode = ScopedProxyMode.INTERFACES)
public class SessionScopedUserService implements UserService {
	// ...
}
@Service
@SessionScope(proxyMode = ScopedProxyMode.INTERFACES)
class SessionScopedUserService : UserService {
	// ...
}

有关更多详细信息,请参阅 Spring 注解编程模型 wiki 页面。

自动检测类并注册 Bean 定义

Spring 可以自动检测构造型类并向 ApplicationContext 注册相应的 BeanDefinition 实例。例如,以下两个类符合此类自动检测的条件:

  • Java

  • Kotlin

@Service
public class SimpleMovieLister {

	private MovieFinder movieFinder;

	public SimpleMovieLister(MovieFinder movieFinder) {
		this.movieFinder = movieFinder;
	}
}
@Service
class SimpleMovieLister(private val movieFinder: MovieFinder)
  • Java

  • Kotlin

@Repository
public class JpaMovieFinder implements MovieFinder {
	// implementation elided for clarity
}
@Repository
class JpaMovieFinder : MovieFinder {
	// implementation elided for clarity
}

要自动检测这些类并注册相应的 bean,您需要将 @ComponentScan 添加到您的 @Configuration 类中,其中 basePackages 属性是这两个类的公共父包。(或者,您可以指定一个逗号、分号或空格分隔的列表,其中包含每个类的父包。)

  • Java

  • Kotlin

@Configuration
@ComponentScan(basePackages = "org.example")
public class AppConfig  {
	// ...
}
@Configuration
@ComponentScan(basePackages = ["org.example"])
class AppConfig  {
	// ...
}

为简洁起见,前面的示例可以使用注解的 value 属性(即 @ComponentScan("org.example"))。

以下替代方案使用 XML:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:context="http://www.springframework.org/schema/context"
	xsi:schemaLocation="http://www.springframework.org/schema/beans
		https://www.springframework.org/schema/beans/spring-beans.xsd
		http://www.springframework.org/schema/context
		https://www.springframework.org/schema/context/spring-context.xsd">

	<context:component-scan base-package="org.example"/>

</beans>

使用 <context:component-scan> 隐式启用 <context:annotation-config> 的功能。在使用 <context:component-scan> 时,通常无需包含 <context:annotation-config> 元素。

类路径包的扫描需要类路径中存在相应的目录条目。当您使用 Ant 构建 JAR 时,请确保您没有激活 JAR 任务的仅文件开关。此外,在某些环境中,类路径目录可能不会根据安全策略公开——例如,JDK 1.7.0_45 及更高版本上的独立应用程序(这需要在清单中设置“Trusted-Library”——请参阅 https://stackoverflow.com/questions/19394570/java-jre-7u45-breaks-classloader-getresources)。在模块路径(Java 模块系统)上,Spring 的类路径扫描通常按预期工作。但是,请确保您的组件类在 module-info 描述符中导出。如果您希望 Spring 调用您的类的非公共成员,请确保它们是“开放的”(即,它们在 module-info 描述符中使用 opens 声明而不是 exports 声明)。

此外,当您使用组件扫描元素时,AutowiredAnnotationBeanPostProcessorCommonAnnotationBeanPostProcessor 都被隐式包含。这意味着这两个组件被自动检测并连接在一起——所有这些都无需在 XML 中提供任何 bean 配置元数据。

您可以通过将 annotation-config 属性设置为 false 来禁用 AutowiredAnnotationBeanPostProcessorCommonAnnotationBeanPostProcessor 的注册。

使用过滤器自定义扫描

默认情况下,只有使用 @Component@Repository@Service@Controller@Configuration 或本身使用 @Component 注解的自定义注解进行注解的类才会被检测为候选组件。但是,您可以通过应用自定义过滤器来修改和扩展此行为。将它们添加为 @ComponentScan 注解的 includeFiltersexcludeFilters 属性(或作为 XML 配置中 <context:component-scan> 元素的 <context:include-filter /><context:exclude-filter /> 子元素)。每个过滤器元素都需要 typeexpression 属性。下表描述了过滤选项:

Table 1. 过滤器类型
过滤器类型 示例表达式 描述

annotation (默认)

org.example.SomeAnnotation

在目标组件的类型级别上_存在_或_元存在_的注解。

assignable

org.example.SomeClass

目标组件可赋值(扩展或实现)的类(或接口)。

aspectj

org.example..*Service+

目标组件匹配的 AspectJ 类型表达式。

regex

org\.example\.Default.*

目标组件类名匹配的正则表达式。

custom

org.example.MyTypeFilter

org.springframework.core.type.TypeFilter 接口的自定义实现。

以下示例显示了忽略所有 @Repository 注解并使用“stub”存储库的配置:

  • Java

  • Kotlin

@Configuration
@ComponentScan(basePackages = "org.example",
		includeFilters = @Filter(type = FilterType.REGEX, pattern = ".*Stub.*Repository"),
		excludeFilters = @Filter(Repository.class))
public class AppConfig {
	// ...
}
@Configuration
@ComponentScan(basePackages = ["org.example"],
		includeFilters = [Filter(type = FilterType.REGEX, pattern = [".*Stub.*Repository"])],
		excludeFilters = [Filter(Repository::class)])
class AppConfig {
	// ...
}

以下清单显示了等效的 XML:

<beans>
	<context:component-scan base-package="org.example">
		<context:include-filter type="regex"
				expression=".*Stub.*Repository"/>
		<context:exclude-filter type="annotation"
				expression="org.springframework.stereotype.Repository"/>
	</context:component-scan>
</beans>

您还可以通过将注解上的 useDefaultFilters=false 或将 <component-scan/> 元素的 use-default-filters="false" 属性设置为 false 来禁用默认过滤器。这实际上禁用了自动检测使用 @Component@Repository@Service@Controller@RestController@Configuration 注解或元注解的类。

在组件中定义 Bean 元数据

Spring 组件还可以向容器贡献 bean 定义元数据。您可以使用与在 @Configuration 注解类中定义 bean 元数据相同的 @Bean 注解来完成此操作。以下示例显示了如何执行此操作:

  • Java

  • Kotlin

@Component
public class FactoryMethodComponent {

	@Bean
	@Qualifier("public")
	public TestBean publicInstance() {
		return new TestBean("publicInstance");
	}

	public void doWork() {
		// Component method implementation omitted
	}
}
@Component
class FactoryMethodComponent {

	@Bean
	@Qualifier("public")
	fun publicInstance() = TestBean("publicInstance")

	fun doWork() {
		// Component method implementation omitted
	}
}

前面的类是一个 Spring 组件,其 doWork() 方法中包含特定于应用程序的代码。但是,它也贡献了一个 bean 定义,该定义具有一个引用 publicInstance() 方法的工厂方法。@Bean 注解标识了工厂方法和其他 bean 定义属性,例如通过 @Qualifier 注解提供的限定符值。可以指定的其他方法级注解是 @Scope@Lazy 和自定义限定符注解。

除了用于组件初始化之外,您还可以将 @Lazy 注解放置在用 @Autowired@Inject 标记的注入点上。在这种情况下,它会导致注入一个惰性解析代理。但是,这种代理方法相当有限。对于复杂的惰性交互,特别是与可选依赖项结合使用时,我们建议使用 ObjectProvider<MyTargetBean>

支持自动装配的字段和方法,如前所述,并额外支持 @Bean 方法的自动装配。以下示例显示了如何执行此操作:

  • Java

  • Kotlin

@Component
public class FactoryMethodComponent {

	private static int i;

	@Bean
	@Qualifier("public")
	public TestBean publicInstance() {
		return new TestBean("publicInstance");
	}

	// use of a custom qualifier and autowiring of method parameters
	@Bean
	protected TestBean protectedInstance(
			@Qualifier("public") TestBean spouse,
			@Value("#{privateInstance.age}") String country) {
		TestBean tb = new TestBean("protectedInstance", 1);
		tb.setSpouse(spouse);
		tb.setCountry(country);
		return tb;
	}

	@Bean
	private TestBean privateInstance() {
		return new TestBean("privateInstance", i++);
	}

	@Bean
	@RequestScope
	public TestBean requestScopedInstance() {
		return new TestBean("requestScopedInstance", 3);
	}
}
@Component
class FactoryMethodComponent {

	companion object {
		private var i: Int = 0
	}

	@Bean
	@Qualifier("public")
	fun publicInstance() = TestBean("publicInstance")

	// use of a custom qualifier and autowiring of method parameters
	@Bean
	protected fun protectedInstance(
			@Qualifier("public") spouse: TestBean,
			@Value("#{privateInstance.age}") country: String) = TestBean("protectedInstance", 1).apply {
		this.spouse = spouse
		this.country = country
	}

	@Bean
	private fun privateInstance() = TestBean("privateInstance", i++)

	@Bean
	@RequestScope
	fun requestScopedInstance() = TestBean("requestScopedInstance", 3)
}

该示例将 String 方法参数 country 自动装配到另一个名为 privateInstance 的 bean 的 age 属性的值。Spring Expression Language 元素通过 #{ <expression> } 符号定义属性的值。对于 @Value 注解,表达式解析器预先配置为在解析表达式文本时查找 bean 名称。

从 Spring Framework 4.3 开始,您还可以声明 InjectionPoint 类型(或其更具体的子类:DependencyDescriptor)的工厂方法参数,以访问触发当前 bean 创建的请求注入点。请注意,这仅适用于 bean 实例的实际创建,而不适用于现有实例的注入。因此,此功能对于原型作用域的 bean 最有意义。对于其他作用域,工厂方法只会在给定作用域中看到触发新 bean 实例创建的注入点(例如,触发惰性单例 bean 创建的依赖项)。在这种情况下,您可以谨慎地使用提供的注入点元数据。以下示例显示了如何使用 InjectionPoint

  • Java

  • Kotlin

@Component
public class FactoryMethodComponent {

	@Bean @Scope("prototype")
	public TestBean prototypeInstance(InjectionPoint injectionPoint) {
		return new TestBean("prototypeInstance for " + injectionPoint.getMember());
	}
}
@Component
class FactoryMethodComponent {

	@Bean
	@Scope("prototype")
	fun prototypeInstance(injectionPoint: InjectionPoint) =
			TestBean("prototypeInstance for ${injectionPoint.member}")
}

常规 Spring 组件中的 @Bean 方法与 Spring @Configuration 类中的对应方法处理方式不同。区别在于 @Component 类不会通过 CGLIB 增强来拦截方法和字段的调用。CGLIB 代理是 @Configuration 类中 @Bean 方法内部调用方法或字段时,创建对协作对象的 bean 元数据引用的方式。此类方法不会以正常的 Java 语义调用,而是通过容器来提供 Spring bean 通常的生命周期管理和代理,即使通过编程调用 @Bean 方法引用其他 bean 也是如此。相比之下,在普通 @Component 类中调用 @Bean 方法中的方法或字段具有标准 Java 语义,没有特殊的 CGLIB 处理或其他限制。

您可以将 @Bean 方法声明为 static,从而允许在不创建其包含配置类的实例的情况下调用它们。这在定义后处理器 bean(例如,BeanFactoryPostProcessorBeanPostProcessor 类型)时尤其有意义,因为此类 bean 在容器生命周期的早期初始化,并且应该避免在该点触发配置的其他部分。对静态 @Bean 方法的调用永远不会被容器拦截,即使在 @Configuration 类中也不会(如本节前面所述),由于技术限制:CGLIB 子类只能覆盖非静态方法。因此,直接调用另一个 @Bean 方法具有标准 Java 语义,导致直接从工厂方法本身返回一个独立实例。@Bean 方法的 Java 语言可见性对 Spring 容器中生成的 bean 定义没有直接影响。您可以根据需要在非 @Configuration 类中以及任何静态方法中自由声明您的工厂方法。但是,@Configuration 类中的常规 @Bean 方法需要可覆盖——即,它们不得声明为 privatefinal@Bean 方法还会在给定组件或配置类的基类上以及组件或配置类实现的接口中声明的 Java 8 默认方法上被发现。这允许在组合复杂配置安排方面具有很大的灵活性,甚至从 Spring 4.2 开始,通过 Java 8 默认方法也可以实现多重继承。最后,单个类可以为同一个 bean 拥有多个 @Bean 方法,作为根据运行时可用依赖项使用的多个工厂方法的安排。这与在其他配置场景中选择“最贪婪的”构造函数或工厂方法的算法相同:在构建时选择具有最多可满足依赖项的变体,类似于容器如何选择多个 @Autowired 构造函数。

命名自动检测组件

当组件作为扫描过程的一部分自动检测时,其 bean 名称由该扫描器已知的 BeanNameGenerator 策略生成。

默认情况下,使用 AnnotationBeanNameGenerator。对于 Spring 构造型注解,如果您通过注解的 value 属性提供名称,则该名称将用作相应 bean 定义中的名称。当使用以下 JSR-250 和 JSR-330 注解而不是 Spring 构造型注解时,此约定也适用:@jakarta.annotation.ManagedBean@javax.annotation.ManagedBean@jakarta.inject.Named@javax.inject.Named

从 Spring Framework 6.1 开始,用于指定 bean 名称的注解属性名称不再需要是 value。自定义构造型注解可以声明一个具有不同名称(例如 name)的属性,并用 @AliasFor(annotation = Component.class, attribute = "value") 注解该属性。有关具体示例,请参阅 ControllerAdvice#name() 的源代码声明。

从 Spring Framework 6.1 开始,对基于约定的构造型名称的支持已被弃用,并将在框架的未来版本中删除。因此,自定义构造型注解必须使用 @AliasFor 来声明 @Componentvalue 属性的显式别名。有关具体示例,请参阅 Repository#value()ControllerAdvice#name() 的源代码声明。

如果无法从此类注解或任何其他检测到的组件(例如通过自定义过滤器发现的组件)派生出显式 bean 名称,则默认 bean 名称生成器将返回未首字母大写的非限定类名。例如,如果检测到以下组件类,则名称将是 myMovieListermovieFinderImpl

  • Java

  • Kotlin

@Service("myMovieLister")
public class SimpleMovieLister {
	// ...
}
@Service("myMovieLister")
class SimpleMovieLister {
	// ...
}
  • Java

  • Kotlin

@Repository
public class MovieFinderImpl implements MovieFinder {
	// ...
}
@Repository
class MovieFinderImpl : MovieFinder {
	// ...
}

如果您不想依赖默认的 bean 命名策略,您可以提供自定义的 bean 命名策略。首先,实现 BeanNameGenerator 接口,并确保包含一个默认的无参数构造函数。然后,在配置扫描器时提供完全限定的类名,如下面的示例注解和 bean 定义所示。

如果您由于多个自动检测到的组件具有相同的非限定类名(即,具有相同名称但位于不同包中的类)而遇到命名冲突,您可能需要配置一个 BeanNameGenerator,该生成器默认使用完全限定类名作为生成的 bean 名称。org.springframework.context.annotation 包中的 FullyQualifiedAnnotationBeanNameGenerator 可用于此类目的。

  • Java

  • Kotlin

@Configuration
@ComponentScan(basePackages = "org.example", nameGenerator = MyNameGenerator.class)
public class AppConfig {
	// ...
}
@Configuration
@ComponentScan(basePackages = ["org.example"], nameGenerator = MyNameGenerator::class)
class AppConfig {
	// ...
}
<beans>
	<context:component-scan base-package="org.example"
		name-generator="org.example.MyNameGenerator" />
</beans>

通常,当其他组件可能对其进行显式引用时,请考虑使用注解指定名称。另一方面,当容器负责装配时,自动生成的名称就足够了。

为自动检测组件提供作用域

与通常的 Spring 管理组件一样,自动检测组件的默认和最常见作用域是 singleton。但是,有时您需要不同的作用域,这可以通过 @Scope 注解指定。您可以在注解中提供作用域名称,如下例所示:

  • Java

  • Kotlin

@Scope("prototype")
@Repository
public class MovieFinderImpl implements MovieFinder {
	// ...
}
@Scope("prototype")
@Repository
class MovieFinderImpl {
	// ...
}

@Scope 注解仅在具体的 bean 类(对于注解组件)或工厂方法(对于 @Bean 方法)上进行内省。与 XML bean 定义相反,没有 bean 定义继承的概念,并且类级别的继承层次结构对于元数据目的而言是无关紧要的。

有关 Spring 上下文中特定于 Web 的作用域(例如“request”或“session”)的详细信息,请参阅 请求、会话、应用程序和 WebSocket 作用域。与这些作用域的预构建注解一样,您还可以通过使用 Spring 的元注解方法来组合自己的作用域注解:例如,一个自定义注解,用 @Scope("prototype") 元注解,可能还声明一个自定义作用域代理模式。

要提供自定义的作用域解析策略而不是依赖于基于注解的方法,您可以实现 ScopeMetadataResolver 接口。请务必包含一个默认的无参数构造函数。然后,您可以在配置扫描器时提供完全限定的类名,如下面的注解和 bean 定义示例所示:

  • Java

  • Kotlin

@Configuration
@ComponentScan(basePackages = "org.example", scopeResolver = MyScopeResolver.class)
public class AppConfig {
	// ...
}
@Configuration
@ComponentScan(basePackages = ["org.example"], scopeResolver = MyScopeResolver::class)
class AppConfig {
	// ...
}
<beans>
	<context:component-scan base-package="org.example" scope-resolver="org.example.MyScopeResolver"/>
</beans>

当使用某些非单例作用域时,可能需要为作用域对象生成代理。原因在 作用域 Bean 作为依赖项 中有描述。为此,组件扫描元素上提供了 scoped-proxy 属性。三个可能的值是:nointerfacestargetClass。例如,以下配置会产生标准的 JDK 动态代理:

  • Java

  • Kotlin

@Configuration
@ComponentScan(basePackages = "org.example", scopedProxy = ScopedProxyMode.INTERFACES)
public class AppConfig {
	// ...
}
@Configuration
@ComponentScan(basePackages = ["org.example"], scopedProxy = ScopedProxyMode.INTERFACES)
class AppConfig {
	// ...
}
<beans>
	<context:component-scan base-package="org.example" scoped-proxy="interfaces"/>
</beans>

使用注解提供限定符元数据

@Qualifier 注解在 使用限定符微调基于注解的自动装配 中讨论。该部分中的示例演示了 @Qualifier 注解和自定义限定符注解的使用,以在解析自动装配候选者时提供细粒度控制。由于这些示例基于 XML bean 定义,因此限定符元数据是通过 XML 中 bean 元素的 qualifiermeta 子元素在候选 bean 定义上提供的。当依赖类路径扫描自动检测组件时,您可以使用候选类上的类型级注解提供限定符元数据。以下三个示例演示了此技术:

  • Java

  • Kotlin

@Component
@Qualifier("Action")
public class ActionMovieCatalog implements MovieCatalog {
	// ...
}
@Component
@Qualifier("Action")
class ActionMovieCatalog : MovieCatalog
  • Java

  • Kotlin

@Component
@Genre("Action")
public class ActionMovieCatalog implements MovieCatalog {
	// ...
}
@Component
@Genre("Action")
class ActionMovieCatalog : MovieCatalog {
	// ...
}
  • Java

  • Kotlin

@Component
@Offline
public class CachingMovieCatalog implements MovieCatalog {
	// ...
}
@Component
@Offline
class CachingMovieCatalog : MovieCatalog {
	// ...
}

与大多数基于注解的替代方案一样,请记住注解元数据绑定到类定义本身,而 XML 的使用允许相同类型的多个 bean 提供其限定符元数据的变体,因为该元数据是按实例而不是按类提供的。