package com.example.springbootdemo.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @RestController 是一个组合注解，相当于 @Controller + @ResponseBody
 * @Controller: 声明这是一个处理 HTTP 请求的控制器 Bean
 * @ResponseBody: 告诉 Spring MVC，这个类中所有方法的返回值都应直接写入 HTTP 响应体中
 * (对于前后端分离项目，通常就是返回 JSON 或纯文本)
 */
@RestController
public class HelloController {

    /**
     * @GetMapping("/hello"): 将此方法映射到处理 GET 方式的 "/hello" 请求
     */
    @GetMapping("/hello")
    public String sayHello() {
        return "Hello, Spring Boot!";
    }
}

// SpringBootDemoApplication.java
package com.example.springbootdemo;

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

@SpringBootApplication
public class SpringBootDemoApplication {
    public static void main(String[] args) {
        // 启动 Spring Boot 应用
        SpringApplication.run(SpringBootDemoApplication.class, args);
    }
}

// 只有当应用是 Servlet Web 应用，并且类路径下存在 Servlet, DispatcherServlet, WebMvcConfigurer 时，
// 并且容器中还没有用户自定义的 WebMvcConfigurationSupport Bean，此配置才会生效。
@ConditionalOnWebApplication(type = Type.SERVLET)
@ConditionalOnClass({ Servlet.class, DispatcherServlet.class, WebMvcConfigurer.class })
@ConditionalOnMissingBean(WebMvcConfigurationSupport.class)
public class WebMvcAutoConfiguration {
    // ...
}

public class DatabaseConnector {
    public void connect() {
        String url = "jdbc:mysql://localhost:3306/dev_db";
        String username = "root";
        String password = "dev_password";
        // ... 连接逻辑
    }
}

package com.example.springbootdemo.config;

import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;

@Component
public class AppInfo {

    // 使用 ${...} 占位符来引用配置文件中的 key
    @Value("${app.name}")
    private String name;

    @Value("${app.owner}")
    private String owner;

    // 使用冒号 ":" 来提供一个默认值
    // 如果配置文件中找不到 app.port，则会使用 8080
    @Value("${app.port:8080}")
    private Integer port;

    @Override
    public String toString() {
        return "AppInfo{" +
                "name='" + name + '\'' +
                ", owner='" + owner + '\'' +
                ", port=" + port +
                '}';
    }
}

@SpringBootTest
class ConfigTest {
    @Autowired
    private AppInfo appInfo;

    @Test
    void testValueAnnotation() {
        System.out.println(appInfo);
    }
}

package com.example.springbootdemo.config;

import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;
import java.util.List;
import java.util.Map;

@Data // Lombok 注解，自动生成 Getter/Setter
@Component
// 关键：将此类与配置文件中 "datasource.mysql" 为前缀的属性进行绑定
@ConfigurationProperties(prefix = "datasource.mysql")
public class MySQLProperties {
    
    private String url;
    private String username;
    private String password;
    private List<String> connectionProperties; // 对应 YAML 中的列表
    private PoolOptions poolOptions;           // 对应 YAML 中的嵌套对象

    @Data
    public static class PoolOptions { // 内部静态类用于映射嵌套对象
        private int maxActive;
        private int minIdle;
    }
}

package com.example.springbootdemo;
import com.example.springbootdemo.config.MySQLProperties;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;

@SpringBootTest
class SpringBootDemoApplicationTests {
    

    @Autowired
    private MySQLProperties mySQLProperties;

    @Test
    void testConfigProperties() {
        System.out.println(mySQLProperties);
    }

}

package com.example.springbootdemo.config;
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component; // 1. 引入 Component 注解

@Data
@Component // 2. 将此类声明为一个通用的 Spring 组件
@ConfigurationProperties(prefix = "datasource.mysql")
public class MySQLProperties {
    // ... 属性不变
}

package com.example.springbootdemo.config;
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;

