// 反例：每当增加新的通知方式，都需要修改此类
public class NotificationService {
    public void sendNotification(String type, String message) {
        if ("email".equals(type)) {
            // send email logic...
        } else if ("sms".equals(type)) {
            // send sms logic...
        }
        // 当需要增加 push 通知时，必须修改此方法
    }
}

/**
 * 1. 定义一个统一的通知器接口（抽象）。
 *    这是“对修改关闭”的基础。
 */
public interface Notifier {
    void send(String message);
}

/**
 * 2. 为每种通知方式提供具体的实现。
 *    这是“对扩展开放”的体现。
 */
@Component("emailNotifier") // 在Spring中注册为Bean
public class EmailNotifier implements Notifier {
    @Override
    public void send(String message) {
        System.out.println("发送邮件通知: " + message);
    }
}

@Component("smsNotifier")
public class SmsNotifier implements Notifier {
    @Override
    public void send(String message) {
        System.out.println("发送短信通知: " + message);
    }
}

/**
 * 3. 高层模块依赖于抽象（接口），而不是具体实现。
 */
@Service
public class NotificationDispatchService {
    // 依赖注入所有Notifier接口的实现
    private final Map<String, Notifier> notifiers;

    /**
     * 遵循最佳实践，使用构造函数注入。
     * 由于这是类中唯一的构造函数，@Autowired注解可以省略。
     */
    public NotificationDispatchService(Map<String, Notifier> notifiers) {
        this.notifiers = notifiers;
    }

    public void sendNotification(String type, String message) {
        // 通过Bean名称（如 "smsNotifier"）动态选择实现
        Notifier notifier = notifiers.get(type + "Notifier");
        if (notifier != null) {
            notifier.send(message);
        } else {
            throw new IllegalArgumentException("不支持的通知类型: " + type);
        }
    }
}

@Service
public class BadUserService {
    // 不推荐：直接在字段上使用@Autowired
    @Autowired
    private UserRepository userRepository;
}

/**
 * 用户服务实现类，演示构造函数注入。
 */
@Service
public class UserServiceImpl implements UserService {

    /**
     * 使用final关键字声明依赖，确保它们在对象构造后不可被更改，增强了线程安全性。
     */
    private final UserRepository userRepository;
    private final PasswordEncoder passwordEncoder;

    /**
     * 构造函数注入（Constructor Injection）。
     * 这是Spring推荐的最佳实践。
     * 从Spring 4.3开始，如果一个类只有一个构造函数，@Autowired注解可以省略，
     * Spring会自动将构造函数参数识别为需要注入的依赖。
     * 
     * @param userRepository  用户数据仓库依赖，由Spring容器自动注入。
     * @param passwordEncoder 密码编码器依赖，由Spring容器自动注入。
     */
    public UserServiceImpl(UserRepository userRepository, PasswordEncoder passwordEncoder) {
        this.userRepository = userRepository;
        this.passwordEncoder = passwordEncoder;
    }
    
    // ... 业务方法 ...
}

/**
 * 用户数据传输对象（DTO），用于API响应。
 * 使用Java Record定义，代码简洁且默认不可变。
 * 只包含希望向客户端暴露的字段。
 * 
 * @param id       用户ID
 * @param username 用户名
 * @param email    电子邮箱
 */
public record UserDTO(Long id, String username, String email) { } 

/**
 * 聚合了用户和地址信息的数据传输对象。
 * 用于通过一次API调用返回组合数据。
 */
public record UserAddressDTO(
        Long id,
        String username,
        String email,
        String street,
        String city,
        String country
) { } 

@Service
public class UserService {

    private final UserRepository userRepository;
    private final AddressRepository addressRepository;

    /**
     * 遵循最佳实践，使用构造函数注入依赖。
     * @param userRepository  用户仓库
     * @param addressRepository 地址仓库
     */
    public UserService(UserRepository userRepository, AddressRepository addressRepository) {
        this.userRepository = userRepository;
        this.addressRepository = addressRepository;
    }
    
    /**
     * 获取用户信息并转换为DTO。
     * @param userId 用户ID
     * @return UserDTO
     */
    public UserDTO getUserById(Long userId) {
        User user = userRepository.findById(userId)
                .orElseThrow(() -> new ResourceNotFoundException("User not found"));
        // 调用私有方法进行转换
        return toUserDTO(user);
    }
    
