아둥바둥 버텨라

좋은 API Response 만들기 리뷰

Mo'Greene — Tue, 23 Jan 2024 09:57:42 +0900

그래야하지 않을까? 싶었지만 하지 않았던 습관들에 대해 지적해주는 글이 아닌가 싶다.

최소 스펙 유지하기

가능한 API 크기를 최소화 한다.
즉, DTO를 중복적으로 사용하지 않는게 중요한 듯 하다.
회사에서 레거시한 프로젝트들을 관리하다 보면 하나의 통합적인 DTO(예를들면 상점 도메인에 사용하는 모든 데이터(!!)를 적어둔 ShopDTO)를 만들어 놓고
중복적으로 사용하며 Response에는 null 값이 숭숭 뚫려있는 프로젝트들이 있었다.

이게 참 백엔드 개발자로써는 중복된 코드를 지양하고(!) 객체지향인것(!) 싶지만
단순히 레이어 간의 파라미터의 역할을 하는 객체를 객체지향 코드로 격상시켜 버린 것이 아닐까 싶다.(그리고 이런 response api를 받으면 프론트 개발자 분들이 쌍욕한다ㅋㅋ)

나는 메서드 단위의 ResponseDTO를 만들어 사용하고 있다.
아무리 중복되는 인자가 있어도 DTO를 2개 이상의 메서드에 반환하는 일은 최소한으로 해둔다.(뭐 정말 똑같은 경우는 어쩔 수 없지만)
DTO 내부의 innerClass 도 지양하고 있다. 하나의 클래스가 너무 커지게 되고 DTO를 부를때도 한줄에 너무 길게 적히다 보니 가독성이 안좋아지는 코드를 많이 보게 되었다.

        MemberDTO.MemberXXXResponse response = MemberRepository.findBy....

camelCase 사용하기

문제없다.

표준 포맷 사용하기

사용자에 노출되는 데이터에는 날짜데이터를 포맷팅 하거나 Date 클래스로 전달하였지만
사용자에게 노출이 안되는 데이터들(jwt 토큰의 만료시간 등등)에는 UNIX 타임스탬프를 사용한 적이 있었던 것 같다.
이 점도 고치도록 하자.

Boolean 타입에는 `null` 이 있으면 안된다.

정말 부끄럽지만 Boolean의 null 값을 하나의 상태값으로 사용한 적이 있다.
참과 거짓의 열거형인데 이것을 true or false or null 으로 사용하였다.
블로그에서도 각각 의미가 있다면 YES, NO, UNKNOWN 으로 표현하는 것을 권장한다.

제한된 문자열 값은 열거형 (Enum) 으로 표현한다.

간혹 시간에 쫓겨 열거형을 사용해야함에도 불구하고 String 으로 DB를 설계하는 경우가 있는데 이런 부분도 신경쓰면서 사용하자.

열거형 (Enum)은 문자열로 표현되어야 한다.

Entity를 설계할 때 @Enumerated(EnumType.STRING) 어노테이션을 사용하여 관리하고 있다.

복수형 빈 값은 빈 배열로

단일 객체에 Null Object Pattern을 대응 하는 것은 기존 시스템의 상황에 따라 기본값을 구현하기 어렵거나 Null 자체가 유의미한 경우가 많아 상황에 따라 선택한다.

복수형 객체를 반환할때 null 일 경우 빈 배열로 전달하도록 하자. 생각도 못해봤다.

일관성 유지하기

결국 네이밍의 중요성인데, 아직까지 네이밍을 구분하기 쉽게 잘(?) 짓는다고 할 수 없어서 항상 생각하면서 네이밍을 짓도록 하자.

필드명 축약 금지, 타입에 맞는 필드명

필드명을 축약하는 것이 버릇이 된다면 나중가면 본인만 알고 전혀 의미를 알 수 없기 때문에 고치도록 하자
Boolean 타입이라면 is, has 등을 prefix로
일시 타입이라면 At 을 suffix로
복수형은 복수형으로

우리 회사의 경우 At을 사용하지 않고 date를 사용하고 있다.(At은 올드해보인다는 말 때문에..)
복수형의 경우는 복수형도 있지만 xxxList 등의 방식으로 반환하고 있다.

MoGreene Code Convention

Mo'Greene — Tue, 2 Jan 2024 11:28:08 +0900

서비스 코드에 Response 등 응답객체 반환 금지
- 테스트 코드 작성시 진행하기 어려운 부분이 있음
- 반환타입에 따라 Controller에서 응답객체로 감싸기
테스트 코드 작성 시 Controller는 Mock테스트, 그 외 Junit 단위테스트로
패키지 구조는 'api'와 'global'로 나눈다.
1. api의 패키지는 도메인별로 나눈다.(기능별 x)
2. exception의 경우 global 패키지 내의 도메인으로 나눈다.(팀 컨벤션에 따라 변경)
3. 디자인패턴을 적용시켜야 할 경우 Service 패키지를 작성하여 그안에 보관한다.
4. api 패키지 내에 특정 도메인만 사용하게 되는 util 패키지를 만들지 않는다.(생길 경우 디자인패턴으로 보관)
5. util의 경우 특정 도메인의 컴포넌트를 DI 하지 않는다. (ex: private final MemberRepository(X))
6. dto패키지 안에는 request, response을 패키지로 나누고 어플리케이션 내부에서 사용할 dto의 경우 dto패키지 안에 넣도록 하자
  ex)
```
dto
ㄴ request
     ㄴ XXXRequest
ㄴ response
     ㄴ XXXResponse
ㄴ XXXDTO
```
메서드 명으로 get, set 등의 prefix를 사용하지 않는다.
노출되어선 안될 내용이 없다면 Entity로 반환해도 문제없다.(ex: 약관 등 간략한 도메인)

JPA

join 및 단방향관계, 양방향관계는 매우 신중하게 결정(특히 삭제되는 데이터를 주의하면서 진행) 애지간하면 join을 걸지 않고 queryDsl을 사용해서 사용한다.
- 유용한 답변
@OneToOne, @ManyToMany는 사용금지
양방향관계 금지
단방향일 경우
연관된 두 객체의 라이프사이클이 동일할 경우에만 @ManyToOne

자바 플레이그라운드 with TDD, 클린코드 - 문자열계산기

Mo'Greene — Sun, 24 Dec 2023 17:21:11 +0900

목표

- 테스트코드의 습관들이기

- 천천히 하더라도 꼭 완주

- 기존 구성에 따라, 내 힘으로 구현 -> 피드백 확인 -> 리팩토링의 과정을 거친다.

객체지향 생활체조원칙

한 메서드에 오직 한 단계의 들여쓰기만 한다.
else 예약어를 쓰지 않는다.
모든 원시 값과 문자열을 포장한다.
한 줄에 점을 하나만 찍는다.
줄여 쓰지 않는다(축약 금지).
모든 엔티티를 작게 유지한다.
3개 이상의 인스턴스 변수를 가진 클래스를 쓰지 않는다.
일급 컬렉션을 쓴다.
getter/setter/프로퍼티를 쓰지 않는다.

문제는 혹시나하는 저작권 때문에 공개할 순 없다는 점..

TEST 코드

..test코드
public class StringCalcTest {  
  
    @BeforeEach  
    public void setUp() {  
       String polynomial = "2 / 2 * 4 - 100 + 207";  
       System.setIn(new ByteArrayInputStream(polynomial.getBytes()));  
    }  
    @Test  
    @DisplayName("문자열 계산기")  
    public void stringCalcTest() {  
       String output = inputString();  
       String[] values = output.split(" ");  
       StringCalculator stringCalculator = new StringCalculator(values);  
       int result = stringCalculator.calculate();  
  
       assertThat(result).isEqualTo(111);  
    }  
    private String inputString() {  
       Scanner sc = new Scanner(System.in);  
       return sc.nextLine();  
    }}

