类路径扫描和托管组件

本章中的大多数示例都使用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
Kotlin

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Component (1)
public @interface Service {

	// ...
}

1	`@Component`使`@Service`的处理方式与`@Component`相同。

@Target(AnnotationTarget.TYPE)
@Retention(AnnotationRetention.RUNTIME)
@MustBeDocumented
@Component (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 Annotation Programming Model 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，您需要在@Configuration类中添加@ComponentScan，其中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”——参见stackoverflow.com/questions/19394570/java-jre-7u45-breaks-classloader-getresources），类路径目录可能不会根据安全策略公开。

在模块路径（Java模块系统）上，Spring的类路径扫描通常按预期工作。但是，请确保您的组件类在您的module-info描述符中导出。如果您希望Spring调用类的非公共成员，请确保它们已“打开”（即，它们在您的module-info描述符中使用opens声明而不是exports声明）。

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

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

使用过滤器自定义扫描

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

表 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 注解并改用“存根”存储库的配置

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 或通过提供 use-default-filters="false" 作为 <component-scan/> 元素的属性来禁用默认过滤器。这有效地禁用了对使用 @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> } 符号定义属性的值。对于 @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（例如，类型为 BeanFactoryPostProcessor 或 BeanPostProcessor 的 Bean）时，这样做尤其有意义，因为此类 Bean 在容器生命周期的早期进行初始化，并且应避免在此时触发配置的其他部分。

由于技术限制，对静态 @Bean 方法的调用永远不会被容器拦截，即使在 @Configuration 类中也是如此（如本节前面所述）：CGLIB 子类化只能重写非静态方法。因此，对另一个 @Bean 方法的直接调用具有标准的 Java 语义，导致独立实例直接从工厂方法本身返回。

@Bean 方法的 Java 语言可见性不会对 Spring 容器中生成的 Bean 定义产生直接影响。您可以根据需要自由地声明工厂方法，适用于非 @Configuration 类以及任何地方的静态方法。但是，@Configuration 类中的常规 @Bean 方法需要可重写——也就是说，它们不能声明为 private 或 final。

@Bean 方法还会在给定组件或配置类的基类上发现，以及在组件或配置类实现的接口中声明的 Java 8 默认方法上发现。这允许在组合复杂的配置安排方面具有很大的灵活性，甚至可以通过 Java 8 默认方法（从 Spring 4.2 开始）实现多重继承。

最后，单个类可以为同一个 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 为 @Component 中的 value 属性声明显式别名。有关具体示例，请参见 Repository#value() 和 ControllerAdvice#name() 的源代码声明。

如果无法从这样的注解中推导出显式 Bean 名称，或者对于任何其他检测到的组件（例如通过自定义过滤器发现的组件），默认 Bean 名称生成器将返回未大写的非限定类名。例如，如果检测到以下组件类，则名称将为 myMovieLister 和 movieFinderImpl。

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 : MovieFinder {
	// ...
}

@Scope 注解仅在具体的 Bean 类（对于带注解的组件）或工厂方法（对于 @Bean 方法）上进行内省。与 XML Bean 定义相反，没有 Bean 定义继承的概念，并且类级别的继承层次结构与元数据无关。

有关 Spring 上下文中“请求”或“会话”等 Web 特定作用域的详细信息，请参见请求、会话、应用程序和 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 属性。三个可能的值是：no、interfaces 和 targetClass。例如，以下配置将生成标准的 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 元素的qualifier 或meta 子元素在候选 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 提供其限定符元数据的变体，因为该元数据是按实例而不是按类提供的。

类路径扫描和托管组件

@Component和其他构造型注解

使用元注解和组合注解

自动检测类和注册Bean定义

使用过滤器自定义扫描

在组件中定义 Bean 元数据

命名自动检测的组件

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

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

`@Component`和其他构造型注解