11-Spring

@Configuration
@ComponentScan("com.example")
public class AppConfig {
    @Bean
    public DataSource dataSource() {
        return new HikariDataSource(...);
    }
}

@Service
public class UserService {
    private final UserRepository userRepository;

    @Autowired
    public UserService(UserRepository userRepository) {
        this.userRepository = userRepository;
    }
}

ApplicationContext ctx = new AnnotationConfigApplicationContext(AppConfig.class);
UserService service = ctx.getBean(UserService.class);

1. 定位 Bean 定义 → BeanDefinition
2. 实例化 Bean → 反射调用构造器
3. 属性填充 → 依赖注入（字段/Setter/构造器）
4. Aware 回调 → BeanNameAware、ApplicationContextAware 等
5. BeanPostProcessor 前置处理
6. 初始化 → @PostConstruct、InitializingBean、init-method
7. BeanPostProcessor 后置处理（AOP 代理生成）
8. 注册销毁回调 → DisposableBean、destroy-method
9. 放入单例缓存 → 可供后续获取

singletonObjects（一级）：完整初始化的 Bean
earlySingletonObjects（二级）：已创建但未初始化的 Bean
singletonFactories（三级）：ObjectFactory，用于创建早期引用

// 注解方式
@Configuration
public class IocConfig {
    @Bean
    public OrderService orderService() {
        return new OrderService();
    }

    @Bean
    public UserService userService() {
        return new UserService(orderService()); // 构造器注入
    }
}

// 注解自动装配
@Service
public class OrderService {
    @Autowired  // 字段注入（不推荐）
    private UserRepository userRepository;

    @Resource   // 按名称注入
    private OrderRepository orderRepository;
}

ApplicationContext ctx = new AnnotationConfigApplicationContext(IocConfig.class);
OrderService orderService = ctx.getBean(OrderService.class);

1. Bean 初始化完成后，AbstractAutowireCapableBeanFactory#initializeBean
2. 调用 wrapIfNecessary 方法
3. 从容器中查找所有 Advisor（切面 + 通知）
4. 判断 Bean 是否匹配切点
5. 匹配则通过 ProxyFactory 创建代理对象
6. 代理对象替换原始 Bean 放入容器

代理对象.method()
  → 拦截器链（MethodInterceptor）
    → 前置通知（@Before）
    → 目标方法执行
    → 返回通知（@AfterReturning）
    → 后置通知（@After）
    → 异常通知（@AfterThrowing）

@Aspect
@Component
public class LogAspect {

    @Pointcut("execution(* com.example.service.*.*(..))")
    public void serviceLayer() {}

    @Before("serviceLayer()")
    public void beforeLog(JoinPoint jp) {
        System.out.println("调用方法: " + jp.getSignature().getName());
    }

    @AfterReturning(pointcut = "serviceLayer()", returning = "result")
    public void afterReturningLog(JoinPoint jp, Object result) {
        System.out.println("方法返回: " + result);
    }

    @Around("serviceLayer()")
    public Object aroundLog(ProceedingJoinPoint pjp) throws Throwable {
        long start = System.currentTimeMillis();
        Object result = pjp.proceed();
        long elapsed = System.currentTimeMillis() - start;
        System.out.println("耗时: " + elapsed + "ms");
        return result;
    }
}

ProxyFactory pf = new ProxyFactory(target);
pf.addAdvice(new MethodInterceptor() {
    @Override
    public Object invoke(MethodInvocation invocation) throws Throwable {
        System.out.println("前置");
        Object result = invocation.proceed();
        System.out.println("后置");
        return result;
    }
});
Object proxy = pf.getProxy();

1. 容器启动，加载 BeanDefinition
   ↓
2. 实例化 Bean（反射调用构造器，支持构造器参数解析）
   ↓
3. 属性填充（依赖注入：@Autowired、Setter、构造器）
   ↓
4. Aware 回调
   ├─ BeanNameAware#setBeanName
   ├─ BeanFactoryAware#setBeanFactory
   ├─ BeanClassLoaderAware#setBeanClassLoader
   └─ ApplicationContextAware#setApplicationContext
   ↓
5. BeanPostProcessor 前置处理
   └─ postProcessBeforeInitialization
   ↓
6. 初始化
   ├─ @PostConstruct 注解方法
   ├─ InitializingBean#afterPropertiesSet
   └─ init-method（XML 配置或 @Bean(initMethod)）
   ↓
7. BeanPostProcessor 后置处理
   └─ postProcessAfterInitialization（AOP 代理在此生成）
   ↓
8. Bean 就绪，可被应用使用
   ↓
9. 容器关闭时销毁
   ├─ @PreDestroy 注解方法
   ├─ DisposableBean#destroy
   └─ destroy-method（XML 配置或 @Bean(destroyMethod)）

// AbstractAutowireCapableBeanFactory#createBean
protected Object createBean(String beanName, RootBeanDefinition mbd, Object[] args) {
    // 1. 实例化
    Object bean = doCreateBean(beanName, mbd, args);
    // 2. 属性填充
    populateBean(beanName, mbd, instanceWrapper);
    // 3. 初始化
    Object exposedObject = initializeBean(beanName, exposedObject, mbd);
    // 4. 注册销毁回调
    registerDisposableBeanIfNecessary(beanName, bean, mbd);
    return exposedObject;
}

@Component
public class MyBean implements BeanNameAware, InitializingBean, DisposableBean {

    private String beanName;

    @Override
    public void setBeanName(String name) {
        this.beanName = name;
        System.out.println("Bean 名称: " + name);
    }

    @PostConstruct
    public void postConstruct() {
        System.out.println("@PostConstruct: Bean 创建后");
    }

    @Override
    public void afterPropertiesSet() {
        System.out.println("InitializingBean: 属性设置完成");
    }

    @Override
    public void destroy() {
        System.out.println("DisposableBean: Bean 销毁");
    }

    @PreDestroy
    public void preDestroy() {
        System.out.println("@PreDestroy: Bean 销毁前");
    }
}

