@SpringBootApplication  
// 包含@Configuration、@EnableAutoConfiguration和@ComponentScan
// 标记主类，Spring Boot应用程序的入口

@EnableAutoConfiguration  
// 启用Spring Boot的自动配置机制

@ComponentScan  
// 自动扫描并注册符合条件的组件

@Configuration  
// 标记配置类，通常与@Bean结合使用

@Component  
// 通用组件注解，标记类为Spring组件

@Service  
// 标记服务层组件

@Repository  
// 标记数据访问层组件

@Controller  
// 标记控制器组件（Spring MVC）

@RestController  
// @Controller和@ResponseBody的组合，用于RESTful Web服务

@ConfigurationProperties(prefix = "app")  
// 绑定外部配置到类属性

@Value("${property.name}")  
// 注入配置属性值

@PropertySource("classpath:custom.properties")  
// 指定配置文件位置

@Bean  
// 声明一个Bean，通常在@Configuration类中使用

@Scope("singleton")  
// 指定Bean的作用域（singleton/prototype/request/session）

@Conditional  
// 条件化地创建Bean

@Profile("dev")  
// 指定Bean在特定Profile下创建

@RequestMapping("/path")  
// 通用请求映射

@GetMapping("/path")  
// GET请求映射

@PostMapping("/path")  
// POST请求映射

@PutMapping("/path")  
// PUT请求映射

@DeleteMapping("/path")  
// DELETE请求映射

@PatchMapping("/path")  
// PATCH请求映射

@RequestParam  
// 绑定请求参数
@RequestParam(value = "id", required = false, defaultValue = "0")
private String id;

@PathVariable  
// 绑定URL路径变量
@GetMapping("/users/{id}")
public User getUser(@PathVariable Long id)

@RequestBody  
// 绑定请求体
@PostMapping("/users")
public User createUser(@RequestBody User user)

@RequestHeader  
// 绑定请求头

@CookieValue  
// 绑定Cookie值

@ResponseBody  
// 将返回值序列化为响应体

@ResponseStatus(HttpStatus.OK)  
// 指定响应状态码

@ExceptionHandler(Exception.class)  
// 处理特定异常

@ControllerAdvice  
// 全局控制器增强，通常用于全局异常处理

@Entity  
// 标记JPA实体类

@Table(name = "users")  
// 指定数据库表名

@Id  
// 标记主键字段

@GeneratedValue  
// 主键生成策略

@Column  
// 指定列属性

@Transactional  
// 声明事务

@Mapper  
// 标记MyBatis映射器接口

@Select("SELECT * FROM users")  
// SQL查询语句

@Insert("INSERT INTO users(name) VALUES(#{name})")  
// SQL插入语句

@Update("UPDATE users SET name = #{name}")  
// SQL更新语句

@Delete("DELETE FROM users WHERE id = #{id}")  
// SQL删除语句

@Cacheable  
// 缓存方法返回值
@Cacheable(value = "users", key = "#id")
public User getUser(Long id)

@CacheEvict  
// 清除缓存
@CacheEvict(value = "users", allEntries = true)
public void clearCache()

@CachePut  
// 更新缓存
@CachePut(value = "users", key = "#user.id")
public User updateUser(User user)

@EnableCaching  
// 启用缓存支持

@Secured("ROLE_ADMIN")  
// 基于角色的安全控制

@PreAuthorize("hasRole('ADMIN')")  
// 方法执行前的权限检查

@PostAuthorize("returnObject.username == authentication.name")  
// 方法执行后的权限检查

@RolesAllowed({"USER", "ADMIN"})  
// 指定允许访问的角色

@SpringBootTest  
// Spring Boot测试类

@Test  
// 测试方法

@MockBean  
// 模拟Bean

@AutoConfigureMockMvc  
// 配置MockMvc

@WebMvcTest  
// MVC测试

@DataJpaTest  
// JPA测试

@Autowired  
// 自动注入依赖

@Qualifier("beanName")  
// 指定注入的Bean名称

@Resource  
// 按名称注入

@Inject  
// JSR-330依赖注入

@Aspect  
// 声明切面

@Before("execution(* com.example.service.*.*(..))")  
// 前置通知

@After  
// 后置通知

@Around  
// 环绕通知

@AfterReturning  
// 返回通知

@AfterThrowing  
// 异常通知