최초 TDD 구현

..초기 testcode -> 구현만 성공
public class StringCalculator {  
    private String[] values;  
  
    public StringCalculator(String[] values) {  
       this.values = values;  
    }  
    public int calculate() {  
       return 5;  
    }}

리팩토링 후 구현

public class StringCalculator {
	private String[] values;

	public StringCalculator(String[] values) {
		this.values = values;
	}

	/**
	 * 문자열 계산
	 * @return int
	 */
	public int calculate() {
		int result = Integer.parseInt(values[0]);
		for (int i = 1; i < values.length; i += 2) {
			int nextNum = Integer.parseInt(values[i + 1]);
			result = switchCalculation(values[i], result, nextNum);
		}
		return result;
	}

	/**
	 * 계산식
	 * @param value 기호
	 * @param result 결과
	 * @param nextNum 뒤에 번호
	 * @return int
	 */
	private int switchCalculation(String value, int result, int nextNum) {
		switch (value) {
			case "+" : return add(result, nextNum);
			case "-" : return subtract(result, nextNum);
			case "*" : return multiply(result, nextNum);
			case "/" : return divide(result, nextNum);
			default: throw new RuntimeException("잘못된 기호를 적었습니다.");
		}
	}

	/**
	 * 덧셈
	 * @param num 기존 값
	 * @param plusNum 더할 값
	 * @return int
	 */
	private int add(int num, int plusNum) {
		return num + plusNum;
	}

	/**
	 * 뺄셈
	 * @param num 기존 값
	 * @param minusNum 뺄 값
	 * @return int
	 */
	private int subtract(int num, int minusNum) {
		return num - minusNum;
	}

	/**
	 * 곱셈
	 * @param num 기존 값
	 * @param multiplyNum 곱할 값
	 * @return int
	 */
	private int multiply(int num, int multiplyNum) {
		return num * multiplyNum;
	}

	/**
	 * 자바 나눗셈
	 * @param num 기존 값
	 * @param divideNum 나눌 값
	 * @return int
	 */
	private int divide(int num, int divideNum) {
		return num / divideNum;
	}
}

결과

리팩토링 생각할 부분

switchCalculation의 파라미터가 3개이상인 부분..

디자인패턴에 대해서

Mo'Greene — Mon, 11 Dec 2023 09:22:34 +0900

뭔가 올드해

평소에 나는 디자인패턴에 대해서 회의적인 느낌을 받았다.

'헤드퍼스트 디자인패턴'이란 책이 개발자라면 필수로 구입해야 하는 책이라고 듣고

서점에서 이 책을 들춰봤을때. 생각했다.

'아 디자인패턴을 알아야 할 이유가 없구나'

책에서 소개하는 싱글톤은 이미 스프링 컨테이너 내에서 객체를 싱글톤으로 관리한다고 알고 있고

프록시 패턴의 경우도 마찬가지.

@ControllerAdvice, @RestControllerAdvice

이 두개의 어노테이션이 프록시패턴을 구현하고 있다고 배웠다.

그러니 책에서 소개하는 팩토리, 옵저버, 커맨드 등의 디자인패턴은 분명

스프링부트에서 사용하는 'MVC패턴'이나

Controller-Service-Repository의 레이어가 위의 역할을 대신해서 동작할 것이다.라고 생각해 왔다.

하지만

코드를 작성하다 보면 분명히 존재한다.

중복된 코드 혹은 비슷한 기능을 가지고 있는데 파라미터만 다르게 구현된 메서드,

Service 코드에서 비즈니스 로직을 전부 구현하다 보니 가독성이 심히 안 좋아진 코드,

단순하게 아키텍처 레이어만 생각하다 보니 하나의 레이어에서만 코드가 과도하게 몰려

비슷한 코드가 쌓이고 또 그렇게 코드 양이 증가하는 부분이 마음에 걸리게 되었다.

만약 그렇다면 패키지 내에 Util 클래스를 분리해서 작성해 볼까 싶었지만

내 멘토가 했던 말이 계속 떠올랐다.

Util 클래스가 특정 Service 혹은 Repository를 주입받아야 된다면 그건 Util 클래스가 아니게 된다.

이것에 관해 고민하다 보니 구현하게 된 게 '디자인패턴'이다.

https://www.youtube.com/watch?v=31wI-c7ExiQ&ab_channel=%ED%95%98%EC%B0%AE%EC%9D%80%EC%98%A4%ED%9B%84

평소 구독하고 보고 있는 개발자 분의 유튜브다.

스프링부트에서 구현할 수 있는 디자인패턴을 생각하다가 위 유튜버를 보고 내 코드에도 적용해 보자 싶었다.

단순하다. 결제승인 로직까지는 동일한 과정을 진행하다가

일반결제와 결제연장의 로직은 PaymentStatus라는 Enum으로 분류된다.

위 부분을 PaymentStrategy 인터페이스를 사용하여 분리해 주었다.

PaymentStatus

@Getter
@RequiredArgsConstructor
public enum PaymentStatus {

    CONFIRM("confirmStrategy"),
    EXTENDS("extendStrategy");
    
    //value값의 부분은 전략패턴 구현체의 이름을 camelCase로 적어준다.
    private final String value;

}

//전략패턴 핸들러 인터페이스
public interface PaymentStrategy {

    /**
     * 결제 승인 핸들러
     */
    void paymentHandler(PaymentTemporal paymentTemporal, PaymentSuccessResponse paymentSuccessResponse);

}

//결제승인 구현체
@Component
@RequiredArgsConstructor
public class ConfirmStrategy implements PaymentStrategy {

	...

    /**
     * 결제 승인 핸들러
     * @param paymentTemporal 임시 결제 테이블
     * @param paymentSuccessResponse 결제 성공 response
     */
    @Override
    public void paymentHandler(PaymentTemporal paymentTemporal, PaymentSuccessResponse paymentSuccessResponse) {
    
    	...
    }
}

//결제 연장 구현체
@Component
@RequiredArgsConstructor
public class ExtendStrategy implements PaymentStrategy {

	...
        
    /**
     * 연장 결제 승인 핸들러
     * @param paymentTemporal 임시 결제 테이블
     * @param paymentSuccessResponse 결제 성공 response
     */
    @Override
    public void paymentHandler(PaymentTemporal paymentTemporal, PaymentSuccessResponse paymentSuccessResponse) {
        
        ...
    }
}

서비스 코드에선

@Service
@RequiredArgsConstructor
public class PaymentService {

	private final Map<String, PaymentStrategy> paymentStrategyMap;
    	...

	/**
	 * 결제 성공시 상점 테이블 저장 후 리다이렉트
	 */
	private void paymentSuccessRedirectView(HttpURLConnection connection, PaymentTemporal paymentTemporal, RedirectView redirectView, PaymentStatus paymentStatus) throws IOException {
    
    		...
        
        	//strategy Payment
		PaymentStrategy paymentStrategy = paymentStrategyMap.get(paymentStatus.getValue());
		paymentStrategy.paymentHandler(paymentTemporal, paymentResponse);
        
        	...
	}
    
    ...
}

전략패턴을 구현하는 paymentStrategyMap을 구현해 주었다.

이게 재밌는 게 PaymentStrategy를 구현한 구현체를 @Component로 컨테이너에 등록시키고

위와 같은 방식으로 paymentStatus.getValue()를 통해 Componenet를 불러주니 정상적으로 동작하였다.

만약 이 방식이 아니었다면 if/else 문으로 분리해 가면서 어떤 구현체를 가져올지 정해야 하는데

그렇게 if문이 생기게 되면 전략패턴을 사용하는 이유가 없어지게 된다.

개인적으로 전략패턴의 의도를 정확하게 구현하지 않았나 싶다.

