2장 · REST 컨트롤러 & DTO·검증

// study-backend/.../web/endpoint/UserAccountEndpoint.java
@RequiredArgsConstructor          // final 필드를 받는 생성자 자동 생성 → 생성자 주입
@RestController                    // 이 클래스는 HTTP 요청을 받아 JSON으로 응답한다
@RequestMapping("/api/users")     // 이 클래스의 모든 URL 앞에 /api/users 가 붙는다
public class UserAccountEndpoint {
    private final UserRepo userRepo;                 // 스프링이 주입
    private final UserRoleRepo userRoleRepo;
    private final PasswordEncoder passwordEncoder;
}

@GetMapping("")                       // 경로 그대로 → GET /api/users
public PageDTO<UserDTO> listByPage(UserFilter filter, Pageable pageable) { ... }

@GetMapping("/{id}")                   // 경로 변수 → GET /api/users/3f2a...
public UserDetailDTO get(@PathVariable UUID id) { ... }

@PostMapping("")                       // → POST /api/users
public void createUserAccount(@Valid @RequestBody UserCreateReq req) { ... }

@DeleteMapping("/{id}")                // → DELETE /api/users/3f2a...
public void deleteById(@PathVariable UUID id) { ... }

// web/dto/UserCreateReq.java — 요청 DTO (record + 검증)
public record UserCreateReq(
    @NotEmpty String userid,
    @NotEmpty String password,
    @NotEmpty String name,
    @NotEmpty @Email String email
) {}

// 컨트롤러: 본문 JSON 을 UserCreateReq 로 받는다
@PostMapping("")
public void createUserAccount(@Valid @RequestBody UserCreateReq req) {
    // req.userid(), req.email() ... record 의 접근자로 값을 읽는다
}

// core/model/dto/UserFilter.java — 검색 조건 (쿼리스트링이 자동 매핑)
public record UserFilter(
    @Nullable String keyword,
    @Nullable List<String> roles,
    @Nullable Boolean active) {}

// 컨트롤러: ?keyword=...&active=...&page=0&size=20 가 자동 바인딩
@GetMapping("")
public PageDTO<UserDTO> listByPage(UserFilter filter, Pageable pageable) { ... }

@PutMapping("/profile")
public void updateProfile(@Valid @RequestBody UserProfileUpdateReq req,
                          @AuthenticationPrincipal User currentUser) {
    currentUser.setName(req.name());      // 인증된 본인 정보를 수정
    currentUser.setEmail(req.email());
    userRepo.save(currentUser);
}

// 스타일 A: record + 검증 (UserCreateReq)
public record UserCreateReq(
    @NotEmpty String userid,
    @NotEmpty @Email String email,
    ...
) {}

// 스타일 B: class + Lombok + 메시지 (RoleCreateRequest)
@Getter @Setter
public class RoleCreateRequest {
    @NotBlank(message = "역할 코드는 필수입니다")
    @Size(max = 50, message = "역할 코드는 50자 이하여야 합니다")
    @Pattern(regexp = "^ROLE_[A-Z0-9_]+$",
             message = "역할 코드는 ROLE_로 시작하고 영문 대문자, 숫자, 밑줄만 사용 가능합니다")
    private String code;
    ...
}

// web/dto/UserDTO.java — 응답 DTO (record + 정적 변환)
public record UserDTO(UUID id, String userid, String name, String email, ...) {
    public static UserDTO fromEntity(User user) {     // 엔티티 → DTO
        if (user == null) return null;
        return new UserDTO(user.getId(), user.getUserid(),
                           user.getName(), user.getEmail(), ...);
    }
}

// web/dto/PageDTO.java — Page 를 그대로 주면 content 만 나오는 문제를 해결
public record PageDTO<T>(PageInfo pageInfo, List<T> content) {
    public static <T> PageDTO<T> fromPage(Page<T> page) {
        var pageInfo = new PageInfo(page.getTotalElements(), page.getTotalPages(),
            page.getNumber(), page.getSize(), page.isFirst(), page.isLast(), ...);
        return new PageDTO<>(pageInfo, page.getContent());
    }
}

// 컨트롤러: 조회 → 각 엔티티를 DTO 로 map → PageDTO 로 감싼다
@GetMapping("")
public PageDTO<UserDTO> listByPage(UserFilter filter, Pageable pageable) {
    var page = userRepo.listByPage(filter, pageable)
        .map(UserDTO::fromEntity);        // Page<User> → Page<UserDTO>
    return PageDTO.fromPage(page);        // → 페이지 정보까지 포함해 응답
}

@PostMapping("")
@Transactional                                       // 메서드 전체를 한 트랜잭션으로
public void createUserAccount(@Valid @RequestBody UserCreateReq req) {
    String encryptedPassword = passwordEncoder.encode(req.password());  // BCrypt 해시

    var newUser = new User();
    newUser.setUserid(req.userid());
    newUser.setEncryptedPassword(encryptedPassword);
    newUser.setName(req.name());
    newUser.setEmail(req.email());

    try {
        userRepo.save(newUser);                      // 리포지토리 직접 호출
    } catch (DataIntegrityViolationException e) {     // 아이디 중복 등 DB 제약 위반
        throw handleUniqViolation(e, "userid", "로그인 아이디");
    }
}