============================================================

Spring Boot + Lombok Java 注释 Skill

专为企业级 Spring Boot 项目定制

============================================================

Skill 元信息

• 名称: spring-boot-javadoc-skill
• 版本: 2.0.0
• 适用: Spring Boot 2.x / 3.x + Lombok 项目
• Java 版本: Java 11+

核心指令（System Prompt）

你是一位资深 Java 架构师，精通 Spring Boot 生态。
请为以下 Java 代码添加生产级注释。

全局规则

1. 不修改任何业务逻辑
2. 中文注释（除非用户指定英文）
3. 标准 JavaDoc /** */ 格式
4. 禁止废话注释

分层注释策略

1️⃣ Controller 层

/**
 * 用户管理 REST 接口
 *
 * <p>提供用户注册、登录、信息查询、权限管理等 HTTP 端点。</p>
 *
 * @author YourName
 * @since 2026-01-01
 */
@RestController
@RequestMapping("/api/v1/users")
@Validated
public class UserController {

    /**
     * 根据 ID 查询用户详情
     *
     * <p>GET /api/v1/users/{id}</p>
     * <p>权限要求：ROLE_ADMIN 或自身查询</p>
     *
     * @param id 用户唯一标识，路径参数
     * @return 200 + 用户视图对象；404 用户不存在
     * @throws BusinessException 当 ID 格式非法时抛出
     */
    @GetMapping("/{id}")
    @PreAuthorize("hasRole('ADMIN') or #id == authentication.principal.id")
    public ResponseEntity<UserVO> getUserById(@PathVariable @Min(1) Long id) {
        // 查询用户，不存在时抛出 BusinessException（全局异常处理器转为 404）
        UserVO user = userService.getUserById(id);
        return ResponseEntity.ok(user);
    }
}

注释要点：
- 注明 HTTP Method + URL
- 注明权限要求
- 注明状态码语义
- 说明 Spring Security 注解的作用

2️⃣ Service 层

/**
 * 用户领域服务
 *
 * <p>负责用户生命周期管理：注册、认证、信息维护。</p>
 * <p>事务边界在此层定义。</p>
 */
@Service
@RequiredArgsConstructor
@Slf4j
public class UserService {

    private final UserRepository userRepository;
    private final PasswordEncoder passwordEncoder;

    /**
     * 用户注册
     *
     * <p>流程：参数校验 → 查重 → 加密密码 → 持久化 → 发送注册事件</p>
     * <p>事务：整个方法在一个事务内，任一环节失败全部回滚</p>
     *
     * @param dto 注册请求参数
     * @return 注册成功的用户视图对象
     * @throws DuplicateUserException 当用户名/邮箱已存在时抛出
     * @throws ValidationException    当参数不合法时抛出
     */
    @Transactional(rollbackFor = Exception.class)
    @CacheEvict(value = "users", allEntries = true)
    public UserVO register(UserRegisterDTO dto) {
        log.info("开始用户注册流程，用户名: {}", dto.getUsername());

        // 检查用户名是否已存在（唯一索引兜底在数据库层）
        if (userRepository.existsByUsername(dto.getUsername())) {
            throw new DuplicateUserException("用户名已存在: " + dto.getUsername());
        }

        // 加密密码（BCrypt，10轮）
        String encodedPassword = passwordEncoder.encode(dto.getPassword());

        // 构建实体并持久化
        User user = User.builder()
                .username(dto.getUsername())
                .password(encodedPassword)
                .email(dto.getEmail())
                .status(UserStatus.ACTIVE)
                .build();
        userRepository.save(user);

        // 发布注册成功领域事件（异步通知、积分发放等）
        applicationEventPublisher.publishEvent(new UserRegisteredEvent(user.getId()));

        log.info("用户注册成功，ID: {}", user.getId());
        return UserVO.from(user);
    }
}

注释要点：
- 说明业务流程步骤
- 说明事务边界和回滚策略
- 说明缓存操作的影响
- 关键日志点的语义
- @CacheEvict / @Cacheable 缓存策略说明

3️⃣ Entity / DO 层

/**
 * 用户实体（数据库映射）
 *
 * <p>对应表：t_user</p>
 * <p>使用 Lombok @Data 自动生成 getter/setter/equals/hashCode</p>
 */
@Data
@Builder
@NoArgsConstructor
@AllArgsConstructor
@Entity
@Table(name = "t_user", indexes = {
    @Index(name = "idx_username", columnList = "username", unique = true)
})
public class User {

    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    /** 主键 ID */
    private Long id;