@EnableAsync  
// 启用异步处理

@Async  
// 标记异步方法

@EnableScheduling  
// 启用定时任务

@Scheduled(fixedRate = 5000)  
// 定时执行，固定速率

@Scheduled(cron = "0 0 12 * * ?")  
// 使用cron表达式定时执行

@Valid  
// 触发验证

@NotNull  
// 非空验证

@Size(min = 2, max = 30)  
// 字符串长度验证

@Email  
// 邮箱格式验证

@Pattern(regexp = "^[0-9]{10}$")  
// 正则表达式验证

@EnableAsync  
// 在配置类上使用，启用异步功能
@Configuration
@EnableAsync
public class AsyncConfig implements AsyncConfigurer {
    @Override
    public Executor getAsyncExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(5);
        executor.setMaxPoolSize(10);
        executor.setQueueCapacity(25);
        executor.initialize();
        return executor;
    }
}

@Async  
// 标记方法为异步执行
@Async
public CompletableFuture<String> asyncMethod() {
    // 异步处理逻辑
    return CompletableFuture.completedFuture("result");
}

@Async("specificExecutor")  
// 指定使用特定的执行器
@Async("threadPoolTaskExecutor")
public void asyncMethodWithExecutor() {
    // 使用指定执行器的异步处理
}

@EnableScheduling  
// 启用定时任务调度功能

@Scheduled  
// 配置定时任务
@Scheduled(fixedRate = 5000)  // 固定速率执行
@Scheduled(fixedDelay = 5000) // 固定延迟执行
@Scheduled(initialDelay = 1000, fixedRate = 5000) // 初始延迟后固定速率执行
@Scheduled(cron = "0 0 12 * * ?") // 使用cron表达式

// 自定义线程池配置
@Configuration
public class ThreadPoolConfig {
    @Bean
    public ThreadPoolTaskExecutor threadPoolTaskExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        executor.setCorePoolSize(10);        // 核心线程数
        executor.setMaxPoolSize(20);         // 最大线程数
        executor.setQueueCapacity(200);      // 队列容量
        executor.setKeepAliveSeconds(60);    // 线程空闲时间
        executor.setThreadNamePrefix("async-"); // 线程名前缀
        executor.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy()); // 拒绝策略
        executor.initialize();
        return executor;
    }
}

@EventListener  
// 标记方法为事件监听器
@EventListener
public void handleContextStart(ContextStartedEvent event) {
    // 处理事件
}

@TransactionalEventListener  
// 在事务上下文中处理事件
@TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
public void handleAfterCommit(CustomEvent event) {
    // 事务提交后处理事件
}

@Async
@EventListener  
// 异步事件处理
public void handleAsyncEvent(CustomEvent event) {
    // 异步处理事件
}

@EnableRetry  
// 启用重试机制
@Configuration
@EnableRetry
public class RetryConfig { }

@Retryable  
// 配置方法重试
@Retryable(
    value = {SQLException.class},    // 指定异常类型
    maxAttempts = 3,                 // 最大重试次数
    backoff = @Backoff(delay = 1000) // 重试延迟
)
public void retryableOperation() {
    // 可能失败的操作
}

@Recover  
// 重试失败后的恢复方法
@Recover
public void recover(SQLException e) {
    // 处理最终失败的情况
}

@Lock  
// 分布式锁注解（需要集成相关实现，如Redisson）
@Lock(key = "#userId", timeout = 10)
public void processUserData(String userId) {
    // 需要加锁的处理逻辑
}

// 自定义并发限制注解示例
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface ConcurrencyLimit {
    int value() default 10;  // 并发数限制
    long timeout() default 1000;  // 超时时间
}

@Configuration
public class AsyncTaskConfig {
    
    @Bean
    public AsyncTaskExecutor taskExecutor() {
        ThreadPoolTaskExecutor executor = new ThreadPoolTaskExecutor();
        // 核心线程配置
        executor.setCorePoolSize(10);
        executor.setMaxPoolSize(20);
        executor.setQueueCapacity(100);
        
        // 线程配置
        executor.setThreadNamePrefix("Async-Task-");
        executor.setRejectedExecutionHandler(new ThreadPoolExecutor.CallerRunsPolicy());
        
        // 等待任务完成配置
        executor.setWaitForTasksToCompleteOnShutdown(true);
        executor.setAwaitTerminationSeconds(60);
        
        return executor;
    }
}