만약 결제에 관한 추가적인 로직이 필요하다면 PaymentService에서 코드를 늘려 가독성을 해치는 것이 아닌

새로운 구현체를 만들어 작성해 주면 되고

각각의 결제로직에서 수정할 부분이 있다면 그 결제로직 부분만 수정하면 된다.

(OCP 원칙을 지키게 된 코드가 아닐까 싶다?)

끝으로

굳이 디자인패턴을 공부해 가면서 적용해 보는 것보다 차라리 그 시간에 다른 필요한 공부를 하는 게 낫다고 생각한다.

딱히 어려운 부분이 있는 것도 아니기에 필요에 의해서 구현하게 된다면

충분히 깔끔한 코드를 객체지향적으로 구현하게 되지 않을까 싶다.

물론 단순히 두 개로 분류할 수 있는 코드를 굳이 인터페이스로 나눈 게 성능에 좋다고 보긴 어렵지만

그 미묘한 확장가능성과 성능의 고민하는 경계선에서 나 나름대로 최선의 선택을 했다고 생각한다.

참조.

https://lsj31404.tistory.com/entry/Spring-%EC%8A%A4%ED%94%84%EB%A7%81%EC%9D%98-DI%EB%A5%BC-%EC%9D%B4%EC%9A%A9%ED%95%9C-%EC%A0%84%EB%9E%B5%ED%8C%A8%ED%84%B4-%EB%8F%84%EC%9E%85

토스페이먼츠 결제모듈 구현

Mo'Greene — Fri, 1 Dec 2023 15:59:29 +0900

회사에서 결제모듈을 구현해야 된다고 했을땐

막연히 겁이 났던것 같다.

당연하지만 남의 돈을 다룬다고 하는 것에 작은 죄책감(?) 때문인지도 모르겠다.

PG 결제모듈은 여러 회사가 있지만 그 중에 토스페이먼츠를 지정해주었다.

https://developers.tosspayments.com/

토스페이먼츠 개발자센터

토스페이먼츠 결제 연동 문서, API, 키, 테스트 내역, 웹훅 등록 등 개발에 필요한 정보와 기능을 확인해 보세요. 결제 연동에 필요한 모든 개발자 도구를 제공해 드립니다.

developers.tosspayments.com

5분 연동 가이드만 보아도 굉장히 쉽게 구현되어있었고 api나 샘플 코드들이 참고하기 쉬웠다는게 마음에 들었다.

https://github.com/tosspayments/payment-samples/tree/main/payment-window

그리고 디스코드에서도 궁금한 점을 물어볼 수 있어서 별다른 어려움 없이 구현했던것 같다.

https://tosspayments.discourse.group/

토스페이먼츠 디스코드 Repo

토스페이먼츠 디스코드 채널에 남겨진 많은 질문을 손쉽게 검색 및 확인하실 수 있습니다.

tosspayments.discourse.group

결제 승인처리 flow

하나의 트랜잭션으로 이루어진것은 아니지만 각각의 흐름에 따라 정리해 보았다.

결제 상품 리스트 전달

먼저 서버에서 결제상품 테이블을 만들어두고 회원에게 전달해준다.

결제 상품 테이블은

id	amount	item_name
1	5000	상품1
2	10000	상품2
3	15000	상품3
4	100	테스트

위와 같이 만들어주었고 프론트는 위 상품리스트 api를 받아 사용자에게 보여주면 된다.

결제 상품, 사용자 정보 '임시 결제 테이블' 저장

선배 개발자의 말로는 임시결제테이블은 로그의 개념으로만 사용된다고 한다.

그래서 아무런 정보가 들어가도 상관없다.

하지만 필수적으로 결제 승인에 필요하고 동일한 상품인지 검증하는 'orderId' 를 만들어 줄 필요가 있다.

결제승인 요청시 필수값 orderId

어떤 값을 넣어야 하나 싶다가 UUID가 생각났다.

맨처음엔 UUID가 128자인 줄 알아서 고려하지 않았는데 36자 문자열에 128비트 값이라고 하더라ㅋ

무튼, 임시결제테이블엔 orderId를 시작으로 추후 결제테이블에서 검증할 회원 정보, 상품정보 등을 넣게 되었다.

카드사 모듈 호출, 결제 요청 후 결제 승인 요청

이후 과정이 결제의 꽃이지 않을까 싶다.

Front에선 결제모듈을 호출하고 결제를 진행하고(은행앱의 결제과정)

결제모듈에서 결제 성공 여부를 확인 후 성공 시 서버에 결제승인 요청을 보내게 된다.

<script>
    let tossPayments = TossPayments("test_ck_OEP59LybZ8Bdv6A1JxkV6GYo7pRe");

    function pay(method, requestJson) {
        console.log(requestJson);
        tossPayments.requestPayment(method, requestJson)
            .catch(function (error) {

                if (error.code === "USER_CANCEL") {
                    alert('유저가 취소했습니다.');
                } else {
                    alert(error.message);
                }

            });
    }

    let path = "/";
    let successUrl = window.location.origin + path + "success";
    let failUrl = window.location.origin + path + "fail";
    let callbackUrl = window.location.origin + path + "va_callback";
    let orderId = new Date().getTime();

    let jsons = {
        "card": {
            "amount": amount,
            "orderId": "sample-" + orderId,
            "orderName": "토스 티셔츠 외 2건",
            "successUrl": successUrl,
            "failUrl": failUrl,
            "cardCompany": null,
            "cardInstallmentPlan": null,
            "maxCardInstallmentPlan": null,
            "useCardPoint": false,
            "customerName": "박토스",
            "customerEmail": null,
            "customerMobilePhone": null,
            "taxFreeAmount": null,
            "useInternationalCardOnly": false,
            "flowMode": "DEFAULT",
            "discountCode": null,
            "appScheme": null
        }

    }
</script>

위의 javascript 코드가 sample 결제모듈 되겠다.

successUrl 을 서버의 결제승인 api로 연결시켜서 추가적인 결제 승인 작업을 진행하면 된다.

결제 승인 요청

@GetMapping(value = "success")
    public String paymentResult(
            Model model,
            @RequestParam(value = "orderId") String orderId,
            @RequestParam(value = "amount") Integer amount,
            @RequestParam(value = "paymentKey") String paymentKey) throws Exception {

        String secretKey = "test_ak_ZORzdMaqN3wQd5k6ygr5AkYXQGwy:";

        Base64.Encoder encoder = Base64.getEncoder();
        byte[] encodedBytes = encoder.encode(secretKey.getBytes("UTF-8"));
        String authorizations = "Basic " + new String(encodedBytes, 0, encodedBytes.length);

        URL url = new URL("https://api.tosspayments.com/v1/payments/" + paymentKey);

        HttpURLConnection connection = (HttpURLConnection) url.openConnection();
        connection.setRequestProperty("Authorization", authorizations);
        connection.setRequestProperty("Content-Type", "application/json");
        connection.setRequestMethod("POST");
        connection.setDoOutput(true);
        JSONObject obj = new JSONObject();
        obj.put("orderId", orderId);
        obj.put("amount", amount);

        OutputStream outputStream = connection.getOutputStream();
        outputStream.write(obj.toString().getBytes("UTF-8"));

        int code = connection.getResponseCode();
        boolean isSuccess = code == 200 ? true : false;
        model.addAttribute("isSuccess", isSuccess);

        InputStream responseStream = isSuccess ? connection.getInputStream() : connection.getErrorStream();

        Reader reader = new InputStreamReader(responseStream, StandardCharsets.UTF_8);
        JSONParser parser = new JSONParser();
        JSONObject jsonObject = (JSONObject) parser.parse(reader);
        responseStream.close();
        model.addAttribute("responseStr", jsonObject.toJSONString());
        System.out.println(jsonObject.toJSONString());

        model.addAttribute("method", (String) jsonObject.get("method"));
        model.addAttribute("orderName", (String) jsonObject.get("orderName"));

        if (((String) jsonObject.get("method")) != null) {
            if (((String) jsonObject.get("method")).equals("카드")) {
                model.addAttribute("cardNumber", (String) ((JSONObject) jsonObject.get("card")).get("number"));
            } else if (((String) jsonObject.get("method")).equals("가상계좌")) {
                model.addAttribute("accountNumber", (String) ((JSONObject) jsonObject.get("virtualAccount")).get("accountNumber"));
            } else if (((String) jsonObject.get("method")).equals("계좌이체")) {
                model.addAttribute("bank", (String) ((JSONObject) jsonObject.get("transfer")).get("bank"));
            } else if (((String) jsonObject.get("method")).equals("휴대폰")) {
                model.addAttribute("customerMobilePhone", (String) ((JSONObject) jsonObject.get("mobilePhone")).get("customerMobilePhone"));
            }
        } else {
            model.addAttribute("code", (String) jsonObject.get("code"));
            model.addAttribute("message", (String) jsonObject.get("message"));
        }

        return "success";
    }