@Configuration
public class BeanConfig {
    @Bean(initMethod = "init", destroyMethod = "cleanup")
    public MyService myService() {
        return new MyService();
    }
}

public class MyService {
    public void init() { /* 初始化逻辑 */ }
    public void cleanup() { /* 清理逻辑 */ }
}

// DefaultSingletonBeanRegistry
private final Map<String, Object> singletonObjects = new ConcurrentHashMap<>(256);

public Object getSingleton(String beanName) {
    Object singletonObject = this.singletonObjects.get(beanName);
    if (singletonObject == null && isSingletonCurrentlyInCreation(beanName)) {
        synchronized (this.singletonObjects) {
            singletonObject = this.singletonObjects.get(beanName);
            // 从三级缓存获取
        }
    }
    return singletonObject;
}

// AbstractBeanFactory#doGetBean
if (isPrototype(beanName)) {
    // 每次创建新实例，不缓存
    Object bean = createBean(beanName, mbd, args);
    // 不注册到单例缓存
    registerDisposableBeanIfNecessary(beanName, bean, mbd);
}

// 默认 singleton，无需额外配置
@Service
public class UserService { ... }

// prototype 作用域
@Service
@Scope("prototype")
public class ShoppingCart { ... }

// request 作用域（Web 环境）
@Component
@Scope("request")
public class RequestData { ... }

// session 作用域
@Component
@Scope("session")
public class UserSession { ... }

// 自定义作用域
@Scope("myScope")
@Component
public class CustomScopedBean { ... }

<bean id="userService" class="com.example.UserService" scope="prototype"/>

@Service
public class SingletonService {
    @Lookup
    public PrototypeBean getPrototypeBean() {
        // Spring 会覆盖此方法，返回新的 prototype 实例
        return null;
    }
}

@Service
public class OrderService {
    private int counter = 0;  // 危险：可变状态

    public void createOrder() {
        counter++;  // 非原子操作，多线程下会丢失更新
    }
}

@Service
public class OrderService {
    // 无可变状态，所有方法都是计算逻辑
    public void createOrder(Order order) {
        // 方法内部使用局部变量，天然线程安全
    }
}

@Service
@Scope("prototype")
public class OrderService {
    private int counter = 0;  // 安全：每个线程获取独立实例
}

@Service
public class UserService {
    // 不使用成员变量存储请求状态
    public String getUserName(Long userId) {
        User user = userRepository.findById(userId);
        return user.getName();
    }
}

@Service
public class CounterService {
    private int counter = 0;

    public synchronized void increment() {
        counter++;
    }
}

@Service
public class UserContext {
    private final ThreadLocal<User> currentUser = new ThreadLocal<>();

    public void setCurrentUser(User user) {
        currentUser.set(user);
    }

    public User getCurrentUser() {
        return currentUser.get();
    }
}

@Service
public class CounterService {
    private final AtomicInteger counter = new AtomicInteger(0);

    public void increment() {
        counter.incrementAndGet();
    }
}

@Service
@Scope("prototype")
public class OrderService {
    private Order currentOrder;  // 每个线程独立
}

1. AutowiredAnnotationBeanPostProcessor 扫描 @Autowired 注解
2. 调用 BeanFactory#resolveDependency 解析依赖
3. 按类型查找候选 Bean
4. 如果只有一个匹配 → 直接注入
5. 如果有多个匹配 → 查找 @Qualifier 或字段名匹配
6. 如果没有匹配且 required=true → 抛出 NoSuchBeanDefinitionException

1. CommonAnnotationBeanPostProcessor 扫描 @Resource 注解
2. 解析 name 属性（默认使用字段名/Setter 方法名）
3. 按名称查找 Bean
4. 如果按名称未找到 → 回退到按类型查找
5. 如果指定了 type 属性 → 按类型查找

// @Autowired 默认按类型注入
@Service
public class UserService {

    // 字段注入
    @Autowired
    private UserRepository userRepository;

    // 配合 @Qualifier 按名称注入
    @Autowired
    @Qualifier("userRepositoryImpl")
    private UserRepository userRepository;

    // 构造器注入（推荐）
    public UserService(@Qualifier("userRepositoryImpl") UserRepository userRepository) {
        this.userRepository = userRepository;
    }

    // required = false 允许为空
    @Autowired(required = false)
    private AuditService auditService;
}

// @Resource 默认按名称注入
@Service
public class OrderService {

    // 按名称注入（默认使用字段名 orderRepository）
    @Resource
    private OrderRepository orderRepository;

    // 指定名称
    @Resource(name = "orderRepositoryImpl")
    private OrderRepository orderRepository;

    // 按类型注入
    @Resource(type = OrderRepository.class)
    private OrderRepository orderRepository;
}

// DefaultSingletonBeanRegistry
// 一级缓存：完整初始化的单例 Bean
private final Map<String, Object> singletonObjects = new ConcurrentHashMap<>(256);
// 二级缓存：早期引用（已创建但未初始化的 Bean）
private final Map<String, Object> earlySingletonObjects = new ConcurrentHashMap<>(16);
// 三级缓存：ObjectFactory，用于创建早期引用
private final Map<String, ObjectFactory<?>> singletonFactories = new HashMap<>(16);

1. 创建 A：
   a. 实例化 A（调用构造器，得到 A 的实例）
   b. 将 A 的 ObjectFactory 放入三级缓存
   c. 开始属性填充 → 发现需要 B

2. 创建 B：
   a. 实例化 B
   b. 将 B 的 ObjectFactory 放入三级缓存
   c. 开始属性填充 → 发现需要 A
   d. 从三级缓存查找 A → 找到 ObjectFactory
   e. 调用 ObjectFactory.getObject() → 返回 A 的早期引用
   f. B 属性填充完成
   g. B 初始化完成
   h. 将 B 从三级缓存移至一级缓存

3. 回到 A：
   a. 获取 B 的引用（已完成）
   b. A 属性填充完成
   c. A 初始化完成
   d. 将 A 从三级缓存移至一级缓存