@Data
@ConfigurationProperties(prefix = "datasource.mysql")
// 移除了 @Component 注解
public class MySQLProperties {
    // ... 属性不变
}

package com.example.springbootdemo.config;

import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Configuration;

// 1. @Configuration 声明这是一个配置管理类
@Configuration
// 2. @EnableConfigurationProperties 明确告诉 Spring Boot
//    去激活并注册 MySQLProperties.class 这个属性类
@EnableConfigurationProperties(MySQLProperties.class)
public class AppConfig {
    // 这个类可以是空的，它的主要作用就是通过注解来集中管理配置。
    // 当然，我们后续还可以在这里定义 @Bean 等。
}

package com.example.springbootdemo.config;

import lombok.Data;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.stereotype.Component;

@Data
@Component
public class AppInfo {
    @Value("${app.owner}")
    private String owner;

    @Value("${app.env}")
    private String env;
}

// SpringBootDemoApplicationTests.java

import com.example.springbootdemo.config.AppInfo;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;

@SpringBootTest
class SpringBootDemoApplicationTests {

    @Autowired
    private AppInfo appInfo;

    @Test
    void testProfile() {
        // 打印注入的配置，验证当前激活的是哪个环境
        System.out.println(appInfo);
    }
}

@Service
public class UserServiceImpl implements UserService {
    
    // 模拟一个简单的 Map 作为缓存
    private final Map<Long, UserVO> userCache = new ConcurrentHashMap<>();

    @Override
    public UserVO findUserById(Long id) {
        // 1. 先从缓存查找
        if (userCache.containsKey(id)) {
            log.info("命中缓存: {}", id);
            return userCache.get(id);
        }

        // 2. 缓存未命中，查询数据库 (核心业务逻辑)
        User user = userMapper.selectById(id);
        if (user == null) {
            return null;
        }
        UserVO userVO = convertToVO(user);

        // 3. 将结果放入缓存
        userCache.put(id, userVO);
        log.info("查询数据库并写入缓存: {}", id);
        
        return userVO;
    }
}

package com.example.democommon.annotation;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target(ElementType.METHOD) // 注解作用于方法上
@Retention(RetentionPolicy.RUNTIME) // 运行时保留，AOP才能读取到
public @interface SimpleCache {
    /**
     * 缓存的键名前缀
     */
    String key();

    /**
     * 缓存过期时间, 单位秒, 默认1小时
     */
    long timeoutSeconds() default 3600;
}

package com.example.demoframework.aspect;

import cn.hutool.cache.Cache;
import cn.hutool.cache.CacheUtil;
import cn.hutool.core.util.StrUtil;
import com.example.democommon.annotation.SimpleCache;
import lombok.extern.slf4j.Slf4j;
import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.annotation.Pointcut;
import org.aspectj.lang.reflect.MethodSignature;
import org.springframework.stereotype.Component;

import java.lang.reflect.Method;

@Aspect //  1.声明这个类是一个切面。
@Component
@Slf4j
public class SimpleCacheAspect {
    // 使用 Hutool 创建一个定时缓存，默认过期时间为1小时
    // `CacheUtil.newTimedCache(...)`: 我们创建了一个 `TimedCache` 实例来存储我们的缓存数据。
    private final Cache<String, Object> cache = CacheUtil.newTimedCache(3600 * 1000);

    /**
     * 定义一个切点，匹配所有被 @SimpleCache 注解标记的方法
     */
    @Pointcut("@annotation(com.example.democommon.annotation.SimpleCache)")
    public void cachePointcut() {
    }