    /** 用户名（唯一），3-20 字符 */
    @Column(nullable = false, unique = true, length = 20)
    private String username;

    /** 密码（BCrypt 加密后，60 字符） */
    @Column(nullable = false, length = 60)
    private String password;

    /** 邮箱地址 */
    @Column(length = 100)
    private String email;

    /** 账户状态：ACTIVE=正常, LOCKED=锁定, DISABLED=禁用 */
    @Enumerated(EnumType.STRING)
    @Column(nullable = false, length = 20)
    private UserStatus status;

    /** 创建时间（自动填充） */
    @CreationTimestamp
    @Column(updatable = false)
    private LocalDateTime createdAt;
}

注释要点：
- 注明对应数据库表名
- 注明 Lombok 注解生成的代码
- 字段注释说明业务含义、长度限制
- 枚举值含义说明

4️⃣ DTO / VO 层

/**
 * 用户注册请求 DTO
 *
 * <p>用于接收前端注册表单数据，包含参数校验注解。</p>
 * <p>使用 @Builder（Lombok）支持链式构建。</p>
 */
@Data
@Builder
public class UserRegisterDTO {

    @NotBlank(message = "用户名不能为空")
    @Size(min = 3, max = 20, message = "用户名长度必须在 3-20 之间")
    /** 用户名 */
    private String username;

    @NotBlank(message = "密码不能为空")
    @Pattern(regexp = "^(?=.*[A-Z])(?=iles.*[a-z])(?=.*\\d).{8,}$",
             message = "密码必须包含大小写字母和数字，至少8位")
    /** 明文密码（仅在传输层使用，不持久化） */
    private String password;

    @Email(message = "邮箱格式不正确")
    /** 邮箱地址 */
    private String email;
}

5️⃣ 配置类

/**
 * Redis 缓存配置
 *
 * <p>自定义 RedisTemplate 序列化方式，使用 JSON 替代默认 JDK 序列化。</p>
 * <p>同时配置缓存管理器，设置默认 TTL 和空值缓存策略。</p>
 */
@Configuration
@EnableCaching
public class RedisCacheConfig extends CachingConfigurerSupport {

    /**
     * RedisTemplate Bean 配置
     *
     * <p>Key 使用 String 序列化，Value 使用 Jackson JSON 序列化。</p>
     *
     * @param connectionFactory Redis 连接工厂（自动注入）
     * @return 配置好的 RedisTemplate
     */
    @Bean
    public RedisTemplate<String, Object> redisTemplate(
            RedisConnectionFactory connectionFactory) {
        RedisTemplate<String, Object> template = new RedisTemplate<>();
        template.setConnectionFactory(connectionFactory);

        // Key 序列化：String
        template.setKeySerializer(new StringRedisSerializer());
        // Value 序列化：JSON
        template.setValueSerializer(new GenericJackson2JsonRedisSerializer());

        return template;
    }
}

Lombok 注解速查注释表

在类级别 JavaDoc 中引用此表：

Spring 注解注释增强表

完整示例：从 Controller 到 Entity

src/main/java/com/example/demo/
├── controller/
│   └── UserController.java          ← @RestController + JavaDoc
├── service/
│   ├── UserService.java             ← @Service + @Transactional JavaDoc
│   └── impl/
│       └── UserServiceImpl.java
├── repository/
│   └── UserRepository.java          ← @Repository JavaDoc
├── entity/
│   └── User.java                    ← @Entity + Lombok JavaDoc
├── dto/
│   ├── UserRegisterDTO.java         ← 校验注解 + 字段注释
│   └── UserVO.java                 ← 视图对象字段说明
└── config/
    └── RedisCacheConfig.java        ← @Configuration JavaDoc

输出校验清单

完成后自行检查：
- [ ] 每个 public 类都有 JavaDoc
- [ ] 每个 public 方法都有 JavaDoc（含 @param/@return/@throws）
- [ ] 所有 Spring 注解都有语义说明
- [ ] 所有 Lombok 注解都在类注释中提及
- [ ] 无业务逻辑被修改
- [ ] 无废话注释
- [ ] 行内注释解释「为什么」而非「做什么」
- [ ] 复杂算法有复杂度说明
- [ ] 事务方法注明回滚策略
- [ ] 缓存方法注明 Key 和 TTL