The-SDK

김대은·2026년 9월 6일

SDK란?

SDK(Software Development Kit)는 특정 플랫폼이나 서비스에서 소프트웨어를 개발할 때 필요한 라이브러리, 도구, 문서 등을 묶어서 제공하는 개발 키트입니다.
약간 개발(빌드)하는 데 필요한 걸 모아놓은 종합 선물 세트

SDK를 사용하는 이유?

만약에 SDK가 없다면

어떤 라이브러리를 사용할지 이것저것 직접 찾아야 하고
각 라이브러리마다 호환성도 맞춰야 함
도구(컴파일러, 디버거 등)도 따로 설치하고 연결해야 함
사용법도 각 라이브러리 문서를 따로 찾아봐야 함

하지만 SDK가 있다면?
SDK는 개발에 필요한 라이브러리, 도구, 문서 등을 함께 제공하기 때문에 개발자가 필요한 구성 요소를 직접 찾아 구성하는 부담을 줄일 수 있습니다.

SDK 사용 이점

효율적인 개발
SDK는 애플리케이션을 개발할 때 필요한 라이브러리나 도구들을 제공해 개발 효율성을 높입니다.

더 빠른 배포
SDK는 개발자가 애플리케이션을 빠르게 구축하고 통합할 수 있는 도구를 제공해 더 빠르게 배포할 수 있게 합니다.

비용 절감
SDK는 애플리케이션을 개발하는 데 필요한 시간과 리소스를 단축시켜주고,
배포와 유지 보수와 관련된 비용을 줄여 프로세스와 업데이트를 단순화시켜준다.

SDK 개념 요약

SDK는 개발자가 특정 플랫폼이나 서비스의 기능을 쉽게 개발하고 활용할 수 있도록 라이브러리, 도구, 문서, 코드 샘플 등을 제공합니다.

SDK 작동 방식

플랫폼별 SDK를 다운로드하거나 설치합니다.
SDK를 사용하여 통합 개발 환경 내에서 애플리케이션을 개발합니다.
효율적인 개발을 위해 SDK에 포함된 지침, 문서, 코드 샘플 및 테스트 도구를 활용합니다.

SDK와 API의 차이점

지금부터 볼 SDK는 지도나 결제처럼 특정 서비스의 API를 쉽게 쓰게 도와주는 SDK예요. 이 관점에서 API와 비교해보겠습니다.

그러면 API를 쓰면 내가 지도를 직접 만들 필요 없이 지도 API를 가져오면 되는데,
문득 "어? 이거 SDK랑 똑같은 거 아닌가?" 라는 생각이 듭니다.

SDK와 API는 비슷해 보이지만, 사실 범위가 다른 개념입니다.

API는 애플리케이션끼리 소통할 수 있게 해주는 규칙입니다. "이렇게 요청하면 이렇게 응답을 주겠다"는 약속으로, 내가 내부에서 어떻게 데이터를 주고받는지 몰라도 정해진 형식으로 요청만 보내면 원하는 데이터나 기능을 받을 수 있습니다.

반면 SDK는 특정 플랫폼이나 서비스의 기능을 쉽게 사용할 수 있도록 라이브러리, API 연동 도구, 문서, 예제 등을 묶어서 제공하는 개발 키트입니다.

이 차이를 지도 기능으로 예를 들어보면 확실해집니다.

지도 API만 쓰면 "이 위도, 경도를 이 형식으로 보내라"는 규칙에 맞춰 요청 코드를 직접 짜야 합니다.
지도 SDK를 쓰면 addMarker(), showMap()처럼 이미 만들어진 함수를 갖다 쓰기만 하면 되므로 훨씬 편합니다.

즉, API만 있으면 그 규칙에 맞춰 요청 코드를 직접 다 짜야 하지만, SDK가 있으면 이미 만들어진 함수를 가져다 쓰면 되기 때문에 개발이 더 편해집니다.

정리하면

API는 "기능을 사용하기 위한 규칙"이고, SDK는 해당 기능을 쉽게 사용할 수 있도록 다양한 도구와 라이브러리 등을 제공하는 "개발 키트"입니다.

The-SDK

The-SDK는 Spring Boot 프로젝트에서 반복적으로 사용되는 공통 기능을 하나의 SDK로 묶어서 제공하는 프로젝트입니다.

Spring Boot로 개발하다 보면 HTTP 요청/응답 로깅, API 응답 형식 통일, 전역 예외 처리, Swagger 설정과 같은 기능을 프로젝트마다 반복해 구현합니다.

그리고 이러한 기능을 구현하다 보면 개발자마다 구현 방식이 달라질 수도 있습니다.
그래서 the-sdk는 이런 문제를 해결하기 위해 공통 기능을 미리 구현해두고, 프로젝트에서 SDK를 추가하는 것만으로 사용할 수 있도록 합니다.

기능은