// AbstractAutowireCapableBeanFactory#doCreateBean
// 提前暴露 ObjectFactory 到三级缓存
addSingletonFactory(beanName, () -> getEarlyBeanReference(beanName, mbd, bean));

// DefaultSingletonBeanRegistry#getSingleton
public Object getSingleton(String beanName) {
    // 先从一级缓存获取
    Object singletonObject = this.singletonObjects.get(beanName);
    if (singletonObject == null && isSingletonCurrentlyInCreation(beanName)) {
        // 再从二级缓存获取
        singletonObject = this.earlySingletonObjects.get(beanName);
        if (singletonObject == null) {
            // 最后从三级缓存获取
            ObjectFactory<?> singletonFactory = this.singletonFactories.get(beanName);
            if (singletonFactory != null) {
                singletonObject = singletonFactory.getObject();
                // 升级：从三级移到二级
                this.earlySingletonObjects.put(beanName, singletonObject);
                this.singletonFactories.remove(beanName);
            }
        }
    }
    return singletonObject;
}

// Spring 自动处理循环依赖，无需额外配置
@Service
public class ServiceA {
    private final ServiceB serviceB;

    @Autowired  // Setter 注入，支持循环依赖解决
    public void setServiceB(ServiceB serviceB) {
        this.serviceB = serviceB;
    }
}

@Service
public class ServiceB {
    private final ServiceA serviceA;

    @Autowired
    public void setServiceA(ServiceA serviceA) {
        this.serviceA = serviceA;
    }
}

// 构造器注入导致的循环依赖无法解决
@Service
public class ServiceA {
    private final ServiceB serviceB;

    @Autowired  // 构造器注入 → 无法解决循环依赖
    public ServiceA(ServiceB serviceB) {
        this.serviceB = serviceB;
    }
}

@Service
public class ServiceA {
    @Lazy  // 延迟加载，打破循环
    @Autowired
    private ServiceB serviceB;
}

TransactionInterceptor#invoke
  → TransactionAspectSupport#invokeWithinTransaction
    → 根据传播行为决定事务策略
      ├─ REQUIRED: 如果当前有事务则加入，否则新建
      ├─ REQUIRES_NEW: 挂起当前事务，新建独立事务
      ├─ NESTED: 当前事务内创建保存点
      └─ 其他: 类似逻辑
    → 获取数据库连接，设置 autoCommit=false
    → 执行业务方法
    → 根据结果决定提交或回滚

// TransactionAspectSupport
if (definition.getPropagationBehavior() == TransactionDefinition.PROPAGATION_REQUIRES_NEW) {
    // 1. 挂起当前事务
    SuspendedResourcesHolder suspendedResources = suspend(tx);
    // 2. 创建新事务
    tx = startTransaction(definition);
    // 3. 执行业务
    // 4. 恢复原事务
    resume(tx, suspendedResources);
}

if (definition.getPropagationBehavior() == TransactionDefinition.PROPAGATION_NESTED) {
    // 1. 创建保存点
    Savepoint savepoint = tx.createSavepoint();
    // 2. 执行业务
    // 3. 成功则释放保存点
    tx.releaseSavepoint(savepoint);
    // 4. 失败则回滚到保存点
    tx.rollbackToSavepoint(savepoint);
}

@Service
public class OrderService {

    // 默认 REQUIRED：加入当前事务，无则新建
    @Transactional
    public void createOrder(Order order) { ... }

    // REQUIRES_NEW：总是新建事务
    @Transactional(propagation = Propagation.REQUIRES_NEW)
    public void writeLog(Log log) { ... }

    // NESTED：嵌套事务
    @Transactional(propagation = Propagation.NESTED)
    public void updateStock(Stock stock) { ... }

    // SUPPORTS：有事务则加入，无则非事务
    @Transactional(propagation = Propagation.SUPPORTS)
    public void queryOrder(Long id) { ... }

    // MANDATORY：必须在事务中调用
    @Transactional(propagation = Propagation.MANDATORY)
    public void processPayment(Payment payment) { ... }

    // NEVER：不能在事务中调用
    @Transactional(propagation = Propagation.NEVER)
    public void sendNotification(Notification notification) { ... }

    // NOT_SUPPORTED：非事务执行
    @Transactional(propagation = Propagation.NOT_SUPPORTED)
    public void exportData() { ... }
}

1. TransactionInterceptor#invoke 拦截方法调用
2. TransactionAspectSupport#invokeWithinTransaction
3. 根据传播行为决定是否创建事务
4. DataSourceTransactionManager#doBegin
   a. 获取数据库连接
   b. 设置 connection.setAutoCommit(false)
   c. 设置隔离级别
   d. 将连接绑定到当前线程（ThreadLocal）
5. 执行业务方法

1. 方法正常返回 → TransactionAspectSupport#commit
   → DataSourceTransactionManager#doCommit
     → connection.commit()
     → 释放连接

2. 方法抛出异常 → TransactionAspectSupport#rollback
   → DataSourceTransactionManager#doRollback
     → connection.rollback()
     → 释放连接

@Service
public class OrderService {

    // 最简方式：使用默认配置
    @Transactional
    public void createOrder(Order order) {
        orderRepository.save(order);
        inventoryService.deductStock(order.getProductId());
    }

    // 自定义配置
    @Transactional(
        propagation = Propagation.REQUIRED,
        isolation = Isolation.READ_COMMITTED,
        timeout = 30,
        rollbackFor = Exception.class,
        readOnly = false
    )
    public void updateOrder(Order order) { ... }

    // 类级别注解：所有方法默认开启事务
    @Transactional
    @Service
    public class UserService { ... }

    // 只读事务优化
    @Transactional(readOnly = true)
    public User getUser(Long id) { ... }
}

@Service
public class OrderService {

    @Autowired
    private ApplicationContext context;

    public void methodA() {
        // 通过代理对象调用，事务生效
        context.getBean(OrderService.class).methodB();
    }

    @Transactional
    public void methodB() {
        // 事务生效
    }
}