적당히 분리해서 진행하면 되고 나의 경우엔 MVC 패턴이 아니다보니

직접 redirectView를 호출하여 결제 성공 페이지, 결제 실패 페이지로 연결해 주었다.

위의 코드는 결제 승인의 과정 뿐이고 실제로는 이 코드 안에

'임시 결제 테이블'에 저장한 orderId 와 비교해 실제로 같은 사람이 결제한 상품인지 검증하는 부분과

같은 상품인지. 같은 가격인지. 등등 여러 방어로직을 만들어 두었다.

카드사 모듈에서 결제된 금액이 결제승인 과정에서 실패된다면 어떻게 되는지 이해가 잘 가지 않아

디스코드에 물어보니 만약 위 결제승인 과정 도중 예외처리가 되어 승인 api가 실패되고 보내지지 않는다면 금액이 지불되지 않는다는 답변을 받았다.

그러니 혹시 이글을 보는 여러분들도 위의 코드를 Controller에서 동작하지 말고

Service 코드에서 @Transactional 어노테이션을 사용해서 예외처리시 rollback 해주시길 바란다.

마무리

결제에 복잡한 과정이 섞여있지 않고 단순한 결제 처리만 있다 보니

별다른 어려운 점 없이 토스페이먼츠 api 만을 분석해서 결제 과정을 구현해 보았다.

참. api 문서라는게 볼 때는 정말 귀찮다가도 구현하게 된다면 그만큼 후련해지는것 같다.

QueryDsl] (SpringBoot + JPA) Offset/Limit과 transform

Mo'Greene — Sun, 29 Oct 2023 21:51:56 +0900

최근 QueryDsl로 회사 프로젝트를 진행하면서 까다로운 상황을 잘 해결해왔다고 생각했는데

이번에 겪은 상황을 해결하는데만 대략 일주일이 걸렸다.

코드를 대략적으로 설명하자면

@Getter @Setter
@Entity
public class Movie {
   
    @Id @GeneratedValue
    private Long id;

    @Column(name = "title")
    private String title;
}

@Getter @Setter
@Entity
public class Actor {

    @Id @GeneratedValue
    private Long id;

    @Column(name = "name")
    private String name;
    
    @ManyToOne
    @JoinColumn(name = "movie")
    private Movie movie;
}

회사의 코드를 들고올 수는 없으니 나와 비슷한 상황을 겪었던 StackOverFlow 질문이 있어 비슷하게 변경해 보았다.(답변이 없다..)

https://stackoverflow.com/questions/70813314/querydsl-springjpa-limit-offset-when-using-transform

QueryDSL (Spring+JPA) Limit/Offset when using Transform

I am trying to use QueryDSL to transform a Many to Many select into a projection while also applying pagination using JPA. I have the following entities: @Getter @Setter @Entity public class Movie ...

stackoverflow.com

Actor의 N:1 단방향 관계를 세팅했다.

양방향관계를 생각하지 않은 이유는 그간 공부하면서 양방향 관계를 최대한 피해야한다는 김영한님의 JPA 가르침 때문이었다.

Projections을 사용해 반환하려는 DTO는

//롬복 생략
public class MovieDto {
    String title;
    List<ActorDto> actors;
}

public class ActorDto {
    String name;
}

이런 방식을 사용해 Movie를 조회할 때 Dto안에 List를 반환하려했다.

이 내용으로 내가 해결하려했던 방법을 몇개 소개하고 실패 케이스와 함께 해결한 방법을 소개하려 한다.

방법 1.

List<MovieDto> all = queryFactory
        .selectFrom(movie)
        .leftJoin(actor)
        .on(movie.id.eq(actor.movie.id))
        .offset(pageable.getPageOffset())
        .limit(pageable.getPageSize())
        .transform(groupBy(movie.id).list(Projections.constructor(MovieDto.class,
                            movie.title,
                            list(Projections.constructor(ActorDto.class, 
                            	actor.name))
)));

트랜스폼을 사용한 방법으로 맨 첫번째에 사용했던 방법이다.

문제의 상황은 페이지네이션을 적용하려고 할때 나오게 되는데

Movie 1, Actor N 의 관계에서 위의 QueryDsl을 사용해 size를 10개로 준다면

Actor의 데이터 수에 따라 결과가

Page = 0, Size = 10

ID	영화 제목	배우 이름
1	영화 제목 1	영화 1 배우
1	영화 제목 1	영화 1 배우
2	영화 제목 2	영화 2 배우
2	영화 제목 2	영화 2 배우
3	영화 제목 3	영화 3 배우
3	영화 제목 3	영화 3 배우
3	영화 제목 3	영화 3 배우
4	영화 제목 4	영화 4 배우
4	영화 제목 4	영화 4 배우
4	영화 제목 4	영화 4 배우

이런 데이터가 나오게 된다.

GroupBy로 MovieDto를 반환할 때 Actor 컬럼이 MovieDto내의 List 형태로 들어가는게 아닌 중복된 row로 추가되어 나온다는 얘기다.

이 데이터는 페이지네이션으로 적용할 수 없다. 10개의 Movie id가 필요한데 전혀 다른 데이터가 나오고 있기 때문이다.

그렇기에 고민해보며

노가다의 방법으로 이런 방법을 생각했다.

방법 2.

List<Movie> query = queryFactory
                .select(Projections.constructor(MovieDto.class,
                	movie.id
                ))
                .from(movie)
                .leftJoin(actor)
                .on(movie.id.eq(actor.member.id))
                .where()
                .offset(pageable.getOffset())
                .limit(pageable.getPageSize())
                .orderBy(member.id.desc())
                .groupBy(	//GroupBy 중복 제거
                        movie
                )
                .fetchJoin().fetch()
                .stream()	//stream 시작
                .peek(p -> {
                    Long movieId = p.getId();
                    List<ActorDto> actorList = queryFactory
                            .selectFrom(actor)
                            .where(actor.movie.id.eq(movieId))
                            .transform(
                                    groupBy(actor.id).list(Projections.constructor(ActorDto.class,
                                            actor.name
                                    ))
                            );
                    p.setActors(actorList);
                })
                .collect(Collectors.toList());

페이징 카운트 코드를 제외한 코드가 되겠다.

성능과 효율도 굉장히 안좋은 코드가 아닌가 싶다.

대략적으로 Movie와 Actor를 설명하자면

GroupBy를 통해 Movie 객체의 중복컬럼 없는 데이터를 뽑아내고

Movie id값을 for문 혹은 stream으로 하나 하나 찾아내어 MovieDto안에 actor 이름을 List로 만들어 넣어주는 것이다.

이렇게 된다면 쿼리문이