HTTP 요청/응답 로깅
API 응답 형식 통일
전역 예외 처리
Swagger/OpenAPI 설정

주요 기능

로깅 필터 : the-sdk의 로깅 필터는 SDK를 추가하면 모든 HTTP 요청과 응답에 구조화된 로그가 자동으로 기록됩니다. 각 요청/응답 쌍은 동일한 UUID(Log-ID)로 연결되어 추적이 가능합니다.

헬스체크나 로그인처럼 로그를 남기기 싫은 URL이 있으면 개발자가 직접 패턴으로 등록해서 제외할 수 있는 기능도 함께 제공합니다.

doFilterInternal을 보면

├─ 로깅 제외 URL이면 → 그냥 필터체인 실행
├─ multipart 요청이면 → handleMultipartRequest
└─ 일반 요청이면 → handleRegularRequest

the-sdk를 보면 로깅 제외 URL일 경우 요청 내용을 로그를 남기지 않고 다음 단계로 넘어가고
요청이 하나가 아닌 여러 개 요청이 같이 들어있는 multipart 요청일 경우 파일 내용 자체는 로그로 남기지 않고, 파일 이름·크기·타입 같은 정보만 요약해서 로그로 남깁니다.
일반 요청일 경우는 그냥 요청 내용을 그대로 로그로 남깁니다.

응답 래퍼 : API가 컨트롤러에서 리턴할 때 보내는 데이터 형식을 공통으로 가지게 해주는 기능

여러 명이 컨트롤러를 만들다 보면, API 응답 형식이 사람마다 제각각 다를 수도 있습니다.

예를 들어서 래퍼가 없다면

// 어떤 API는 이렇게
{ "id": 1, "name": "홍길동" }

// 어떤 API는 에러 나면 이렇게
{ "error": "not found" }

// 또 다른 API는
"성공했습니다"

이렇게 응답 형식이 다 다르면, 프론트엔드에서 API마다 다른 방식으로 응답을 파싱해야 하고, 성공/실패를 판단하는 기준도 API마다 달라져서 유지보수가 힘들어집니다.

the-sdk의 응답 래퍼를 쓰면

// 성공했을 때
{
 "status": "OK",
 "code": 200,
 "message": "완료되었습니다",
 "data": { "id": 1, "name": "홍길동" }
}

// 실패했을 때
{
  "status": "NOT_FOUND",
  "code": 404,
  "message": "사용자를 찾을 수 없습니다"
}

이런 식으로 API 응답이 {status, code, message, data}라는 일관된 형식으로 응답한다.

the-sdk는 응답이 실패했을 때 data 값이 null이면 생략하는
@JsonInclude(JsonInclude.Include.NON_NULL)
이 어노테이션이 붙어있어서 data 값이 안 보입니다.

만약 컨트롤러가 데이터를 그냥 리턴하면
ApiResponseWrapper가 응답이 나가기 직전에 가로채서 자동으로 이렇게 감싸줍니다.

{ "status": "OK", "code": 200, "message": "OK", "data": { "id": 1, "name": "홍길동" } }

필요하면 개발자가 직접 감싸서 리턴할 수도 있습니다.

CommonApiResponse.success("조회 완료", userDto)
CommonApiResponse.error("찾을 수 없습니다", HttpStatus.NOT_FOUND)

application.yml의 sdk.* 설정

sdk.* 설정 구조

sdk:
  logging:      # LoggingFilter 설정
  response:     # ApiResponseWrapper 설정
  swagger:      # SwaggerConfig 설정
  exception:    # GlobalExceptionHandler 설정

각 기능(logging, response, swagger, exception)은 모두 enabled 옵션을 갖고 있으며, true/false로 해당 기능 전체를 켜고 끌 수 있습니다. 그 외 세부 설정은 기능마다 다릅니다.

1. sdk.logging

logging:
  enabled: true
  not-logging-urls:
    - "/v3/api-docs/**"
    - "/swagger-ui/**"
    - "/actuator/**"

not-logging-urls는 로그를 남기지 않을 URL 패턴

2. sdk.response

response:
  enabled: true
  not-wrapping-urls:
    - "/v3/api-docs/**"
    - "/swagger-ui/**"

not-wrapping-urls는 CommonApiResponse로 감싸지 않을 URL 패턴

3. sdk.swagger

swagger:
  enabled: true
  title: "ReadyGSM API"
  paths-to-match:
    - "/api/**"

title은 Swagger API 문서의 이름을 설정하고, paths-to-match는 Swagger 문서에 포함할 API 경로를 설정합니다.

4. sdk.exception

exception:
  enabled: true
  use-english-message: true

use-english-message는 에러 메시지를 영어로 할지 한글로 할지 정합니다.

Ready GSM에서는 The-SDK를 어떻게 사용하고 있을까?

