위 사진과 같이 출발지/목적지의 도로 정보를 탐색할 수 없을때 kakao mobility api의 자동차 길찾기에서 102/103 result code를응답한다.

이전에 비슷한 문제로 105,106 result code 응답시 요청 파라미터에 roadEvent를 추가 설정해주며 해결할 수 있었지만,

102/103 code의 경우 출발지/목적지의 좌표가 카카오 내부 좌표 데이터와 다르게 너무 큰 차이가 난다거나, 주변에 도로가 전혀 없는 것이 문제라고 판단했다.

우선 다른 장소들도 많지만 이슈가 생긴 "성산일출봉"을 기준으로 이슈를 해결하겠다.

현재 사용 중인 여행 장소 데이터셋은 한국관광공사 Tour API를 기반으로 하고 있다.

한국관광공사 Tour API의 성산 일출봉 좌표 값으로 구글맵에 적용해보면 주변 도로와 떨어진 곳에 좌표값이 설정되어 있다.

이를 해결하기 위해 2가지 해결방법을 떠올렸다.

1. 다중 출발지 길찾기/다중 목적지 길찾기의 요청 파라미터의 radius를 설정해주어 출발지/목적지의 길찾기 반경을 조절하여 해결한다.

2. 출발지/목적지의 주소 값을 이용하여 지오 코딩을 통해 도로와 출발지/목적지와 비슷한 근처 주차장및 적절한 좌표를 활용하여 해결한다. 지오코딩을 사용할 플랫폼은 카카오를 먼저 사용해본다. 같은 플랫폼이므로 똑같은 주소라도 좌표값이 카카오 서비스에 문제가 없는 좌표를 사용중 일 것 같다.

결론적으로 1안은 실패했다. 다중 출발지/목적지 길찾기의 radius는 10KM를 지원하지만, 한국관광공사 Tour API의 성산 일출봉 좌표 값이 도로와 상당히 떨어져 있어서 그런지 최대치로 요청해도 결과가 나오지 않았기 때문이다.

2안을 테스트할 차례이다. 우선 카카오맵 REST API를 사용하기 위해선행과정을 해야 한다.

카카오 맵 - 로컬 - REST API-주소로 좌표 변환으로 얻은 좌표를 구글맵에 적용해보면 주변에 도로가 가까이 있다.

이 좌표를 가지고 다시 다중 출발지/목적지 길찾기에 요청을 하면 당연히 200 OK와 정상적인 응답이 나온다.

또한 다중 출발지/목적지 길찾기를 쓰지않고 기존에 사용하던 자동차 길찾기 API에 요청해도 정상적으로 응답하게 된다.

카카오 플랫폼의 주소 - 좌표 변환 데이터 를 쓰게 되면 카카오의 자동차 길찾기 API가 문제 없이 작동한다.

나중에 운영환경을 위해서 비용을 고려하여 다른 주소 - 좌표 변환 API들과 비교 및 길찾기 요청을 추가적으로 해보았다.

구글의 경우 무료 사용 10,000건이후 유료이다.

카카오의 경우 일간 100,000건 무료 이므로 카카오를 계속 사용하는 것이 좋아 보인다.

정리

다중 길찾기 API는 무료 요청 제공량이 상대적으로 적기 때문에, 자동차 길찾기 실패 시 곧바로 다중 길찾기를 호출하기보다는 먼저 지오코딩을 수행한 후 자동차 길찾기를 재시도하는 방식을 사용한다.

1. 카카오 맵을 사용 권한을 활성하기 위해 사용설정을 하려고 했다.

하지만 카카오 맵 사용 권한을 활성화 하기위해 "추가 기능 신청"을 해야 된다고 뜬다.

테스트만 해보고 싶었던 건데 추가 기능 신청까지 해야되나?..

그래서 테스트 앱으로 시도해보기 위해 찾아보았다. 테스트 앱용 추가기능을 참고하자.

테스트 앱용에서 카카오 맵 사용설정이 바로 활성화 된다.

요청을 보내면 성공하게 된다. 테스트앱의 REST API KEY를 사용하여 카카오 맵 로컬 - 주소로 좌표 변환 요청을 보내면 성공하게 된다.

2. 개인 개발자 비즈앱-카카오 비즈니스 통합 서비스 약관 동의

3. 개인 개발자 비즈앱 전환버튼 클릭- 전환 목적 작성

4. 결과

프로젝트 초기에 회원 관련 API는 /auth, /members, /profile 세 가지 리소스로 나누어 사용하고 있었다.

• /auth → 회원/비회원 여부를 구분하는 용도
• /members → 회원 엔터티에 대한 CRUD와 동시에 로그인/로그아웃까지 담당
• /profile → 회원 활동 데이터 조회

그러나 REST API 설계 원칙을 다시 살펴보니 현재 구조는 문제가 있었다.

• /members에서 인증(로그인/로그아웃) 기능까지 담당하고 있었음
• /profile은 사실상 회원 엔터티(/members/{memberId})의 역할을 중복하고 있었음
• /auth는 단순히 회원/비회원을 구분하는 수준에 그치고 있었음

즉, 각 리소스의 역할이 뒤섞여 있어서, 실제 개발 과정에서 API의 역할을 직관적으로 파악하기 어려웠다. 결국 코드를 직접 확인하거나 프론트엔드에서 호출되는 API를 추적해야 무슨 역할을 하는지 알 수 있었다.

리팩토링 방향

• /members 회원 엔터티 자체를 다루는 리소스로 제한. → 회원가입(등록) 및 공개 가능한 회원 정보 조회 정도로만 사용.

• /auth 인증(Authentication) 전용 리소스. → 로그인, 로그아웃, 토큰 갱신 등 인증/인가와 직접 관련된 작업만 담당.

• /profile → /me /profile은 사실상 /members/{memberId}와 동일한 의미로 쓰이고 있었음. 하지만 REST 관례상 현재 로그인한 사용자 자신을 표현하는 /me가 더 직관적이므로 이를 대체 리소스로 사용. → 내 정보 조회, 내 활동(여행 일정 등) 조회/수정에 활용.

결론

/members — 회원 엔터티 관리

회원가입과 같은 비회원 등록 작업이나, 회원 목록·프로필 조회 등 공개 정보 제공이 필요한 상황에서 사용된다.

POST   /members                  # 회원가입
GET    /members                  # 회원 목록 조회 (예: 랭킹, 검색 결과)
GET    /members/{memberId}       # 특정 회원의 공개 프로필 조회

/me — 현재 로그인한 사용자

항상 현재 로그인한 나 자신을 의미하므로 별도의 식별자를 붙이지 않는다. 내 계정 정보와 내가 만든 활동 데이터를 조회·수정할 수 있다.

- 회원 자기 정보
GET    /me                  # 내 계정 정보
PATCH  /me/nickname         # 닉네임 수정
PATCH  /me/password         # 비밀번호 수정
DELETE /me                  # 회원 탈퇴

- 회원 활동 데이터
GET    /me/travel-plans     # 내가 만든 여행 일정 목록
GET    /me/travel-plans/42  # 내 여행 일정 단일 조회

/auth — 인증과 인가

/auth는 말 그대로 로그인, 로그아웃, 토큰 갱신 등 인증 관련 작업만을 담당한다. 회원 데이터나 프로필은 여기서 다루지 않는다.

- 로컬 로그인
POST   /auth/sign-in
POST   /auth/sign-out
POST   /auth/refresh         # JWT 재발급

- 로그인 여부 확인
GET    /auth/me              # 현재 로그인 상태 확인

spring & react를 사용해 MVP(Minimum viable Product) 프로젝트를 만드는 과정중 REST API END POINT를 리팩토링 하는 과정에서 처음 rest pai 설계 원칙을 참고하여 END POINT를 개발한 후 end point를 수정해야 했었다.

초기에는 빠르게 프로토 타입으로 프로젝트를 완성하는 것을 목표로 했기 때문에, REST API 설계 원칙을 완전히 이해하지 못한 채로 위 사진과 같이 엉성한 REST API를 구성하였었다.

그러나 리팩토링 시점에 이르러, API 버전 관리, 언더바(_) 사용, 명사의 단수/복수 표현, 리소스-식별자-서브 리소스 계층 구조를 제대로 지키지 않았던 문제들이 생겨났다.

그 결과, 단순히 End Point만 수정하는 과정임에도 불구하고 "이 API가 어떤 요청을 처리하는지"를 코드까지 열어봐야 이해할 수 있었습니다. 프론트엔드 개발 과정에서도, 특정 화면에 필요한 여러 개의 API 중 어떤 것이 어떤 데이터를 반환하는지 직관적으로 구분하기 어려웠습니다.

이를 통해 REST API 설계 원칙을 정확히 지키는 것의 중요성을 크게 깨닫게 되었고, 블로그를 통해 REST API 설계 원칙을 정리하고, 실제 리팩토링 과정을 기록해 두기로 했습니다.

REST API 원칙 및 제약

1. 일관된 인터페이스(Uniform Interface) URI로 지정한 리소스에 대한 조작을 통일하고 한정적인 인터페이스로 수행하여야 한다. 즉, API 설계자가 정한 HTTP METHOD와 규약으로만 수행할 수 있다.

2. 클라이언트-서버(Client — Server) 자원를 제공하는 쪽이 서버, 자원을 요청 하는 쪽을 클라이언트라 한다. 이 둘은 독립적으로 분리되어 구성되어야 한다. 각각 별도로 개발되고 대체 가능하도록 유지 해야 한다.

3. 무상태(Stateless) 작업에 대한 요청의 상태 정보를 저장하거나 관리 하지 않는다. 세션, 인증, 쿠키 등의 정보는 별도로 저장하기 때문에 요청에 대한 어떠한 상태 정보를 저장하지 않고 단순 처리할 수 있어야 한다. 이를 위해 모든 요청에는 필요한 모든 정보가 포함되어야 한다.

4. 캐시 가능(Cacheable) 서버는 캐시 가능 여부를 제공해야 한다. 캐시가 가능 할 경우 클라이언트는 응답 데이터를 재 사용 하여 성능과 서버의 가용성을 올릴 수 있다.

5.계층화된 시스템(Layered System) 계층화된 구조로 구성되어야 한다. 각 계층 자신이 통신하는 컴포넌트 외 다른 계층에 대한 정보를 얻을 수 없도록 분리되어야 한다.

REST API 설계 가이드 라인

• 명사형 리소스 사용하지 않는다. REST API NAMING을 위해서는 동사보다는 명사를 사용하는 것이 좋다. REST는 명사를 사용하여 리소스를 표현하고, HTTP METHOD를 이용하여 API의 동작을 표현하여 동사 역할을 하기 때문이다.

- BAD CASE
<https://api.example.com/members/getCart
- GOOD CASE
GET <https://api.example.com/members/cart>

• 복수형 명사를 사용한다. REST API의 RESOURCE는 자원이라고 볼 수 있다. RESOURCE는 단일 자원이 아닌 여러개의 자원(컬렉션)을 의미하므로 복수형을 사용하는 것이 자연스럽다. 그러므로 식별자를 추가로 사용하여 단일 자원을 얻을 수 있다.

- PLURAL CASE
GET https://api.example.com/orders
- SINGULAR CASE
GET https://api.example.com/orders/:orderId

팀에 따라 단일 자원을 반환 RESOURCE는 단수형 명사를 사용하기도 한다.

• 언버바(_) 사용하지 말고 하이픈(-)을 사용하라. URI를 쉽게 읽고 해석하기 위해서 하이픈(-)을 사용해 가독성을 높일 수 있다.

- BAD CASE
GET <https://api.example.com/productOptions/:optionId>
- GOOD CASE
GET <https://api.example.com/product-options/:optionId>

• 소문자를 사용하라. URL에서는 프로토콜과 호스트 주소는 대소문자를 구분하지 않지만 운영체제에 따라 구분하는 경우가 있으므로 소문자로 통일해서 사용하는것이 관례이다.

- BAD CASE
<https://api.example.com/products/1/Reviews>
- GOOD CASE
<https://api.example.com/products1/reviews>

• 리소스에 대한 식별이 필요한 경우에 PATH PARAMETER(/{ID})방식을 사용한다.