    // `@Around`: 我们使用环绕通知，因为它能完全控制方法的执行流程：
    // 先查缓存，如果缓存没有，再执行原方法 `joinPoint.proceed()`，最后将结果放入缓存。
    @Around("cachePointcut()")
    public Object doAround(ProceedingJoinPoint joinPoint) throws Throwable {
        // 1. 获取注解和方法信息 在我们的这次调试中出发是的就是
        // UserVO com.example.demosystem.service.impl.UserServiceImpl.findUserById(Long)
        MethodSignature signature = (MethodSignature) joinPoint.getSignature();
        // 方法:
        // public com.example.demosystem.vo.UserVO com.example.demosystem.service.impl.UserServiceImpl.findUserById(java.lang.Long)
        Method method = signature.getMethod();
        // 通过反射获取我们方法上的注解
        SimpleCache cacheAnnotation = method.getAnnotation(SimpleCache.class);
        // 2. 根据方法和参数生成动态的缓存 Key
        String keyPrefix = cacheAnnotation.key();
        String argsString = StrUtil.join(",", joinPoint.getArgs());
        // 获取我们请求中传入的UserID的值与方法参数名进行拼接，例如 user:1
        String key = keyPrefix + ":" + argsString;

        // 3. 检查缓存 (Hutool 的 get 方法会自动处理过期)
        // `cache.get(key)`: Hutool 缓存的核心方法。如果键存在且未过期，它会返回值；
        // 否则返回 `null`。这一个方法就代替了 `containsKey` 和 `get` 两步操作。
        Object cachedResult = cache.get(key);
        if (cachedResult != null) {
            log.info("命中缓存: {}", key);
            return cachedResult;
        }
        // 4. 缓存未命中，执行目标方法
        log.info("查询数据库并写入缓存: {}", key);
        Object actualResult = joinPoint.proceed();

        // 5. 将结果放入缓存，并设置注解中指定的过期时间
        if (actualResult != null) {
            long timeoutMillis = cacheAnnotation.timeoutSeconds() * 1000;
            // `cache.put(key, actualResult, timeoutMillis)`:
            // 将数据存入缓存，并动态地为其指定一个从注解中读取的、毫秒级的过期时间。
            cache.put(key, actualResult, timeoutMillis);
        }
        return actualResult;
    }
}

package com.example.demosystem.service.impl;

import com.example.democommon.annotation.SimpleCache;
import com.example.demosystem.entity.User;
import com.example.demosystem.mapper.UserMapper;
import com.example.demosystem.service.UserService;
import com.example.demosystem.vo.UserVO;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;

@Service
@RequiredArgsConstructor
@Slf4j
public class UserServiceImpl implements UserService {

    private final UserMapper userMapper;

    @Override
    // 为方法加上注解，设置 key 前缀和 10 秒的过期时间
    @SimpleCache(key = "user", timeoutSeconds = 10)
    public UserVO findUserById(Long id) {
    }
    
    // ... 其他方法保持不变 ...
}

package com.example.demoframework.aspect;

import lombok.extern.slf4j.Slf4j;
import org.aspectj.lang.ProceedingJoinPoint;
import org.aspectj.lang.annotation.Around;
import org.aspectj.lang.annotation.Aspect;
import org.aspectj.lang.annotation.Pointcut;
import org.springframework.stereotype.Component;

@Aspect
@Component
@Slf4j
public class PerformanceAspect {

//    * 这是本节的核心。我们使用 `execution` 指示符，精确地描述了一个“范围”。
//            * `public *`: 匹配所有 `public` 方法，返回任意类型。
//            * `com.example.demosystem.service..`: 匹配 `service` 包 及其所有子包。这里的 `..` 至关重要。
//            * `*.*(..)`: 匹配所有类的所有方法，接受任意参数。
    @Pointcut("execution(public * com.example.demosystem.service..*.*(..))")
    public void serviceMethods() {}

    @Around("serviceMethods()")
    public Object profile(ProceedingJoinPoint pjp) throws Throwable {
        long start = System.currentTimeMillis();
        // 获取被拦截的目标对象的类名。
        String className = pjp.getTarget().getClass().getSimpleName();
        // 获取被拦截的方法名。
        String methodName = pjp.getSignature().getName();

        // 执行原始方法
        Object result = pjp.proceed();
        long end = System.currentTimeMillis();
        log.info("PERFMON: {}.{} 执行耗时: {} ms", className, methodName, (end - start));
        return result;
    }
}

