좋은 API 문서에 대한 고찰 (Swagger, Springdoc, Rest Docs)

개요좋은 API 문서란백엔드 개발자에게 좋은 API를 설계하는 일은 매우 중요하다. 백엔드 개발자에게 있어서는 API의 사용자가 곧 고객이나 다름 없기 때문이다. 그렇기 때문에, 좋은 API를 설계하고 이를 더 빠르게, 저렴하게, 일관적이며 언제든 이용 가능하도록 제공하는 일은 백엔드 개발자의 중요한 사명이라고 할 수 있다.그러나 백엔드 개발자에게는 좋은 API를 설계하는 것만큼 중요한 일이 하나 더 있다. 바로 좋은 API 문서를 작성하는 일이다. API 문서는 API를 사용하기 위해 사용자가 알아야 할 필수적인 정보들로, (미래의 나를 포함한) 나와 협업하는 모든 동료들에게 중요한 정보 제공처가 된다.그렇다면 좋은 API 문서란 무엇일까? 각자가 생각하는 바가 다르겠지만, 나는 “신뢰 가능한” API..

• format_list_bulleted 개발 일지/Server
• · 2024. 10. 26.
• textsms

@JsonNaming이 Query Parameter 또는 Form Data 요청에서 동작하지 않는 이유

Introduction현재 일부 API는 요청으로 들어오는 request data와 응답으로 반환되는 json의 네이밍 컨벤션으로 snake case를 채택하고 있다. 최근의 가장 대표적인 사례로는 oauth2 스펙을 준수한 API들의 지원이 있었는데, 이러한 snake case 변수명들이 Java 코드에까지 침투하도록 두고 싶지는 않았다.이를 해결하기 위해 지금까지는 jackson의 ObjectMapper의 직렬화/역직렬화 단계에서 카멜 케이스와 스네이크 케이스의 자동 변환을 수행할 수 있게 해주는 @JsonNaming 어노테이션을 이용해왔는데, 최근 유사한 이슈를 같은 방법으로 해결하려 했지만 동작하지 않았던 경험이 있어 이를 정리해보고자 한다.  @RequestBody의 Snake Case 매핑@G..

• format_list_bulleted 카테고리 없음
• · 2024. 4. 27.
• textsms

[Spring] 최초 실행 시 동작하는 로직을 정의해보자

도입 서비스를 운영하다보면, 다양한 이유로 애플리케이션의 구동 시점에 단 한 번만 실행되어야 하는 로직을 정의할 필요성을 느끼게 될 수도 있다. 최초 실행 시 긴 시간을 요구하는 로직들을 사용자에게 빠르게 제공하기 위한 Warm up 과정이나, 실행 시점에 입력된 동적 환경변수를 기반으로 제어되는 로직의 관리 등이 이에 해당한다. 그렇다면, 이러한 로직들은 어떻게/어디에 정의해야 할까? 이 글에서는 그 방법을 3가지로 분류하여 소개한다. Bean 생명주기를 이용 Runner를 이용 Event를 이용 Bean 생명주기를 이용 생성자 @Slf4j @Component public class MyBean { private final RequiredBean requiredBean; @Value("${hello.w..

• format_list_bulleted 개발 일지/Spring
• · 2024. 3. 2.
• textsms

Spring Event 도입기 (2) - 리스너 밖으로 전파되는 예외를 처리하라, Spring Event Exception Handling

이번 글에서는 Spring Event 도입기 1장에서 언급한 이벤트 리스너 밖으로 전파된 예외의 처리에 대해 다룬다. Spring Event의 자세한 사용 방법은 1장에서 소개하고 있다. Spring Event 도입기 (1) - 핵심 로직을 변경으로부터 보호하라 핵심 로직 변경에 따른 문제 발생과 해결 문제 - 가독성 저하 현재 사내에서 운영하는 서비스에는 사용자의 요청을 받으면 엔티티를 생성해 저장하고 메시지 큐에 발행한다라는 핵심 로직이 존 devpanpan.tistory.com 리스너의 사용 방법에 따른 분류 리스너는 동기/비동기로, 발행 즉시/발행 주체의 트랜잭션 범위에 따라 다양하게 정의할 수 있다. 이 글에서는 리스너의 사용 사례를 아래의 4가지로 분류하고 각각의 예외 처리 방법을 살펴본다. ..

• format_list_bulleted 개발 일지/Spring
• · 2024. 1. 20.
• textsms

Spring Event 도입기 (1) - 핵심 로직을 변경으로부터 보호하라

핵심 로직 변경에 따른 문제 발생과 해결 문제 - 가독성 저하 현재 사내에서 운영하는 서비스에는 사용자의 요청을 받으면 엔티티를 생성해 저장하고 메시지 큐에 발행한다라는 핵심 로직이 존재한다. 이 코드는 처음에는 아주 짧았고, 가독성도 나쁘지 않았다. 그러나 기획이 추가됨에 따라 해당 코드에는 여러 부가 로직들이 추가되었다. 엔티티의 생성 후 또다른 엔티티를 생성해야 하기도 하고, 메시지 큐에 발행하기 전 엔티티에 특정 변환 작업이 추가되기도 했다. 기획이 변경됨에 따라 이러한 변경 사항은 추가되기도, 다시 제거되기도 하며 핵심 로직을 포함한 클래스에 다양한 변경을 일으켰다. 그러다보니 코드는 점점 길어지고 가독성도 나빠졌다. 수정이 잦으니 여러 사람의 작업에 의해 conflict가 발생할 때도 많아졌고..

• format_list_bulleted 개발 일지/Spring
• · 2024. 1. 14.
• textsms

동적 쿼리로 조건 검색 기능 구현하기 (Spring Boot 3, Querydsl)

Introduction 저는 현재 주문제작 케이크 업체 탐색 서비스 “당도”의 백엔드 개발을 담당하고 있습니다. 당도에서는 사용자들이 원하는 업체를 빠르고 효율적으로 찾아낼 수 있도록 업체 검색 시 다양한 필터를 제공하고 있는데요. 제공되는 필터의 종류는 다음과 같습니다. 업체가 만드는 케이크의 카테고리 (꽃, 캐릭터, 레터링 등) 업체가 판매하는 메뉴의 최소/최대가 업체가 제공하는 외부 서비스 링크의 종류 (카카오톡 채널, 인스타그램 등) 케이크 수령 방식 (배송, 픽업) 업체 검색 API는 이러한 조건들을 모두 고려하여 제공할 데이터를 구성하게 되는데요. 이러한 조건을 적용한 쿼리는 Spring Data JPA의 Query Method 방식으로 생성하기에는 너무 많은 조건을 가지고 있었습니다. 그렇다..

• format_list_bulleted 개발 일지/Spring
• · 2023. 4. 29.
• textsms