저희 더모먼트의 학과체험신청 서비스인 Ready GSM은 The-SDK를 Gradle 의존성에 추가해 로깅, API 응답 래핑, 전역 예외 처리 등 기능을 활용하고 있습니다.

Ready GSM에서는 build.gradle을 확인해보면

implementation("com.github.themoment-team:the-sdk:1.5")

이렇게 The-SDK를 의존성으로 추가하고 있습니다.

Ready GSM, SDK 설정

로깅

Ready GSM에서는

sdk:
	logging: 
		enabled: true

이를 통해 HTTP 요청과 응답에 대한 로그를 SDK에서 처리할 수 있도록 구성되어있습니다.

not-logging-urls:
- "/v3/api-docs/**"
- "/swagger-ui/**"
- "/api/v1/auth/callback"
- "/api/v1/chat/test-sse"
- "/api/v1/chat"

이렇게 특정 URL은 로깅 대상에서 제외하고 있습니다.

응답 형식 통일

ReadyGSM에서는 The-SDK의 Response Wrapper를 사용해 API 응답 형식을 일정하게 통일하고 있습니다.

이 기능 덕분에

Controller에서 응답 형식을 일일이 안 맞춰도 됨
프로젝트 전체에서 일관된 API 응답 형식을 유지 가능

다만 ReadyGSM에는 모든 API 응답을 Wrapper로 감싸지 않는 경로도 존재합니다.

not-wrapping-urls:
	- "/v3/api-docs/**"
    - "/v3/api-docs"
    - "/swagger-ui/**"
    - "/swagger-ui.html"
    - "/api/v1/application/admin/excel"
    - "/api/v1/chat/test-sse" 
	- "/api/v1/chat"

ReadyGSM에서는 다음과 같은 URL을 not-wrapping-urls에 등록하여 Response Wrapper 적용 대상에서 제외하고 있습니다.

예외 처리

sdk:
	exception:
    enabled: true
    use-english-message: true

전역 예외 처리 기능 적용 코드
use-english-message 설정을 통해 예외 메시지를 영어로 사용할 수 있도록 설정되어 있습니다.

Swagger

ReadyGSM에서는 Swagger를 The-SDK를 통해 자동으로 설정해서 사용하고 있습니다.

sdk:
  swagger:
    enabled: true
    title: "ReadyGSM API"
    paths-to-match:
      - "/api/**"

이렇게 적용합니다.
ReadyGSM의 Controller에서 /api/... 형태로 정의된 API 중 /api/로 시작하는 API들을 Swagger 문서에 포함시키도록 설정한 것입니다.

The-SDK는 Swagger 설정을 제공하기 때문에 ReadyGSM에서는 application.yml을 통해 필요한 설정만 지정해서 사용할 수 있습니다.

최종 정리

The-SDK는 반복적인 보일러플레이트 코드를 줄여주는 스프링 부트용 SDK로, 크게 네 가지 기능을 제공합니다.

로깅 필터는 모든 HTTP 요청/응답을 자동으로 로그에 기록하며, 같은 Log-ID로 요청-응답 쌍을 추적할 수 있게 해줍니다. 파일이 포함된 multipart 요청은 파일 내용 대신 이름·크기·타입 같은 정보만 남겨 로그가 불필요하게 커지는 것을 막습니다.

응답 래퍼는 개발자마다 제각각이던 API 응답 형식을 {status, code, message, data}라는 하나의 구조로 자동 통일해줍니다. 컨트롤러가 데이터를 그냥 리턴하기만 해도 ApiResponseWrapper가 응답이 나가기 직전에 가로채서 감싸주기 때문에, 개발자가 매번 직접 형식을 맞출 필요가 없습니다.

이 외에도 Swagger 자동 설정을 통해 API 문서를 구성하고, 전역 예외 처리로 에러 발생 시에도 동일한 응답 형식을 보장합니다.

이 네 가지 기능은 application.yml의 sdk.* 설정을 통해 각각 독립적으로 켜고 끄거나(enabled), URL 패턴 단위로 세부 동작을 조정할 수 있습니다. 덕분에 팀원들은 같은 코드를 반복 작성하지 않고도, 설정 몇 줄만으로 일관된 로깅·응답 형식·문서화·예외 처리를 프로젝트 전체에 적용할 수 있습니다.

김대은

da2un

이전 포스트

AI 하네스

다음 포스트

The-SDK

SDK란?

SDK를 사용하는 이유?

SDK 사용 이점

SDK 개념 요약

SDK 작동 방식

SDK와 API의 차이점

The-SDK

주요 기능

application.yml의 sdk.* 설정

1. sdk.logging

2. sdk.response

3. sdk.swagger

4. sdk.exception

Ready GSM에서는 The-SDK를 어떻게 사용하고 있을까?

Ready GSM, SDK 설정

로깅

응답 형식 통일

예외 처리

Swagger

최종 정리

AI 하네스

OAuth 인증인가 흐름

0개의 댓글