package com.example.demosystem.entity;

import com.baomidou.mybatisplus.annotation.IdType;
import com.baomidou.mybatisplus.annotation.TableId;
import com.baomidou.mybatisplus.annotation.TableName;
import lombok.Data;
import java.math.BigDecimal;

@Data
@TableName("t_account")
public class Account {
    @TableId(value = "id", type = IdType.AUTO)
    private Integer id;
    private Integer userId;
    private BigDecimal balance;
}

package com.example.demosystem.mapper;

import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.example.demosystem.entity.Account;
import org.apache.ibatis.annotations.Param;
import org.apache.ibatis.annotations.Update;

import java.math.BigDecimal;

public interface AccountMapper extends BaseMapper<Account> {
    @Update("update t_account set balance = balance - #{amount} where user_id = #{userId}")
    void decrease(@Param("userId") Integer userId, @Param("amount") BigDecimal amount);

    @Update("update t_account set balance = balance + #{amount} where user_id = #{userId}")
    void increase(@Param("userId") Integer userId, @Param("amount") BigDecimal amount);
}

package com.example.demosystem.service;

import com.example.demosystem.mapper.AccountMapper;
import lombok.RequiredArgsConstructor;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;

import java.math.BigDecimal;

@Service
@RequiredArgsConstructor
public class AccountService {

    private final AccountMapper accountMapper;

    @Transactional // 关键注解：声明此方法内的所有数据库操作都受事务管理
    public void transfer(Integer fromUserId, Integer toUserId, BigDecimal amount) {
        // 1. 扣减转出方余额
        accountMapper.decrease(fromUserId, amount);

        // 2. 模拟一个异常
        if (true) {
            throw new RuntimeException("模拟转账过程中发生意外...");
        }

        // 3. 增加转入方余额
        accountMapper.increase(toUserId, amount);
    }
}

package com.example.demosystem.controller;

import com.example.democommon.common.Result;
import com.example.demosystem.service.AccountService;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.tags.Tag;
import lombok.RequiredArgsConstructor;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

import java.math.BigDecimal;

@Tag(name = "账户管理", description = "演示事务")
@RestController
@RequestMapping("/account")
@RequiredArgsConstructor
public class AccountController {

    private final AccountService accountService;

    @Operation(summary = "模拟转账")
    @PostMapping("/transfer")
    public ResponseEntity<Result<Void>> transfer(@RequestParam Integer from, @RequestParam Integer to, @RequestParam BigDecimal amount) {
        accountService.transfer(from, to, amount);
        return ResponseEntity.ok(Result.success());
    }
}

@Service
public class MyService {
    public void methodA() {
        this.methodB(); // this 调用，绕过了代理，事务失效！
    }

    @Transactional
    public void methodB() {
        // ...
    }
}

@Transactional
public void methodC() {
    try {
        // ... 数据库操作 ...
        throw new RuntimeException();
    } catch (Exception e) {
        // 异常被“吞”了，事务无法回滚
        log.error("发生异常", e);
    }
}

// ... imports ...
import org.springframework.cache.annotation.EnableCaching;

@SpringBootApplication(scanBasePackages = "com.example")
@MapperScan("com.example.*.mapper")
@EnableCaching // 启用 Spring 缓存功能
public class SpringBootDemoApplication {
    // ... main method ...
}

package com.example.demoframework.config;