    /**
     * 聚合用户与地址信息，并转换为一个DTO。
     * @param userId 用户ID
     * @return UserAddressDTO
     */
    public UserAddressDTO getUserWithAddress(Long userId) {
        User user = userRepository.findById(userId)
                .orElseThrow(() -> new ResourceNotFoundException("User not found"));
        Address address = addressRepository.findByUser(user)
                .orElse(new Address()); // 地址不存在则返回空地址对象

        return toUserAddressDTO(user, address);
    }

    /**
     * 私有的转换方法，负责将User实体映射到UserDTO。
     */
    private UserDTO toUserDTO(User user) {
        return new UserDTO(user.getId(), user.getUsername(), user.getEmail());
    }
    
    /**
     * 私有的转换方法，负责将User和Address实体聚合映射到UserAddressDTO。
     */
    private UserAddressDTO toUserAddressDTO(User user, Address address) {
        return new UserAddressDTO(
                user.getId(),
                user.getUsername(),
                user.getEmail(),
                address.getStreet(),
                address.getCity(),
                address.getCountry()
        );
    }
}

/**
 * 定义一个MapStruct的Mapper接口。
 * componentModel = "spring" 会使其作为一个Spring Bean被容器管理。
 */
@Mapper(componentModel = "spring")
public interface UserMapper {

    /**
     * MapStruct会自动生成此方法的实现，将User实体转换为UserDTO。
     */
    UserDTO toUserDTO(User user);

    /**
     * 通过@Mapping注解处理多源对象到单一目标的映射。
     * source指定源对象的属性路径，target指定目标DTO的属性名。
     */
    @Mapping(source = "user.id", target = "id")
    @Mapping(source = "user.username", target = "username")
    @Mapping(source = "user.email", target = "email")
    @Mapping(source = "address.street", target = "street")
    @Mapping(source = "address.city", target = "city")
    @Mapping(source = "address.country", target = "country")
    UserAddressDTO toUserAddressDTO(User user, Address address);
}

/**
 * 专门用于异步配置的类。
 * @Configuration 标记此类为一个Spring配置类，容器会扫描并处理其中的@Bean定义。
 */
@Configuration
/**
 * @EnableAsync 启用Spring的异步方法执行能力。这是异步功能的总开关。
 * Spring会寻找@Async注解的方法，并通过AOP代理使其异步执行。
 */
@EnableAsync
public class AsyncConfig {

    /**
     * 自定义一个任务执行器（线程池）Bean，用于处理所有@Async任务。
     * @return Executor 线程池实例。
     */
    @Bean(name = "taskExecutor")
    public Executor taskExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(5);
        executor.setMaxPoolSize(10);
        executor.setQueueCapacity(25);
        executor.setThreadNamePrefix("MyAsync-");
        executor.initialize();
        return executor;
    }
}

import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PathVariable;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * OrderController 作为API端点，是整个业务流程的触发入口。
 * 它接收外部的HTTP请求，并委托给Service层进行处理。
 * @RestController 组合了@Controller和@ResponseBody，表示所有方法返回的都是JSON等数据体。
 */
@RestController
@RequestMapping("/api/orders") // 定义该控制器下所有API的公共URL路径前缀
public class OrderController {

    private final OrderService orderService;

    /**
     * 遵循最佳实践，通过构造函数注入OrderService。
     * @param orderService 订单服务
     */
    public OrderController(OrderService orderService) {
        this.orderService = orderService;
    }

    /**
     * 创建一个处理下单请求的POST API。
     * 外部客户端（如浏览器、App）向此URL发送POST请求即可触发整个业务。
     * 例如：POST http://localhost:8080/api/orders/create/ORD-12345
     * 
     * @param orderId 订单ID，从URL路径中动态获取。
     * @return ResponseEntity 包含成功信息的HTTP响应。
     */
    @PostMapping("/create/{orderId}")
    public ResponseEntity<String> createOrder(@PathVariable String orderId) {
        // 调用OrderService的核心业务逻辑
        orderService.placeOrder(orderId);
        // 立即向客户端返回响应，无需等待邮件发送
        return ResponseEntity.ok("订单创建请求已接受，确认邮件将异步发送。");
    }
}

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.stereotype.Service;