@Transactional(rollbackFor = Exception.class)
public void createOrder() {
    try {
        // 业务逻辑
    } catch (Exception e) {
        TransactionAspectSupport.currentTransactionStatus().setRollbackOnly();
        throw new RuntimeException(e);
    }
}

1. SpringApplication.run(Application.class)
2. 创建 ApplicationContext
3. 刷新上下文 → invokeBeanFactoryPostProcessors
4. 处理 @EnableAutoConfiguration 注解
5. @EnableAutoConfiguration 的 @Import 导入 AutoConfigurationImportSelector
6. AutoConfigurationImportSelector#selectImports
   a. 读取 META-INF/spring.factories 中的 EnableAutoConfiguration 配置
   b. 得到候选配置类列表
   c. 过滤掉 spring.autoconfigure.exclude 中排除的配置
7. 加载配置类，解析 @Bean 方法
8. 根据 @Conditional 系列注解进行条件判断
9. 符合条件的 @Bean 注册到容器

# META-INF/spring.factories
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
  org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration,\
  org.springframework.boot.autoconfigure.jdbc.JdbcTemplateAutoConfiguration,\
  org.springframework.boot.autoconfigure.data.redis.RedisAutoConfiguration

my-spring-boot-starter/
├── src/main/java/
│   └── com/example/myapp/
│       ├── MyAppAutoConfiguration.java    # 自动配置类
│       └── MyAppProperties.java           # 属性绑定类
├── src/main/resources/
│   ├── META-INF/
│   │   └── spring.factories               # 注册自动配置
│   └── META-INF/additional-spring-configuration-metadata.json
└── pom.xml

// 启动类
@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

# application.yml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/example
    username: root
    password: password
  redis:
    host: localhost
    port: 6379

// 方式一：启动类注解排除
@SpringBootApplication(exclude = DataSourceAutoConfiguration.class)
public class Application { ... }

// 方式二：配置文件排除
spring.autoconfigure.exclude=\
  org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration

// 1. 属性绑定类
@ConfigurationProperties(prefix = "myapp")
public class MyAppProperties {
    private String name = "default";
    private int timeout = 5000;
    // getter/setter
}

// 2. 自动配置类
@Configuration
@EnableConfigurationProperties(MyAppProperties.class)
@ConditionalOnClass(MyService.class)
@ConditionalOnMissingBean(MyService.class)
@EnableConfigurationProperties(MyAppProperties.class)
public class MyAppAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean
    public MyService myService(MyAppProperties properties) {
        return new MyService(properties.getName(), properties.getTimeout());
    }
}

// 3. 注册到 spring.factories
// org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
//   com.example.myapp.MyAppAutoConfiguration

// 启动时打印条件评估报告
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

// 在日志级别中开启
// logging.level.org.springframework.boot.autoconfigure=DEBUG

1. 容器启动时扫描指定包（@ComponentScan）
2. 发现所有标注了注解的类
3. 根据注解类型进行不同处理：
   a. @Component/@Service/@Repository → 注册为 Bean
   b. @Configuration → 解析 @Bean 方法
   c. @RestController → 注册为 Web 控制器
   d. @Transactional → 创建 AOP 代理
4. @ConfigurationProperties → 绑定配置属性到 Bean 字段
5. @Conditional* → 条件判断后决定是否注册

// 配置文件
// application.yml: myapp.name=test, myapp.timeout=5000

@ConfigurationProperties(prefix = "myapp")
public class MyAppConfig {
    private String name;      // 自动绑定 myapp.name
    private int timeout;      // 自动绑定 myapp.timeout
    // getter/setter
}

// 启动类
@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

// 配置类
@Configuration
public class AppConfig {
    @Bean
    public RestTemplate restTemplate() {
        return new RestTemplate();
    }
}

// 配置属性类
@ConfigurationProperties(prefix = "app")
@Component
public class AppProperties {
    private String name;
    private int port;
}

// Service 层
@Service
public class UserService {
    private final UserRepository userRepository;

    public UserService(UserRepository userRepository) {
        this.userRepository = userRepository;
    }
}

// Controller 层
@RestController
@RequestMapping("/api/users")
public class UserController {

    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        return userService.getUser(id);
    }

    @PostMapping
    public User createUser(@RequestBody User user) {
        return userService.createUser(user);
    }
}

// 数据访问层
@Repository
public class UserRepositoryImpl implements UserRepository { ... }

// 事务管理
@Service
public class OrderService {
    @Transactional
    public void createOrder(Order order) { ... }
}

1. 用户发送 HTTP 请求
   ↓
2. Tomcat 接收请求 → 映射到 DispatcherServlet
   ↓
3. DispatcherServlet#doDispatch
   a. 调用 getHandler() 查找 Handler
      → HandlerMapping 根据 URL 查找 HandlerExecutionChain
      → HandlerExecutionChain 包含 Handler + 拦截器列表
   b. 调用 getHandlerAdapter() 获取适配器
      → 支持多种 Handler：Controller 接口、注解式、HttpRequestHandler
   c. 执行拦截器 preHandle()（按顺序）
      → 任一返回 false 则中断请求
   d. HandlerAdapter#handle() 执行 Handler
      → 解析请求参数 → 调用 Controller 方法 → 返回 ModelAndView
   e. 执行拦截器 postHandle()（按逆序）
   f. 渲染视图
      → ViewResolver 解析视图名 → View#render()
   g. 执行拦截器 afterCompletion()（按逆序）
   ↓
4. 返回 HTTP 响应给客户端

// DispatcherServlet#doDispatch
protected void doDispatch(HttpServletRequest request, HttpServletResponse response) {
    // 1. 查找 Handler
    HandlerExecutionChain mappedHandler = getHandler(request);

    // 2. 获取适配器
    HandlerAdapter ha = getHandlerAdapter(mappedHandler.getHandler());

    // 3. 执行拦截器 preHandle
    if (!mappedHandler.applyPreHandle(request, response)) return;

    // 4. 执行 Handler
    ModelAndView mv = ha.handle(request, response, mappedHandler.getHandler());

    // 5. 执行拦截器 postHandle
    mappedHandler.applyPostHandle(request, response, mv);

    // 6. 渲染视图
    processDispatchResult(request, response, mappedHandler, mv, null);
}