import com.fasterxml.jackson.annotation.JsonAutoDetect;
import com.fasterxml.jackson.annotation.PropertyAccessor;
import com.fasterxml.jackson.databind.ObjectMapper;
import com.fasterxml.jackson.databind.jsontype.impl.LaissezFaireSubTypeValidator;
import org.springframework.cache.CacheManager;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.data.redis.cache.RedisCacheConfiguration;
import org.springframework.data.redis.cache.RedisCacheManager;
import org.springframework.data.redis.connection.RedisConnectionFactory;
import org.springframework.data.redis.serializer.Jackson2JsonRedisSerializer;
import org.springframework.data.redis.serializer.RedisSerializationContext;
import org.springframework.data.redis.serializer.StringRedisSerializer;

import java.time.Duration;

/**
 * Spring Cache 配置类，用于将缓存存储到 Redis。
 */
@Configuration
public class CacheConfig {

    /**
     * 配置并创建 CacheManager Bean，Spring 将使用它来管理缓存。
     *
     * @param factory Spring 自动注入的 Redis 连接工厂。
     * @return 配置好的 RedisCacheManager。
     */
    @Bean
    public CacheManager cacheManager(RedisConnectionFactory factory) {
        // 1. 创建 Redis Key 和 Value 的序列化器
        // Key 使用字符串序列化器
        StringRedisSerializer redisSerializer = new StringRedisSerializer();
        // Value 使用自定义的 Jackson JSON 序列化器
        Jackson2JsonRedisSerializer<Object> jackson2JsonRedisSerializer = createJacksonSerializer();

        // 2. 配置默认的缓存规则
        RedisCacheConfiguration config = RedisCacheConfiguration.defaultCacheConfig()
                // 设置缓存默认过期时间为 1 小时
                .entryTtl(Duration.ofHours(1))
                // 设置 Key 的序列化方式
                .serializeKeysWith(RedisSerializationContext.SerializationPair.fromSerializer(redisSerializer))
                // 设置 Value 的序列化方式
                .serializeValuesWith(RedisSerializationContext.SerializationPair.fromSerializer(jackson2JsonRedisSerializer))
                // 禁止缓存 null 值
                .disableCachingNullValues();

        // 3. 根据以上配置创建 CacheManager
        return RedisCacheManager.builder(factory)
                .cacheDefaults(config)
                .build();
    }

    /**
     * 创建一个自定义配置的 Jackson 序列化器。
     * @return Jackson2JsonRedisSerializer 实例
     */
    private Jackson2JsonRedisSerializer<Object> createJacksonSerializer() {
        ObjectMapper objectMapper = new ObjectMapper();
        // 允许 Jackson 序列化所有字段（包括 private）
        objectMapper.setVisibility(PropertyAccessor.ALL, JsonAutoDetect.Visibility.ANY);
        // 在序列化的 JSON 中存储对象的类型信息，以便在反序列化时能恢复为原始类型
        objectMapper.activateDefaultTyping(LaissezFaireSubTypeValidator.instance, ObjectMapper.DefaultTyping.NON_FINAL);

        return new Jackson2JsonRedisSerializer<>(objectMapper, Object.class);
    }
}

// ... imports ...
import org.springframework.cache.annotation.CacheEvict;
import org.springframework.cache.annotation.CachePut;
import org.springframework.cache.annotation.Cacheable;

@Service
@RequiredArgsConstructor
@Slf4j
public class UserServiceImpl implements UserService {

    private final UserMapper userMapper;

    @Override
    @Cacheable(cacheNames = "users", key = "#id")
    public UserVO findUserById(Long id) {
        log.info("执行数据库查询: findUserById, ID: {}", id);
        User user = userMapper.selectById(id);
        if (user == null) { return null; }
        return convertToVO(user);
    }

    @Override
    // updateUser 方法需要返回更新后的对象，才能被 @CachePut 放入缓存
    @CachePut(cacheNames = "users", key = "#dto.id")
    public UserVO updateUser(UserEditDTO dto) {
        // ... (省略校验逻辑) ...
        User user = Convert.convert(User.class, dto);
        userMapper.updateById(user);
        // 返回更新后的VO，以便@CachePut更新缓存
        return findUserById(dto.getId()); 
    }

