Spring Boot 备忘清单

依赖倒置原则倡导我们应该 面向抽象（接口）编程，而不是面向具体实现编程。其目标是让上层不再依赖下层，实现依赖关系的“倒置”。

Spring 框架正是为解决传统编程中对象创建和关系管理的难题而生，它通过将对象的创建权和关系管理权从业务代码中移交出去，引出了其核心思想——控制反转。

控制反转 (Inversion of Control, IoC) 是一种核心设计思想，其主要目的就是用来降低代码之间的耦合度。核心理念是：将对象的创建权和对象之间关系的管理权交出去，由一个独立的第三方容器来负责。

依赖注入 (Dependency Injection, DI) 是实现 IoC 思想最常见、最重要的方式。Spring 是一个完美实现了 IoC 思想，并以 DI 作为其核心机制的顶级容器框架。

Spring 是一个轻量级的控制反转(IoC)和面向切面(AOP)的容器框架，旨在简化企业级 Java 应用的开发。它通过促进松耦合和可测试性，让我们能将精力完全集中在核心业务逻辑的实现上。

Spring Framework 6.x 要求 JDK 的最低版本为 Java 17。

• IDE: IntelliJ IDEA 2024.1.4
• 构建工具: Apache Maven 3.9.11
• 项目 JDK: Java 17
• Spring Framework: 6.2.9
• 测试框架: JUnit 5.13.4

使用 <constructor-arg> 标签，在实例化 Bean 的同时完成依赖注入。

<bean id="userDaoBean" class="com.example.spring6.bean.UserDao"/>

<bean id="userServiceBean" class="com.example.spring6.bean.UserService">
    <constructor-arg name="userDao" ref="userDaoBean"/>
</bean>

在现代 Spring/Boot 中已不再使用，了解即可。

<beans xmlns="http://www.springframework.org/schema/beans"
       xmlns:p="http://www.springframework.org/schema/p"
       xmlns:c="http://www.springframework.org/schema/c" ...>

    <!-- p 命名空间简化 Setter 注入 -->
    <bean id="user2" class="com.example.spring6.bean.User" p:name="Prorise" p:age="25"/>

    <!-- c 命名空间简化构造器注入 -->
    <bean id="service2" class="com.example.spring6.bean.UserService" c:userDao-ref="userDaoBean"/>

</beans>

将易变配置移至 .properties 文件，通过 <context:property-placeholder> 加载。

<!-- beans.xml -->
<beans xmlns:context="http://www.springframework.org/schema/context" ...>
    <!-- 加载 jdbc.properties 文件 -->
    <context:property-placeholder location="classpath:jdbc.properties"/>

    <bean id="dataSource" class="com.alibaba.druid.pool.DruidDataSource">
        <property name="driverClassName" value="${db.driver}"/>
        <property name="url" value="${db.url}"/>
    </bean>
</beans>

# jdbc.properties
db.driver=com.mysql.cj.jdbc.Driver
db.url=jdbc:mysql://localhost:3306/testdb

• 构造方法实例化 (默认): 调用无参构造器。
• 静态工厂方法:

  <bean id="apiClient" class="com.example.spring6.bean.LegacyApiClient" factory-method="getInstance"/>
  

• 实例工厂方法:

  <bean id="poolManager" class="com.example.spring6.bean.ConnectionPoolManager"/>
  <bean id="connectionPool" factory-bean="poolManager" factory-method="createPool"/>
  

• FactoryBean 接口: 实现 FactoryBean 接口，将复杂的实例化逻辑封装在 getObject() 方法中。

  <bean id="product" class="com.example.spring6.bean.ProductFactoryBean"/>
  

  获取 product 得到的是 getObject() 的返回值；获取 &product 得到的是 FactoryBean 本身。

1. 实例化: Spring 调用构造方法创建 Bean 实例。
2. 属性填充: Spring 通过 DI 为 Bean 注入依赖。
3. 初始化回调 (前): BeanPostProcessor 的 postProcessBeforeInitialization 执行。
4. 初始化: 执行 @PostConstruct 注解的方法或 init-method 指定的方法。
5. 初始化回调 (后): BeanPostProcessor 的 postProcessAfterInitialization 执行。
6. Bean 可用: Bean 处于可用状态。
7. 销毁: 容器关闭时，执行 @PreDestroy 注解的方法或 destroy-method 指定的方法。

// SpringBootDemoApplication.java
@SpringBootApplication
public class SpringBootDemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(SpringBootDemoApplication.class, args);
    }
}

// HelloController.java
@RestController
public class HelloController {
    @GetMapping("/hello")
    public String sayHello() {
        return "Hello, Spring Boot!";
    }
}

Spring Boot 打包生成的 JAR (Fat JAR) 内置了所有依赖和 Tomcat 服务器，可以通过 java -jar 命令直接运行。

# 打包
mvn package
# 运行
java -jar target/spring-boot-demo-0.0.1-SNAPSHOT.jar

@SpringBootApplication 是一个复合注解，包含了：