- BAD CASE
GET <https://api.example.com/orders/orderId?order-id=1>
- GOOD CASE
GET <https://api.example.com/orders/1>

• 컬렉션 필터링이 필요한 경우 쿼리 파라미터(query parameter)를 사용한다.(예시: 페이지네이션, 정렬 등)

- BAD CASE
GET <https://api.example.com/products/page/2/size/20>
- GOOD CASE
GET <https://api.example.com/products?page=2&size=20>

REST API 버전 관리 방법

URI versioning

https://api.example.com/v1/members/1

Request Parameter versioning

https://api.example.com/members/1?version=1

MIME type versioning

https://api.example.com/members/1
Accept: application/vnd.example.v1+json

Header versioning

https://api.example.com/members/1

- http header
API-Version: 1

가장 많이 사용되는 방식은 URI versioning이다.

요청/응답 규약 전략

Content-Type / Accept 헤더

요청(Request) 시에는 Content-Type으로 본문(body)의 형식을 명시한다. 응답(Response) 시에는 Accept 헤더를 참고하여 클라이언트가 원하는 형식(JSON, XML 등)을 반환한다. 일반적으로 REST API에서는 application/json을 기본으로 사용한다.

- 요청 예시
POST /api/v1/members HTTP/1.1
Content-Type: application/json
Accept: application/json

응답 래핑 (Response Wrapping)

가능하다면 리소스 자체를 그대로 반환한다.

불필요하게 data, result 같은 추가 래퍼(wrapper) 객체로 감싸지 않는다.

- BAD CASE
{
  "data": {
    "id": 1,
    "name": "Alice"
  }
}

- GOOD CASE
{
  "id": 1,
  "name": "Alice"
}

빈 컬렉션 처리

빈 배열은 null이 아닌 빈 배열([]) 로 반환한다.

이 방식이 클라이언트 단에서 처리하기 가장 일관적이다.

- BAD CASE
NULL
- GOOD CASE
[], {}

없는 리소스 처리

존재하지 않는 단일 리소스는 404 Not Found 상태코드로 반환한다. 빈 응답 대신 명확한 상태코드를 사용해야 한다.

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "errorCode": "MEMBER_NOT_FOUND",
  "message": "해당 회원을 찾을 수 없습니다."
}

고민

REST 중첩 리소스를 어떻게 해결해야 하는가?

소규모 프로젝트에서는 리소스 중첩의 Depth가 얕아 크게 문제가 되지 않는다. 하지만 프로젝트 규모가 커질수록 중첩 구조가 점점 깊어질 수 있고, 그럴 경우 URL의 가독성과 유지보수성이 급격히 떨어진다. 이를 해결하기 위해 보통 중첩 구조(Nested Resource) 를 평탄화(Flat Resource) 방식으로 풀어내는 전략을 사용한다. 예시:

2중첩

• nested resource

  # 스토어의 상품 목록
  GET /stores/10/products
  

상품의 리뷰 목록

GET /products/200/reviews

주문의 아이템 목록

GET /orders/555/items

- flat resource
```http
# 스토어의 상품 목록
GET /products?storeId=10

# 상품의 리뷰 목록
GET /reviews?productId=200

# 주문의 아이템 목록
GET /order-items?orderId=555

3중첩

• nested resource

  # 스토어의 특정 카테고리 상품 목록
  GET /stores/10/categories/3/products
  

고객의 특정 주문의 아이템 목록

GET /customers/99/orders/555/items

상품의 특정 옵션(variant)의 재고 이력

GET /products/200/variants/12/inventories

- flat resource
```http
# 스토어의 특정 카테고리 상품 목록
GET /products?storeId=10&categoryId=3

# 고객의 특정 주문의 아이템 목록
GET /order-items?customerId=99&orderId=555

# 상품의 특정 옵션(variant)의 재고 이력
GET /inventories?productId=200&variantId=12

4중첩

• nested resource

  # 스토어 → 카테고리 → 상품 → 리뷰
  GET /stores/10/categories/3/products/200/reviews
  

고객 → 주문 → 아이템 → 반품

GET /customers/99/orders/555/items/7/returns

스토어 → 상품 → 옵션(variant) → 가격 변경 이력

GET /stores/10/products/200/variants/12/price-changes

- flat resource
```http
# 스토어 → 카테고리 → 상품 → 리뷰
GET /reviews?storeId=10&categoryId=3&productId=200

# 고객 → 주문 → 아이템 → 반품
GET /returns?customerId=99&orderId=555&itemId=7

# 스토어 → 상품 → 옵션(variant) → 가격 변경 이력
GET /price-changes?storeId=10&productId=200&variantId=12

직접 예시를 만들어 보면, 3중첩부터는 평탄화(flat) 하는 편이 가독성과 재사용성 측면에서 유리해 보인다. 2중첩의 경우도 상황에 따라 flat 대안이 좋을 수 있지만, 예를 들어 GET /products/200/reviews처럼 목록을 “어느 문맥에서 보느냐”가 중요한 경우에는 2중첩을 유지하는 것이 더 자연스러울 때가 있다.

결국 Path Param은 리소스 식별, Query Param은 필터/정렬/페이지네이션, Body는 리소스 표현(생성/수정 데이터) 이라는 원칙 아래 상황에 맞게 유연하게 선택하는 것이 바람직하다. 단일 리소스 조회/수정/삭제는 가능하면 flat으로 두고, 목록·생성 컨텍스트는 2중첩까지는 허용, 3중첩 이상은 flat로 풀기를 기본 가이드로 삼는것이 바람직해 보인다.

Stack은 사전 정의 그대로 "쌓다"라는 뜻을 가지고 있다. 즉, 접시에 음식을 쌓아 올리듯 데이터를 차곡차곡 쌓아올리는 것을 말한다. 이렇게 아래 그림과 같이 스택은 마지막에 저장한 데이터를 가장 먼저 꺼내게 되는데 이러한 자료 구조를 LIFO구조라고 한다.

Java의 Stack이란?

java의 stack class는 vactor class를 상속 받고 있으므로 Thread-Safe하다는 특징이 있다.

추가로 java로 stack을 구현할경우 java.util.stack을 사용하여 구현 해도 되지만 Java의 Stack 구현체인 Vector는 동기화된 메서드로 구현되어 있어 멀티 쓰레드 환경에 안전하게 구현되어 있기 때문에 단일 쓰레드 환경에서는 성능상 불리하다. 한 예로 아래 Stack Class의 push 메서드의 구현체를 보면 synchronized가 붙어 있다.

• stack.push()

    public E push(E item) {
        addElement(item);
  
        return item;
    }
  

- stack.push()의 구현체 addElement()
```java

public synchronized void addElement(E obj) {
        modCount++;
        add(obj, elementData, elementCount);
    }

Java 공식문서에서도 스택을 Stack Class보다 Deque Class를 사용하라고 권장하고 있다.

정리하자면 나는 취준 코테를 준비하므로 java.util.stack class를 이용할 생각이다. 코딩테스트 풀이 예시들을 보면 대부분 Stack 클래스를 활용해 구현하는 경우가 많다. 다만, 시간 제한이나 성능이 중요한 문제에서는 Deque를 스택처럼 활용하는 것이 더 효율적인 선택이 될 수 있다.

Java로 구현해보기

package stack;

import java.util.ArrayDeque;
import java.util.Deque;

public class Stack {
    public static void main(String[] args) {
        //stack 생성
        java.util.Stack<String> stack = new java.util.Stack<>();
        stack.push("A");
        stack.push("B");
        stack.push("C");

        // 1. push() : 데이터 삽입
        System.out.println("push 후 stack: "+stack);

        // 2. peek() : 최상단 원소 확인 (삭제 안 됨)
        System.out.println("peek(): " + stack.peek());
        System.out.println("peek 후 stack: " + stack);

        // 3. pop() : 최상단 원소 꺼내기
        System.out.println("pop(): " + stack.pop());
        System.out.println("pop 후 stack: " + stack);

        //4. 성능 측정 테스트
        runBenchmark();


    }

    /**
     * 2. Stack vs Deque 성능 비교 메서드
     */
    private static void runBenchmark() {
        System.out.println("\n=== Stack vs Deque 성능 비교 ===");
        for (int n = 1; n <= 1_000_000; n *= 10) {
            long stackTime = benchmarkStack(n);
            long dequeTime = benchmarkDeque(n);

            System.out.printf("[N=%d] Stack: %.3f ms | Deque: %.3f ms%n",
                    n, stackTime / 1_000_000.0, dequeTime / 1_000_000.0);
        }
    }

    /**
     *  Stack 성능 측정
     */
    private static long benchmarkStack(int n) {
        java.util.Stack<Integer> stack = new java.util.Stack<>();
        long start = System.nanoTime();
        for (int i = 0; i < n; i++) stack.push(i);
        for (int i = 0; i < n; i++) stack.pop();
        return System.nanoTime() - start;
    }

    /**
     *  Deque 성능 측정
     */
    private static long benchmarkDeque(int n) {
        Deque<Integer> deque = new ArrayDeque<>();
        long start = System.nanoTime();
        for (int i = 0; i < n; i++) deque.push(i);
        for (int i = 0; i < n; i++) deque.pop();
        return System.nanoTime() - start;
    }
}

실행결과:

push 후 stack: [A, B, C]
peek(): C
peek 후 stack: [A, B, C]
pop(): C
pop 후 stack: [A, B]

=== Stack vs Deque 성능 비교 ===
[N=1] Stack: 0.008 ms | Deque: 0.006 ms
[N=10] Stack: 0.005 ms | Deque: 0.004 ms
[N=100] Stack: 0.037 ms | Deque: 0.027 ms
[N=1000] Stack: 0.308 ms | Deque: 0.343 ms
[N=10000] Stack: 0.579 ms | Deque: 0.635 ms
[N=100000] Stack: 3.794 ms | Deque: 2.663 ms
[N=1000000] Stack: 21.302 ms | Deque: 19.855 ms

Process finished with exit code 0

전체적으로 Deque를 활용한 스택 구현이 Stack 클래스보다 성능 면에서 우위를 보였다. 따라서 코딩테스트에서는 큰 차이가 없을 수 있지만, 실제 프로젝트 환경에서는 Deque를 사용하는 것이 더 바람직한 것 같다.

인증된 사용자 요청 처리 과정

1. 사용자가 로그인 요청을 보내고, 서버는 인증에 성공하면 Access Token과 Refresh Token이 포함된 JWT를 발급한다.
2. JWT는 Bearer 방식이므로, 클라이언트는 이후 요청 시 Authorization 헤더에 Bearer <Access Token>형식으로 토큰을 포함해 서버에 요청을 보낸다.
3. 서버는 Spring Security의 FilterChain을 통해 요청을 가로채고, JwtAuthenticationFilter에서 Authorization 헤더를 추출하여 JwtTokenProvider.validateToken()을 통해 토큰의 유효성을 검증한다. 이후 검증이 성공하면 SecurityContextHolder에 인증 정보를 등록한다.
4. 인증이 완료된 요청만 Spring Security의 인증 절차를 통과하여 Controller로 전달되며, 컨트롤러는 해당 요청을 처리하게 된다.
5. 예를 들어, 사용자 정보를 조회하는 요청의 경우 컨트롤러에서는 @AuthenticationPrincipal 또는 SecurityContextHolder를 통해 현재 인증된 사용자 정보를 조회한 후 응답을 반환한다.

코딩을 시작하기 전 이런 의문이 생겼다.

SecurityContextHolder의 인증 정보가 계속 유지되는가?