/**
 * 订单服务，处理主要的业务逻辑。
 */
@Service
public class OrderService {

    private static final Logger log = LoggerFactory.getLogger(OrderService.class);
    private final NotificationService notificationService;

    /**
     * 通过构造函数注入NotificationService。
     * 关键点：Spring注入的是NotificationService的AOP代理对象，而非原始实例。
     */
    public OrderService(NotificationService notificationService) {
        this.notificationService = notificationService;
    }

    /**
     * 处理下订单的业务方法。
     * @param orderId 新创建的订单ID。
     */
    public void placeOrder(String orderId) {
        log.info("开始处理订单业务逻辑: {}...", orderId);
        // ... (处理订单本身的业务逻辑，如保存到数据库) ...
        log.info("订单 {} 业务逻辑处理完成。准备异步发送确认邮件...", orderId);

        // 正确做法：通过注入的代理对象调用异步方法。
        // Spring的AOP会拦截此调用，并将其放入后台线程池异步执行。
        notificationService.sendConfirmationEmail(orderId);
        
        log.info("placeOrder方法执行完毕，已立即返回。无需等待邮件发送。", orderId);
    }
}

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import org.springframework.scheduling.annotation.Async;
import org.springframework.stereotype.Service;

/**
 * 异步通知服务，专门负责执行耗时的通知任务。
 */
@Service
public class NotificationService {
    private static final Logger log = LoggerFactory.getLogger(NotificationService.class);

    /**
     * 发送邮件的异步方法。
     * @Async("taskExecutor") 明确指定使用我们自定义的线程池Bean，是生产级代码的最佳实践。
     */
    @Async("taskExecutor")
    public void sendConfirmationEmail(String orderId) throws InterruptedException {
        log.info("开始发送邮件给订单: {}... 当前线程: {}", orderId, Thread.currentThread().getName());
        // 模拟5秒的耗时操作
        Thread.sleep(5000); 
        log.info("订单 {} 的邮件发送成功！", orderId);
    }
}

/**
 * Spring Security配置类。
 * @Configuration 声明这是一个Spring配置类。
 */
@Configuration
/**
 * @EnableWebSecurity 启用Spring Security的Web安全功能。这是配置的入口点。
 */
@EnableWebSecurity
public class SecurityConfig {

    /**
     * 定义并注册一个SecurityFilterChain Bean，用于配置HTTP安全策略。
     * Spring Security会使用这个Bean来构建其安全过滤器链。
     * 
     * @param http HttpSecurity构建者，由Spring容器自动注入，用于链式配置安全规则。
     * @return 构建完成的SecurityFilterChain实例。
     * @throws Exception 在配置过程中可能抛出异常。
     */
    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        // 使用Lambda DSL风格进行配置，这是现代Spring Security推荐的方式，更具可读性。
        http
            .authorizeHttpRequests(authz -> authz
                // 1. 授权规则配置
                // 对所有匹配"/admin/**"路径的请求，要求用户必须拥有"ADMIN"角色。
                // hasRole()方法会自动为角色名添加"ROLE_"前缀进行匹配。
                .requestMatchers("/admin/**").hasRole("ADMIN")
                // 对所有匹配"/user/**"路径的请求，要求用户必须拥有"USER"角色。
                .requestMatchers("/user/**").hasRole("USER")
                // 对任何其他未匹配的请求，要求用户必须是已认证（登录）状态。
                .anyRequest().authenticated()
            );

        // 2. 配置登录方式
        // 启用表单登录功能，并使用其默认配置。
        // 这会自动生成一个登录页面、处理登录请求的URL(/login POST)以及处理登录成功/失败的逻辑。
        http.formLogin(Customizer.withDefaults());

        // 3. 构建并返回SecurityFilterChain
        // build()方法固化所有配置，并创建一个不可变的SecurityFilterChain实例。
        return http.build();
    }
    
    /**
     * 定义一个PasswordEncoder Bean，用于密码的加密与比对。
     * 必须提供一个PasswordEncoder，否则会报错。
     * BCrypt是官方推荐的强度较高的加密算法。
     */
    @Bean
    public PasswordEncoder passwordEncoder() {
        return new BCryptPasswordEncoder();
    }
}