@RestController 方法返回值
  → RequestResponseBodyMethodProcessor
    → 使用 HttpMessageConverter 将返回值序列化为 JSON
    → 直接写入 HttpServletResponse
    → 跳过 ViewResolver 和视图渲染

// 启动类
@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

// REST 控制器
@RestController
@RequestMapping("/api/users")
public class UserController {

    @GetMapping("/{id}")
    public User getUser(@PathVariable Long id) {
        return userService.getUser(id);
    }

    @PostMapping
    public ResponseEntity<User> createUser(@Valid @RequestBody UserDTO dto) {
        User user = userService.createUser(dto);
        return ResponseEntity.ok(user);
    }

    @PutMapping("/{id}")
    public User updateUser(@PathVariable Long id, @RequestBody UserDTO dto) {
        return userService.updateUser(id, dto);
    }

    @DeleteMapping("/{id}")
    public ResponseEntity<Void> deleteUser(@PathVariable Long id) {
        userService.deleteUser(id);
        return ResponseEntity.noContent().build();
    }
}

@Component
public class LogInterceptor implements HandlerInterceptor {

    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
        System.out.println("请求路径: " + request.getRequestURI());
        return true;
    }

    @Override
    public void postHandle(HttpServletRequest request, HttpServletResponse response, Object handler, ModelAndView modelAndView) {
        System.out.println("请求处理完成");
    }

    @Override
    public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) {
        System.out.println("请求结束");
    }
}

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Autowired
    private LogInterceptor logInterceptor;

    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(logInterceptor)
                .addPathPatterns("/**")
                .excludePathPatterns("/error");
    }
}

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(BusinessException.class)
    public ResponseEntity<?> handleBusinessException(BusinessException e) {
        return ResponseEntity.status(HttpStatus.BAD_REQUEST)
                .body(Map.of("error", e.getMessage()));
    }

    @ExceptionHandler(Exception.class)
    public ResponseEntity<?> handleException(Exception e) {
        return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR)
                .body(Map.of("error", "Internal Server Error"));
    }
}

1. 客户端建立 TCP 连接
   ↓
2. Acceptor 线程接收连接
   a. ServerSocketChannel#accept() 接收新连接
   b. 将连接注册到 Poller
   ↓
3. Poller 线程轮询连接事件
   a. Selector#select() 等待事件
   b. 可读事件 → 读取请求数据
   c. 可写事件 → 写入响应数据
   d. 读取完成 → 提交到 Worker 线程
   ↓
4. Worker 线程处理请求
   a. 解析 HTTP 请求行和请求头
   b. 通过 Adapter 转换为 Servlet Request
   c. 交给 Engine → Host → Context → Wrapper
   d. 执行 Servlet（Spring MVC 的 DispatcherServlet）
   e. 获取 Servlet Response
   ↓
5. 响应写回
   a. Adapter 转换为 HTTP 响应
   b. Poller 线程将响应写回客户端
   ↓
6. 关闭或保持连接

<!-- server.xml -->
<Connector port="8080"
           protocol="HTTP/1.1"
           maxThreads="200"
           minSpareThreads="25"
           maxSpareThreads="75"
           acceptCount="100"
           connectionTimeout="20000"
           redirectPort="8443" />

# application.yml
server:
  port: 8080
  tomcat:
    threads:
      max: 200
      min-spare: 25
    accept-count: 100
    connection-timeout: 20000
    max-connections: 8192
    min-connections: 10
    basedir: /tmp/tomcat

@Configuration
public class TomcatConfig {

    @Bean
    public WebServerFactoryCustomizer<TomcatServletWebServerFactory> tomcatCustomizer() {
        return factory -> {
            factory.addConnectorCustomizers(connector -> {
                connector.setMaxThreads(200);
                connector.setMinSpareThreads(25);
                connector.setAcceptCount(100);
                connector.setConnectionTimeout(20000);
            });
        };
    }
}

<!-- server.xml Connector 配置 -->
<Connector port="8080" protocol="org.apache.coyote.http11.Http11NioProtocol"
           maxThreads="200"
           minSpareThreads="25"
           maxSpareThreads="75"
           acceptCount="100"
           connectionTimeout="20000"
           disableUploadTimeout="true" />

1. SQL 模板：SELECT * FROM user WHERE id = #{id}
2. MyBatis 解析为：SELECT * FROM user WHERE id = ?
3. 使用 PreparedStatement
4. ps.setInt(1, id) 设置参数
5. 数据库执行预编译 SQL

1. SQL 模板：SELECT * FROM ${tableName} WHERE id = #{id}
2. MyBatis 解析为：SELECT * FROM user WHERE id = ?
   （${tableName} 直接替换为 "user"，#{id} 替换为 ?）
3. 只有 #{id} 使用 PreparedStatement 参数绑定
4. ${tableName} 的值直接嵌入 SQL

// 危险：如果 tableName = "user; DROP TABLE user"
// 使用 ${} 会导致 SQL 注入
// 必须使用白名单校验
String[] allowedTables = {"user", "order", "product"};
if (!Arrays.asList(allowedTables).contains(tableName)) {
    throw new IllegalArgumentException("Invalid table name");
}

// Mapper 接口
@Mapper
public interface UserMapper {

    // #{id} → 预编译，安全
    @Select("SELECT * FROM user WHERE id = #{id}")
    User selectById(@Param("id") Long id);

    // #{name} → 预编译，安全
    List<User> selectByName(@Param("name") String name);

    // ${tableName} → 动态表名，需要白名单
    @Select("SELECT * FROM ${tableName} WHERE id = #{id}")
    User selectFromTable(@Param("tableName") String tableName, @Param("id") Long id);