filterChain

    public SecurityFilterChain filterChain(HttpSecurity httpSecurity) throws Exception {
        return httpSecurity
                .httpBasic(Customizer.withDefaults())
                .csrf(AbstractHttpConfigurer::disable)
                .sessionManagement(session ->session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
                .authorizeHttpRequests(auth -> auth
                        .requestMatchers("/members/login","/members/sign-in", "/members/sign-in/test").permitAll()
                        .requestMatchers("/members/test").hasRole("USER")
                        .anyRequest().authenticated()
                )
                .addFilterBefore(new JwtAuthenticationFilter(jwtTokenProvider), UsernamePasswordAuthenticationFilter.class).build();
    }

위 SecurityConfig에서 SessionCreationPolicy.STATELESS 설정을 보면 알 수 있듯, JWT는 상태를 저장하지 않는(Stateless) 인증 방식이다. 즉, 서버는 로그인 상태나 인증 세션을 별도로 유지하지 않는다.

또한 Spring Security의 SecurityContextHolder는 ThreadLocal 기반으로 동작하므로, 하나의 HTTP 요청에 대해서만 인증 정보를 유지하고, 요청이 끝나면 해당 Context는 자동으로 사라진다.

따라서 "한 번 인증된 사용자의 정보가 계속 유지되는가?" 같은 고민은 하지 않아도 된다. 모든 요청은 JWT 토큰을 통해 매번 독립적으로 인증되기 때문이다.

SecurityContextHolder 사용방식

SecurityConfig

http.authorizeHttpRequests(auth -> auth
        .requestMatchers("/members/test").hasRole("USER")
        .anyRequest().authenticated()
);
http.addFilterBefore(new JwtAuthenticationFilter(jwtTokenProvider), UsernamePasswordAuthenticationFilter.class);

SecurityConfig에서 인증된 사용자만 접근 가능하도록 엔드포인트를 지정하고 JWT 인증 필터를 등록한다.

MemberController

    @GetMapping("/test")
    public ResponseEntity<MemberInfo> getMemberTest() {
        Member member = memberService.getMemberInfo();
        return ResponseEntity.ok(MemberInfo.builder()
                .name(member.getName())
                .signInId(member.getUsername())
                .email(member.getEmail())
                .gender(member.getGender())
                .birthday(member.getBirthday())
                .score(member.getScore())
                .level(member.getLevel())
                .win(member.getWin())
                .lose(member.getLose())
                .build());
    }

인증이 완료된 요청을 처리하기 위한 Controller를 설계한다.

MemberService

    public Member getMemberInfo() {
        Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
        String userName = authentication.getName();
        log.info("인증된 사용자 이름:{}", userName);

        return memberRepository.findByUsername(userName)
                .orElseThrow(() -> new UserNotFoundException(userName));

    }

JwtAuthenticationFilter에서 JWT의 유효성 검증이 완료되면, 해당 토큰의 사용자 정보를 담은 Authentication 객체가 SecurityContextHolder에 저장되었기 때문에

MemberService에서 SecurityContextHolder.getContext().getAuthentication()을 통해 인증된 사용자의 username을 조회할 수 있으며, 이를 통해 DB에서 해당 사용자의 상세 정보를 조회할 수 있다.

요청 결과

인증 및 권한 확인이 모두 완료되었기 때문에, 서버는 요청을 성공적으로 처리하고 클라이언트에 HTTP 200 OK 응답과 함께 결과를 반환한다.

@AuthenticationPrincipal 사용방식

@AuthenticationPrincipal은 Spring Security에서 현재 인증된 사용자의 정보를 컨트롤러 메서드 파라미터로 주입받을 수 있도록 도와주는 어노테이션이다.

처음에는 단순히 @AuthenticationPrincipal과 Member를 사용하면 바로 사용자 정보를 조회할 수 있을 거라 생각했다.

MemberController

@GetMapping("/test")
    public ResponseEntity<MemberInfo> getMemberTest(@AuthenticationPrincipal Member member) {

                return ResponseEntity.ok(MemberInfo.builder()
                .name(member.getName())
                .signInId(member.getUsername())
                .email(member.getEmail())
                .gender(member.getGender())
                .birthday(member.getBirthday())
                .score(member.getScore())
                .level(member.getLevel())
                .win(member.getWin())
                .lose(member.getLose())
                .build());
    }

하지만 실제 실행 결과는 500 서버 오류였다.

로그를 확인해보니 다음과 같은 NPE(NullPointerException)가 발생했다

java.lang.NullPointerException: Cannot invoke "com.agora.debate.member.entity.Member.getName()" because "member" is null

문제 원인 분석

분명히 JWT 토큰을 검증하는 JwtAuthenticationFilter에서 다음과 같이 User를 등록했었다. ** JwtTokenProvier.getAuthentication()**

        UserDetails principal = new User(claims.getSubject(), "", authorities);
        return new UsernamePasswordAuthenticationToken(principal, "", authorities);

문제는 principal에 Spring Security의 기본 User 객체를 사용했다는 점이다.

컨트롤러에서는 @AuthenticationPrincipal Member member로 주입을 받으려 했기 때문에, 타입이 맞지 않아 null이 주입된 것이다.

즉, SecurityContextHolder에 등록된 객체는 User인데, @AuthenticationPrincipal은 이를 Member로 캐스팅할 수 없으니 null이 된 것이다.

        Member member = memberRepository.findByUsername(claims.getSubject())
                .orElseThrow(() -> new UsernameNotFoundException("사용자를 찾을 수 없습니다."));

        return new UsernamePasswordAuthenticationToken(member, "", authorities);

해결방법

JwtTokenProvider.getAuthentication()에서 User 대신 내가 직접 구현한 Member를 principal로 등록하면 된다.

이렇게 수정하면 SecurityContextHolder에 등록된 객체가 Member가 되므로, 컨트롤러에서 @AuthenticationPrincipal Member member를 통해 정상적으로 사용자 정보를 주입받을 수 있다.

@AuthenticationPrincipal을 사용하려면 SecurityContextHolder에 등록되는 principal 객체가 실제로 주입받으려는 타입(Member 또는 CustomUserDetails)과 일치해야 한다.

결론

처음에는 SecurityContextHolder.getContext().getAuthentication()를 통해 인증 정보를 직접 꺼내서 사용하는 방식도 고려했지만, 코드의 가독성과 의도를 명확하게 전달하기 위해 @AuthenticationPrincipal을 사용하는 방식으로 정리하였다.

이 어노테이션을 사용하면 컨트롤러에서 바로 인증된 사용자 객체를 주입받을 수 있어 코드가 훨씬 간결해지고, 비즈니스 로직에 집중할 수 있는 장점이 있다.

따라서 이후 인증된 사용자 정보가 필요한 컨트롤러에서는 @AuthenticationPrincipal을 통해 일관성 있게 처리할 예정이다.

build.gradle

    //스프링 시큐리티
    implementation 'org.springframework.boot:spring-boot-starter-security'
    implementation 'io.jsonwebtoken:jjwt-api:0.11.5'
    runtimeOnly 'io.jsonwebtoken:jjwt-impl:0.11.5'
    runtimeOnly 'io.jsonwebtoken:jjwt-jackson:0.11.5'

2. JWT Token DTO 생성

클라이언트에게 토큰을 발급해주기 위해 JwtToken DTO을 생성해준다.

@Builder
@Data
@AllArgsConstructor
public class JwtToken {
    private String grantType;
    private String accessToken;
    private String refreshToken;
}

JwtToken의 필드중 grantType은 JWT에 대한 인증 타입이다. 인증 타입에 대해서 잘 모르므로 널리 사용되는 "Bearer"방식을 사용할 것이다. ex) Authorization: Bearer

Bearer 인증 방식이란 ? ACCESS TOKEN을 HTTP REQEUST HEADER의 Authorization을 포함하여 전송하는 방식이다.

3. 암호키 설정

JWT를 만들 때, 토큰의 서명(Signature)을 생성하는 데 사용할 암호화 키를 설정해야 한다.

openssl rand -hex 32

생성된 secret key를 application.properties에서 설정한다.(필자의 경우, application-scret.properties에 설정함) application-scret.properties

jwt.secret=your_secret_key

4. JwtTokenProvider 구현

Spring Security와 JWT 토큰을 사용하여 인증과 권한 부여를 처리하는 클래스이다.JWT 토큰의 생성, 복호화, 검증 기능을 구현한 클래스이다. 이후 로그인 기능에서 JWT를 생성하고 JwtAuthenticationFilter에서 유효성 검사를 하는데 사용된다.

@Component
public class JwtTokenProvider {
    private final Key key;

    public JwtTokenProvider(@Value("${jwt.secret}") String secretKey) {
        byte[] keyBytes = Decoders.BASE64.decode(secretKey);
        this.key = Keys.hmacShaKeyFor(keyBytes);
    }

    public JwtToken generateToken(Authentication authentication) {
        String authorities = authentication.getAuthorities().stream()
                .map(GrantedAuthority::getAuthority)
                .collect(Collectors.joining(","));

        long now = (new Date()).getTime();

        Date accessTokenExpiresIn = new Date(now + 86400000);
        String accessToken = Jwts.builder()
                .setSubject(authentication.getName())
                .claim("auth", authorities)
                .setExpiration(accessTokenExpiresIn)
                .signWith(key, SignatureAlgorithm.HS256)
                .compact();

        String refreshToken = Jwts.builder()
                .setExpiration(new Date(now + 86400000))
                .signWith(key, SignatureAlgorithm.HS256)
                .compact();

        return JwtToken.builder()
                .grantType("Bearer")
                .accessToken(accessToken)
                .refreshToken(refreshToken)
                .build();
    }

    public Authentication getAuthentication(String accessToken) {
        // Jwt 토큰 복호화
        Claims claims = parseClaims(accessToken);

        if (claims.get("auth") == null) {
            throw new RuntimeException("권한 정보가 없는 토큰입니다.");
        }

        Collection<? extends GrantedAuthority> authorities = Arrays.stream(claims.get("auth").toString().split(","))
                .map(SimpleGrantedAuthority::new)
                .collect(Collectors.toList());

        UserDetails principal = new User(claims.getSubject(), "", authorities);
        return new UsernamePasswordAuthenticationToken(principal, "", authorities);
    }

    public boolean validateToken(String token) {
        try {
            Jwts.parserBuilder()
                    .setSigningKey(key)
                    .build()
                    .parseClaimsJws(token);
            return true;
        } catch (SecurityException | MalformedJwtException e) {
            log.info("Invalid JWT Token", e);
        } catch (ExpiredJwtException e) {
            log.info("Expired JWT Token", e);
        } catch (UnsupportedJwtException e) {
            log.info("Unsupported JWT Token", e);
        } catch (IllegalArgumentException e) {
            log.info("JWT claims string is empty.", e);
        }
        return false;
    }


    // accessToken
    private Claims parseClaims(String accessToken) {
        try {
            return Jwts.parserBuilder()
                    .setSigningKey(key)
                    .build()
                    .parseClaimsJws(accessToken)
                    .getBody();
        } catch (ExpiredJwtException e) {
            return e.getClaims();
        }
    }

}

generateToken()

Spring Security의 Authentication 객체에서 권한정보(Authorities)를 추출한 후, 이를 쉼표(,)로 구분된 문자열로 반환하여 JWT의 클레임(auth)에 저장할 수 있도록 가공한다.

AccessToken는 다음과 같이 생성된다. Header 기본적인 헤더는 자동으로 설정되므로 따로 설정하지 않았다. Payload 만료시간(exp): setExpiration(accessTokenExpiresIn) 제목(sub): setSubject(authentication.getName()) 권한정보(auth): claim("auth", authorities) Signature signWith(key, SignatureAlgorithm.HS256) 를 설정하고 signature(signWith)을 설정해준다.

refreshToken은 Access Token을 재발급받기 위한 용도로 사용되므로 만료시간,과 서명정보만 생성한다.

5. getAuthentication()

Access token을 복호화하여 사용자의 인증 정보(Authentication)를 생성한다. parseClaims()를 사용하여 권한 정보를 추출하여 권한 정보가 없을경우 RuntimeException을 일으킨다.

Collection<? extends GrantedAuthority>로 리턴받는 이유? 권한 정보를 다양한 타입의 객체로 처리할 수 기 떄문이다.

GrantedAuthority란? Authorities이라는 목록의 타입이다. Collection와 같은 형태를 의미한다. 필자는 GrantedAuthority의 대표적 구현체인 SimpleGrantedAuthority를 사용했다. SimpleGrantedAuthority는 문자열로 역할(예: "USER")을 하는 객체이다. 최종적으로 Collection=[SimpleGrantedAuthority("USER"),SimpleGrantedAuthority("ADMIN")]과 같은 형태를 가진다.