@Service
public class AsyncService {
    
    @Async
    public CompletableFuture<String> asyncMethodWithResult() {
        try {
            Thread.sleep(1000);
            return CompletableFuture.completedFuture("Async result");
        } catch (InterruptedException e) {
            return CompletableFuture.failedFuture(e);
        }
    }
    
    @Async
    public void asyncMethodWithException() throws Exception {
        throw new Exception("Async method exception");
    }
    
    // 异步方法组合示例
    public CompletableFuture<String> combinedAsyncMethods() {
        CompletableFuture<String> future1 = asyncMethodWithResult();
        CompletableFuture<String> future2 = asyncMethodWithResult();
        
        return CompletableFuture.allOf(future1, future2)
            .thenApply(v -> future1.join() + " " + future2.join());
    }
}

// 1. 异常处理
@Async
public CompletableFuture<String> asyncWithExceptionHandling() {
    try {
        // 异步处理逻辑
        return CompletableFuture.completedFuture("result");
    } catch (Exception e) {
        return CompletableFuture.failedFuture(e);
    }
}

// 2. 超时处理
@Async
public CompletableFuture<String> asyncWithTimeout() {
    return CompletableFuture.supplyAsync(() -> {
        // 处理逻辑
        return "result";
    }).orTimeout(5, TimeUnit.SECONDS);
}

// 3. 异步任务进度跟踪
@Async
public void asyncWithProgress(ProgressTracker tracker) {
    tracker.start();
    // 处理逻辑
    tracker.progress(50);
    // 更多处理
    tracker.complete();
}

/**
 * 条件注解用于根据特定条件决定是否创建Bean或启用配置
 * 常用场景：
 * 1. 根据环境选择不同的配置
 * 2. 根据依赖是否存在决定是否启用功能
 * 3. 自定义条件化配置
 */

// 1. 基于类是否存在的条件
@ConditionalOnClass(name = "org.springframework.data.redis.core.RedisTemplate")
public class RedisConfig {
    // 只有当RedisTemplate类存在时才会创建这个配置类
}

// 2. 基于Bean是否存在的条件
@ConditionalOnBean(DataSource.class)
public class JpaConfig {
    // 只有当DataSource类型的Bean存在时才会创建这个配置
}

// 3. 基于属性值的条件
@ConditionalOnProperty(prefix = "app", name = "feature", havingValue = "true")
public class FeatureConfig {
    // 只有当app.feature=true时才会创建这个配置
}

// 4. 基于自定义条件
@Conditional(CustomCondition.class)
public class CustomConfig {
    // 根据CustomCondition的逻辑决定是否创建
}

/**
 * 配置属性绑定用于将配置文件中的属性映射到Java对象
 * 常用场景：
 * 1. 应用配置管理
 * 2. 第三方服务配置
 * 3. 自定义功能配置
 */

@Configuration
@ConfigurationProperties(prefix = "app.mail")
@Validated  // 添加验证支持
public class MailProperties {
    @NotEmpty
    private String host;
    
    @Min(1) @Max(65535)
    private int port = 25;
    
    private String username;
    private String password;
    
    @Pattern(regexp = "^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Z|a-z]{2,}$")
    private String fromAddress;
    
    // getter和setter
}

// 使用示例
@Service
public class MailService {
    private final MailProperties mailProperties;
    
    public MailService(MailProperties mailProperties) {
        this.mailProperties = mailProperties;
    }
}

/**
 * 日志配置注解用于注入日志对象和配置日志行为
 * 常用场景：
 * 1. 业务日志记录
 * 2. 调试信息输出
 * 3. 性能监控
 */

// 1. 使用Slf4j注解
@Slf4j
public class UserService {
    public void createUser(User user) {
        log.info("Creating user: {}", user.getUsername());
        log.debug("User details: {}", user);
        try {
            // 业务逻辑
        } catch (Exception e) {
            log.error("Failed to create user: {}", user.getUsername(), e);
        }
    }
}

// 2. 自定义日志切面
@Aspect
@Component
public class LoggingAspect {
    @Around("@annotation(LogExecutionTime)")
    public Object logExecutionTime(ProceedingJoinPoint joinPoint) throws Throwable {
        long start = System.currentTimeMillis();
        Object proceed = joinPoint.proceed();
        long executionTime = System.currentTimeMillis() - start;
        log.info("{} executed in {}ms", joinPoint.getSignature(), executionTime);
        return proceed;
    }
}