N+1 이 아니라 N+size 의 쿼리문 개수가 나가게 된다ㅋㅋ

size 의 수만큼 for 문을 돌면서 Actor 테이블을 조회할 텐데 Actor의 수가 늘면 늘수록 아주 재밌는 현상이 벌어질 것이다ㅋㅋ

이 Entity관계에 대해 고민해서 나온 해결방법은 하나였다.

방법 3.

양방향 관계 설정

@Getter @Setter
@Entity
public class Movie {
   
    @Id @GeneratedValue
    private Long id;

    @Column(name = "title")
    private String title;
    
    //추가부분
    @OneToMany(mappedBy = "movie")
    private List<Actor> actors;
}

@Getter @Setter
@Entity
public class Actor {

    @Id @GeneratedValue
    private Long id;

    @Column(name = "name")
    private String name;
    
    @ManyToOne
    @JoinColumn(name = "movie")
    private Movie movie;
}

최대한 단방향 관계로써 테이블을 구현하려고 하다 양방향관계를 도입하였다.

연관관계의 주인은 Actor로 설정하여 Actor 테이블에 FK 키가 매핑되도록 만들었다.

이후 구현한 코드

public Page<MovieDto> findMovie(Pageable pageable, SearchRequest request) {

        List<Movie> query = queryFactory
                .selectFrom(movie)
                .leftJoin(actor)
                .on(movie.id.eq(actor.movie.id))
                .where(
                	//동적쿼리 작성부분
                )
                .offset(pageable.getOffset())
                .limit(pageable.getPageSize())
                .groupBy(movie)
                .orderBy(movie.id.desc())
                .fetchJoin().fetch();

        //MovieDto 데이터 삽입
        List<MovieDto> dtoList = query.stream().map(m -> {

            Movie dto = Movie.builder()
                    .title(m.getTitle)
                    .build();

            List<Actor> actorList = m.getActors().stream()
                    .map(a ->
                            ActorDto.builder()
                                    .name(a.getName())
                                    .build()
                    ).toList();

            dto.setActors(actorList);
            return dto;
        }).toList();

        JPAQuery<Long> count = queryFactory
                .select(movie.count())
                .from(movie)
                .where(
                	//동적쿼리부분
                );

        return PageableExecutionUtils.getPage(dtoList, pageable, count::fetchOne);
    }

카운트 쿼리와 전체적인 부분을 추가한 코드를 완성했다.

성능과 효율의 측면에서도 N+1의 문제를 예방했다고 생각하고

방법2. 에서 나온 size만큼의 N+size 도 없이 한번의 쿼리를 사용하여

어플리케이션 레벨에서의 처리로 해결하였다.

결론.

최대한 단방향 관계로 모든 테이블을 구현하고자 했었다.

그게 정답이라고 생각하였고 양방향관계의 공부를 소홀히 하니 쉽게 접근하기 두려웠던 것이었다.

하지만 MyBatis와 다르게 서브쿼리를 지양하고

코드적으로 테이블이 아닌 객체를 다루는 것에 대해 일주일 가까히 생각하다보니

Spring Data Jpa를 사용하게 된다면 모든 테이블을 단방향 관계로 설계하는 게 아닌

필요에 따라

양방향 관계를 설정하는 방법과 이유에 대해 많이 이해하게 되었지 않았나 싶다.

JPA] 자연키 vs 대리키

Mo'Greene — Wed, 11 Oct 2023 22:07:02 +0900

<자바 ORM 표준 JPA 프로그래밍> p.143 발췌

권장하는 식별자 선택 전략

데이터베이스 기본 키는 다음 3가지 조건을 모두 만족해야 한다.

1. null값은 허용하지 않는다.

2. 유일해야 한다.

3.변해선안된다.

테이블의 기본 키를 선택하는 전략은 크게 2가지가 있다.

자연 키(natural key)

-비즈니스에의미가있는키

- 예: 주민등록번호, 이메일, 전화번호

대리 키(surrogate key)

- 비즈니스와 관련 없는 임의로 만들어진 키, 대체 키로도 불린다. - 예: 오라클 시퀀스, auto_increment, 키생성 테이블 사용

자연 키보다는 대리 키를 권장한다

자연 키와 대리 키는 일장 일단이 있지만 될 수 있으면 대리 키의 사용을 권장한다. 예를 들어 자연 키인 전화번호를 기본 키로 선택한다면 그 번호가 유일할 수는 있지만, 전화번호가 없을 수도 있고 전화번호가 변경될 수도 있다. 따라서 기본 키로 적당하지 않다. 문제는 주민등록번호처럼 그럴듯 하게 보이는 값이다. 이 값은 null이 아니고 유일하며 변하지 않는다는 3가지 조건을 모두 만족하 는 것 같다. 하지만 현실과 비즈니스 규칙은 생각보다 쉽게 변한다. 주민등록번호조차도 여러 가지 이유로 변경될 수 있다.

비즈니스 환경은 언젠가 변한다

나의 경험을 하나 이야기하겠다. 레거시 시스템을 유지보수할 일이 있었는데, 분석해보니 회원 테 이블에 주민등록번호가 기본 키로 잡혀 있었다. 회원과 관련된 수많은 테이블에서 조인을 위해 주 민등록번호를 외래 키로 가지고 있었고 심지어 자식 테이블의 자식 테이블까지 주민등록번호가 내려가 있었다. 문제는 정부 정책이 변경되면서 법적으로 주민등록번호를 저장할 수 없게 되면서 발생했다. 결국 데이터베이스 테이블은 물론이고 수많은 애플리케이션 로직을 수정했다. 만약 데 이터베이스를 처음 설계할 때부터 자연 키인 주민등록번호 대신에 비즈니스와 관련 없는 대리 키 를 사용했다면 수정할 부분이 많지는 않았을 것이다.

기본 키의 조건을 현재는 물론이고 미래까지 충족하는 자연 키를 찾기는 쉽지 않다. 대리 키는 비 즈니스와 무관한 임의의 값이므로 요구사항이 변경되어도 기본 키가 변경되는 일은 드물다. 대리 키를 기본 키로 사용하되 주민등록번호나 이메일처럼 자연 키의 후보가 되는 컬럼들은 필요에 따 라 유니크 인덱스를 설정해서 사용하는 것을 권장한다.

JPA는 모든 엔티티에 일관된 방식으로 대리 키 사용을 권장한다

비즈니스 요구사항은 계속해서 변하는데 테이블은 한 번 정의하면 변경하기 어렵다. 그런 면에서 외부 풍파에 쉽게 흔들리지 않는 대리 키가 일반적으로 좋은 선택이라 생각한다.

네이버 문자(sms) 서비스 구현

Mo'Greene — Tue, 12 Sep 2023 23:01:10 +0900

최근 신입으로 맡게된 프로젝트에서 사용하게 될 문자인증 서비스를 위해 문자 관련한 api를 찾아보았다.

제공하는 라이브러리를 조사해보니

coolsms

https://coolsms.co.kr/

세상에서 가장 안정적이고 빠른 메시지 발송 플랫폼 - 쿨에스엠에스

손쉬운 결제 전용계좌, 신용카드, 계좌이체 등 국내 결제 뿐만 아니라 해용신용카드로 한번의 카드번호 등록으로 자동충전까지 지원합니다. 전용계좌, 신용카드, 계좌이체 등 다양한 결제 방식

coolsms.co.kr

NHN Cloud

https://docs.nhncloud.com/ko/Notification/SMS/ko/api-guide/

API v3.0 가이드 - NHN Cloud 사용자 가이드

Notification > SMS > API v3.0 Guide v3.0 API 소개 v2.4와 달라진 사항 시크릿 키가 도입되었습니다. v3.0 API 호출 시에는 헤더에 시크릿 키를 추가해야 성공하게 됩니다. 대량 발송 요청을 조회할 수 있는 API