Authentication란? SicurityContext에 의해 관리하고 Authentication는 principal, Credentials, Authorities로 구성되어 있다. 참고

validateToken()

토큰의 유효성을 검증한다. 토큰의 서명키를 설정하여 예외 처리를 통해 토큰의 유효성 여부를 판단한다. SecurityException | MalformedJwtException : 서명(Signature)이 잘못되었거나, JWT 형식이 잘못된 경우 ExpiredJwtException : 토큰의 exp(만료시간)가 지나서 더 이상 사용할 수 없는 경우 UnsupportedJwtException : 지원되지 않는 JWT 구조나 알고리즘인 경우 IllegalArgumentException : 토큰이 null이거나 빈 문자열인 경우

parseClaims()

AccessToken을 복호화하여 서명(Signature)을 검증하고 payload의 claim들을 반환한다. 만료된 토큰인 경우에도 Clam들을 반환한다.

6. JwtAuthenticationFilter 구현

클라이언트 요청 시 JWT 인증을 하기 위해 설치하는 커스텀 필터로 이후 구현할 SecurityConfig에서 addFilterBefore()를 통해 UsernamePasswordAuthenticationFilter 이전에 JwtAuthenticationFilter가 실행되게 할 것이다.

클라이언트의 요청에서 JWT 토큰의 유효성 검사를 하고 해당 토큰의 인증 정보(Authentication)를 Security Context에 저장하여 인증된 요청을 처리할 수 있도록 설정한다.

@RequiredArgsConstructor
public class JwtAuthenticationFilter extends GenericFilterBean {
    private final JwtTokenProvider jwtTokenProvider;

    @Override
    public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException {

        HttpServletRequest httpRequest = (HttpServletRequest) request;

        String path = httpRequest.getRequestURI();

        // 필터를 적용하지 않을 경로 설정
        if (path.startsWith("/members/sign-in") || path.startsWith("/members/sign-in/test")
                || path.startsWith("/members/signup")) {
            chain.doFilter(request, response);
            return;
        }

        String token = resolveToken(httpRequest);


        if (token != null && jwtTokenProvider.validateToken(token)) {
            Authentication authentication = jwtTokenProvider.getAuthentication(token);
            SecurityContextHolder.getContext().setAuthentication(authentication);
        }
        chain.doFilter(request, response);
    }

    private String resolveToken(HttpServletRequest request) {
        String bearerToken = request.getHeader("Authorization");
        if (StringUtils.hasText(bearerToken) && bearerToken.startsWith("Bearer")) {
            return bearerToken.substring(7);
        }
        return null;
    }
}

doFilter()

회원가입, 로그인, 필터 작동 테스트에서는 필터가 작동하지 않게 설정. jwtTokenProvider에서 작성한 validateToken()을 사용하여 토큰의 유효성을 검사하고 jwtTokenProvider.getAuthentication()을 이용하여 Authentication객체를 생성한 후 SecurityContext에 Authentication를 저장한다.

resolveToken()

HttpServletRequest의 Header에서 토큰을 추출하여 반환한다.

Bearer 방식에서는 JWT가 Authorization 헤더에 "Bearer <토큰값>" 형식으로 포함된다.

7. SecurityConfig 구현

Spring Security의 설정을 담당한다.

@Configuration
@EnableWebSecurity
@RequiredArgsConstructor
public class SecurityConfig {
    private final JwtTokenProvider jwtTokenProvider;

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity httpSecurity) throws Exception {
        return httpSecurity
                .httpBasic(Customizer.withDefaults())
                .csrf(AbstractHttpConfigurer::disable)
                .sessionManagement(session ->session.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
                .authorizeHttpRequests(auth -> auth
                        .requestMatchers("/members/login","/members/sign-in", "/members/sign-in/test").permitAll()
                        .requestMatchers("/members/test").hasRole("USER")
                        .anyRequest().authenticated()
                )
                .addFilterBefore(new JwtAuthenticationFilter(jwtTokenProvider), UsernamePasswordAuthenticationFilter.class).build();
    }

    @Bean
    public PasswordEncoder passwordEncoder() {
        // BCrypt Encoder 사용
        return PasswordEncoderFactories.createDelegatingPasswordEncoder();
    }

}

filterChain()

REST API이므로 basic auth 및 csrf보안을 사용하지 않는다. JWT를 사용하므로 세션을 사용하지 않는다. 권한별로 요청을 허가하도록 요청에 대한 인가 규칙 설정한다. JWT 인증을 위하여 직접 구현한 필터를UsernamePasswordAuthenticationFilter 전에 실행한다.

requestMatchers를 통해 회원가입, 로그인, 필터 작동 테스트의 요청을 권한이 없어도 요청을 허가했지만 JwtAuthenticationFilter에서 다시 필터를 적용하지 않을 경로 설정한 이유?

passwordEncoder()

DelegatingPasswordEncoder를 사용하여 기본 인코딩 알고리즘을 "bcrypt"로 설정하며, 동시에 여러 인코딩 방식을 지원할 수 있는 구조를 설정한다.

8. 인증을 위한 Entity, Repository 설정

자신의 프로젝트에 맞는 Entity를 설정하고 UserDetails interface를 구현한다. 혼동을 피하기 위해 username은 사용자 ID로 사용되며 인증은 username과 password를 이용하여 진행한다.

package com.agora.debate.member.entity;

import com.agora.debate.global.enums.Gender;
import jakarta.persistence.*;
import lombok.*;
import org.springframework.security.core.GrantedAuthority;
import org.springframework.security.core.authority.SimpleGrantedAuthority;
import org.springframework.security.core.userdetails.UserDetails;

import java.time.LocalDate;
import java.util.ArrayList;
import java.util.Collection;
import java.util.List;
import java.util.stream.Collectors;

/**
 * TODO: @EqualsAndHashCode(of = "id")공부
 */
@Entity
@Table(name = "member")
@Builder
@EqualsAndHashCode(of = "id")
@Getter
@NoArgsConstructor(access = AccessLevel.PROTECTED)
@AllArgsConstructor
@ToString
public class Member implements UserDetails {
    @Id
    @GeneratedValue(strategy = GenerationType.IDENTITY)
    @Column(name = "member_id")
    private Long id;

    @Column(nullable = false,unique = true)
    private String name;

    @Column(name = "username", nullable = false, unique = true)
    private String username;

    @Column(nullable = false)
    private String password;

    @Column(nullable = false, unique = true)
    private String email;

    @Enumerated(EnumType.STRING)
    @Column(nullable = false)
    private Gender gender;

    @Column(name = "birth_date", nullable = false)
    private LocalDate birthday;

    @Builder.Default
    @Column(nullable = false)
    private int score=100;

    @Builder.Default
    @Column(nullable = false)
    private int level=1;

    @Builder.Default
    @Column(nullable = false)
    private int win=0;

    @Builder.Default
    @Column(nullable = false)
    private int lose=0;

    @ElementCollection(fetch = FetchType.EAGER)
    @CollectionTable(name = "member_roles", joinColumns = @JoinColumn(name = "member_id"))
    @Column(name = "role")
    @Builder.Default
    private List<String> roles = new ArrayList<>();
    @Override
    public Collection<? extends GrantedAuthority> getAuthorities() {
        return this.roles.stream()
                .map(SimpleGrantedAuthority::new)
                .collect(Collectors.toList());
    }

    //Default=true
    @Override
    public boolean isAccountNonExpired() {
        return UserDetails.super.isAccountNonExpired();
    }
    //Default=true
    @Override
    public boolean isAccountNonLocked() {
        return UserDetails.super.isAccountNonLocked();
    }
    //Default=true
    @Override
    public boolean isCredentialsNonExpired() {
        return UserDetails.super.isCredentialsNonExpired();
    }
    //Default=true
    @Override
    public boolean isEnabled() {
        return UserDetails.super.isEnabled();
    }
}

getAuthorites()

멤버가 가지고 있는 권한 목록(rloes)을 SimpleGrantedAuthority로 변환하여 반환한다.

MemberRepository

@Repository
public interface MemberRepository extends JpaRepository<Member, Long> {
    ....

    Optional<Member> findByUsername(String username);

    ....

}

9. 로그인을 위한 signIn Service 구현

    @Transactional
    public JwtToken signIn(SignInDto signInDto) {
        memberRepository.findByUsername(signInDto.getUsername())
                .orElseThrow(() -> new UserNameNotMatchException());

        UsernamePasswordAuthenticationToken authenticationToken = new UsernamePasswordAuthenticationToken(signInDto.getUsername(), signInDto.getPassword());

        Authentication authentication = null;

        try {
            authentication = authenticationManagerBuilder.getObject().authenticate(authenticationToken);
        } catch (AuthenticationException e) {
            throw new BadCredentialsException("authentication실패");
        }
        JwtToken jwtToken = jwtTokenProvider.generateToken(authentication);
        return jwtToken;
    }

사용자 존재 여부 확인 사용자의 입력값(username, password)을 기반으로 Authentication객체 생성한다. authenticate() 메서드를 통해 요청된 Member에 대한 검증 진행한다. 이떄 authenticate()가 내부적으로 loadUserByUsername()을 (아래 CustomUserDetailsService()에서 구현 예정) 검증에 성공시 인증된 Authentication객체를 기반으로 jwtTokenProvider.generateToken()을 이용하여 JWT토큰을 생성한다.

10. CustomUserDetailsService 구현

@Service
@RequiredArgsConstructor
public class CustomUserDetailsService implements UserDetailsService {

    private final MemberRepository memberRepository;

    @Override
    public UserDetails loadUserByUsername(String username) {
        return memberRepository.findByUsername(username)
                .map(this::createUserDetails)
                .orElseThrow(() -> new UsernameNotFoundException("해당하는 회원을 찾을 수 없습니다."));
    }

    private UserDetails createUserDetails(Member member) {
        return User.builder()
                .username(member.getUsername())
                .password(member.getPassword())
                .roles(member.getRoles().toArray(new String[0]))
                .build();
    }

}

Spring Security에서 제공하는 UserDetailsService 인터페이스를 구현한 클래스이다. 로그인 시 입력된 username을 기반으로 사용자 정보를 조회하고, Spring Security가 인증에 사용할 수 있도록 UserDetails 객체로 변환해 반환한다.

JWT(Json Web Token)란 인증에 필요한 정보들을 암호호시킨 JSON 토큰을 의미한다. 보통 JWT와 같은 토큰기반 인증 방식은 토큰을 HTTP 헤더에 실어 서버가 클라이언트를 식별하는 방식이다.

JWT 데이터는 BASE-64URL를 통해 인코딩하여 직렬화한것이다. 토큰 내부의 위변조 방지를 위하여 개인키 암호화 방식을 사용한 전자 서명도 들어 있다.

직렬화란? 데이터를 저장하거나 전송할 수 있도록 문자열과 같은 형식으로 변환하는 과정을 말한다.

따라서 서버는 로그인 등의 인증 과정에서 사용자에게 JWT를 발급해준다. 사용자는 이후 요청 시 이 JWT를 함께 전송하고, 서버는 토큰의 유효성을 검증한 뒤 요청을 처리하고 응답을 반환한다.

사용자가 로그인에 성공하면 서버는 인증 수단으로 JWT를 발급한다. 이 토큰은 자격 증명 역할을 하기 때문에 보안에 특히 주의해야 하며, 브라우저의 로컬스토리지나 세션스토리지에 민감한 정보를 장기간 저장하는 것은 권장되지 않는다.

JWT 구조

JWT는 "."을 구분자로 직렬화된 세가지 문자열의 조합이다. "."을 기준으로 Header, Payload, Signature을 의미한다.

Header에는 JWT에서 사용할 타입과 알고리즘 종류가 담겨져 있다.

Header에는 JWT에서 사용할 타입과 알고리즘 종류가 담겨져 있다. alg:서명 암호화 알고리즘 종류(HAMC,RSA,ECDSA 등) typ: 토큰 유형

Payload

Payload는 사용자 권한 정보와 데이터(Claim)가 들어있다.

Clam이란? key-value 형식으로 이루어진 한쌍의 정보

