Java 后端 / 系统课时
组织组件扫描与配置类
组织组件扫描与配置类
本课建立清晰的 Bean 注册边界:业务类交给组件扫描发现,第三方或基础设施对象由配置类显式创建,并通过启动与接口请求验证容器装配结果。
学习目标
- 根据启动类包位置判断默认组件扫描范围
- 正确选择
@Component、@Service、@Repository与@RestController - 使用
@Configuration和@Bean注册基础设施对象
从启动类确定扫描边界
@SpringBootApplication 组合了自动配置、配置声明和组件扫描。默认情况下,Spring 从启动类所在包开始,递归扫描其子包。因此启动类通常放在应用根包,例如 com.example.enterprise,业务、接口和配置类都放在其下。

如果组件位于根包之外,它不会自动成为 Bean。优先调整包结构,让应用代码位于统一根包下;只有整合独立模块时,才显式配置额外扫描范围,避免把过大的父包加入扫描。
用语义化组件注解组织业务对象
@Component 是通用组件注解;@Service 表示业务服务;@Repository 表示数据访问组件,并可参与持久化异常转换;@Controller 与 @RestController 用于 Web 入口。它们都能被组件扫描发现,但语义化注解更能表达职责,也便于后续按层实施规则。
不要在普通数据对象、请求参数或 JPA 实体上添加组件注解。这些对象应由业务代码、Web 绑定器或持久化框架创建,而不是作为默认单例长期保存在容器中。
使用配置类注册基础设施 Bean
JDK 类和第三方类通常无法直接添加 @Component。此时使用 @Configuration 集中描述创建方式,再通过 @Bean 把返回对象交给容器管理。下面是片段示例,文件分别位于注释所示路径。
// EnterpriseApplication.java
package com.example.enterprise;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
@SpringBootApplication
public class EnterpriseApplication {
public static void main(String[] args) {
SpringApplication.run(EnterpriseApplication.class, args);
}
}
// config/TimeConfiguration.java
package com.example.enterprise.config;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import java.time.Clock;
@Configuration(proxyBeanMethods = false)
public class TimeConfiguration {
@Bean
Clock businessClock() {
// JDK 类型不能添加组件注解,因此在配置类中显式注册
return Clock.systemUTC();
}
}
// service/BusinessClockService.java
package com.example.enterprise.service;
import org.springframework.stereotype.Service;
import java.time.Clock;
import java.time.Instant;
@Service
public class BusinessClockService {
private final Clock clock;
public BusinessClockService(Clock clock) {
this.clock = clock;
}
public Instant currentTime() {
return Instant.now(clock);
}
}
// web/TimeController.java
package com.example.enterprise.web;
import com.example.enterprise.service.BusinessClockService;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import java.util.Map;
@RestController
@RequestMapping("/api/time")
public class TimeController {
private final BusinessClockService clockService;
public TimeController(BusinessClockService clockService) {
this.clockService = clockService;
}
@GetMapping
Map<String, String> currentTime() {
return Map.of("utcTime", clockService.currentTime().toString());
}
}下面的命令在后台启动应用,等待接口可用后请求一次并停止进程:
./mvnw spring-boot:run > app.log 2>&1 &
APP_PID=$!
until RESPONSE=$(curl -sf http://localhost:8080/api/time); do sleep 1; done
printf '%s\n' "$RESPONSE"
kill "$APP_PID"预期输出:
{"utcTime":"<TIME>"}<TIME> 是实际请求时生成的 UTC 时间。接口能够返回结果,说明控制器和服务被组件扫描发现,Clock 由配置类注册,并通过构造器完成了依赖注入。
控制扫描范围与 Bean 冲突
需要扫描外部模块时,可以在启动类使用 @ComponentScan(basePackages = {...}),但应列出稳定、明确的包,而不是扫描 com 之类的宽泛根包。扫描范围过大可能加载测试组件、旧实现或第三方内部类,使启动行为难以预测。
配置类建议按基础设施主题拆分,例如时间、序列化、HTTP 客户端和缓存。若同一类型注册了多个 Bean,应使用 @Primary 指定默认项,或在注入点配合 @Qualifier 选择名称;不要依赖方法名或加载顺序碰巧匹配。
proxyBeanMethods = false 适合 Bean 方法彼此独立的配置类,可减少代理开销。若一个 @Bean 需要另一个 Bean,优先把依赖声明为方法参数,让容器负责解析,而不是直接调用同一配置类中的方法。