docs.nhncloud.com

Naver Cloud

https://www.ncloud.com/

NAVER CLOUD PLATFORM

cloud computing services for corporations, IaaS, PaaS, SaaS, with Global region and Security Technology Certification

www.ncloud.com

등이 있고

찾아보면 더 많이 되겠지만 이 안에서 사용할 것을 고려하기로 했다.

코드를 구현하는 것 자체는 api문서가 각각 너무 잘나와있고 구현하기에 어렵지 않다고 생각했다.

그렇다면 개발자로써 무엇을 생각하여 3개의 라이브러리 중 하나를 골라야할까

여러 이유가 있겠지만 몇가지를 추려서 생각해보았다.

가격, 사용법, 추가과정

1. 가격

coolsms 가격

https://coolsms.zendesk.com/hc/ko/articles/115001071551-%EB%AC%B8%EC%9E%90%ED%83%80%EC%9E%85%EB%B3%84-%EB%B9%84%EC%9A%A9

기본적으로 일반문자(sms)를 사용한다는 가정하에 건당 13.67 ~ 18.18원이 나온다.

nhn cloud

https://www.nhncloud.com/kr/pricing/m-content?c=Notification&s=SMS

NHN Cloud : 유연하게 안전하게 비즈니스의 힘이 되는 통합 클라우드 서비스

안정적이고 유연한 기업용 클라우드 컴퓨팅 서비스, 오픈스택 기반의 개방성과 신뢰로 고객사의 비즈니스에 힘이 되는 NHN Cloud

www.nhncloud.com

수신 1건당 9.9원이 나온다.

naver cloud platform

https://www.ncloud.com/product/applicationService/sens

NAVER CLOUD PLATFORM

cloud computing services for corporations, IaaS, PaaS, SaaS, with Global region and Security Technology Certification

www.ncloud.com

50건 이하 건당 무료! 50건 이상 9원이 나오게 된다.

테스트로 사용해도 충분할 50건의 무료문자도 주는걸 보니

가격적으로는 naver를 사용하는게 옳다고 본다.

(물론 다른 플랫폼에서도 무료 건수를 주는 걸로 알고있지만 네이버 만큼 주는건 아닌걸로 안다.)

2. 사용법

실제로 내가 회사에 들어온 후 추가개발을 맡게 된 레거시 프로젝트들은 전부 coolsms로 구현되어 있었고

이번에 혼자 개발에 들어가니 여러가지를 조사하며 선임개발자에게 물어봤다.

왜 coolsms 사용하셨어요? 가격이 비싸지 않나요?

사용하기 되게 쉬워서요.

말 그대로다. (물론 그 이후에 추가적인 이유를 알려주었다. 기획서 등..)

https://github.com/coolsms/coolsms-java-examples/tree/main

coolsms를 보면 별다른 설정 없이 build.gradle 추가하고 깃허브에 있는 코드(단일 메시지 발송 예제)를 그대로 사용하면 끝이다.

발급받은 키 하나만 적으면 바로 메세지를 보낼 수 있다는 것이다..

아 물론 다른 api가 그렇다고 해서 어렵다? 그건 동의할 수 없다.

조금 암호화된 과정을 추가해주어서 그렇게 보일 수 있지만 전혀 문제될 부분이 아니었다.

그러므로 사용법은 api를 잘 보면 되므로 문제될 것이 없다.

3. 추가과정

별다른건 아니다. 추가적인 확장성? 등을 생각해보았다.

현재 다니는 SI 업체로써 주어진 상황에만 맞추면 되는게 아닌

추후 나의 서비스를 구축 할때의 상황을 고려해보고자 했다.

네이버 클라우드 플랫폼을 사용하게 된다면 네이버 클라우드 내의 서비스를 이용할 확률

즉, 내가 지도앱을 생각할 때도 굳이 카카오 지도 등을 생각하지 않고

이미 계정을 갖고 있는 네이버 지도를 사용하지 않을까? 하는 생각말이다.

실제 서비스 회사에서의 고려사항은 어떨지 모르지만 여러 라이브러리를 가져와 사용하는 것 보다.

하나의 안정적인 라이브러리를 사용하는게 안정성에서도 옳지 않을까? 하는 생각을 하게 되었다.

자.

잡설은 길었다. 코드를 구현해보자.

환경설정

Java 17
SpringBoot 3.1.3

네이버에서 준비해야 할건 3개다.

accessKey, secretKey, serviceId 어렵지 않고 구글로 충분히 찾아볼 수 있으니 생략하려 한다.

public class NaverApi {

	public static final String ACCESS_KEY = "발급받은 accessKey";
	public static final String SECRET_KEY = "발급받은 secretKey";
	public static final String SERVICE_ID = "발급받은 serviceId";
	public static final String SENDER_PHONE = "보내려는 번호";
    
}

@Value를 통해 application.yml에서 가져오는 방법이 있겠지만 constant 패키지 내부에 보관하는 방식으로

api에서 사용할 key 들을 보관하기로 했다.

Controller

@RestController
@RequiredArgsConstructor
public class MessageController {

	private final MessageService messageService;

	@PostMapping("/api/sms")
	public String testMethod(@RequestBody MessageRequest request) throws UnsupportedEncodingException, NoSuchAlgorithmException, URISyntaxException, InvalidKeyException, JsonProcessingException {

		return messageService.sendSms(request);
	}

}

MessageService를 주입받아 sendSms 메서드를 호출하기만 하면 된다.

MessageRequest의 경우

@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
@Builder
@ToString
public class MessageRequest {

	private String to;

}

어노테이션을 주렁주렁 달았지만 필요없는 것이 많다.

Service

@Slf4j
@Service
public class MessageService {

	/**
	 * 인증번호 구현
	 * @param request
	 * @return
	 */
	public String sendSms(MessageRequest request) throws UnsupportedEncodingException, NoSuchAlgorithmException, InvalidKeyException, JsonProcessingException, URISyntaxException {

		String sixRandomNumber = makeRandomNumber();
		Long time = System.currentTimeMillis();

		HttpHeaders headers = new HttpHeaders();
		headers.setContentType(MediaType.APPLICATION_JSON);
		headers.set("x-ncp-apigw-timestamp", time.toString());
		headers.set("x-ncp-iam-access-key", NaverApi.ACCESS_KEY);
		headers.set("x-ncp-apigw-signature-v2", makeSignature(time));

		List<MessageRequest> messages = new ArrayList<>();
		messages.add(request);

		SmsRequest smsRequest = SmsRequest.builder()
			.type("SMS")
			.contentType("COMM")
			.countryCode("82")
			.from(NaverApi.SENDER_PHONE)
			.content("인증번호는 [" + sixRandomNumber + "] 입니다.")
			.messages(messages)
			.build();

		ObjectMapper objectMapper = new ObjectMapper();
		String body = objectMapper.writeValueAsString(smsRequest);

		HttpEntity<String> httpBody = new HttpEntity<>(body, headers);
		RestTemplate restTemplate = new RestTemplate();
		restTemplate.setRequestFactory(new HttpComponentsClientHttpRequestFactory());

		SmsResponse response =  restTemplate.postForObject(new URI("https://sens.apigw.ntruss.com/sms/v2/services/" + NaverApi.SERVICE_ID + "/messages"), httpBody, SmsResponse.class);

		if (Objects.requireNonNull(response).getStatusCode().equals("202")) {
			return sixRandomNumber;
		}
		if (response.getStatusName().equals("fail")) {
			return response.getStatusName();
		}
		return sixRandomNumber;
	}

	/**
	 * 난수 생성 메서드
	 * @return
	 */
	private String makeRandomNumber() {
		StringBuilder sb = new StringBuilder();
		for (int i = 0; i < 6; i++) {
			sb.append((int) (Math.random() * 9));
		}
		return sb.toString();
	}

