@PostConstruct

定位：JSR-250 标准注解，标记在依赖注入完成后执行的初始化方法。它是 Spring 生命周期回调的首选推荐方式，与 Spring API 零耦合。

定义与作用

@PostConstruct 是 Java 通用注解规范（JSR-250）定义的注解，位于 javax.annotation 包下（Spring 6 / Jakarta EE 9+ 后迁移至 jakarta.annotation）。

其核心语义是：在对象构造完成且所有依赖注入结束后，立即执行被标注的方法。该方法用于执行 Bean 的初始化逻辑，例如：

预热缓存、加载配置到内存
初始化数据库连接池、线程池
校验必填属性是否合法
注册监听器或启动后台任务

与 InitializingBean.afterPropertiesSet() 相比，@PostConstruct 不强制实现 Spring 接口，代码可在非 Spring 容器（如 Jakarta EE 应用服务器）中复用。

适用位置与常用属性

项目	说明
标注位置	方法上（实例方法，不能是静态方法）
方法签名	`public` / `protected` / `package-private`，返回类型必须为 `void`，无参数
执行次数	每个 Bean 实例生命周期内仅执行一次
执行时机	依赖注入完成后、`InitializingBean.afterPropertiesSet()` 之前、`BeanPostProcessor.beforeInit` 之后
属性	该注解本身无属性，纯标记注解

约束：一个类中只能有一个方法被 @PostConstruct 标注。若存在多个，Spring 容器启动时将抛出 BeanCreationException。

核心原理

Spring 容器通过 CommonAnnotationBeanPostProcessor 识别并处理 @PostConstruct 注解。该处理器本身是一个 BeanPostProcessor，在 postProcessBeforeInitialization() 阶段通过反射调用被标注的方法。

与 InitializingBean 的执行顺序

在同一个 Bean 中，如果同时存在 @PostConstruct 和 InitializingBean：

@PostConstruct 方法先执行
afterPropertiesSet() 后执行

这个顺序由 CommonAnnotationBeanPostProcessor 的优先级决定——它在 postProcessBeforeInitialization() 中处理 @PostConstruct，而 InitializingBean 的调用由 Spring 内部在 BPP 前处理之后直接触发。

完整示例：飞翔科技学生管理系统的课程缓存预热

场景简述

飞翔科技后端开发小崔负责学生管理系统的课程模块。系统启动时需要将课程列表从数据库加载到内存缓存，避免每次查询都访问数据库。CTO 大翔明确要求：缓存必须在系统对外提供服务前就绪，不能在第一次请求时现查现建。

操作前：无生命周期回调的代码

小崔最初的实现将缓存初始化放在构造器中，导致启动时依赖尚未注入完成：

@Service
public class CourseService {

    private final CourseDao courseDao;
    private List<Course> courseCache;

    public CourseService(CourseDao courseDao) {
        this.courseDao = courseDao;
        // 错误！构造器执行时，courseDao 可能尚未完全初始化
        // 若 CourseDao 也有初始化逻辑，此时调用可能拿到未就绪的对象
        this.courseCache = courseDao.findAll();
        System.out.println("[CourseService] 缓存加载完成，共 " + courseCache.size() + " 门课程");
    }

    public List<Course> listCourses() {
        return courseCache;
    }
}

运行结果：

[CourseService] 缓存加载完成，共 0 门课程

问题分析：构造器注入虽然保证了 courseDao 引用非空，但 CourseDao 自身的初始化（如数据源预热）可能尚未完成。此时调用 findAll() 可能返回空结果或抛出异常。

操作后：使用 @PostConstruct 的完整代码

小崔重构代码，将缓存预热逻辑移到 @PostConstruct 方法中：

import org.springframework.stereotype.Service;
import javax.annotation.PostConstruct;
import java.util.ArrayList;
import java.util.List;

@Service
public class CourseService {

    private final CourseDao courseDao;
    private List<Course> courseCache;

    // 构造器仅负责依赖注入，不做业务初始化
    public CourseService(CourseDao courseDao) {
        this.courseDao = courseDao;
        System.out.println("[CourseService] 构造器执行，courseDao 已注入");
    }

    /**
     * 依赖注入完成后，执行缓存预热
     * 此时 courseDao 已完成其自身的所有初始化回调
     */
    @PostConstruct
    public void warmCache() {
        System.out.println("[CourseService] @PostConstruct 开始执行缓存预热...");
        this.courseCache = courseDao.findAll();
        System.out.println("[CourseService] 缓存预热完成，共 " + courseCache.size() + " 门课程");
    }

    public List<Course> listCourses() {
        if (courseCache == null) {
            throw new IllegalStateException("课程缓存尚未初始化");
        }
        return new ArrayList<>(courseCache); // 返回副本，防止外部修改
    }

    public Course findById(Long id) {
        return courseCache.stream()
            .filter(c -> c.getId().equals(id))
            .findFirst()
            .orElse(null);
    }
}

依赖的 DAO 层：

import org.springframework.stereotype.Repository;
import javax.annotation.PostConstruct;
import java.util.Arrays;
import java.util.List;

@Repository
public class CourseDao {

    private List<Course> mockDatabase;

    @PostConstruct
    public void initMockData() {
        System.out.println("[CourseDao] @PostConstruct 初始化模拟数据...");
        this.mockDatabase = Arrays.asList(
            new Course(1L, "Java 程序设计", 4),
            new Course(2L, "数据结构与算法", 3),
            new Course(3L, "操作系统原理", 4),
            new Course(4L, "计算机网络", 3),
            new Course(5L, "Spring 框架实战", 2)
        );
        System.out.println("[CourseDao] 模拟数据就绪，共 " + mockDatabase.size() + " 条");
    }