    // ${orderBy} → 动态排序，需要白名单
    @Select("SELECT * FROM user ORDER BY ${orderBy}")
    List<User> selectAllOrderBy(@Param("orderBy") String orderBy);
}

<!-- #{推荐使用} -->
<select id="selectById" resultType="User">
    SELECT * FROM user WHERE id = #{id}
</select>

<!-- ${仅用于动态表名/列名} -->
<select id="selectFromTable" resultType="User">
    SELECT * FROM ${tableName} WHERE id = #{id}
</select>

public List<User> selectFromTable(String tableName) {
    // 白名单校验
    Set<String> allowedTables = Set.of("user", "order", "product");
    if (!allowedTables.contains(tableName)) {
        throw new IllegalArgumentException("Invalid table: " + tableName);
    }
    return userMapper.selectFromTable(tableName, id);
}

<!-- 动态 IN 条件：使用 foreach -->
<select id="selectByIds" resultType="User">
    SELECT * FROM user WHERE id IN
    <foreach collection="ids" item="id" open="(" separator="," close=")">
        #{id}
    </foreach>
</select>

SqlSessionFactory
  └── SqlSession（一级缓存：PerpetualCache，默认开启）
        └── Executor
              ├── BaseExecutor（基本执行器）
              ├── CachingExecutor（二级缓存装饰器，可选）
              └── BatchExecutor（批处理执行器）

1. 调用 Mapper 方法 → SqlSession.selectList()
   ↓
2. Executor 查询二级缓存
   a. 如果命中 → 直接返回结果
   b. 如果未命中 → 查询一级缓存
   ↓
3. 一级缓存查询
   a. 如果命中 → 直接返回结果，同时写入二级缓存
   b. 如果未命中 → 查询数据库
   ↓
4. 查询数据库，得到结果集
   ↓
5. 将结果写入一级缓存和二级缓存
   ↓
6. 返回结果

1. 执行 INSERT/UPDATE/DELETE
2. 清除一级缓存
3. 清除二级缓存（该 namespace 下的）
4. 执行 SQL 写入数据库
5. 提交事务

// BaseExecutor#query
public <E> List<E> query(MappedStatement ms, Object parameter, RowBounds rowBounds, ResultHandler resultHandler) {
    // 1. 查询一级缓存
    CacheKey key = createCacheKey(ms, parameter, rowBounds);
    List<E> list = localCache.getObject(key);
    if (list != null) {
        return list;  // 缓存命中
    }
    // 2. 查询数据库
    list = doQuery(ms, parameter, rowBounds, resultHandler);
    // 3. 写入一级缓存
    localCache.putObject(key, list);
    return list;
}

<!-- 在 Mapper XML 中开启二级缓存 -->
<mapper namespace="com.example.UserMapper">
    <cache type="org.mybatis.caches.redis.RedisCache"
           eviction="LRU"
           flushInterval="60000"
           size="512"
           readOnly="false"/>
</mapper>

// 一级缓存：同一 SqlSession 内有效
SqlSession sqlSession = sqlSessionFactory.openSession();
UserMapper mapper = sqlSession.getMapper(UserMapper.class);

// 第一次查询：访问数据库
User user1 = mapper.selectById(1L);
// 第二次查询：命中一级缓存，不访问数据库
User user2 = mapper.selectById(1L);
// user1 == user2（同一对象）

sqlSession.close(); // 关闭后一级缓存清除

<!-- 方式一：XML 配置 -->
<mapper namespace="com.example.UserMapper">
    <cache/>  <!-- 开启二级缓存 -->

    <select id="selectById" resultType="User" useCache="true">
        SELECT * FROM user WHERE id = #{id}
    </select>
</mapper>

// 方式二：注解配置
@Mapper
public interface UserMapper {
    @Select("SELECT * FROM user WHERE id = #{id}")
    @CacheNamespace
    User selectById(Long id);
}

// 二级缓存：跨 SqlSession 有效
SqlSession session1 = sqlSessionFactory.openSession();
UserMapper mapper1 = session1.getMapper(UserMapper.class);
User user1 = mapper1.selectById(1L);
session1.close(); // 关闭 SqlSession，结果写入二级缓存

SqlSession session2 = sqlSessionFactory.openSession();
UserMapper mapper2 = session2.getMapper(UserMapper.class);
User user2 = mapper2.selectById(1L); // 命中二级缓存
session2.close();