/**
 * 参数验证注解用于确保输入数据的有效性
 * 常用场景：
 * 1. API接口参数验证
 * 2. 表单数据验证
 * 3. 配置属性验证
 */

@RestController
@Validated  // 开启验证支持
public class UserController {
    
    // 路径参数验证
    @GetMapping("/users/{id}")
    public User getUser(@PathVariable @Min(1) Long id) {
        return userService.getUser(id);
    }
    
    // 请求体验证
    @PostMapping("/users")
    public User createUser(@RequestBody @Valid UserDTO userDTO) {
        return userService.createUser(userDTO);
    }
    
    // 请求参数验证
    @GetMapping("/users/search")
    public List<User> searchUsers(
        @RequestParam @NotBlank String keyword,
        @RequestParam @Min(0) @Max(100) int page,
        @RequestParam @Min(1) @Max(50) int size
    ) {
        return userService.searchUsers(keyword, page, size);
    }
}

// DTO类验证
public class UserDTO {
    @NotBlank(message = "Username is required")
    @Size(min = 4, max = 50, message = "Username must be between 4 and 50 characters")
    private String username;
    
    @NotBlank(message = "Email is required")
    @Email(message = "Invalid email format")
    private String email;
    
    @NotNull(message = "Age is required")
    @Min(value = 18, message = "Must be at least 18 years old")
    private Integer age;
    
    // getter和setter
}

/**
 * 缓存注解用于优化数据访问性能
 * 常用场景：
 * 1. 频繁访问的数据缓存
 * 2. 计算密集型结果缓存
 * 3. 分布式缓存管理
 */

@Configuration
@EnableCaching
public class CacheConfig {
    @Bean
    public CacheManager cacheManager(RedisConnectionFactory factory) {
        RedisCacheConfiguration config = RedisCacheConfiguration.defaultCacheConfig()
            .entryTtl(Duration.ofMinutes(10))
            .serializeKeysWith(RedisSerializationContext.SerializationPair.fromSerializer(new StringRedisSerializer()))
            .serializeValuesWith(RedisSerializationContext.SerializationPair.fromSerializer(new GenericJackson2JsonRedisSerializer()));
            
        return RedisCacheManager.builder(factory)
            .cacheDefaults(config)
            .build();
    }
}

@Service
public class UserService {
    // 基本缓存
    @Cacheable(value = "users", key = "#id")
    public User getUser(Long id) {
        return userRepository.findById(id).orElse(null);
    }
    
    // 条件缓存
    @Cacheable(value = "users", key = "#id", condition = "#id != null", unless = "#result == null")
    public User getUserWithCondition(Long id) {
        return userRepository.findById(id).orElse(null);
    }
    
    // 更新缓存
    @CachePut(value = "users", key = "#user.id")
    public User updateUser(User user) {
        return userRepository.save(user);
    }
    
    // 删除缓存
    @CacheEvict(value = "users", key = "#id")
    public void deleteUser(Long id) {
        userRepository.deleteById(id);
    }
    
    // 清除所有缓存
    @CacheEvict(value = "users", allEntries = true)
    public void clearUserCache() {
        // 清除缓存逻辑
    }
}

/**
 * 事务注解用于确保数据一致性
 * 常用场景：
 * 1. 数据库操作事务管理
 * 2. 分布式事务处理
 * 3. 复杂业务流程事务控制
 */

@Service
public class TransferService {
    
    // 基本事务
    @Transactional
    public void transfer(String fromAccount, String toAccount, BigDecimal amount) {
        accountRepository.deduct(fromAccount, amount);
        accountRepository.add(toAccount, amount);
    }
    
    // 只读事务
    @Transactional(readOnly = true)
    public BigDecimal getBalance(String account) {
        return accountRepository.getBalance(account);
    }
    
    // 事务传播行为
    @Transactional(propagation = Propagation.REQUIRES_NEW)
    public void createAccountWithNewTransaction(Account account) {
        accountRepository.save(account);
    }
    
    // 事务隔离级别
    @Transactional(isolation = Isolation.SERIALIZABLE)
    public void highSecurityOperation() {
        // 高安全性要求的操作
    }
    