    @Override
    @CacheEvict(cacheNames = "users", key = "#id")
    public void deleteUserById(Long id) {
        log.info("从数据库删除用户, ID: {}", id);
        userMapper.deleteById(id);
    }
    
    // ... 其他方法 ...
}

package com.example.demosystem.dto.external;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;

@Data
@Schema(description = "外部文章数据传输对象")
public class PostDTO {
    @Schema(description = "关联的用户ID", example = "1")
    private Integer userId;
    
    @Schema(description = "文章ID", example = "1")
    private Integer id;
    
    @Schema(description = "文章标题")
    private String title;
    
    @Schema(description = "文章内容")
    private String body;
}

package com.example.demoframework.config;

import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.client.RestClient;
// ... 其他 import ...

@Configuration
@RequiredArgsConstructor
public class WebConfig implements WebMvcConfigurer {
    
    // ... 已有的拦截器等配置 ...

        @Override
        public void addInterceptors(InterceptorRegistry registry) {
                registry.addInterceptor(logInterceptor) // 注册我们编写的日志拦截器
                                .addPathPatterns("/**"); // 指定拦截所有路径

                // 认证拦截器
                registry.addInterceptor(authInterceptor)
                                .addPathPatterns("/**")
                                .excludePathPatterns(
                                                "/auth/login",
                                                "/external/**", // ！！！注意这里 我们添加了外部接口无需验证我们的TOken
                                                "/files/**",
                                                "/springboot-uploads/**",
                                                "/swagger-ui/**",
                                                "/v3/api-docs/**",
                                                "/error" // 添加错误页面排除
                                );
        }

        @Bean
        public RestClient restClient() {
                return RestClient.builder()
                                .baseUrl("https://jsonplaceholder.typicode.com")
                                .build();
        }
}

package com.example.demosystem.service;

import cn.hutool.core.lang.Assert;
import com.example.democommon.common.ResultCode;
import com.example.democommon.exception.BusinessException;
import com.example.demosystem.dto.external.PostDTO;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.core.ParameterizedTypeReference;
import org.springframework.http.HttpStatusCode;
import org.springframework.stereotype.Service;
import org.springframework.web.client.RestClient;

import java.util.List;

@Service
@RequiredArgsConstructor
@Slf4j
public class ExternalApiService {

    private final RestClient restClient;

    public PostDTO getUserFirstPost(Integer userId) {
        // 1. 调用外部 API 获取指定用户的所有文章列表
        List<PostDTO> posts = restClient.get()
                .uri("/posts?userId={userId}", userId)
                .retrieve()
                .onStatus(HttpStatusCode::is4xxClientError, (req, resp) -> {
                    log.error("调用外部 API 客户端错误: 状态码={}, 响应体={}", resp.getStatusCode(), resp.getBody().toString());
                    throw new BusinessException(ResultCode.BAD_REQUEST);
                })
                .body(new ParameterizedTypeReference<>() {
                });

        // 2. 使用 Hutool Assert 进行业务断言
        Assert.notEmpty(posts, "该用户尚未发布任何文章");

        // 3. 业务处理：返回第一篇文章
        return posts.get(0);
    }
}

package com.example.demosystem.controller;

import com.example.democommon.common.Result;
import com.example.demosystem.dto.external.PostDTO;
import com.example.demosystem.service.ExternalApiService;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.Parameter;
import io.swagger.v3.oas.annotations.tags.Tag;
import lombok.RequiredArgsConstructor;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.*;

@Tag(name = "外部API调用", description = "演示RestClient")
@RestController
@RequestMapping("/external")
@RequiredArgsConstructor
public class ExternalApiController {

    private final ExternalApiService externalApiService;