클레임은 Registered claims, Public claims, Private claims으로 세가지로 나뉜다. Registered claims(미리 정의된 클레임): sub(제목), name(발행자),iat(발행시간), exp(만료시간)등이 있다.

Public claims: 사용자가 정의할 수 있는 클레임 Private claims: 동의한 당사자들 간에 정보를 공유하기 위해 작성된 클레임으로 등록되지도 않고, 공개되지도 않는다.

Signature

Signature 는 Header, Payload를 Base64-URL로 인코딩한 후 헤더에서 지정된 알고리즘을 가져와서 서명한다.

Signature 구조는 인코딩된 Header와 Payload외 개인키(secret)을 합쳐서 암호화한 값이다.

HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  secret)

서명은 메시지가 전송 중에 변경되지 않았는지 확인하는 데 사용되며, 개인 키로 서명된 토큰의 경우 JWT를 보낸 사람이 본인인지 확인할 수도 있습니다.

Header와 Payload는 단순히 인코딩된 값이기 때문에 제 3자가 복호화 및 조작할 수 있지만, Signature는 서버 측에서 관리하는 비밀키가 유출되지 않는 이상 복호화할 수 없다. 따라서 Signature는 토큰의 위변조 여부를 확인하는데 사용된다.

JWT 인증 과정

1. 사용자가 ID, PW를 입력하여 서버에 로그인 인증을 요청한다.
2. 서버는 클라이언트에게 요청받으면 Header, PayLoa, Sinature를 정의한다. Header, PayLoa, Sinature를 암호화하며 JWT를 생성하고 클라이언트에게 발급한다.
3. 서버로부터 발급받은 JWT를 저장 후 header에 Authorization을 담아서 요청을 보낸다.
4. 서버는 request header에서 Authorization에 담긴 JWT가 자신의 서버에서 발행한 토큰인지 검증 후 일치한다면 인증을 통과시켜주고 요청을 처리한다.

만약 ACCESS TOKEN의 시간이 만료되었다면 서버는 401 Unauthorized 로 응답한다. 클라이언트가 REFRESH TOKEN을 통해 서버에게 새로운 ACCESS TOKEN을 발급받고 요청을 보내야 한다.

참고자료

JWT https://jwt.io/introduction https://inpa.tistory.com/entry/WEB-%F0%9F%93%9A-JWTjson-web-token-%EB%9E%80-%F0%9F%92%AF-%EC%A0%95%EB%A6%AC#jwt_%EA%B5%AC%EC%A1%B0

스프링 시큐리티(Spring Security)는 스프링 기반의 애플리케이션 보안(인증, 인가, 권한)을 담당하는 스프링 하위 프레임워크이다. 스프링 시큐리티에서는 주로 서블릿 필터(filter)와 이들로 구성된 필터체인으로의 구성된 위임 모델을 사용한다.

용어

• 접근 주체(Principal): 보호된 리소스에 접근하려는 사용자 또는 시스템이다. 일반적으로 로그인한 사용자 정보를 의미한다.
• 인증(Authentication): 인증은 '증명하다'라는 의미로 예를 들어, 유저A가 아이디와 비밀번호를 이용하여 로그인하는 과정에서 유저 A가 맞는지 증명하는 것을 말한다.
• 인가(Authorization): '허가'와 같은 의미로 사용된다. 인증된 사용자가 요청한 리소스를 사용할 수 있는 권한이 있는지 검사하는것을 의미한다.
• 권한(Roles): 사용자가 시스템에서 수행할 수 있는 기능이나 리소스 접근 권한이다.

기본 동작 구조

스프링 시큐리티의 동작 구조는 공식문서에 따르면 다음과 같다.

스프링 시큐리티는 서블릿 필터기반으로 동작한다. 서블릿 필터는 서블릿 실행에 대한 전처리 및 후처리를 실행하는 역할이다.

클라이언트가 요청을 보내면, WAS는 이 요청을 웹 컨테이너를 통해 처리한다. 웹 컨테이너는 요청 URI를 기반으로 어떤 서블릿이 처리할지 결정하고, 그 서블릿과 관련된 FilterChain(Filter 목록 + 서블릿)을 생성한다. 이 FilterChain은 먼저 여러 Filter들을 실행하며 요청을 가공하거나 보안을 적용한 뒤,최종적으로 서블릿(예: DispatcherServlet)을 실행해 초기화된 서블릿으로 처리를 넘긴다.

DelegatingFilterProxy

하지만 서블릿 컨테이너는 Spring에서 정의한 Bean을 인식하지 못한다. 이를 해결하기 위해 Spring은 DelegatingFilterProxy라는 Filter구현체를 제공한다.

public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) {
    Filter delegate = getFilterBean(someBeanName); //1
    delegate.doFilter(request, response);  //2
}

1. Spring Bean으로 등록된 Filter를 지연해서 가져온다.
2. 위임된 Filer를 수행한다.

이렇게 DelegatingFilterProxy는 서블릿 Filter의의 기능을 Bean Filter로 위임하여 실행할 수 있도록 해준다. 즉, DelegatingFilterProxy는 Bean Filter를 Filter로 위임하는 중간 다리 역할을 해준다.

FilterChainProxy

FilterChainProxy는 스프링 시큐리티(Spring Security)가 제공하는 특수한 Filter 구현체로 SecurityFilterChain를 통해 여러개의 SecurityFilterChain을 위임할 수 있게 해준다. FilterChainProxy도 Spring에서 제공하는 Bean이므로 서블릿 컨테이너에 직접 등록되지 않고DelegatingFilterProxy 로 매핑된다.

SecurityFilterChain

SecurityFilterChain은 FilterChainProxy가 현재 요청에 대해 어떤 Security Filter를 호출해야 할지 결정하는데 사용된다.

Security Filtersms Bean이지만 DelegatingFilterProxy대신에 FilterChainProxy에 등록된다. 그러므로 FilterChainProxy는 스프링 시큐리티(Spring Sicurity)의 시작점 역할을 한다. FilterChainProxy는 SecurityFilterChain을 통해 여러 Filter 인스턴스로 위임하여 실행할수 있다.

또한 여러 개의 SecurityFilterChain을 설정해두고, FilterChainProxy를 통해 요청 URL에 따라 각각의 SecurityFilterChain을 매핑하여 적용할 수 있다. 특정 요청에 대해 스프링 시큐리티가 무시하려면, SecurityFilterChain에 보안 Filter를 0개 설정하면 된다.

그럼 인증(Authentication)된 객체가 어떻게 저장될까?

SecurityContextHolder

Spring Security에서는 인증(Authentication) 정보를 SecurityContextHolder를 통해 전역적으로 관리한다.
실제로는 인증에 성공한 사용자의 Authentication 객체가 SecurityContextHolder가 보유한 SecurityContext 내부에 저장된다.

이 SecurityContext는 일반적으로 ThreadLocal기반으로 동작하여, 각 요청 스레드마다 독립된 인증 정보를 안전하게 분리하여 관리할 수 있도록 한다.

Authentication

• Principal 유저에 대한 정보를 가지고 있다.
• Credentials 인증에 사용되는 자격 증명 정보 (예: 비밀번호, 토큰 등).
  인증이 완료되면 보안상의 이유로 null로 설정되는 경우가 많다.
  • Authorities 유저의 권한 정보를 가지고 있다. 사용자가 가진 권한 목록을 담고 있으며, 내부적으로는 GrantedAuthority의 리스트로 구성된다.

Spring Security Structure

1. Http Request 사용자가 /login 요청을 보냄 (아이디/비밀번호 포함)

2. AuthenticationFilter UsernamePasswordAuthenticationFilter가 요청을 가로채고,

사용자가 입력한 아이디/비밀번호를 가지고 UsernamePasswordAuthenticationToken 객체 생성

3. AuthenticationManager로 토큰 전달 AuthenticationFilter는 AuthenticationManager에게 위에서 만든 토큰을 넘김

4. AuthenticationManager는 실제 인증을 AuthenticationProvider에 위임 일반적으로 사용되는 구현체는 ProviderManager임

5. AuthenticationProvider → UserDetailsService 사용 인증을 처리하기 위해 UserDetailsService의 loadUserByUsername() 호출

6. UserDetailsService가 DB에서 User 정보 조회 아이디로 사용자를 찾고, 비밀번호, 권한 정보 등을 포함한 UserDetails 객체를 리턴

7. UserDetails를 기반으로 Authentication 객체 생성 AuthenticationProvider는 아이디/비밀번호가 일치하면, 인증 완료 상태의 Authentication 객체를 생성하고 반환

8. AuthenticationManager → 인증 성공 결과 반환 최종적으로 인증된 Authentication 객체를 AuthenticationManager가 AuthenticationFilter에 반환

9. AuthenticationFilter가 인증 성공 시 SecurityContext에 저장 SecurityContextHolder.getContext().setAuthentication(...) 호출

10. SecurityContextHolder에 인증 정보 저장 완료 이후부터는 이 정보(Authentication)를 통해 사용자 정보, 권한 등을 어디서든 사용할 수 있음 (예: @AuthenticationPrincipal 등)

처음에는 아래와 같이 직접 유효성 검사 클래스를 만들어 Controller에서 Service 호출 전에 명시적으로 검증하려고 했다.

초기 설계

public class SignUpValidator {

    public String checkId(String target) {

    }
    public String checkLoginId(String target) {

    }
    public String checkPassword(String target) {

    }
    public String checkEmail(String target) {

    }
    public String checkGender(String target) {

    }
    public LocalDate checkBirthday(LocalDate target) {

    }
}

초기 설계 방안으로 utils 패키지에 SignUpValidator 클래스를 만들어 controller에서 service로 회원가입 사이클을 시작하기 전에 SignUpValidator를 수행하려고 했다. 하지만 vaild 로직은 어떤 프로젝트에서도 사용되므로 관련 애노테이션이 있다고 생각하고 찾아보았다.

Spring에서는 이미 이를 위해 표준화된 @Valid, @Validate, @GroupSequence등 여러 애노테이션을 제공하고 있었다.

@Valid란?

@Valid는 JSR-303 표준 스펙으로써 빈 검증기(Bean Validator)를 이용해 객체의 제약 조건을 검증하도록 지시하는 어노테이션이다. JSR 표준의 빈 검증 기술의 특징은 DTO나 VO 객체의 필드에 달린 어노테이션으로 편리하게 검증을 한다는 것이다.

@Valid 사용법

 @PostMapping
    public String checkId(@RequestBody @Valid SignUpDto signUpDto,
    Errors errors) {}

public class SignUpDto {

    @NotBlank
    private String name;

    @NotBlank
    private String loginId;

    @Pattern(regexp = "(?=.*[0-9])(?=.*[a-zA-Z])(?=.*\\\\W)(?=\\\\S+$).{8,16}\n")
    private String password;
    }

이렇게 유효성 검사가 필요한 Request 객체에 @Valid 어노테이션을 사용해 유효성 검사를 적용할 수 있다.

유효성 검사 애노테이션 종류

@Validate란?

@Validated 어노테이션은 org.springframework.validation 안에 있는 어노테이션이다. 공식문서의 내용에 따르면 "Variant of JSR-303's Valid, supporting the specification of validation groups","but also optionally specifying the validation groups for method-level validation in the annotated class."라고 한다. 즉, @Validated 어노테이션은 @Valid의 확장이며, "Validation Group"을 지원한다는 사실을 알 수 있다. 즉, @Validated는 @Valid와 비슷하지만 검증 그룹(Validation Group)을 사용할 수 있는 기능이 추가된 Spring 고유의 애노테이션이다.

Validation Group 사용법

1. 유효성 검사 그룹을 식별하기 위한 “마커 인터페이스(Marker Interface) 생성. 참조 용도로만 사용되기 때문에 어떠한 동작을 실행하는 기능이 없는 빈 인터페이스여야 한다.

   public class ValidationGroups {
    public interface SignUpGroup { }
    public interface UserUpdateGroup { }
   

}