	/**
	 * sms signature 생성
	 * @param time
	 * @return
	 */
	public String makeSignature(Long time) throws UnsupportedEncodingException, NoSuchAlgorithmException, InvalidKeyException {
		String space = " ";					// one space
		String newLine = "\n";					// new line
		String method = "POST";					// method
		String url = "/sms/v2/services/" + NaverApi.SERVICE_ID + "/messages";	// url (include query string)
		String timestamp = time.toString();			// current timestamp (epoch)
		String accessKey = NaverApi.ACCESS_KEY;			// access key id (from portal or Sub Account)
		String secretKey = NaverApi.SECRET_KEY;

		String message = new StringBuilder()
			.append(method)
			.append(space)
			.append(url)
			.append(newLine)
			.append(timestamp)
			.append(newLine)
			.append(accessKey)
			.toString();

		SecretKeySpec signingKey = new SecretKeySpec(secretKey.getBytes("UTF-8"), "HmacSHA256");
		Mac mac = Mac.getInstance("HmacSHA256");
		mac.init(signingKey);

		byte[] rawHmac = mac.doFinal(message.getBytes("UTF-8"));

		return Base64.encodeBase64String(rawHmac);
	}

}

중요한 부분은 sms를 보낼때 http 호출하기 위해서 헤더에 signature값을 만들어 보내준다는 것이다.

그 부분이 makeSignature라는 메서드가 되고 그 반환값을 헤더에 넣어주어 RestTemplate으로 네이버 api 호출을 한다.

그 안에 makeRandomNumber은 인증번호를 보낼 때 받게 되는 6개의 무작위 숫자 알고리즘이다.

SmsRequest, SmsResponse

@Getter
@Setter
@NoArgsConstructor
@AllArgsConstructor
@Builder
public class SmsRequest {

	private String type;
	private String contentType;
	private String countryCode;
	private String from;
	private String content;
	private List<MessageRequest> messages;

}


@Getter
@Setter
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class SmsResponse {

	private String requestId;
	private LocalDateTime requestTime;
	private String statusCode;
	private String statusName;
}

사용할 DTO 클래스

Test

@SpringBootTest
class MessageServiceTest {

	@Autowired
	MessageService messageService;

	@Test
	@DisplayName("sendSms 단위 테스트")
	void sendSms() throws UnsupportedEncodingException, NoSuchAlgorithmException, URISyntaxException, InvalidKeyException, JsonProcessingException {
		//given
		MessageRequest request = MessageRequest.builder()
			.to("01022745320").
			build();

		//when
		String response = messageService.sendSms(request);

		//then
		assertNotEquals("fail", response);
	}
}

테스트 코드를 실행해보고 메시지를 받았다.

사실 api 대로 진행하기만 하면 문제될 부분이 없어 난이도 자체는 어렵지 않았다.

예외처리를 추가해주면서 프론트엔드와 소통하면 될 듯 하다.

Swagger Opendoc API

Mo'Greene — Tue, 18 Jul 2023 22:58:13 +0900

Swagger..

https://swagger.io/

API Documentation & Design Tools for Teams | Swagger

Loved by all • Big & Small Thousands of teams worldwide trust Swagger to deliver better products, faster.

swagger.io

개인적으로 Postman을 사용했었을 때 굳이 Postman 말고 다른 걸 사용할 필요가 있을까 하는 생각이었다.

하지만 회사에 들어가고 나서 선임이 말해준 이유는 충분히 Postman이 아닌 다른 API플랫폼을 찾기엔 충분했다.

Postman의 경우 기업이 운영하기에 사용량이 많아지면 '유료'로 가격이 책정된다는 것이었다.

맨날 혼자 사이드 프로젝트를 하던 사람에겐 '아 맞다' 한 이유였다.

Swagger의 경우에도 크게 SpringFox와 SpringDoc으로 나뉘어 있지만 SpringFox의 경우 업데이트가 2020년 이후로 멈춰있어

SpringDoc을 사용해서 개발하는 게 옳다고 본다.

https://github.com/springdoc/springdoc-openapi

GitHub - springdoc/springdoc-openapi: Library for OpenAPI 3 with spring-boot

Library for OpenAPI 3 with spring-boot. Contribute to springdoc/springdoc-openapi development by creating an account on GitHub.

github.com

요즘은 굳이 다른 블로그를 안 보고 직접 문서를 번역기로 돌려 이해하는 것에 재미 들렸다.

환경설정

Java 11
SpringBoot 2.6.8
Spring Web
Lombok

Java 17 + SpringBoot 3.x.x 버전은 이미 Github에 잘 정리되어 있다.

나의 경우 아직 Java 11과 스프링부트 3 이하 버전의 프로젝트에 추가개발을 맡게 되어 이렇게 진행하려고 한다.

application.yml

springdoc:
  swagger-ui:
    path: /swagger-ui.html

build.gradle

    // Swagger OpenDoc Api
    implementation group: 'org.springdoc', name: 'springdoc-openapi-ui', version: '1.6.9'

Controller

package com.example.swaggertemplate.controller;

import com.example.swaggertemplate.dto.TestDTO;
import io.swagger.v3.oas.annotations.Operation;
import io.swagger.v3.oas.annotations.responses.ApiResponse;
import io.swagger.v3.oas.annotations.responses.ApiResponses;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * @name : TestController
 * @author : Mo-Greene
 * @date : 2023/07/18
 * 스웨거 테스트
 */
@RestController
public class TestController {

    @GetMapping("/api")
    @Operation(summary = "Swagger 테스트", description = "스웨거 테스트")
    @ApiResponses({
            @ApiResponse(responseCode = "200", description = "Success"),
            @ApiResponse(responseCode = "400", description = "Fail")
    })
    public void api(TestDTO testDTO) {
        System.out.println("testDTO = " + testDTO);
    }
}

TestDTO

package com.example.swaggertemplate.dto;

import io.swagger.v3.oas.annotations.media.Schema;
import lombok.Data;

@Data
public class TestDTO {

    @Schema(description = "Swagger Content", example = "swagger example")
    private String content;
}

따로 SwaggerConfig를 사용해 설정을 잡아주지 않아도 되는 점이 좋은 것 같다.

결과화면

API 문서화 작업은 그만큼 시간이 들어가는 작업이다.

혼자서 작업한다면 상관없지만 분명 클라이언트 혹은 이 코드를 참고하게 될 다른 개발자들에게 전해줄 수 있는 문서가 될 수 있기에

시간을 할애해서라도 작업해 두는 것을 권한다.

Vue.js3 Login + JWT 토큰

Mo'Greene — Tue, 11 Jul 2023 22:17:42 +0900

서론.

프론트엔드는 하나하나 잘 정리하지 않은 채 작업을 한다면 코드의 양이나 복잡도가 너무나도 높아지는 느낌을 받았다.

그로 인해 상태관리 라이브러리 (Pinia, Vuex..)를 굉장히 효율적으로 사용해야

중복되고 복잡한 코드의 양을 줄일수 있다는 것을 느끼고 있다.

당장에 로그인만 하더라도 JWT토큰을 백엔드에서 구현하는 것과 함께 Vue.js 내에서 관리해 줘야 되는 게여간 까다로운 게 아니란 것을 알게 되었다.

그렇기에 정리를 해두고 계속 고쳐가는 방향으로 진행하려고 한다.

JWT 토큰

https://mo-greene.tistory.com/108

Jwt + SpringSecurity + Mybatis 구현

Vue.js 와 SpringBoot를 사용해 게시판 토이프로젝트를 구현하고 있다. CRUD과정은 전부 끝났고 Vue.js와 씨름하며 시간을 보내다가 드디어 로그인 파트로 넘어왔다. https://www.inflearn.com/course/%EC%8A%A4%ED%94

mo-greene.tistory.com

