250224 TIL - AI 활용 비즈니스 프로젝트 - @어노테이션 정리

1. Spring MVC / Web 관련 어노테이션
- @RestController
기능: 해당 클래스가 RESTful 웹 API의 컨트롤러임을 선언합니다.
이유: JSON 형태의 응답을 자동으로 직렬화하며, 클라이언트와의 HTTP 통신을 간소화합니다.

- @RequestMapping, @PostMapping, @GetMapping, @PatchMapping
기능: URL 경로와 HTTP 메서드(POST, GET, PATCH 등)를 매핑하여 클라이언트의 요청을 해당 메서드와 연결합니다.
이유: API 엔드포인트를 명확하게 정의하고, 요청 처리 로직을 분리하여 유지보수를 쉽게 합니다.

- @RequestParam, @PathVariable, @RequestBody
기능:
@RequestParam: URL 쿼리스트링에서 파라미터 값을 추출합니다.
@PathVariable: URL 경로의 변수 값을 매핑합니다.
@RequestBody: 요청 본문(body)을 자바 객체로 매핑합니다.
이유: 클라이언트에서 전달하는 데이터(쿼리, 경로, JSON 등)를 쉽게 파싱하여 메서드 파라미터로 주입할 수 있게 해줍니다.

- @Valid (주로 DTO 클래스에서 사용)
기능: 요청으로 전달된 객체의 유효성을 검사합니다.
이유: 클라이언트로부터 입력받은 데이터가 규정된 제약조건(예: NotEmpty, Size 등)을 충족하는지 자동으로 검증하여 잘못된 데이터 처리를 방지합니다.

2. 의존성 주입 및 스테레오타입 어노테이션
@Service
기능: 해당 클래스를 서비스 컴포넌트로 등록하여 비즈니스 로직을 담당하도록 합니다.
이유: 애플리케이션의 핵심 로직을 분리하고, 스프링 컨테이너가 관리하도록 하여 DI(의존성 주입)를 활용합니다.

@Repository
기능: 데이터베이스와의 상호작용을 담당하는 클래스임을 표시합니다.
이유: 예외 전환(스프링의 DataAccessException) 등 데이터 접근 관련 기능을 제공하며, 스프링이 해당 클래스를 빈으로 관리하게 합니다.

- @RequiredArgsConstructor (Lombok)
기능: final 필드나 @NonNull 필드에 대해 생성자를 자동으로 생성합니다.
이유: 의존성 주입 시 생성자 주입을 간편하게 처리하며, 코드의 간결함과 안정성을 높입니다.

3. JPA 관련 어노테이션
- @Entity
기능: 해당 클래스를 JPA 엔티티(데이터베이스 테이블에 대응되는 객체)로 지정합니다.
이유: 객체와 관계형 데이터베이스 간의 매핑을 관리하여 ORM(Object-Relational Mapping)을 가능하게 합니다.

- @Table
기능: 엔티티가 매핑될 데이터베이스 테이블의 이름과 제약조건(예: Unique Constraint)을 설정합니다.
이유: 데이터베이스 테이블 구조와 제약조건을 세밀하게 관리하여 데이터 무결성을 보장합니다.

- @Id, @GeneratedValue
기능:
@Id: 엔티티의 기본 키(primary key)를 지정합니다.
@GeneratedValue: 기본 키의 생성 전략(예: AUTO)을 설정합니다.
이유: 각 엔티티의 고유 식별자를 자동으로 관리하여 데이터베이스 작업(조회, 수정, 삭제 등)을 용이하게 합니다.

- @Column
기능: 엔티티 필드와 데이터베이스 칼럼 간의 매핑 정보를 정의합니다(칼럼 이름, nullable 여부, 길이 등).
이유: 데이터베이스 스키마와의 정밀한 매핑을 통해 데이터 유효성 및 저장 방식을 제어합니다.

- @ManyToOne, @JoinColumn
기능:
@ManyToOne: 여러 엔티티가 하나의 엔티티와 연관된 관계임을 나타냅니다.
사용한 부분 : 하나의 Category 또는 User는 여러 Store와 연결될 수 있음 -> @ManyToOne 사용
Store Entity에서 
    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "category_id", nullable = false)
    private Category category;

    @ManyToOne(fetch = FetchType.LAZY)
    @JoinColumn(name = "user_id", nullable = false)
    private User user;