    @Operation(summary = "获取用户的首篇文章", description = "调用JSONPlaceholder API")
    @GetMapping("/users/{userId}/first-post")
    public ResponseEntity<Result<PostDTO>> getUserFirstPost(
            @Parameter(description = "目标用户的ID", required = true, example = "1") @PathVariable Integer userId) {
        PostDTO post = externalApiService.getUserFirstPost(userId);
        return ResponseEntity.ok(Result.success(post));
    }
}

// ... imports ...
import org.springframework.retry.annotation.EnableRetry;

@SpringBootApplication(scanBasePackages = "com.example")
@MapperScan("com.example.*.mapper")
@EnableCaching
@EnableRetry // 启用 Spring Retry 功能
public class SpringBootDemoApplication {
    // ... main method ...
}

package com.example.democommon.exception;

// 这是一个简单的标记异常，继承自 RuntimeException
// 它的唯一作用就是告诉 Spring Retry：“嘿，看到我这个类型的异常时，你应该发起重试！”
public class RetryableException extends RuntimeException {
    public RetryableException(String message) {
        super(message);
    }
}

package com.example.demosystem.service;

import cn.hutool.core.lang.Assert;
import com.example.democommon.common.ResultCode;
import com.example.democommon.exception.BusinessException;
import com.example.democommon.exception.RetryableException; // 导入新异常
import com.example.demosystem.dto.external.PostDTO;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.core.ParameterizedTypeReference;
import org.springframework.http.HttpStatusCode;
import org.springframework.retry.annotation.Backoff;
import org.springframework.retry.annotation.Recover;
import org.springframework.retry.annotation.Retryable;
import org.springframework.stereotype.Service;
import org.springframework.web.client.RestClient;
import java.util.Collections;
import java.util.List;

@Service
@RequiredArgsConstructor
@Slf4j
public class ExternalApiService {

    private final RestClient restClient;

    @Retryable(
            include = RetryableException.class, // 只对我们自定义的 RetryableException 异常进行重试
            maxAttempts = 3, // 最多重试3次（包括第一次调用）
            backoff = @Backoff(delay = 2000, multiplier = 2) // 退避策略：第一次重试等2秒，第二次等4秒
    )
    public PostDTO getUserFirstPost(Integer userId) {
        log.info("正在尝试调用外部 API, userId: {}", userId);

        List<PostDTO> posts = restClient.get()
                .uri("/posts?userId={userId}", userId)
                .retrieve()
                .onStatus(HttpStatusCode::is4xxClientError, (req, resp) -> {
                    // 遇到 4xx 错误，抛出非重试的 BusinessException
                    throw new BusinessException(ResultCode.BAD_REQUEST);
                })
                .onStatus(HttpStatusCode::is5xxServerError, (req, resp) -> {
                    // 遇到 5xx 错误，抛出可重试的 RetryableException
                    throw new RetryableException("外部服务暂时不可用, 状态码: " + resp.getStatusCode());
                })
                .body(new ParameterizedTypeReference<>() {});

        Assert.notEmpty(posts, "该用户尚未发布任何文章");

        return posts.get(0);
    }

    @Recover
    public PostDTO recover(RetryableException e, Integer userId) {
        // 当所有重试都失败后，此方法将被调用
        log.error("调用外部 API 达到最大重试次数后仍然失败, userId: {}. 异常信息: {}", userId, e.getMessage());
        // 可以在此执行降级逻辑，例如返回一个默认的 PostDTO 对象或 null
        // throw new BusinessException("外部服务持续不可用，请稍后再试");
        return null; // 此处我们选择返回 null
    }
}

// ... imports ...

@Configuration
@RequiredArgsConstructor
public class WebConfig implements WebMvcConfigurer {
    
    // ... 已有的拦截器等配置 ...

    @Bean
    public RestClient restClient() {
        return RestClient.builder()
                // 暂时将 baseUrl 修改为 httpbin.org
                .baseUrl("https://httpbin.org")
                .build();
    }
}