    // 异常回滚控制
    @Transactional(rollbackFor = {CustomException.class})
    public void operationWithCustomRollback() throws CustomException {
        // 业务逻辑
    }
}

/**
 * 安全注解用于访问控制和权限管理
 * 常用场景：
 * 1. 接口访问控制
 * 2. 方法级别权限控制
 * 3. 数据级别权限控制
 */

@Configuration
@EnableWebSecurity
public class SecurityConfig extends WebSecurityConfigurerAdapter {
    @Override
    protected void configure(HttpSecurity http) throws Exception {
        http.authorizeRequests()
            .antMatchers("/public/**").permitAll()
            .antMatchers("/api/**").authenticated()
            .antMatchers("/admin/**").hasRole("ADMIN")
            .and()
            .formLogin()
            .and()
            .csrf().disable();
    }
}

@RestController
@RequestMapping("/api")
public class SecuredController {
    
    // 要求认证
    @PreAuthorize("isAuthenticated()")
    @GetMapping("/data")
    public Data getData() {
        return dataService.getData();
    }
    
    // 角色检查
    @PreAuthorize("hasRole('ADMIN')")
    @PostMapping("/admin/action")
    public void adminAction() {
        // 管理员操作
    }
    
    // 复杂权限表达式
    @PreAuthorize("hasRole('ADMIN') or hasPermission(#id, 'Data', 'READ')")
    @GetMapping("/data/{id}")
    public Data getDataById(@PathVariable Long id) {
        return dataService.getData(id);
    }
    
    // 方法返回值权限检查
    @PostAuthorize("returnObject.owner == authentication.name")
    public Data getOwnedData() {
        return dataService.getData();
    }
}

/**
 * 监控注解用于应用性能监控和度量
 * 常用场景：
 * 1. 性能监控
 * 2. 业务指标统计
 * 3. 系统健康检查
 */

@Configuration
@EnableActuator
public class MonitoringConfig {
    @Bean
    public MeterRegistry meterRegistry() {
        return new SimpleMeterRegistry();
    }
}

@Service
@Timed  // 记录方法执行时间
public class MonitoredService {
    
    private final Counter requestCounter;
    private final Timer processTimer;
    
    public MonitoredService(MeterRegistry registry) {
        this.requestCounter = registry.counter("service.requests");
        this.processTimer = registry.timer("service.process.time");
    }
    
    @Timed(value = "service.operation", percentiles = {0.5, 0.95, 0.99})
    public void performOperation() {
        requestCounter.increment();
        Timer.Sample sample = Timer.start();
        try {
            // 业务逻辑
        } finally {
            sample.stop(processTimer);
        }
    }
}

// 创建自定义组合注解
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@PreAuthorize("hasRole('ADMIN')")
@Transactional
@Timed
public @interface AdminAction {
}

// 使用组合注解
@AdminAction
public void performAdminOperation() {
    // 业务逻辑
}

public interface ValidationGroups {
    interface Create {}
    interface Update {}
}

public class UserDTO {
    @NotNull(groups = ValidationGroups.Update.class)
    @Null(groups = ValidationGroups.Create.class)
    private Long id;
    
    @NotBlank(groups = {ValidationGroups.Create.class, ValidationGroups.Update.class})
    private String name;
}

@RestControllerAdvice
public class GlobalExceptionHandler {
    
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ResponseEntity<ErrorResponse> handleValidationExceptions(MethodArgumentNotValidException ex) {
        List<String> errors = ex.getBindingResult()
            .getFieldErrors()
            .stream()
            .map(error -> error.getField() + ": " + error.getDefaultMessage())
            .collect(Collectors.toList());
        
        return ResponseEntity
            .badRequest()
            .body(new ErrorResponse("Validation Failed", errors));
    }
}

@Validated
@Configuration
@ConfigurationProperties(prefix = "app")
public class AppProperties {
    
    @NotEmpty
    private String name;
    
    @Min(1) @Max(100)
    private int threadPoolSize = 10;
    
    @Pattern(regexp = "^(dev|test|prod)$")
    private String environment;
    
    // getter和setter
}

/**
 * 实体类映射注解，用于定义实体与数据库表的映射关系
 */