    public List<Course> findAll() {
        return mockDatabase;
    }
}

实体类：

public class Course {
    private Long id;
    private String name;
    private int credits;

    public Course(Long id, String name, int credits) {
        this.id = id;
        this.name = name;
        this.credits = credits;
    }

    // getters
    public Long getId() { return id; }
    public String getName() { return name; }
    public int getCredits() { return credits; }

    @Override
    public String toString() {
        return "Course{id=" + id + ", name='" + name + "', credits=" + credits + "}";
    }
}

Spring Boot 启动验证：

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.ConfigurableApplicationContext;

@SpringBootApplication
public class StudentManagementApplication {
    public static void main(String[] args) {
        ConfigurableApplicationContext context =
            SpringApplication.run(StudentManagementApplication.class, args);

        CourseService service = context.getBean(CourseService.class);
        System.out.println("\n=== 业务查询结果 ===");
        service.listCourses().forEach(System.out::println);

        context.close();
    }
}

运行结果及分析：

[CourseDao] @PostConstruct 初始化模拟数据...
[CourseDao] 模拟数据就绪，共 5 条
[CourseService] 构造器执行，courseDao 已注入
[CourseService] @PostConstruct 开始执行缓存预热...
[CourseService] 缓存预热完成，共 5 门课程

=== 业务查询结果 ===
Course{id=1, name='Java 程序设计', credits=4}
Course{id=2, name='数据结构与算法', credits=3}
Course{id=3, name='操作系统原理', credits=4}
Course{id=4, name='计算机网络', credits=3}
Course{id=5, name='Spring 框架实战', credits=2}

执行顺序验证：

CourseDao 实例化 → 属性填充 → @PostConstruct（mock 数据就绪）
CourseService 实例化 → 构造器执行（courseDao 已注入且已完成初始化）
CourseService 的 @PostConstruct 执行（缓存预热成功拿到 5 条数据）
Bean 就绪，业务查询返回完整缓存

易错场景与面试考点

易错场景一：标注静态方法

@Service
public class ConfigLoader {

    private static Map<String, String> configMap;

    // 错误！Spring 不会调用静态的 @PostConstruct 方法
    @PostConstruct
    public static void loadConfig() {
        configMap = new HashMap<>();
        configMap.put("school.name", "乐途大学");
    }
}

问题：@PostConstruct 要求标注在实例方法上。静态方法属于类而非实例，Spring 的 CommonAnnotationBeanPostProcessor 通过反射调用实例方法，静态方法不会被识别为生命周期回调。启动时可能静默失败，或抛出 BeanCreationException（取决于容器版本）。

正确写法：

@PostConstruct
public void loadConfig() {
    configMap = new HashMap<>();
    configMap.put("school.name", "乐途大学");
}

易错场景二：方法带有参数或返回值

@Service
public class StudentService {

    // 错误！@PostConstruct 方法不能有参数
    @PostConstruct
    public String init(String param) {
        return "initialized";
    }
}

问题：JSR-250 规范明确规定 @PostConstruct 方法必须无参数、返回 void。带有参数或返回值会导致容器启动失败，抛出 BeanCreationException。

易错场景三：与构造器注入混用时的时序误解

@Service
public class ReportService {

    private final DataSource dataSource;
    private Connection testConnection;

    public ReportService(DataSource dataSource) {
        this.dataSource = dataSource;
        // 危险！此时 DataSource 可能尚未完成 @PostConstruct 预热
        try {
            this.testConnection = dataSource.getConnection();
        } catch (SQLException e) {
            throw new RuntimeException(e);
        }
    }

    @PostConstruct
    public void validateConnection() {
        // 正确的连接验证应该放在这里
    }
}

问题分析：构造器注入仅保证依赖对象的引用已传递，但不保证该依赖已完成其自身的初始化回调。若 DataSource 在 @PostConstruct 中预热连接池，构造器阶段调用 getConnection() 可能拿到未就绪的连接池。

团队规范（飞翔科技）：白歌架构师在 Code Review 检查清单中明确写入——"构造器只做赋值，初始化逻辑全部移到 @PostConstruct 或 afterPropertiesSet()"。

面试考点

Q1：@PostConstruct 和构造器有什么区别？

构造器在实例化阶段执行，此时依赖引用可能已传入但尚未完成其自身的初始化；@PostConstruct 在属性填充完成后执行，此时当前 Bean 及其所有依赖均已完成注入和初始化，是执行业务准备逻辑的安全时机。

Q2：如果同时存在 @PostConstruct 和 afterPropertiesSet()，执行顺序是什么？

@PostConstruct 先执行，afterPropertiesSet() 后执行。因为 CommonAnnotationBeanPostProcessor 在 postProcessBeforeInitialization() 阶段处理 @PostConstruct，而 InitializingBean 的调用由 Spring 在 BPP 链处理之后统一触发。

Q3：@PostConstruct 在 Spring Boot 测试中是否执行？

在 @SpringBootTest 或 @ContextConfiguration 加载的上下文中，@PostConstruct 会正常执行。但在使用 MockitoBean 替换 Bean 后，原 Bean 的 @PostConstruct 不会执行（因为实例已被 Mock 替代）。

本文档仅讲解 @PostConstruct 注解。关于销毁阶段的对应注解 @PreDestroy、Spring 接口 InitializingBean / DisposableBean、以及容器扩展点 BeanPostProcessor / BeanFactoryPostProcessor，请分别参阅本章其他独立文档。严禁在讲解 @PostConstruct 时混入 @PreDestroy 或 AOP 代理的详细实现，以保持知识点的原子性和教学清晰度。