• @EnableAutoConfiguration: 启用自动配置，根据类路径上的依赖自动配置 Bean。
• @ComponentScan: 启用组件扫描，默认扫描启动类所在的包及其子包。
• @SpringBootConfiguration: 声明启动类本身是一个配置类。

自动配置类通过 @ConditionalOn... 系列注解实现按需加载。

通过 application-{profile}.yml 文件为不同环境（dev, test, prod）创建独立配置。

# application.yml (主配置文件)
spring:
  profiles:
    active: dev # 指定默认激活的环境

# application-dev.yml
server:
  port: 8080

# application-prod.yml
server:
  port: 80

激活 Profile 的方式 (高优先级覆盖低优先级):

1. 在 application.yml 中配置 spring.profiles.active。
2. 通过命令行参数: java -jar my-app.jar --spring.profiles.active=prod。

@GetMapping("/search")
public String searchUsers(
    @RequestParam String keyword,
    @RequestParam(required = false, defaultValue = "1") Integer page) {
    // ...
}

@PostMapping("/create")
public String createUser(@RequestBody User user) {
    // ...
}

// 自动封装：当参数是 POJO 且没有 @RequestBody 时，
// Spring MVC 会自动将同名请求参数绑定到 POJO 属性上。
@GetMapping("/filter")
public String filterUsers(UserQuery query) {
    // ...
}

通过 Jackson 注解，可以精确控制 Java 对象与 JSON 之间的转换。

@Data
public class UserVO {
    @JsonProperty("user_name") // username -> user_name
    private String name;

    @JsonFormat(pattern = "yyyy-MM-dd HH:mm:ss")
    private LocalDateTime createTime;
}

通过 Jakarta Bean Validation API 和 @Validated 实现声明式参数校验。

1. 添加依赖: spring-boot-starter-validation
2. 在 DTO 中添加注解:

   @Data
   public class UserSaveDTO {
       @NotBlank(message = "用户名不能为空")
       private String username;
       
       @Email(message = "邮箱格式不正确")
       private String email;
   }
   

3. 在 Controller 中激活校验:

   @RestController
   @Validated // 可以在类上添加
   public class UserController {
       @PostMapping("/users")
       public void saveUser(@Validated @RequestBody UserSaveDTO dto) {
           // ...
       }
   }
   

   校验失败会抛出 MethodArgumentNotValidException，可由全局异常处理器捕获。

通过 @RestControllerAdvice 和 @ExceptionHandler，可以集中处理所有 Controller 抛出的异常，返回统一的 Result 格式。

@Slf4j
@RestControllerAdvice
public class GlobalExceptionHandler {

    // 处理自定义业务异常
    @ExceptionHandler(BusinessException.class)
    public ResponseEntity<Result<Void>> handleBusinessException(BusinessException ex) {
        return ResponseEntity.status(HttpStatus.BAD_REQUEST)
                             .body(Result.error(ex.getResultCode()));
    }

    // 处理参数校验异常
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<Result<Void>> handleValidationException(MethodArgumentNotValidException ex) {
        String message = ex.getBindingResult().getFieldErrors().stream()
                .map(e -> e.getField() + ": " + e.getDefaultMessage())
                .collect(Collectors.joining("; "));
        return ResponseEntity.status(HttpStatus.BAD_REQUEST)
                             .body(Result.error(message));
    }

    // 兜底处理所有未知异常
    @ExceptionHandler(Exception.class)
    public ResponseEntity<Result<Void>> handleUnknownException(Exception ex) {
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                             .body(Result.error("系统异常，请联系管理员"));
    }
}

• @Before: 目标方法执行前。
• @AfterReturning: 目标方法成功返回后。
• @AfterThrowing: 目标方法抛出异常后。
• @After: 无论成功或异常，在目标方法之后都会执行。
• @Around: 环绕通知，最强大，可完全控制目标方法执行。

• @annotation: 匹配被特定注解标记的方法。

  @Pointcut("@annotation(com.example.democommon.annotation.SimpleCache)")
  

• execution: 匹配方法签名。

  // 匹配 com.example.demosystem.service 包及其子包下所有 public 方法
  @Pointcut("execution(public * com.example.demosystem.service..*.*(..))")
  

@Aspect
@Component
@Slf4j
public class PerformanceAspect {
    @Pointcut("execution(public * com.example.demosystem.service..*.*(..))")
    public void serviceMethods() {}

    @Around("serviceMethods()")
    public Object profile(ProceedingJoinPoint pjp) throws Throwable {
        long start = System.currentTimeMillis();
        try {
            return pjp.proceed(); // 执行原始方法
        } finally {
            long end = System.currentTimeMillis();
            log.info("{}.{} 执行耗时: {} ms", pjp.getTarget().getClass().getSimpleName(), pjp.getSignature().getName(), (end - start));
        }
    }
}

通过注解为方法增加缓存能力，无需修改业务逻辑。

1. 添加依赖: spring-boot-starter-data-redis (已包含 spring-boot-starter-cache)
2. 启用缓存: 在启动类上添加 @EnableCaching。
3. 配置 Redis:

   # application.yml
   spring:
     data:
       redis:
         host: localhost
         port: 6379
   