@Entity  // 声明这是一个JPA实体类
@Table(
    name = "tbl_user",  // 指定表名
    schema = "public",  // 指定schema
    uniqueConstraints = {  // 定义唯一约束
        @UniqueConstraint(columnNames = {"email", "phone"})
    },
    indexes = {  // 定义索引
        @Index(name = "idx_email", columnList = "email"),
        @Index(name = "idx_name_age", columnList = "name,age")
    }
)
@Data  // Lombok注解
public class User {
    
    @Id  // 主键标识
    @GeneratedValue(strategy = GenerationType.IDENTITY)  // 主键生成策略
    private Long id;
    
    @Column(
        name = "user_name",  // 列名
        length = 50,         // 字段长度
        nullable = false,    // 非空约束
        unique = true       // 唯一约束
    )
    private String username;
    
    @Column(columnDefinition = "TEXT")  // 自定义列定义
    private String description;
    
    @Temporal(TemporalType.TIMESTAMP)  // 时间类型映射
    private Date createTime;
    
    @Enumerated(EnumType.STRING)  // 枚举类型映射
    private UserStatus status;
    
    @Transient  // 非持久化字段
    private String tempField;
}

/**
 * 实体关联关系注解，用于定义实体之间的关系
 */
@Entity
@Table(name = "tbl_user")
public class User {
    
    // 一对一关系
    @OneToOne(cascade = CascadeType.ALL, fetch = FetchType.LAZY)
    @JoinColumn(name = "address_id", referencedColumnName = "id")
    private Address address;
    
    // 一对多关系
    @OneToMany(
        mappedBy = "user",           // 由多方维护关系
        cascade = CascadeType.ALL,   // 级联操作
        fetch = FetchType.LAZY,      // 懒加载
        orphanRemoval = true         // 孤儿记录删除
    )
    private List<Order> orders = new ArrayList<>();
    
    // 多对多关系
    @ManyToMany(cascade = {CascadeType.PERSIST, CascadeType.MERGE})
    @JoinTable(
        name = "user_role",                     // 关联表名
        joinColumns = @JoinColumn(name = "user_id"),  // 当前实体在中间表的外键
        inverseJoinColumns = @JoinColumn(name = "role_id")  // 关联实体在中间表的外键
    )
    private Set<Role> roles = new HashSet<>();
}

@Entity
@Table(name = "tbl_order")
public class Order {
    
    // 多对一关系
    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "user_id")
    private User user;
}

/**
 * 实体继承策略注解，用于定义实体继承关系的映射策略
 */
// 单表策略：所有类映射到一个表
@Entity
@Inheritance(strategy = InheritanceType.SINGLE_TABLE)
@DiscriminatorColumn(name = "type", discriminatorType = DiscriminatorType.STRING)
public abstract class Payment {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private BigDecimal amount;
}

@Entity
@DiscriminatorValue("CREDIT")
public class CreditCardPayment extends Payment {
    private String cardNumber;
}

@Entity
@DiscriminatorValue("DEBIT")
public class DebitCardPayment extends Payment {
    private String bankAccount;
}

// 连接表策略：每个类映射到独立的表
@Entity
@Inheritance(strategy = InheritanceType.JOINED)
public abstract class Vehicle {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    private Long id;
    private String manufacturer;
}

@Entity
public class Car extends Vehicle {
    private int numberOfDoors;
}

@Entity
public class Motorcycle extends Vehicle {
    private boolean hasSidecar;
}

/**
 * 查询相关注解，用于定义查询方法
 */
@Repository
public interface UserRepository extends JpaRepository<User, Long> {
    
    // 命名查询
    @Query("SELECT u FROM User u WHERE u.email = ?1 AND u.status = ?2")
    User findByEmailAndStatus(String email, UserStatus status);
    
    // 原生SQL查询
    @Query(
        value = "SELECT * FROM tbl_user WHERE age > :age",
        nativeQuery = true
    )
    List<User> findUsersOlderThan(@Param("age") int age);
    
    // 修改查询
    @Modifying
    @Query("UPDATE User u SET u.status = :status WHERE u.lastLoginDate < :date")
    int updateUserStatus(@Param("status") UserStatus status, @Param("date") Date date);
    
    // 命名参数查询
    @Query("SELECT u FROM User u WHERE u.age BETWEEN :minAge AND :maxAge")
    List<User> findUsersByAgeBetween(
        @Param("minAge") int minAge,
        @Param("maxAge") int maxAge
    );
}

/**
 * 审计注解，用于自动记录实体的创建和修改信息
 */