<!-- 手动刷新缓存 -->
<insert id="insertUser" flushCache="true">
    INSERT INTO user (name) VALUES (#{name})
</insert>

1. MyBatis 启动时加载所有 Interceptor 实现
2. 将 Interceptor 添加到 interceptorChain
3. 创建核心对象（Executor 等）时
   a. 调用 InterceptorChain#pluginAll(target)
   b. 遍历所有 Interceptor
   c. 调用 interceptor.plugin(target)
   d. 通过 Plugin.wrap() 创建代理对象
4. 返回代理对象替代原始对象

// Plugin#wrap
public static Object wrap(Object target, Interceptor interceptor) {
    Map<Class<?>, Set<Integer>> signatureMap = getSignatureMap(interceptor);
    Class<?> type = target.getClass();
    Class<?>[] interfaces = getAllInterfaces(type, signatureMap);
    if (interfaces.length > 0) {
        // 创建 JDK 动态代理
        return Proxy.newProxyInstance(
            type.getClassLoader(),
            interfaces,
            new Plugin(target, interceptor, signatureMap)
        );
    }
    return target;
}

1. 调用代理对象的方法
2. Plugin#invoke 被触发
   a. 检查当前方法是否在拦截列表中
   b. 如果是 → 调用 interceptor.intercept(invocation)
   c. 如果不是 → 直接调用原始方法
3. Interceptor#intercept 执行自定义逻辑
   a. 执行前置逻辑
   b. 调用 invocation.proceed() 执行目标方法
   c. 执行后置逻辑

@Intercepts({
    @Signature(
        type = StatementHandler.class,
        method = "prepare",
        args = {Connection.class, Integer.class}
    )
})
public class PageInterceptor implements Interceptor {

    @Override
    public Object intercept(Invocation invocation) throws Throwable {
        // 1. 获取 StatementHandler
        StatementHandler statementHandler = (StatementHandler) invocation.getTarget();

        // 2. 获取原始 SQL
        BoundSql boundSql = statementHandler.getBoundSql();
        String originalSql = boundSql.getSql();

        // 3. 改造 SQL，添加分页
        String pageSql = originalSql + " LIMIT #{offset}, #{limit}";

        // 4. 创建新的 BoundSql
        BoundSql newBoundSql = new BoundSql(
            boundSql.getConfiguration(),
            pageSql,
            boundSql.getParameterMappings(),
            boundSql.getParameterObject()
        );

        // 5. 替换 BoundSql
        MetaObject metaObject = SystemMetaObject.forObject(statementHandler);
        metaObject.setValue("delegate.boundSql", newBoundSql);

        // 6. 执行原始方法
        return invocation.proceed();
    }

    @Override
    public Object plugin(Object target) {
        return Plugin.wrap(target, this);
    }

    @Override
    public void setProperties(Properties properties) {
    }
}

// Java 配置
@Configuration
public class MyBatisConfig {
    @Bean
    public MybatisPlusInterceptor mybatisPlusInterceptor() {
        MybatisPlusInterceptor interceptor = new MybatisPlusInterceptor();
        interceptor.addInnerInterceptor(new PaginationInnerInterceptor());
        return interceptor;
    }
}

<!-- XML 配置 -->
<plugins>
    <plugin interceptor="com.example.PageInterceptor">
        <property name="dialect" value="mysql"/>
    </plugin>
</plugins>

CacheKey = MappedStatement.getId()
           + 操作类型（QUERY/UPDATE）
           + 参数值
           + RowBounds（offset, limit）
           + 动态 SQL 的 SQL 字符串

1. SqlSession.selectList() 调用
   ↓
2. Executor#query(ms, parameter, rowBounds)
   ↓
3. 创建 CacheKey（由 MappedStatement、参数、RowBounds 等组成）
   ↓
4. 查询本地缓存（localCache）
   a. 命中 → 直接返回
   b. 未命中 → 查询数据库
   ↓
5. 数据库查询 → 得到结果
   ↓
6. 写入本地缓存
   ↓
7. 返回结果

以下操作会清除一级缓存：
1. SqlSession.close() — 关闭 SqlSession
2. SqlSession.clearCache() — 手动清除
3. 执行 INSERT/UPDATE/DELETE 操作
4. 调用 commit() 或 rollback()

// LocalCache 内部结构
public class LocalCache {
    private final Map<Object, Object> cache = new HashMap<>(16);

    public Object getObject(Object key) {
        return cache.get(key);  // HashMap 查询
    }

    public void putObject(Object key, Object value) {
        cache.put(key, value);  // HashMap 写入
    }

    public void clear() {
        cache.clear();  // 清除缓存
    }
}

// BaseExecutor#query
public <E> List<E> query(...) {
    CacheKey key = createCacheKey(ms, parameter, rowBounds);
    // 查询一级缓存
    List<E> list = localCache.getObject(key);
    if (list != null) {
        return list;  // 缓存命中
    }
    // 缓存未命中，查询数据库
    list = doQuery(ms, parameter, rowBounds, resultHandler);
    localCache.putObject(key, list);  // 写入缓存
    return list;
}

// 一级缓存默认开启，无需配置
SqlSession sqlSession = sqlSessionFactory.openSession();
UserMapper mapper = sqlSession.getMapper(UserMapper.class);

// 同一 SqlSession 内的相同查询
User user1 = mapper.selectById(1L);  // 第一次：访问数据库
User user2 = mapper.selectById(1L);  // 第二次：命中缓存
// user1 == user2（相同对象引用）

// 不同 SqlSession 之间不共享一级缓存
SqlSession sqlSession2 = sqlSessionFactory.openSession();
UserMapper mapper2 = sqlSession2.getMapper(UserMapper.class);
User user3 = mapper2.selectById(1L);  // 访问数据库（非缓存命中）

sqlSession.close();
sqlSession2.close();

@Service
public class UserService {

    @Autowired
    private UserMapper userMapper;

    @Transactional  // 开启事务
    public void processUser() {
        // 同一事务内，Spring 复用同一个 SqlSession
        // 因此一级缓存在事务内有效
        User user1 = userMapper.selectById(1L);
        User user2 = userMapper.selectById(1L);
        // 两次查询命中一级缓存
    }
}

// 手动清除一级缓存
sqlSession.clearCache();

// 注意：Spring 管理的 SqlSession 不要手动清除
// Spring 事务结束后会自动关闭 SqlSession

┌─────────────────────────────────────┐
│            Spring AI App             │
│  (ChatClient, VectorStore, Agent)   │
├─────────────────────────────────────┤
│          Spring AI Core API          │
│  (ChatModel, Prompt, Embedding)     │
├─────────────────────────────────────┤
│        AI Provider Adapters         │
│  (OpenAI, Ollama, Azure, ...)       │
├─────────────────────────────────────┤
│          Vector Store Adapters      │
│  (Milvus, PgVector, Redis, ...)     │
└─────────────────────────────────────┘

1. 创建 ChatClient
2. 构建 Prompt（系统消息、用户消息、上下文）
3. 调用 chatClient.call(prompt)
4. Spring AI 根据配置选择 AI 提供商
5. 适配层转换为提供商 API
6. 发送 HTTP 请求到 AI 服务
7. 解析响应，返回 AI 回复

1. 文档加载 → DocumentReader
2. 文本切分 → DocumentSplitter
3. 向量化 → EmbeddingModel
4. 存储到向量数据库 → VectorStore
5. 用户提问 → 向量化
6. 相似文档检索 → VectorStore.similaritySearch()
7. 构建 Prompt（问题 + 检索结果）
8. 调用 AI 生成回答

<!-- pom.xml -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
</dependency>

# application.yml
spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      chat:
        model: gpt-4

@Service
public class AIService {

    private final ChatClient chatClient;

    public AIService(ChatClient.Builder builder) {
        this.chatClient = builder.build();
    }

    public String chat(String question) {
        return chatClient.prompt()
                .user(question)
                .call()
                .content();
    }

    public String chatWithSystem(String question) {
        return chatClient.prompt()
                .system("你是一个专业的Java技术顾问")
                .user(question)
                .call()
                .content();
    }
}

public Flux<String> streamChat(String question) {
    return chatClient.prompt()
            .user(question)
            .stream()
            .content();
}

@Service
public class RAGService {

    private final VectorStore vectorStore;
    private final ChatClient chatClient;

    public RAGService(VectorStore vectorStore, ChatClient.Builder builder) {
        this.vectorStore = vectorStore;
        this.chatClient = builder.build();
    }

    public String query(String question) {
        // 1. 检索相关文档
        List<Document> docs = vectorStore.similaritySearch(
                Search.query(question).withTopK(3));

        // 2. 构建上下文
        String context = docs.stream()
                .map(Document::getContent)
                .collect(Collectors.joining("\n"));

        // 3. 生成回答
        return chatClient.prompt()
                .system("基于以下上下文回答问题，如果上下文没有相关信息，请说"我不知道"")
                .user("上下文：" + context + "\n问题：" + question)
                .call()
                .content();
    }
}

用户请求
  ↓
Agent 接收请求
  ↓
┌─────────────────────────────┐
│  1. Memory 查询历史上下文     │
│  2. RAG 检索相关知识          │
│  3. 判断是否需要调用工具       │
│  4. 构建完整 Prompt           │
│  5. 调用 AI 模型生成回答      │
│  6. 解析工具调用请求（可选）   │
│  7. 执行工具调用（可选）       │
│  8. 将结果加入上下文           │
│  9. 返回最终回答              │
└─────────────────────────────┘
  ↓
返回给用户

步骤 1：添加 Maven 依赖
  ↓
步骤 2：配置 AI 模型和向量数据库
  ↓
步骤 3：准备领域知识文档
  ↓
步骤 4：实现文档向量化（索引构建）
  ↓
步骤 5：实现 Agent 服务（核心逻辑）
  ↓
步骤 6：提供 REST API 接口
  ↓
步骤 7：增强（Tool Calling、Memory 等）

<dependencies>
    <!-- Spring AI 核心 -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-openai-spring-boot-starter</artifactId>
    </dependency>
    <!-- 向量数据库（以 Milvus 为例） -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-milvus-store-spring-boot-starter</artifactId>
    </dependency>
</dependencies>

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      chat:
        model: gpt-4
    vectorstore:
      milvus:
        client:
          host: localhost
          port: 19530
        collection-name: agent_knowledge
        embedding-dimension: 1536

@Service
public class DocumentIngestionService {

    private final VectorStore vectorStore;
    private final DocumentReader documentReader;

    public DocumentIngestionService(VectorStore vectorStore,
                                     @Value("classpath:/docs") DocumentReader documentReader) {
        this.vectorStore = vectorStore;
        this.documentReader = documentReader;
    }

    public void ingestDocuments() {
        // 1. 读取文档
        List<Document> documents = documentReader.get();

        // 2. 文档切分（默认按 1000 字符切分）
        // Spring AI 自动处理切分和向量化

        // 3. 存储到向量数据库（自动向量化）
        vectorStore.add(documents);

        System.out.println("已导入 " + documents.size() + " 个文档片段");
    }
}

@Service
public class KnowledgeAgent {

    private final ChatClient chatClient;
    private final VectorStore vectorStore;

    public KnowledgeAgent(ChatClient.Builder builder, VectorStore vectorStore) {
        this.chatClient = builder.build();
        this.vectorStore = vectorStore;
    }

    /**
     * Agent 核心方法：接收问题，返回回答
     */
    public String ask(String question) {
        // 1. 从向量库检索相关知识
        List<Document> relevantDocs = vectorStore.similaritySearch(
                Search.query(question)
                        .withTopK(3)
                        .withSimilarityThreshold(0.7));

        // 2. 构建上下文
        String context = relevantDocs.stream()
                .map(doc -> "参考资料：" + doc.getContent())
                .collect(Collectors.joining("\n\n"));

        // 3. 构建 Prompt 并调用 AI
        String systemPrompt = """
                你是一个专业的知识问答助手。
                请基于以下参考资料回答用户的问题。
                如果参考资料中没有相关信息，请回答"抱歉，我没有找到相关信息"。
                """;

        return chatClient.prompt()
                .system(systemPrompt)
                .user("参考资料：\n" + context + "\n\n问题：" + question)
                .call()
                .content();
    }
}

@RestController
@RequestMapping("/api/agent")
public class AgentController {

    private final KnowledgeAgent knowledgeAgent;

    public AgentController(KnowledgeAgent knowledgeAgent) {
        this.knowledgeAgent = knowledgeAgent;
    }

    @PostMapping("/ask")
    public Map<String, String> ask(@RequestBody Map<String, String> request) {
        String question = request.get("question");
        String answer = knowledgeAgent.ask(question);
        return Map.of("question", question, "answer", answer);
    }
}

@Component
public class WeatherTool {

    @Tool(description = "获取指定城市的天气信息")
    public String getWeather(@ToolParam(description = "城市名称") String city) {
        // 调用天气 API
        return city + "今天晴，温度25°C";
    }
}

// Agent 使用 Tool
@Service
public class ToolAgent {

    private final ChatClient chatClient;
    private final WeatherTool weatherTool;

    public ToolAgent(ChatClient.Builder builder, WeatherTool weatherTool) {
        this.chatClient = builder
                .tools(weatherTool)  // 注册工具
                .build();
    }

    public String ask(String question) {
        return chatClient.prompt()
                .user(question)
                .call()
                .content();
        // AI 会自动判断是否需要调用天气工具
    }
}