백엔드에서 구현한 JWT토큰은 위 블로그에 포스팅해놨다.

특이점은 기존에 JPA로 구현하는 토큰과는 다르게 Mybatis로 회원테이블을 구현했다는 점이고

그 외에는 특이사항이 없을 듯하다.

Login.vue

<template>
    <v-card>
        <div class="d-flex align-center justify-center" style="height: 100vh">
            <v-sheet width="400" class="mx-auto">
                <v-form fast-fail ref="loginForm">
                    <v-text-field
                        variant="outlined"
                        v-model="username"
                        label="username"
                        :rules="usernameRules"
                    ></v-text-field>

                    <v-text-field
                        variant="outlined"
                        v-model="password"
                        label="password"
                        :rules="passwordRules"
                    ></v-text-field>

                    <v-btn
                        color="primary"
                        block
                        class="mt-2"
                        @click="validation">Log in</v-btn>
                </v-form>
                <div class="mt-2">
                    <p class="text-body-2">Don't have an account? <a href="#">Sign Up</a></p>
                </div>
            </v-sheet>
        </div>
    </v-card>
</template>


<script setup>
import * as loginApi from '@/api/login/login'
import {ref} from "vue";
import {useLoginStore} from "@/store/login";
import { useRouter } from "vue-router";

const username = ref();
const password = ref();
const loginForm = ref();
const loginStore = useLoginStore();
const router = useRouter();

//login Logic
const login = async () => {
    try {
        // Your login logic here
        const response = await loginApi.login(username.value, password.value);

        if (response.status === 200) {
            await loginStore.setToken(response.data.token);
            localStorage.setItem('access_token', response.data.token)
            await loginStore.getUserInfo();

            await router.push({path: '/'})
        }

    } catch (e) {
        alert(e.response.data.message)
    }
}

//Validation loginForm
async function validation (){
    const { valid } = await loginForm.value.validate();

    if (valid) await login();
    else {
        alert('로그인 양식에 맞지 않습니다.')
    }
}
const usernameRules = ref([
    value => {
        if (value) return true
        return '아이디를 적어주세요.'
    },
])
const passwordRules = ref([
    value => {
        if (value) return true
        return '비밀번호를 적어주세요.'
    },
])
</script>

테스트용 아이디와 비밀번호다.

중요한 부분이라고 생각되는 코드는

if (response.status === 200) {
            await loginStore.setToken(response.data.token);
            localStorage.setItem('access_token', response.data.token)
            await loginStore.getUserInfo();

            await router.push({path: '/'})
        }

이 부분으로

Pinia로 작성한 loginStore 모듈에 setToken과 getUserInfo를 호출할 것이고

결론적으로 사용자의 로컬스토리지에 'access_token'의 키값으로 토큰을 저장할 것이다.

로그인 전

로그인 후

현업에선 어떻게 사용하는지 모르지만 로컬스토리지에는 기본적으로 사용자의 정보가 담겨서는 안 된다고 한다.

그렇기에 토큰을 담아주고 이 토큰을 사용하여 사용자정보를 가져오는 방식으로 사용하려고 한다.

store/login.js

import {defineStore} from "pinia";
import {ref} from "vue";
import * as loginApi from '@/api/login/login'

export const useLoginStore = defineStore("login", () => {
    //state
    const token = ref(null);
    const userNo = ref(null);
    const username = ref(null);
    const role = ref(null);

    //actions
    async function setToken(newToken) {
        token.value = newToken;
    }

    //유저 정보
    async function getUserInfo() {
        try {
            const localToken = localStorage.getItem('access_token');
            const response = await loginApi.getUserInfo(localToken);

            token.value = localToken;
            userNo.value = response.data.data.userNo;
            username.value = response.data.data.username;
            role.value = response.data.data.role;
        } catch (e) {
            localStorage.removeItem('access_token');
        }
    }

    return {
        token,
        userNo,
        username,
        role,
        setToken,
        getUserInfo,
    }
})

Pinia의 사용방법에 빨리 익숙해지기 위해 사용하고 있다.

개인적으로 Vuex보다 훨씬 쉽게 사용할 수 있다고 생각하고 CompositionApi에 맞는 라이브러리가 아닌가 생각이 든다.

localStorage에서 'access_token' 값을 가져와 loginApi(토큰을 통해 유저정보 반환 Api)를 호출한다.

그 후 State값에 추가해 주면 된다.

※ catch의 경우

catch의 에러 값은 보통 '만료된 jwt' 혹은 '유효하지 않은 jwt'에러를 뱉는다.

그 이유로 에러를 뱉어준다면 localStorage에 있는 토큰을 지워주는 것으로 상태값을 초기화해준다고 생각하였다.(개인적으론 정답은 아닌 코드라고 생각한다.)

@/api/login.js

import http from "@/api/http";

/**
 * 로그인 api
 * @param username
 * @param password
 * @returns {Promise<axios.AxiosResponse<any>>}
 */
export async function login(username, password) {

    const loginDto = {
        username: username,
        password: password
    }
    return await http.post('/api/login', loginDto);
}

/**
 * 토큰을 사용해 유저 정보 api
 * @param token
 * @returns {Promise<void>}
 */
export async function getUserInfo(token) {
    return await http.get('/api/users', {
        headers: {
            Authorization: `Bearer ${token}`
        }
    });
}

axios 통신이다. 프런트엔드에서 토큰값을 전해줄 때 headers에다가 전달해 주는 것을 잊지 않아야 한다.

App.vue

<template>
    <v-app>
        <NavBar/>
        <AppBar/>
        <v-main>
            <v-container>
                <router-view/>
            </v-container>
        </v-main>
    </v-app>
</template>

<script setup>
import NavBar from "@/components/NavBar.vue";
import AppBar from "@/components/AppBar.vue";
import {useLoginStore} from "@/store/login";

const loginStore = useLoginStore();

loginStore.getUserInfo();

</script>

<style scoped>
.v-application {
    background-color: lightgray;
}
</style>

마지막으로 App.vue에 pinia에서 만든 getUserInfo를 사용하여 토큰값이 존재할 경우 계속해서 사용자의 정보를 유지하는 방식을 만들었다.

이것으로 새로고침이나 state가 초기화되는 상황에서 만약 사용자의 localStorage에 토큰값이 있다면 유저정보를 가져와 자동으로 로그인할 수 있는 방식으로 만들 수 있게 되었다.

아둥바둥 버텨라

좋은 API Response 만들기 리뷰

최소 스펙 유지하기

camelCase 사용하기

표준 포맷 사용하기

Boolean 타입에는 null 이 있으면 안된다.

제한된 문자열 값은 열거형 (Enum) 으로 표현한다.

열거형 (Enum)은 문자열로 표현되어야 한다.

복수형 빈 값은 빈 배열로

일관성 유지하기

필드명 축약 금지, 타입에 맞는 필드명

MoGreene Code Convention

JPA

자바 플레이그라운드 with TDD, 클린코드 - 문자열계산기

디자인패턴에 대해서

토스페이먼츠 결제모듈 구현

결제 승인처리 flow

QueryDsl] (SpringBoot + JPA) Offset/Limit과 transform

방법 1.

Page = 0, Size = 10

방법 2.

방법 3.

양방향 관계 설정

결론.

JPA] 자연키 vs 대리키

네이버 문자(sms) 서비스 구현

가격, 사용법, 추가과정

1. 가격

2. 사용법

3. 추가과정

환경설정

Controller

Service

SmsRequest, SmsResponse

Test

Swagger Opendoc API

환경설정

application.yml

build.gradle

Controller

TestDTO

결과화면

Vue.js3 Login + JWT 토큰

서론.

JWT 토큰

Login.vue

store/login.js

@/api/login.js

App.vue

Boolean 타입에는 `null` 이 있으면 안된다.