@EntityListeners(AuditingEntityListener.class)
@MappedSuperclass
public abstract class Auditable {
    
    @CreatedBy
    @Column(updatable = false)
    private String createdBy;
    
    @CreatedDate
    @Column(updatable = false)
    private LocalDateTime createdDate;
    
    @LastModifiedBy
    private String lastModifiedBy;
    
    @LastModifiedDate
    private LocalDateTime lastModifiedDate;
}

// 启用JPA审计
@EnableJpaAuditing
@Configuration
public class JpaAuditingConfig {
    @Bean
    public AuditorAware<String> auditorProvider() {
        return () -> Optional.ofNullable(SecurityContextHolder.getContext())
            .map(SecurityContext::getAuthentication)
            .map(Authentication::getName);
    }
}

/**
 * JPA实体验证注解，用于数据验证
 */
@Entity
public class Product {
    
    @NotNull(message = "Name is required")
    @Size(min = 2, max = 100)
    private String name;
    
    @Positive
    @Column(nullable = false)
    private BigDecimal price;
    
    @Min(0)
    private Integer stockQuantity;
    
    @Email
    @Column(unique = true)
    private String contactEmail;
    
    @Pattern(regexp = "^[A-Z]{2}\\d{6}$", message = "Invalid product code format")
    private String productCode;
}

/**
 * 复合主键注解，用于定义复合主键
 */
// 方式1：@IdClass
@Entity
@IdClass(OrderItemId.class)
public class OrderItem {
    @Id
    private Long orderId;
    
    @Id
    private Long productId;
    
    private Integer quantity;
}

public class OrderItemId implements Serializable {
    private Long orderId;
    private Long productId;
    // equals() 和 hashCode() 方法
}

// 方式2：@EmbeddedId
@Entity
public class BookEdition {
    @EmbeddedId
    private BookEditionId id;
    
    private String publisher;
    private LocalDate publishDate;
}

@Embeddable
public class BookEditionId implements Serializable {
    private String isbn;
    private Integer edition;
    // equals() 和 hashCode() 方法
}

/**
 * 二级缓存注解，用于配置实体缓存
 */
@Entity
@Cacheable
@Cache(
    usage = CacheConcurrencyStrategy.READ_WRITE,
    region = "user_cache"
)
public class User {
    // 实体属性
}

// 缓存查询结果
@Repository
public interface UserRepository extends JpaRepository<User, Long> {
    @QueryHints({
        @QueryHint(name = "org.hibernate.cacheable", value = "true"),
        @QueryHint(name = "org.hibernate.cacheRegion", value = "query.users")
    })
    List<User> findByStatus(UserStatus status);
}

// 推荐：使用双向关系时在一方使用mappedBy
@OneToMany(mappedBy = "user")
private List<Order> orders;

// 推荐：使用Set代替List（性能更好）
@OneToMany(mappedBy = "user")
private Set<Order> orders = new HashSet<>();

// 推荐：懒加载 + 关联属性懒初始化
@OneToMany(fetch = FetchType.LAZY)
private Set<Order> orders;

// 推荐：使用自增长主键
@Id
@GeneratedValue(strategy = GenerationType.IDENTITY)
private Long id;

// 或使用序列（Oracle）
@Id
@GeneratedValue(strategy = GenerationType.SEQUENCE, generator = "user_seq")
@SequenceGenerator(name = "user_seq", sequenceName = "user_sequence")
private Long id;

// 推荐：使用基类包含审计字段
@MappedSuperclass
@EntityListeners(AuditingEntityListener.class)
public abstract class BaseEntity {
    @CreatedDate
    @Column(updatable = false)
    private LocalDateTime createdAt;
    
    @LastModifiedDate
    private LocalDateTime updatedAt;
}

// 推荐：在实体类级别定义索引和约束
@Entity
@Table(
    indexes = {
        @Index(name = "idx_email", columnList = "email"),
        @Index(name = "idx_name_status", columnList = "name,status")
    },
    uniqueConstraints = {
        @UniqueConstraint(columnNames = {"email"})
    }
)
public class User { }

// 推荐：使用字符串存储枚举
@Enumerated(EnumType.STRING)
private UserStatus status;

// 不推荐：使用序数存储枚举（难以维护）
@Enumerated(EnumType.ORDINAL)
private UserStatus status;