2. DTO에서 그룹 적용
```java
public class SignUpDto {

    // 닉네임: 한글, 영문, 숫자 2~15자
    @NotBlank(groups = {ValidationGroups.SignUpGroup.class, ValidationGroups.UserUpdateGroup.class})
    @Pattern(
            regexp = "^[가-힣a-zA-Z0-9]{2,15}$",
            message = "닉네임은 한글, 영문, 숫자 조합 2~15자여야 합니다.",
            groups = {ValidationGroups.SignUpGroup.class, ValidationGroups.UserUpdateGroup.class}
    )
    }

3. 컨트롤러에서 그룹 유효성 검사

   @PostMapping
    public String checkId(@RequestBody @Validated(ValidationGroups.SignUpGroup.class) SignUpDto signUpDto, Errors errors)

4. 결과 확인

Cursor IDE는 VS Code 기반이긴 하지만, 기본 제공되는 Git GUI 기능에서는 커밋 템플릿을 불러오지 못하기 때문에 불편했다. 특히 커밋 메시지를 일정한 형식으로 작성하려는 경우에는 따로 지원되는 내장 기능이나 플러그인이 없어서 CLI를 함께 사용하는 게 훨씬 낫다는 결론에 도달했다.

그래서 다음과 같은 흐름으로 Git 브랜치 전략을 구성하고 사용하기로 했다:

1. Jira 이슈 페이지에서 브랜치를 생성하면 원격 브랜치가 자동으로 만들어진다.

2. 로컬에서는 동일한 이름의 브랜치를 수동으로 생성한다.

3. 해당 로컬 브랜치를 원격 브랜치와 트래킹(tracking) 연결한 후 작업한다.

   master branch (원격, 최종 통합 브랜치)
   └─ feature/화면, 메인, 유저 등 (원격, 기능 단위 브랜치)
   └─ local branch (로컬, 개발자 단위 브랜치)
   

   결론적으로, Jira에서 기능 단위 원격 브랜치를 만들고, 로컬 브랜치에서 작업한 후 master로 병합하는 구조로 통일해나갈 계획이다.

REMOTE BRANCH와 LOCAL BRANCH이란?

기존에는 IntelliJ 기반으로 Git을 사용했기 때문에, 새 브랜치를 만들면 자동으로 로컬 브랜치와 원격 브랜치가 같은 이름으로 연동되어 생성되는 경우가 많았다. 그래서 로컬과 원격 브랜치의 차이나 트래킹 개념을 정확히 인식하지 못한 채 작업해왔던 것이다.

그러나 Cursor IDE에서는 Git CLI 사용을 하게 되면서 로컬 브랜치 / 원격 브랜치 / 트래킹 브랜치의 개념을 명확하게 이해해야만 브랜치 관리가 가능했다.

로컬 브랜치가 원격 브랜치와 트래킹된 상태라면, git push만으로도 자동으로 연결된 브랜치로 푸시할 수 있다.

CLI에서 GIT 사용 해보기

1. 깃허브와 리액트 프로젝트 연동

지라에서 원격 브랜치 생성 후

git checkout - b "로컬브랜치" "원격 브랜치" 원격 브랜치와 로컬 브랜치 트래킹 설정을 하였다.

2.git commit message template적용

git config --global commit.template "커밋 메시지 템플릿 주소"를 통해 커밋 메시지 템플릿을 적용했다.

CLI에서 최신정보 반영하는방법

현재 이 상황은 다음과 같았다.

origin/master       ← 최신 코드 있음
   ↑
   │   (반영하고 싶은 내용)
   ↓
INOUT-41-debate-stage  ← 작업 중인 로컬 브랜치 

git checkout INOUT-41-debate-stage을 하여 내가 업데이트할 로컬 브랜치로 이동한다.

git fetch origin을 하여 원격 브랜치 최신 정보 가져온 후, git merge origin/master를 통해 origin/master의 최신 내용을 병합한다.

성공했다면 아래 사진과 같은 흐름을 보이며 정상적으로 master 브랜치의 코드가 성공적으로 병합된다.

기존의 여행지 동기화 코드는 tourSpotItems 리스트를 돌면서 다음과 같은 구조를 가지고 있었습니다:

for (PlaceResponse.PlaceItem placeItem : tourSpotItems) {
    // 1. contentId로 Place 조회
    Optional<Place> findPlace = placeService.findByContentId(placeItem.getContentid());

    if (findPlace.isPresent()) {
        // 2. Place가 존재하면, AreaCode와 CityCode를 조회하여 변경사항 비교
        AreaCode areaCode = areaCodeService.findByAreaCode(
            cityCodeService.findAreaCodeByCityCode(
                findPlace.get().getCityCode().getCityCode()
            ).orElseThrow(...)
        ).orElseThrow(...);

        // 3. 변경된 내용이 있으면 업데이트
        ...
    } else {
        // 4. Place가 존재하지 않으면 AreaCode와 CityCode를 조회하여 새로 저장
        AreaCode areaCode = areaCodeService.findByAreaCode(placeItem.getAreacode())
            .orElseThrow(...);
        CityCode cityCode = cityCodeService.findByCityCodeAndAreaCodeId(
            placeItem.getSigungucode(), areaCode.getAreaCodeId()
        ).orElseThrow(...);

        placeService.save(...);
    }
}

}

빅오(Big-O) 분석

placeItems 개수가 N개라고 할 때,

매 placeItem마다 3번의 select 쿼리가 발생한다.

따라서 전체 쿼리 수는 O(N) x O(3N) 이다.

하지만, 쿼리당 네트워크 I/O 및 DB 접근 시간이 고정으로 존재하기 때문에, 결국 전체 처리 시간은 선형적으로 오래 걸리게 된다.

현실적인 문제

예를 들어 총 50000개의 데이터를 저장해야된다면,

총 3번 × 50000 = 약 15만 번의 DB 왕복 쿼리 발생

실제로 처리 시간이 32분이나 소요되었다...

2. 개선 방법

개선 목표

• DB 왕복 횟수를 극적으로 줄인다.
• 메모리에서 빠른 연산이 가능한 구조를 만든다.

개선 아이디어

• Place, AreaCode, CityCode를 초기에 모두 한번에 조회해서 메모리에 올린다.
• 검색할 때마다 Map을 활용해 O(1) 시간복잡도로 빠르게 찾는다.

개선된 코드 주요 구조

Map<String, Place> existingPlaces = placeService.findAllByContentIdIn(contentIds)
    .stream()
    .collect(Collectors.toMap(Place::getContentId, Function.identity()));

Map<String, AreaCode> areaCodeMap = areaCodeService.findAll()
    .stream()
    .collect(Collectors.toMap(AreaCode::getAreaCode, Function.identity()));

Map<String, List<CityCode>> cityCodeMap = cityCodeService.findAll()
    .stream()
    .collect(Collectors.groupingBy(cityCode -> cityCode.getAreaCode().getAreaCode()));

이후 for문 구조

for (PlaceResponse.PlaceItem placeItem : tourSpotItems) {
    Place existingPlace = existingPlaces.get(placeItem.getContentid());
    AreaCode areaCode = areaCodeMap.get(placeItem.getAreacode());
    CityCode cityCode = cityCodeMap.getOrDefault(placeItem.getAreacode(), List.of())
        .stream()
        .filter(c -> c.getCityCode().equals(placeItem.getSigungucode()))
        .findFirst()
        .orElse(null);
    // 이후 저장 또는 수정
}

빅오(Big-O) 분석

초기에 Place, AreaCode, CityCode 조회: 각각 1번의 select (총 3번)

for문 순회는 순수 메모리 연산

Map 조회는 O(1) 시간복잡도 따라서 전체 쿼리 수는 O(N) + O(3N) 이다.

최종 빅오

전체 처리 시간: O(N) (메모리 접근만)

DB 왕복 쿼리: O(3) (초기 한번씩만)

3. 결과

기존: 32분 소요 (DB 왕복 15만 번)

개선: 약 2~3분 소요 (DB 왕복 3번)

4. 결론

데이터량이 많은 경우, DB에서 자주 읽지 말고 미리 캐싱하자.

Map을 이용하면 O(1)로 빠르게 데이터 접근이 가능하다.

Stream과 Collectors를 이용해 초기 메모리 세팅을 깔끔하게 할 수 있다.

• 리뷰(review) 테이블에 추천 수를 나타내는 컬럼이 없어, 사용자 피드백을 수치화하거나 정렬 기준으로 활용하기 어렵다.
• 여행 경로 저장을 위한 테이블이 부재하여, 일정 간 장소 간 이동 경로를 명확히 표현하기 어렵다.
• 이동 수단을 저장하는 테이블이 존재하지 않아, 이동 방식에 따른 시간/거리 정보를 관리하기 어렵다.
• 여행지와 숙소가 각각 별도의 테이블로 분리되어 있어, 여행 경로를 from → to 형태로 저장할 때 장소 간 연결 정보를 설계하는 데 복잡함이 발생한다.

장소 테이블 통합으로 구조 간소화

이를 해결하기 위해, 여행지와 숙소를 하나의 place 테이블로 통합하고,place_type 컬럼을 도입하여 장소의 유형(숙소/관광지/음식점 등)을 구분하도록 구조를 변경하였다.

여행지, 숙소, 음식점 등을 하나의 place_id로 통일하여 처리할 수 있게 되었고, 장소 간 이동 경로를 저장하는 travel_plan_route에서는 from_place_id, to_place_id만으로 명확하게 경로를 표현할 수 있게 되었다.

개인 프로젝트를 시작하면서, 외부 API 데이터를 수집해 데이터베이스에 저장하기 위해 간단한 구조의 ERD를 먼저 설계하고, WebClient를 이용한 데이터 수집 및 저장 작업을 시작했습니다.

초기에는 단순한 여행지 정보만 처리할 계획이었기 때문에, ERD도 최소한의 구조로 간단하게 설계하여 개발을 시작했습니다. 하지만 프로젝트를 진행하면서 기능을 추가하거나 수정하는 과정에서 전체적인 방향을 충분히 정리하지 않은 채 작업을 이어가다 보니, DB 구조가 계속 변경되었고, 여기에 DB 설계 역량이 부족했던 점까지 더해져 테이블을 반복적으로 수정하는 데 많은 시간을 소모하게 되었습니다. 그 결과, 기존 테이블 구조의 변경은 물론 테이블 간 관계 설정도 반복적으로 손봐야 하는 상황이 발생하게 되었습니다.

특히, 외부 API의 데이터 구조를 충분히 분석하지 않고 개발을 서둘렀던 점이 이후 구조 변경의 가장 큰 원인이 되었다.

ERD 재설계

DB 구조를 어차피 전반적으로 수정해야 하는 상황이었기 때문에, 기존 ERD의 문제점부터 파악해보았습니다. 처음에는 외부 API에서 제공하는 식별값(content_id 등)을 PK로 사용하면 안 된다는 개념에 익숙하지 않아, 중간에 대체 키(id)를 도입하긴 했지만, 설계에 일관성이 없어서 오히려 불필요하거나 애매한 구조가 되었습니다.

이에 따라 ERD를 전면적으로 수정하며 다음과 같은 원칙을 적용했습니다:

• 모든 테이블에 내부 식별용 id를 AUTO INCREMENT로 생성하여 기본키(PK)로 사용
• 외부 API가 제공하는 식별값(content_id 등)은 비즈니스 키로 보고 UNIQUE 제약조건만 부여

이러한 구조로 변경함으로써, 외래 키(FK)가 비즈니스 키의 변경에 영향을 받는 문제를 예방할 수 있었고, 데이터의 정합성과 유지보수성도 함께 개선할 수 있었습니다.

개선된 ERD

1. 지라 로그인 - 앱 - 더 많은 앱 살펴보기

2.검색창에 github for jira 검색 후 클릭

3. getapp을 하여 Atlassian과 github 연동하기

4. add another organization - Select an organization in Git-Hub을 클릭 후 open할 repo를 선택한다.
5. jira github 연동 결과

Jira 이슈와 GitHub 브랜치 연동

https://roll-over-program.tistory.com/78 위 블로그 참고하여 branch연동

이슈키를 포함하여 branch를 생성하고 git commit message에 이슈키를 포함하여 commit을 해야 jira에서 이슈 추적이 자동으로 된다 그러므로 git commit message template을 수정해야할듯

github action로 jira issue 자동화하기

참고 블로그: https://velog.io/@sangpok/Github-%ED%98%91%EC%97%85-%EC%84%A4%EC%A0%95Github-Issue-Jira-%EC%97%B0%EB%8F%99

1. github repository secret 등록하기

1. secrets를 등록하고 싶은 github repo에 접속한 뒤에, "Settings>Security>Secrets and variables >Actions" 탭에 접근해 나오는 페이지에서 하단 "New repository secret"을 누른다.

Name에는 변수명을, Secret에는 값을 입력하고 "add secret"을 누른다.

GitHub에 저장된 Secrets 값은 워크플로우 파일 안에서 ${{ secrets.VARIABLE_NAME }} 형태로 불러올 수 있다. 예를 들어, Jira 로그인을 위해 아래와 같이 환경 변수를 설정하면 된다:

env:
  JIRA_BASE_URL: ${{ secrets.JIRA_BASE_URL }}
  JIRA_API_TOKEN: ${{ secrets.JIRA_API_TOKEN }}
  JIRA_USER_EMAIL: ${{ secrets.JIRA_USER_EMAIL }}

2. .github/ISSUE_TEMPLATE 작성

name: '이슈 생성'
description: 'Repo에 이슈를 생성하며, 생성된 이슈는 Jira와 연동됩니다.'
labels: [feat]
title: '이슈 이름을 작성해주세요'
body:
  - type: input
    id: parentKey
    attributes:
      label: '🎟️ 상위 작업 (Ticket Number)'
      description: '상위 작업의 Ticket Number를 기입해주세요'
      placeholder: 'INOUT-00'
    validations:
      required: true

  - type: input
    id: branch
    attributes:
      label: '🌳 브랜치명 (Branch)'
      description: '영어로 브랜치명을 작성해주세요'
    validations:
      required: true

  - type: input
    id: description
    attributes:
      label: '📝 상세 내용(Description)'
      description: '이슈에 대해서 간략히 설명해주세요'
    validations:
      required: true

  - type: textarea
    id: tasks
    attributes:
      label: '✅ 체크리스트(Tasks)'
      description: '해당 이슈에 대해 필요한 작업목록을 작성해주세요'
      value: |
        - [ ] Task1
        - [ ] Task2
    validations:
      required: true

3. .github/workflows/create-jira-issye.yml 작성

name: Create Jira issue
on:
  issues:
    types:
      - opened
jobs:
  create-issue:
    name: Create Jira issue
    runs-on: ubuntu-latest
    steps:
      - name: Login
        uses: atlassian/gajira-login@v3
        env:
          JIRA_BASE_URL: ${{ secrets.JIRA_BASE_URL }}
          JIRA_API_TOKEN: ${{ secrets.JIRA_API_TOKEN }}
          JIRA_USER_EMAIL: ${{ secrets.JIRA_USER_EMAIL }}

      - name: Checkout main code
        uses: actions/checkout@v4
        with:
          ref: main

      - name: Issue Parser
        uses: stefanbuck/github-issue-praser@v3
        id: issue-parser
        with:
          template-path: .github/ISSUE_TEMPLATE/issue-form.yml

      - name: Log Issue Parser
        run: |
          echo '${{ steps.issue-parser.outputs.issueparser_parentKey }}'
          echo '${{ steps.issue-parser.outputs.__ticket_number }}'
          echo '${{ steps.issue-parser.outputs.jsonString }}'

      - name: Convert markdown to Jira Syntax
        uses: peter-evans/jira2md@v1
        id: md2jira
        with:
          input-text: |
            ### Github Issue Link
            - ${{ github.event.issue.html_url }}

            ${{ github.event.issue.body }}
          mode: md2jira

      - name: Create Issue
        id: create
        uses: atlassian/gajira-create@v3
        with:
          project: SKP
          issuetype: Task
          summary: '${{ github.event.issue.title }}'
          description: '${{ steps.md2jira.outputs.output-text }}'
          fields: |
            {
              "parent": {
                "key": "${{ steps.issue-parser.outputs.issueparser_parentKey }}"
              }
            }

      - name: Log created issue
        run: echo "Jira Issue ${{ steps.issue-parser.outputs.parentKey }}/${{ steps.create.outputs.issue }} was created"

      - name: Checkout develop code
        uses: actions/checkout@v4
        with:
          ref: develop

      - name: Create branch with Ticket number
        run: |
          ISSUE_NUMBER="${{ steps.create.outputs.issue }}"
          ISSUE_TITLE="${{ steps.issue-parser.outputs.issueparser_branch}}"
          BRANCH_NAME="${ISSUE_NUMBER}-$(echo ${ISSUE_TITLE} | sed 's/ /-/g')"
          git checkout -b "${BRANCH_NAME}"
          git push origin "${BRANCH_NAME}"

      - name: Update issue title
        uses: actions-cool/issues-helper@v3
        with:
          actions: 'update-issue'
          token: ${{ secrets.GITHUB_TOKEN }}
          title: '[${{ steps.create.outputs.issue }}] ${{ github.event.issue.title }}'

      - name: Add comment with Jira issue link
        uses: actions-cool/issues-helper@v3
        with:
          actions: 'create-comment'
          token: ${{ secrets.GITHUB_TOKEN }}
          issue-number: ${{ github.event.issue.number }}
          body: 'Jira Issue Created: [${{ steps.create.outputs.issue }}](${{ secrets.JIRA_BASE_URL }}/browse/${{ steps.create.outputs.issue }})'

issue가 close될떄도 처리하기 위한 close-jira-issue.yml도 추가했다.

name: Close Jira issue
on:
  issues:
    types:
      - closed

jobs:
  close-issue:
    name: Close Jira issue
    runs-on: ubuntu-latest

    steps:
      - name: Login to Jira
        uses: atlassian/gajira-login@v3
        env:
          JIRA_BASE_URL: ${{ secrets.JIRA_BASE_URL }}
          JIRA_API_TOKEN: ${{ secrets.JIRA_API_TOKEN }}
          JIRA_USER_EMAIL: ${{ secrets.JIRA_USER_EMAIL }}

      - name: Extract Jira issue key from GitHub issue title
        id: extract-key
        run: |
          ISSUE_TITLE="${{ github.event.issue.title }}"
          JIRA_KEY=$(echo "$ISSUE_TITLE" | grep -oE '[A-Z]+-[0-9]+')
          echo "JIRA_KEY=$JIRA_KEY" >> $GITHUB_ENV

      - name: Close Jira issue
        if: env.JIRA_KEY != ''
        uses: atlassian/gajira-transition@v3
        with:
          issue: ${{ env.JIRA_KEY }}
          transition: Done

4. Github Action 권한 설정

settings - Actions -General탭에 접근하여 Read and Write Permission 체크하기

5. github Actions 테스트

먼저 GitHub의 Issues 탭에 들어가서 새로운 이슈를 작성해준다.

이슈를 생성하면, 자동으로 실행되는 GitHub Actions를 Actions 탭에서 확인할 수 있다.

정상적으로 작동했다면, 아래와 같이 Jira에 자동으로 이슈가 생성된 것도 확인할 수 있다.

원래는 생성된 Jira 이슈 상태에 따라 작업 브랜치를 자동으로 상위 브랜치에 병합되도록 GitHub Actions로 자동화를 시도했었다. 예를 들어, Sub-task는 Task 브랜치로, Task는 Epic 브랜치로, 그리고 최종적으로 Epic은 master 브랜치로 병합되도록 하는 구조였는데, 아직 Git 사용에 익숙하지 않다 보니 현재는 브랜치 병합은 수동으로 진행하고 있다. 추후 Git 사용에 익숙해지면 이 부분도 다시 자동화할 예정!

Sub-task 생성 삽질기

위 글의 .github/workflows/create-jira-issye.yml를 보면 완성된 코드가 이미 들어가 있지만 task(모든 기타 표준 이슈 유형) 유형 이슈에서 Sub-task(모든 하위 작업 이슈 유형) 유형 이슈를 연동해주는 과정에서 발생한 에러에 대한 내용이다.

우선 jira의 이슈 계층 구조는 다음과 같다.

1. Epic 가장 상위 계층 (hierarchyLevel: -1) 하위로는 표준 이슈 유형들만 가능 (예: Task, Story, Bug 등) ❌ Sub-task는 직접적으로 Epic 밑에 둘 수 없음

2. Standard Issue Types (모든 기타 표준 이슈 유형)(hierarchyLevel: 0) 예: Task, Story, Bug 등 상위: Epic 가능 ✅ 하위: Sub-task 가능 ✅

3. Sub-task(모든 하위 작업 이슈 유형) (hierarchyLevel: -1) 반드시 표준 이슈 유형(Task, Story 등)의 하위로만 생성 가능 ❌ Epic의 직접 하위가 될 수 없음

위 구조는 기본적으로 jira free tier에서 고정된 계층 구조이다. 그러므로 당연히 Sub-task가 Task와 연동 될 줄 알았다. issue를 만들어보면 다음과 같은 에러가 생긴다.

관리자 설정과 프로젝트 설정 모두 'Sub-task'를 설정해주어도 오류가 해결되지 않았지만 프로젝트 설정> 하위작업을 'Sub-task'로 통일하니깐 해결되었다(모든 name을 통일해 줘야 하는듯 왠래 '하위 작업'으로 표시되어 있었는데 같은 의미인줄 알고 내버려 둿었다.)

변경 후 실행 결과:

참고

1.설정되지 않은 issueType을 설정하면 이렇게 오류가 생긴다.

2. 존재하지 않는 branch를설정하면 생기는 오류

      - name: Checkout jiratest code
        uses: actions/checkout@v4
        with:
          ref: 존재하지 않는 branch

      - name: Checkout jiratest code
        uses: actions/checkout@v4
        with:
          ref: main

존재하는 branch로 수정하면 해결된다.

예전에 팀 프로젝트를 진행할 땐 개인적으로 기획서는 문서로, 일정은 캘린더로, 소통은 디스코드, 카카오톡을 같이 사용했었다. 처음엔 괜찮았지만, 시간이 지날수록 업무 메시지랑 개인 메시지가 섞이고, 회의 내용은 디스코드에 정리했지만 결국 기억에 의존하거나 코드 주석으로 메모하는 식으로 진행하게 됐었다.

근데 그렇게 하다 보니 전체적인 흐름을 파악하기가 점점 어려워졌고,회의 내용도 정해진 템플릿 없이 그때그때 대충 메모하는 식으로 작성되다 보니 정작 나중에 회의록을 봐도 무슨 얘길 했는지 잘 기억이 안 났다.

예를 들어 "이번 주에 누구가 로그인 기능 맡기로 했음" 이런 식으로만 적어두고, 구체적인 마감 기한이나 어떤 방식으로 구현할지 같은 중요한 내용은 빠지는 경우가 많았다. 그러다 보니 일정이 밀리거나, 서로 다른 방식으로 작업해서 충돌이 생기는 경우도 종종 있었다. 그래서 이번 프로젝트에선 처음부터 Jira를 도입해보기로 했다.

협업 툴이 워낙 많긴 하지만, Jira는 프로젝트의 흐름을 타임라인으로 추적할 수 있고, 작업 보드에서 각자의 할 일과 진행 상황을 한눈에 파악할 수 있어서 꽤 만족스러웠다. 특히 팀원 간 업무가 어떻게 분배되어 있는지도 명확하게 보여서, 소통할 때 훨씬 수월해졌다.

새로운 개인 프로젝트를 시작하면서, 이전 프로젝트들에서의 Git 커밋 메시지 작성 습관을 되돌아보게 되었다. 그동안은 기능을 구현할 때마다 메시지를 간단하게 "xx 기능 구현 완료"라고 작성하거나, 때로는 아예 커밋 메시지를 생략하기도 했다.

이러한 방식은 처음에는 편하게 느껴졌지만, 나중에 해당 코드를 수정하거나 회귀할 때 큰 불편함이 있었다. 과거의 커밋 메시지를 확인해봐도 어떤 작업을 했는지 명확하게 파악하기 어려워 결국 코드를 다시 처음부터 읽고, 그때의 의도를 기억해내려 애써야 했기 때문이다.

그래서 이번에는 커밋 메시지를 좀 더 체계적으로 관리하기로 마음먹었다. 잘 정리된 블로그 글을 참고하면서, Git 커밋 메시지 템플릿을 활용해 커밋 기록을 명확하고 일관성 있게 남기려 한다.

Commit Message 7가지 규칙

1. 제목과 본문을 한 행으로 구분
2. 제목은 영문 기준 50자 이내 작성
3. 제목 첫글자는 대문자로 작성
4. 제목 끝에 마침표(.) 금지
5. 제목은 명령문으로 작성
6. 본문의 각 행은 72자 내로 작성
7. 본문은 어떻게보다 무엇을, 왜에 맞춰 작성

커밋 메시지 기본구조

커밋 메세지의 구조는 공식 가이드라은 없지만 기본적으로 Subject, Body, Footer세 부분으로 나뉘며, 각 부분을 한 줄의 공백으로 구분한다.

type :  Subject

body

footer

Git Commit Type 명세표

내가 사용할 Git Commit Message Template

# type: Subject

# 본문

# ----------------------------------------
#  Type 종류
# ----------------------------------------
# ADD       : 새로운 코드나 파일 추가
# MODIFY    : 기존 기능 수정
# FIX       : 버그 수정
# DOCS      : 문서(주석, README 등) 수정
# REMOVE    : 코드나 파일 삭제
# IMPLEMENT : 무언가의 전체 동작을 "구현"했을 때 사용 (ADD보다 큰 단위)
# TEST      : 테스트 코드 추가 및 수정
# RENAME    : 파일명, 변수명, 함수명 등의 이름 변경
# MOVE      : 코드나 파일 이동
# CHORE     : 빌드/패키지 매니저 설정 등 기타 작업

# ----------------------------------------
#  제목(Subject) 작성 규칙
# ----------------------------------------
# - 제목 작성 후 반드시 한 줄 띄워서 본문과 구분
# - 제목은 대문자로 시작, 마침표는 쓰지 않음
# - 제목은 명령문으로 작성 

# ----------------------------------------
#  본문(Body) 작성 규칙
# ----------------------------------------
# - 본문 작성 후 한 줄 띄워서 Resolves 영역과 구분
# - 각 행은 72자 이내로 작성
# - "무엇을", "왜" 했는지를 중심으로 작성
# - 본문은 여러 줄로 구성 가능

git commit message template 적용하기

ntelliJ - File - Settings - Plugin에 가서 commit message template을 사용하여 적용하였다.

위 플러그인은 설치후 적용 결과 한글이 깨지는 현상이 생겻다..

상단 가장 우측 Help - Edit Custom VM Options 에서 -Dfile.encoding=UTF-8을 추가해서 해결 완료

특정 엔티티를 영속 상태로 만들 떄 연관되어 있는 엔티티도 함께 영속 상태로 만드는것이다.

만약 Parent 객체와 child 객체가 연관되어 있다고 가정하자.

@Entity
public class Parent {
    @Id
    @GeneratedValue
    private Long id;
    private String name;

    @OneToMany(mappedBy = "parent")
    private List<Child> childList=new ArrayList<Child>();
}

@Entity
public class Child {
    @Id
    @GeneratedValue
    private Long id;

    private String name;

    @ManyToOne
    @JoinColumn(name = "parent_id")
    private Parent parent;
}

            Child child1 = new Child();
            Child child2 = new Child();

            Parent parent = new Parent();
            parent.addChild(child1);
            parent.addChild(child2);

            em.persist(parent);
            em.persist(child1);
            em.persist(child2);

child객체의 갯수만큼 계속 persist하면 너무 귀찮다! 이때 사용하는 것이 cascade다.

@Entity
public class Parent {
    @Id
    @GeneratedValue
    private Long id;
    private String name;

    @OneToMany(mappedBy = "parent",cascade = CascadeType.ALL)
    private List<Child> childList=new ArrayList<Child>();

}

child 코드는 동일하다.

            Child child1 = new Child();
            Child child2 = new Child();

            Parent parent = new Parent();
            parent.addChild(child1);
            parent.addChild(child2);

            em.persist(parent);

실행 결과:

Hibernate: 
    /* insert for
        hellojpa.Parent */insert 
    into
        Parent (name, id) 
    values
        (?, ?)
Hibernate: 
    /* insert for
        hellojpa.Child */insert 
    into
        Child (name, parent_id, id) 
    values
        (?, ?, ?)
Hibernate: 
    /* insert for
        hellojpa.Child */insert 
    into
        Child (name, parent_id, id) 
    values
        (?, ?, ?)

Parent에 cascade = CascadeType.ALL을 설정해줌으로 Parent객체만 persist해도 자식객체가 전부 저장된다.

헷갈릴수도 있지만 영속성 전이(cascade)는 연관관계를 매핑하는 것과 아무 관련이 없다. 엔티티를 영속화할 때 연관된 엔티티도 함께 영속화하는 편리함 을 제공할 뿐이다.

주의사항

참조하는 곳이 하나일 때 사용해야한다.(자식 엔티티가 서로 다른 2개 이상의 부모 엔티티가 연관관계를 갖고있다면 조심해야 한다.)

참고로 CASCADE의 종류는 All, persist, remove, merge, refresh, detach가 있다.

고아객체란?

고아 객체는 부모 엔티티와 연관관계가 끊어진 자식 엔티티를 말한다.

orphanRemoval = true 옵션

참조가 제거된 엔티티는 다른 곳에서 참조하지 않는 고아 객체로 보고 삭제하는 기능

• @OneToOne, @OneToMany만 가능
• 참조하는 곳이 하나일 때 사용해야한다.(자식 엔티티가 서로 다른 2개 이상의 부모 엔티티가 연관관계를 갖고있다면 조심해야 한다.)
• 특정 엔티티가 개인 소유할 때 사용

참고 자료 출처: 출처

프록시(Proxy)란, 영문 그대로 '대리자'라는 뜻으로, 실제 객체를 대신하여 대리 역할을 수행하는 객체를 말한다.

위 사진과 같이 프록시는 실제 클래스를 상속받아서 만들어지기떄문에 실제 클래스 똑같이 생겼다. 이론상 사용자 관점에서는 진짜 객체인지 프록시인지 구분하지 않고 사용할 수 있다.

프록시의 동작 과정

프록시 객체는 실제 객체의 참조(target)을 가지고 있으므로 프록시 객체를 호출하면 실제 객체의 메소드를 호출한다.

em.getReference()를 하여 프록시 객체를 생성할 수 있다.

다음 그림은 em.getReference()을 통해 MemberProxy를 생성후 .getName()을 호출했을떄 동작 과정을 나타낸 그림이다.(영속성 컨텍스트가 클린(clean)한 상태 가정)

1. getName() 호출
2. 프록시(MemberProxy)는 영속성 컨텍스트에 초기화 요청을 한다.
3. member를 영속화하기 위해 DB 조회
4. 실제 member 객체 영속화 후 프록시(MemberProxy)의 참조(target)과 연결한다.
5. 프록시(MemberProxy)가 참조(target)의 메소드(getName)을 호출후 반환한다.

정리

• 프록시 객체는 처음 사용할 때 한 번만 초기화된다.

• 프록시를 초기화한다는 것은 프록시 객체가 실제 엔티티로 바뀌는것이 아니다.

            Member findMember = em.getReference(Member.class, member.getId());
            System.out.println("findMember.getClass() = " + findMember.getClass());

            findMember.getUsername();

            System.out.println("findMember.getClass() = " + findMember.getClass());

실행 결과:

findMember.getClass() = class hellojpa.Member$HibernateProxy$NXbKWHsJ
Hibernate: 
    select
        m1_0.MEMBER_ID,
        m1_0.createBy,
        m1_0.createdDate,
        m1_0.lastModifiedBy,
        m1_0.lastModifiedDate,
        t1_0.TEAM_ID,
        t1_0.name,
        m1_0.USERNAME 
    from
        Member m1_0 
    left join
        Team t1_0 
            on t1_0.TEAM_ID=m1_0.team_TEAM_ID 
    where
        m1_0.MEMBER_ID=?
findMember.getClass() = class hellojpa.Member$HibernateProxy$NXbKWHsJ

• 프록시 객체는 원본 엔티티를 상속 받으므로 타입체크 를 주의해야 한다. 타입 체크시 == 비교를 사용하지 않고 instance of를 사용하자.

  
            Member RefMember = em.getReference(Member.class, member.getId());
           System.out.println("RefMember.getClass() = " + RefMember.getClass());
           System.out.println(" RefMember instanceof Member = " + (RefMember instanceof Member));

  실행결과:

  RefMember.getClass() = class hellojpa.Member$HibernateProxy$uyIJHorZ
  RefMember instanceof Member = true

• 영속성 컨텍스트에 찾는 엔티티가 이미 있으면 em.getReference()를 호출해 도 실제 엔티티 반환된다.

            Member findMember = em.find(Member.class, member.getId());
            System.out.println("findMember.getClass() = " + findMember.getClass());

            findMember.getUsername();
            Member RefMember = em.getReference(Member.class, member.getId());
            System.out.println("RefMember.getClass() = " + RefMember.getClass());

실행 결과:

findMember.getClass() = class hellojpa.Member
findMember.getClass() = class hellojpa.Member

• ==비교가 필요할 경우를 대비하여 jpa는 항상 한 트렌잭션 안 에서 같은 엔티티에 대한 동일성을 보장을 해준다.(==는 항상 true여야 한다.)

            System.out.println("================");
            Member findMember = em.find(Member.class, member.getId());
            System.out.println("findMember.getClass() = " + findMember.getClass());

            Member RefMember = em.getReference(Member.class, member.getId());
            System.out.println("RefMember.getClass() = " + RefMember.getClass());

            em.clear();
            System.out.println("================");
            Member RefMember2 = em.getReference(Member.class, member.getId());
            System.out.println("RefMember2.getClass() = " + RefMember2.getClass());

            Member findMember2 = em.find(Member.class, member.getId());
            System.out.println("findMember2.getClass() = " + findMember2.getClass());

            System.out.println("findMember == RefMember:" + (findMember==RefMember));
            System.out.println("findMember2 == RefMember2:" + (findMember2==RefMember2));

실행 결과:

================
Hibernate: 
    select
        m1_0.MEMBER_ID,
        m1_0.createBy,
        m1_0.createdDate,
        m1_0.lastModifiedBy,
        m1_0.lastModifiedDate,
        t1_0.TEAM_ID,
        t1_0.name,
        m1_0.USERNAME 
    from
        Member m1_0 
    left join
        Team t1_0 
            on t1_0.TEAM_ID=m1_0.team_TEAM_ID 
    where
        m1_0.MEMBER_ID=?
findMember.getClass() = class hellojpa.Member
RefMember.getClass() = class hellojpa.Member
================
RefMember2.getClass() = class hellojpa.Member$HibernateProxy$dfy1PGsC
Hibernate: 
    select
        m1_0.MEMBER_ID,
        m1_0.createBy,
        m1_0.createdDate,
        m1_0.lastModifiedBy,
        m1_0.lastModifiedDate,
        t1_0.TEAM_ID,
        t1_0.name,
        m1_0.USERNAME 
    from
        Member m1_0 
    left join
        Team t1_0 
            on t1_0.TEAM_ID=m1_0.team_TEAM_ID 
    where
        m1_0.MEMBER_ID=?
findMember2.getClass() = class hellojpa.Member$HibernateProxy$dfy1PGsC
================
findMember == RefMember:true
findMember2 == RefMember2:true

• 영속성 컨텍스트의 도움을 받을 수 없는 준영속 상태일 때, 프록시를 초기화하면문제 발생 (하이버네이트는org.hibernate.LazyInitializationException 예외를 터트림)

            Member refMember = em.getReference(Member.class, member.getId());

            em.detach(refMember);

            System.out.println("refMember.getUsername() = " + refMember.getUsername());

org.hibernate.LazyInitializationException: could not initialize proxy [hellojpa.Member#1] 

//이하 생략...

참고 자료 출처: 출처