spring:
  datasource:
    # JDBC URL指向的是RDS Proxy的端点，而不是RDS数据库的端点
    url: jdbc:postgresql://<proxy-endpoint>:<port>/<database>
    username: <database-user>
    password: <password>
    hikari:
      # 池大小：根据应用的并发能力设置，推荐配置为固定大小。
      maximum-pool-size: 20
      minimum-idle: 20

      # max-lifetime: 连接最大生命周期（毫秒）。
      # 必须设置，以防止拿到已被Proxy放弃的“僵尸连接”。建议15-30分钟。
      max-lifetime: 1800000 

      # keepalive-time: 连接保活心跳（毫秒）。
      # 防止连接因网络不活动而被防火墙或Proxy终止。建议60秒。
      keepalive-time: 60000

// 使用Lombok的@Slf4j注解可以自动生成一个名为log的SLF4J Logger实例。
@Slf4j
@Service
public class MyBusinessService {
    
    public void processData(String dataId) {
        // DEBUG级别：用于开发调试，记录方法入口、参数等。
        log.debug("开始处理数据，ID: {}", dataId);

        if (dataId == null) {
            // WARN级别：记录潜在问题，但不影响当前流程。
            log.warn("数据ID为null，可能导致后续处理异常。");
        }

        try {
            // ... 核心业务逻辑 ...
            // INFO级别：记录关键业务节点和流程完成。
            log.info("数据ID {} 处理成功。", dataId);
        } catch (Exception e) {
            // ERROR级别：记录影响功能的严重错误，并附带异常堆栈。
            log.error("处理数据ID {} 时发生严重错误。", dataId, e);
        }
    }
}

logging:
  level:
    # 根日志级别，默认为INFO
    root: INFO
    # 为特定包设置更详细的日志级别，便于开发调试
    com.example.myapp.service: DEBUG
    # 关闭Hibernate等框架的冗余日志
    org.hibernate.SQL: WARN

// 假设有一个UserRepository和User实体类
// import org.springframework.cache.annotation.Cacheable;
// import org.springframework.stereotype.Service;
// import java.util.Optional;

@Service
public class UserService {

    private final UserRepository userRepository; // 假设已通过构造函数注入

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

    /**
     * 根据用户ID获取用户信息，并将结果缓存到名为"users"的缓存中。
     * 如果缓存中已存在该ID对应的用户，则直接返回缓存结果，不会执行方法体。
     * 
     * @param id 用户ID
     * @return 对应的User对象，如果不存在则返回null
     */
    @Cacheable("users")
    public User getUserById(Long id) {
        System.out.println("从数据库查询用户，ID: " + id); // 用于演示缓存是否生效
        return userRepository.findById(id).orElse(null);
    }

    // ... 其他业务方法 ...
}

# application.yml
management:
  endpoints:
    web:
      exposure:
        include: "health,info,metrics" # 暴露指定的端点
  endpoint:
    health:
      show-details: always # 总是显示健康检查的详细信息

# --- 阶段 1: 构建应用程序 ---
# 使用Maven官方镜像作为构建环境，该镜像包含了Java JDK和Maven
FROM maven:3.8.5-openjdk-17 AS build

# 设置容器内的工作目录
WORKDIR /workspace

# 复制项目的pom.xml文件，利用Docker的层缓存机制，先下载依赖
COPY pom.xml .
# 运行Maven命令下载所有依赖，不执行编译，加快后续的构建速度
RUN mvn dependency:go-offline

# 复制项目的源代码
COPY src ./src

# 执行Maven打包命令，跳过测试以节省时间，生成最终的JAR包
RUN mvn clean package -DskipTests

# --- 阶段 2: 构建最终运行镜像 ---
# 使用一个精简的OpenJDK镜像作为运行环境，该镜像只包含JRE，体积更小，更安全
FROM openjdk:17-jdk-slim

# 设置容器内的工作目录
WORKDIR /app

# 从 'build' 阶段复制最终生成的JAR文件到当前阶段的镜像中
COPY --from=build /workspace/target/*.jar app.jar

# 暴露应用程序监听的端口，例如Spring Boot默认的8080端口
EXPOSE 8080

# 定义容器启动时执行的命令，运行Spring Boot应用
ENTRYPOINT ["java", "-jar", "app.jar"]