4. 配置 JSON 序列化 (推荐): 创建 CacheConfig Bean 来定制序列化方式。
5. 在 Service 方法上使用注解:

@Service
public class UserServiceImpl implements UserService {
    // SpEL 表达式: #id 表示取方法的 id 参数作为 key
    @Cacheable(cacheNames = "users", key = "#id")
    public UserVO findUserById(Long id) { /* ... */ }

    @CachePut(cacheNames = "users", key = "#dto.id")
    public UserVO updateUser(UserEditDTO dto) { /* ... */ }

    @CacheEvict(cacheNames = "users", key = "#id")
    public void deleteUserById(Long id) { /* ... */ }
}

Spring Boot 3.2+ 推荐的同步 HTTP 客户端，替代 RestTemplate。

// 1. 在配置类中创建 Bean
@Bean
public RestClient restClient() {
    return RestClient.builder()
            .baseUrl("https://jsonplaceholder.typicode.com")
            .build();
}

// 2. 在 Service 中注入并使用
@Service
@RequiredArgsConstructor
public class ExternalApiService {
    private final RestClient restClient;

    public PostDTO getUserFirstPost(Integer userId) {
        return restClient.get()
                .uri("/posts?userId={userId}", userId)
                .retrieve()
                // 优雅地处理 5xx 错误
                .onStatus(HttpStatusCode::is5xxServerError, (req, resp) -> {
                    throw new RetryableException("外部服务暂时不可用");
                })
                .body(new ParameterizedTypeReference<List<PostDTO>>() {})
                .get(0);
    }
}

为可能失败的操作（如外部 API 调用）增加自动重试能力。

1. 添加依赖: spring-retry
2. 启用重试: 在启动类上添加 @EnableRetry。
3. 在方法上使用注解:

@Service
public class ExternalApiService {

    @Retryable(
        include = RetryableException.class, // 只对特定异常重试
        maxAttempts = 3,                      // 最多重试3次
        backoff = @Backoff(delay = 2000)      // 每次重试间隔2秒
    )
    public PostDTO getUserFirstPost(Integer userId) { /* ... */ }

    // 当所有重试都失败后，此方法将被调用作为降级方案
    @Recover
    public PostDTO recover(RetryableException e, Integer userId) {
        log.error("调用外部 API 达到最大重试次数后仍然失败", e);
        return null; // 返回默认值或抛出最终异常
    }
}

无需人工干预，按预定时间自动触发任务。

1. 启用调度: 在启动类上添加 @EnableScheduling。
2. 创建定时任务:

   @Component
   @Slf4j
   public class SystemTasks {
       // 每隔 5 秒执行一次 (从上一次任务开始计时)
       @Scheduled(fixedRate = 5000)
       public void runAtFixedRate() { /* ... */ }
   
       // 上一次任务结束后，延迟 3 秒再执行
       @Scheduled(fixedDelay = 3000)
       public void runAtFixedDelay() { /* ... */ }
   
       // 每天凌晨 3 点执行
       @Scheduled(cron = "0 0 3 * * ?")
       public void archiveOldLogs() { /* ... */ }
   }
   

前置条件: JDK 21+ & Spring Boot 3.2+

极大地提升 I/O 密集型应用的吞吐量，线程不再是瓶颈。

一键开启:

# application.yml
spring:
  threads:
    virtual:
      enabled: true

开启后，Tomcat 会使用虚拟线程处理每个 HTTP 请求。这与 @Async 使用的平台线程池是互补的，而非替代关系。

@ExtendWith(MockitoExtension.class)
class UserServiceImplTest {

    @InjectMocks
    private UserServiceImpl userService;

    @Mock
    private UserMapper userMapper;

    @Test
    void testFindUserById_whenUserExists() {
        // GIVEN: "打桩"，设定模拟对象的行为
        User mockUser = new User();
        mockUser.setId(1L);
        when(userMapper.selectById(1L)).thenReturn(mockUser);

        // WHEN: 执行被测试方法
        UserVO resultVO = userService.findUserById(1L);

        // THEN: 验证结果
        assertThat(resultVO.getId()).isEqualTo(1L);
    }
}

行为验证 (verify): 用于测试 void 方法或验证交互。

// 验证 userMapper.deleteById(1L) 方法被调用了恰好 1 次
verify(userMapper, times(1)).deleteById(1L);

@WebMvcTest 创建一个只包含 Web 层组件的轻量级 Spring 测试上下文。

@WebMvcTest(controllers = UserController.class)
class UserControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @MockBean // 用 MockBean 替换真实的 UserService
    private UserService userService;

    @Test
    void testGetUserById_whenUserExists() throws Exception {
        // GIVEN: "打桩" Service 层的行为
        UserVO mockUserVO = new UserVO();
        mockUserVO.setId(1L);
        when(userService.findUserById(1L)).thenReturn(mockUserVO);

        // WHEN & THEN: 模拟 HTTP 请求并验证响应
        mockMvc.perform(get("/users/1"))
                .andExpect(status().isOk())
                .andExpect(content().contentType(MediaType.APPLICATION_JSON))
                .andExpect(jsonPath("$.data.id").value(1L));
    }
}