이렇게 사용함
@JoinColumn: 연관 관계를 맺는 칼럼의 이름, nullable 여부 등을 지정하여 외래 키 제약 조건을 설정함
이유:
관계 표현: 도메인 모델에서 하나의 Category나 User가 여러 Store와 연관될 수 있음을 명확하게 모델링합니다.
데이터 무결성: 외래 키를 통해 데이터베이스 수준에서 참조 무결성을 보장하고, Store 레코드가 반드시 유효한 Category나 User를 참조하도록 합니다.
ORM 매핑 효율성: JPA는 ManyToOne 관계를 활용해 연관 엔티티를 효과적으로 로딩하거나 지연 로딩(lazy loading)하는 등, 객체 간 관계를 자연스럽게 관리할 수 있게 합니다.

4. 유효성 검사 및 제약 조건 어노테이션 (Jakarta Bean Validation)
- @NotEmpty, @NotNull, @Size
기능: DTO나 엔티티 필드에 입력값 제약 조건을 부여합니다.
이유: 클라이언트로부터 입력받은 데이터의 형식과 길이를 검증하여 잘못된 데이터로 인한 오류나 보안 문제를 예방합니다.

5. Lombok 어노테이션
- @Getter, @Setter
기능: 클래스의 모든 필드에 대해 getter와 setter 메서드를 자동 생성합니다.
이유: 보일러플레이트 코드를 줄여 코드의 가독성과 유지보수를 향상시킵니다.

- @NoArgsConstructor, @AllArgsConstructor
기능: 인자 없는 생성자와 모든 필드를 인자로 받는 생성자를 자동으로 생성합니다.
이유: 객체 생성의 유연성을 높이고, JPA나 JSON 직렬화/역직렬화 시 필요로 하는 생성자를 간편하게 제공합니다.

- @Builder
기능: 빌더 패턴을 자동으로 구현하여 객체 생성 시 가독성과 유연성을 높입니다.
이유: 복잡한 생성자 호출 대신 명시적인 필드 설정으로 객체를 생성할 수 있어, 코드의 안정성과 가독성을 개선합니다.

6. Swagger / OpenAPI 어노테이션
- @Operation
기능: API 메서드의 기능, 요약, 설명 등을 문서화합니다.
이유: API 문서를 자동으로 생성하여 클라이언트 개발자나 팀원에게 API 사용법과 동작 방식을 명확히 전달합니다.

- @ApiResponse
기능: API 호출에 대한 응답 코드와 설명을 문서화합니다.
이유: 예상되는 HTTP 상태 코드와 응답 내용을 명시하여 API의 사용성을 높입니다.

- @Parameter
기능: API 메서드의 파라미터에 대한 정보를 문서화합니다(예: 설명, 기본값, 숨김 처리 등).
이유: API 소비자가 각 파라미터의 역할과 요구사항을 이해하기 쉽게 합니다.

- @Tag
기능: API 그룹(예: 기능별 카테고리)을 지정하여 문서화 시 그룹화합니다.
이유: API 문서의 구조를 체계적으로 분류하여 관리 및 탐색을 용이하게 합니다.

7. 커스텀 보안 및 유저 컨텍스트 관련 어노테이션
- @RoleCheck
기능: 메서드 호출 전 사용자의 역할(권한)을 확인하여 접근을 제어합니다.
이유: API 접근 제어를 통해 특정 역할(예: MANAGER, MASTER 등)만이 해당 기능을 사용할 수 있도록 보안 문제를 해결합니다.

- @CurrentUser, @CurrentUserInject
기능: 현재 요청을 보낸 사용자의 정보를 컨텍스트에 주입합니다.
이유: API 호출 시 사용자 정보를 쉽게 참조할 수 있도록 하여, 권한 검사나 감사(audit) 로그, 사용자별 데이터 처리 등을 구현하는 데 도움을 줍니다.