안녕하세요, 토스뱅크 Server Developer 김인회 · 이준영입니다.
토스뱅크는 다른 은행과 달리 시스템을 MSA(Microservice Architecture)로 구축해 빠른 개발과 배포 속도를 누리고 있습니다. 하지만 "은탄환은 없다"는 말처럼, MSA는 다양한 복잡함을 수반했는데요. 그중 하나가 바로 Enum입니다.
이번 글에서는 MSA 환경에서 Enum이 왜 문제가 될 수 있는지, 그리고 토스뱅크는 이를 어떻게 해결했는지에 대해 소개해 드리려고 합니다.

MSA에서는 독이 될 수 있는 Enum
Enum은 타입 안정성, 컴파일 타임 체크, IDE의 자동완성 등의 장점이 있어서 Java 혹은 Kotlin을 다뤄본 개발자라면 자주 사용하는 도구일 것 입니다.
하지만 MSA환경에서는 이러한 Enum이 자칫 독이 될 수도 있는데요.
MSA에서는 하나의 Enum을 각 서버끼리 공유할 때 정의되지 않은 Enum 값이 넘어오면 Deserialize 에러가 발생합니다.


많게는 1년에 한두번씩 꾸준히 발생하는 이 문제는, 단순히 휴먼 에러라고 치부하기에는 너무 빈번하고 치명적이에요. 담당자가 바뀌거나, 서비스가 확장되거나, 새로운 Enum 값이 추가되는 순간 다시 문제가 발생하기 시작했고 토스뱅크 또한 예외는 아니었습니다. 
발전하는 MSA 속에서 Enum 관리가 점점 어려워지기 시작했고 결국 사람의 주의가 아닌 시스템적으로 이 문제를 예방하고 관리할 수 있는 방법이 필요해지기 시작했습니다.

제공자와 소비자
MSA에서 Enum 문제가 복잡해지는 이유 중 하나는 통신 주체에 따라 기대하는 동작이 다르기 때문입니다. 
그래서 저희는 요청 주체 기준으로 Enum 사용을 '제공자'와 '소비자'로 나누었고 각각의 Use Case에 맞는 전략을 수립했습니다.

1. 클라이언트(소비자) → 서버(제공자): 요청을 수신하는 입장에서는 오류가 명확해야 한다.
클라이언트가 Enum 값을 요청으로 전달하고, 서버가 이를 파싱해 처리하는 구조에서 서버는 Enum 값의 의미를 정확히 이해하고 처리해야 하므로, 정의되지 않은 값을 받을 경우 즉시 에러를 반환하는 것이 타당합니다. 
예를 들어 "UNKNOWN"으로 처리해 흐름을 이어가면, 의도하지 않은 상태로 비즈니스 로직이 흘러갈 수 있고, 데이터 무결성이 훼손될 우려가 있습니다.
따라서 이 경우에는 Enum 값을 엄격하게 검증하고, 알 수 없는 값은 400 Bad Request 등의 클라이언트 오류로 응답하는 것이 바람직합니다.

2. 서버(제공자) → 클라이언트(소비자) : 처리는 소비자의 선택에 맡긴다
반대로 서버가 Enum 값을 응답으로 보내고, 클라이언트가 이를 파싱하는 구조에서는 상황이 달라집니다. 서버가 Enum을 확장하여 새로운 값을 보내더라도, 클라이언트는 그 값을 아직 모를 수 있어요. 이때는 클라이언트 쪽에서 어떻게 대응할지를 선택할 수 있어야 합니다. 
예를 들어,
알 수 없는 값이면 경고를 띄우고 무시한다
fallback 동작으로 "UNKNOWN" 또는 "기타"로 처리한다
오류를 발생시켜 사용자에게 명시적으로 알린다
이처럼 소비자가 상황에 맞게 처리 전략을 선택할 수 있도록 열려 있는 구조가 필요합니다.
Kafka 소비자나 이벤트 핸들러 등 외부로부터 Enum을 수신하는 구조에서도 마찬가지입니다.  

이렇게, 각 Use Case 별 전략 수립 과정을 거쳐서 저희는 Enum deserialize 오류로부터 자유로워질 수 있는 아래 세 가지 해결책을 도출했습니다.

Enum을 선택적으로 deserialize하기 - EnumString
EnumString 전파하기 - ArchUnit
Enum 배포 의존성 끊기 - Meta Expose
이번 글에서는 이 세 가지 해결책을 통해 어떻게 Enum deserialize 오류를 극복했는지 자세히 살펴보겠습니다.
1. Enum을 선택적으로 deserialize하기 - EnumString
알지 못하는 Enum 값이 들어왔을 때 이를 역직렬화(deserialize)하는 방안을 고민하며, 처음에는 다음과 같은 방법들을 떠올렸어요.

@JsonEnumDefaultValue 혹은 @JsonCreator 설정을 추가해서 입력과 일치하는 Enum이 없으면 기본값을 내려준다.
@JsonCreator와 Property 를 사용해서 기본값을 반환할 Enum을 선택할 수 있게 한다.
하지만 이러한 해결법들은 기본값을 내려주더라도 도메인 로직상 여전히 예기치 않은 버그가 발생할 수 있으며, 개발자가 의도한대로 동작을 완전히 제어하기 어렵다는 한계가 있었습니다.
따라서 저희는 Enum 타입이 지닌 장점을 유지하면서도, 예상치 못한 값이 들어왔을 때 개발자가 직접 원하는 동작을 정의할 수 있는 유연한 접근법을 도입하기로 결정했어요.
하지만, 단순히 String으로 처리하는 것으로는 이 같은 유연성을 만족시키기 어렵고 사용성에 제한을 두기도 어려웠기 때문에, 아래와 같은 사용성을 제공하는 전용 라이브러리를 제작하게 되었습니다.



EnumString의 사용 예시를 코드로 보면 아래와 같은데요. 만약, EnumString이 아래와 같이 되어 있다고 가정하면,
abstract class EnumString<E : Enum<E>, T : EnumString<E, T>>(
    @get:JsonValue
    override val value: String,
) : DelegatedValue<String>(value), Comparable<EnumString<E, T>> {

    
    
    open fun toEnumOrElse(defaultValueSupplier: () -> E): E = toEnumOrNull() ?: defaultValueSupplier()
    
    open fun toEnumOrThrow(exceptionSupplier: () -> RuntimeException = { IllegalStateException("\"$value\" 에 해당하는 ${EnumName}을 찾을 수 없습니다. dependency version을 체크해주세요.") }): E = toEnumOrNull()
        ?: throw exceptionSupplier()
        
    open fun toEnumOrNull(): E? = EnumFinder.findByNameOrNull(value)
    
    companion object {
        val CONSTRUCTOR_CACHE = ConcurrentHashMap<KClass<out EnumString<*, *>>, KCallable<*>>()
        inline fun <E : Enum<E>, reified T : EnumString<E, T>> E.toEnumString(): T {
            val constructor = CONSTRUCTOR_CACHE.computeIfAbsent(T::class) {
                ...
            }
            return constructor.call(this.name) as T
        }
    }
}

EnumString을 적용하려는 Enum은 아래처럼 간단히 EnumString 인터페이스만 구현하면 됩니다.
Enum class Animal {

	DOG,
	CAT,
	RABBIT,
	;	
}

class AnimalString private constructor(
	override val value: String
) : EnumString<Animal>(...)

이렇게 정의된 다음에는, DTO에서 Enum을 EnumString 타입으로 선언하고 나서 필요에 따라 선택적으로 역직렬화 결과를 처리할 수 있게 되는데요. 
data class Foo(
 val animal: AnimalString,
)

// 아래와 같이 선택적으로 Enum을 deserialize 할 수 있습니다. 
fun helloWorld() {
	foo.animal.toEnumOrElse { throw IllegalArgumentException("역직렬화에 실패했어요.") }
	
	foo.animal.toEnumOrElse { return@toEnumOrElse Animal.DOG }
	
	// 혹은 필요에 따라 아래와 같은 편의 제공 메소드를 활용할 수도 있습니다.
	foo.animal.toEnumOrThrow()
	foo.animal.toEnumOrNull()
}
사용자는 상황에 따라 세 가지 메소드를 유연하게 선택해 사용할 수 있습니다.
toEnumOrNull / toEnumOrElse: 무시해도 괜찮은 경우에는 null 또는 지정된 기본값을 반환하고,
toEnumOrThrow: 무시하면 안 되고 반드시 함께 버전업 되어야 하는 경우에는 예외를 발생시킵니다.
이처럼 EnumString을 도입하면서 불명확한 Enum 입력에 대해 “예외 발생” 또는 “기본값 할당” 등 원하는 동작을 직접 정의할 수 있게 되었고, 결과적으로 Deserialize 과정에서 발생할 수 있는 오류를 안전하게 제어할 수 있게 되었습니다.

2. EnumString 전파하기 - ArchUnit
아무리 좋은 해결책 이더라도, 전파되지 않으면 무용지물이죠. 특히, 새로 합류한 구성원이 과거 문제를 잘 모른 채 기존처럼 Enum을 사용할 가능성도 고려해야 했어요. 그래서, 저희는 제공자 → 소비자 패턴에서 EnumString 사용을 시스템적으로 강제할 수 있는 방법을 찾기 시작했고 그 결과 ArchUnit을 찾게 되었습니다.

ArchUnit은, 패키지와 클래스간의 의존성을 테스트 해주는 오픈소스 라이브러리 도구로 저희만의 커스텀 룰을 만들어서 제공하면 제공자 → 소비자 패턴에서 EnumString을 막을 수 있었습니다.
그래서 저희는 공용 레포에 대해 ArchUnit으로 규칙을 만들고, 컨슈머 코드에서 Enum 사용을 감지해 빌드 시점에 실패하도록 설정했습니다. 덕분에 새로운 구성원도 EnumString을 자연스럽게 사용하게 만들 수 있었습니다.




3. Enum 배포의존성 끊기 - Meta Expose
위에서 소개한 EnumString 도입 이후, 서비스는 이전보다 훨씬 안정적으로 운영될 수 있게 되었습니다. 특히 버전과 무관하게 무시 가능한 Enum 값들에 대해서는 문제가 거의 발생하지 않게 되었죠.
하지만, 모든 Enum이 그렇게 유연할 수는 없었습니다. 어떤 Enum은 반드시 서비스 간에 함께 버전업이 되어야만 의미가 유지되며, 그렇지 않으면 여전히 오류가 발생할 수 있습니다.
예를 들어, 소비자(Consumer)라고 하더라도 "정의되지 않은 Enum 값을 받으면 도메인 로직이 깨지므로 오류를 발생시켜야 하는" 경우도 있었고, 제공자(Publisher) 입장에서도 Enum이 갱신되지 않은 소비자에게 메시지를 전송하면 실패가 발생하는 구조는 여전히 유효했습니다.
이를 해결하기 위해 저희는 Enum의 버전 동기화 상태를 관찰(Observe)하고 감지할 수 있는 시스템, Meta-Expose를 설계하고 도입하게 되었습니다.

Meta Expose의 핵심 구성과 동작 방식
Meta Expose의 구조를 그려보면 아래와 같은데요. 중앙의 Meta-Expose-Hub에서 Enum을 사용하는 모든 서버를 watch하고 있다가 버전이 올라가지 않은 서버를 자동으로 감지해 어드민과 모니터링 도구로 알림을 주게 됩니다.

자동 노출된 Enum API
Meta-Expose 라이브러리를 사용하는 서비스는 자신의 Enum 정의값을 자동으로 외부 API로 노출합니다.
이 API는 서비스 코드에 추가 작업 없이 자동 구성(auto config)됩니다.
중앙 Hub에서의 정합성 검증
Meta-Expose-Hub는 ServiceDiscovery를 통해 Enum API를 가진 서비스를 식별하고, 주기적으로 호출하여 Enum 정의값을 수집합니다.
이를 기준 Enum과 비교해 정의의 일관성을 검증합니다.
동적으로 서비스 식별
ServiceDiscovery는 Meta-Expose 의존성을 가진 서비스만을 식별해 관리합니다.
신규 서비스도 자동으로 포함되어, 누락 없이 전체 시스템을 커버할 수 있습니다.
Grafana를 통한 모니터링
검증 결과는 Prometheus에 지표(metric)로 수집되고, Grafana 대시보드를 통해 실시간으로 시각화됩니다.
특정 Enum 정의가 불일치하거나 누락된 서비스가 있는 경우 대시보드에서 바로 확인할 수 있으며, 알림 연동도 가능합니다.


이 시스템을 통해 저희는 다음과 같은 효과를 얻을 수 있게 되었고, 마침내 Enum deserialize 에러에서 자유로워질 수 있었습니다.
Enum 변경 시, 모든 관련 서비스가 실제로 버전업 되었는지를 눈으로 확인 가능합니다.
신규 Enum 추가 이후 배포 누락 서비스가 있다면 빠르게 감지하여 운영환경에서 발생할 수 있는 리스크를 사전에 제거할 수 있었습니다.
신규 구성원이 Enum 정의 방식에 익숙하지 않더라도 자동 검증과 시각화 덕분에 실수를 방지할 수 있었습니다.
마치며
실수를 완전히 막을 순 없지만, 이를 문제로 확산되지 않도록 시스템 차원에서 방어하는 것은 개발자의 몫입니다. 그래서 저희는 예측 가능한 구조와 자동화된 감시 체계를 통해 오류를 사전에 차단하고자 했어요. 이러한 노력 덕분에, 수백 번의 배포와 확장되는 MSA 환경 속에서도 단 한 번의 Enum 이슈 없이 안정적인 서비스를 운영하는 성과를 얻을 수 있었습니다.
토스뱅크는 고객의 자산을 직접 다루는 은행 서비스 특성상, 1년에 한 번 발생할 수 있는 작은 버그라도 결코 가볍게 넘기지 않습니다. 성능만큼 안정성이 중요한 은행 도메인에서, 구조적으로 실수를 방지하고 예측 가능한 시스템을 함께 설계해 나가고 싶다면, 토스뱅크에 합류해 주세요.



안녕하세요, 토스뱅크 Server Developer 김인회 · 이준영입니다.
토스뱅크는 다른 은행과 달리 시스템을 MSA(Microservice Architecture)로 구축해 빠른 개발과 배포 속도를 누리고 있습니다. 하지만 "은탄환은 없다"는 말처럼, MSA는 다양한 복잡함을 수반했는데요. 그중 하나가 바로 Enum

토스뱅크 여신의 발전하는 MSA에서 Enum을 안전하게 사용하는 노하우를 알려드립니다.

에러 0%, MSA에서의 Enum 관리 전략

안녕하세요, 토스 신용대출 찾기 서비스 팀 Server Developer 류경린입니다.
신용대출 찾기 서비스는 다양한 제휴사의 대출 상품을 연동하여, 고객이 보다 편리하게 대출 상품을 탐색하고 신청할 수 있도록 돕는 서비스입니다. 
이번 글에서는 신규 제휴사 연동 이후 제휴사의 테스트 서버가 유효한 응답을 주지 않거나, 특정 케이스를 테스트하기 어려운 상황을 어떻게 해결했는지, 그리고 이를 위해 설계한 mock 서버를 소개하고자 해요.

배경
신규 제휴사 연동 이후 다음과 같은 문제들이 반복적으로 발생했어요.
제휴사 개발 서버의 불안정한 응답 혹은 장애
특정 퍼널 또는 고객 조건에 맞는 테스트 데이터 확보의 어려움
테스트 과정에서 실제 제휴사 서버로부터 유효한 응답을 받기 어려운 상황
이러한 문제들은 QA 및 신규 기능 개발 효율을 떨어뜨릴 뿐 아니라, 서비스 출시 일정에도 영향을 주었습니다. 이를 해결하기 위해 사용자, 제휴사, 퍼널 단위로 정밀하게 동작을 제어할 수 있는 mock 서버를 설계했어요.

용어 정리
본격적인 설명에 앞서, 대출 도메인과 관련된 주요 용어를 간략히 정리할게요.
제휴사: 은행, 저축은행, 보험사 등 대출 상품을 제공하는 금융기관
가심사 조회: 고객 정보를 활용해 대출 금리, 한도 등을 간단히 확인하는 행위
대출 신청: 가심사 결과를 바탕으로 고객이 특정 상품에 대해 대출을 신청하는 행위
대출 실행: 제휴사가 고객 정보를 활용해 대출을 실행하고 자금을 입금하는 행위

요구사항
기능적 / 비기능적 요구사항은 아래와 같았어요.
기능적 요구사항

유저, 제휴사, 퍼널 단위로 mock 사용 여부를 설정할 수 있어야 한다.
동기/비동기 응답 방식을 모두 지원해야 한다.
relay 서버 역할을 수행해야 한다.
유저가 쉽게 설정할 수 있어야 한다.

비기능적 요구사항

기존 비즈니스 로직은 변경하지 않는다.
mock 서버에서 로직을 처리하기 위해 필요한 값은 커스텀 헤더로 전달한다.
토스 내 타 서비스에서도 mock 서버를 손쉽게 연동할 수 있는 유연한 구조를 제공한다.

설계 및 구현
mock 서버는 다음과 같은 구성요소로 설계되었습니다.

커스텀 헤더 주입
설정
예약(비동기 응답 지원)
mock 데이터 생성
Relay 서버 역할
메신저봇 연동
유연한 연동 구조 제공

1. 커스텀 헤더 주입
신용대출 찾기 서비스는 mock 동작 여부나 mock 데이터 생성 시 필요한 유저 정보를 클라이언트 요청의 헤더를 통해 주입받습니다. 이렇게 하면 비즈니스 로직에는 전혀 영향을 주지 않고, 테스트를 유연하게 제어할 수 있어요.
테스트 환경에서만 동작하도록 @Profile("dev") 설정을 통해 관리하며, 실제 통신 로직(RestTemplate, WebClient)에서 헤더 주입이 이뤄집니다.

RestTemplate
RestTemplate에는 인터셉터를 통해 요청마다 헤더를 추가할 수 있어요. 아래는 유저 ID와 원장 ID를 주입하는 예시입니다.
해당 인터셉터를 RestTemplate에 등록하면, 모든 제휴사 요청에 자동으로 헤더가 포함됩니다.
class MockServerHeaderInjectionInterceptor : ClientHttpRequestInterceptor {
    override fun intercept(
        request: HttpRequest,
        body: ByteArray,
        execution: ClientHttpRequestExecution,
    ): ClientHttpResponse {
        val headers = request.headers
        headers.add(MOCK_SERVER_HEADER_X_REQUEST_ID, "ids")
        headers.add(MOCK_SERVER_HEADER_X_USER_ID, "userId")

        return execution.execute(request, body)
    }
}

WebClient
WebClient에서는 ExchangeFilterFunction을 활용해 헤더를 주입해요. 아래는 동일한 목적의 필터 예시입니다.
WebClient 설정 시 이 필터를 .filter(addMockServerHeaderFilter())와 같이 등록해주면 돼요.
private fun addMockServerHeaderFilter(): ExchangeFilterFunction {
    return ExchangeFilterFunction.ofRequestProcessor { clientRequest: ClientRequest ->
        val injectedHeaders = ClientRequest.from(clientRequest)
            .headers { headers: org.springframework.http.HttpHeaders ->
                headers.add(MOCK_SERVER_HEADER_X_REQUEST_ID, "ids")
                headers.add(MOCK_SERVER_HEADER_X_USER_ID, "userId")
            }
            .build()
        Mono.just(injectedHeaders)
    }
}

2. 설정
모든 설정값은 DB 테이블에서 관리하여 유연성을 확보했어요.
partner_metadata: 제휴사 메타데이터
응답의 동기 / 비동기 방식 여부
네트워크 설정
암호화 여부 등
partner_response: 퍼널별 mock 응답 데이터
mock 데이터
응답 결과 json layout 등
user_status: 유저별 mock 응답 사용 여부 및 응답 지연 설정
콜백 을 N 초 후에 받을 것인지
특정 퍼널 에 대해 어떤 mock 응답을 받을 것인지 등

정의된 정보를 사용해 mock 응답 을 생성합니다.
val key = Triple(companyId, funnelType, status)
// 주어진 정보를 사용해 response 를 생성한다.
val response = partnerResponseService.create(key, metadata, requests)

3. 예약
mock 서버에서는 실제 제휴사처럼 콜백 응답을 지연하여 전송하는 기능이 필요합니다. 이를 통해 비동기 응답을 테스트할 수 있도록 지원하며, 실제 서비스 환경을 더 현실감 있게 시뮬레이션할 수 있어요.
예약은 다음과 같이 두 단계로 구성됩니다.

1. 예약 등록
가심사 조회나 대출 신청 API 호출 시점에, 예약 정보를 DB에 저장합니다.
각 요청에 대해 몇 초 후 콜백을 호출할 지 결정되며, 이 설정은 유저 설정(user_status) 또는 제휴사 메타데이터(partner_metadata)에 정의된 값을 사용합니다.
저장된 예약 정보는 schedule.executeTs 필드에 실행 시점을 기록합니다.

2. 예약 실행
mock 서버에서는 @Scheduled를 사용해 1분 단위로 주기적인 예약 조회 작업을 수행합니다.
실행 시점(executeTs)이 지난 예약 건들을 조회한 후, ThreadPoolTaskScheduler를 사용해 콜백 API 요청을 실제로 전송합니다.
private fun reserveInternal(schedule: ScheduleEntity, forceReserve: Boolean = false) {
  handlers
      .filter { it.canHandle(schedule) }
      .forEach { handler ->
          repository.save(schedule)
          if (forceReserve) {
              schedule.reserve()
              repository.save(schedule)
              scheduler.schedule(
                  { submitTask(schedule, handler) },
                  schedule.executeTs.atZone(ZoneId.systemDefault()).toInstant(),
              )
              return@forEach
          }

          lockExecutor.runOnce(
              lockKey = "$LOCK_KEY_PREFIX${schedule.id}",
              lockDuration = Duration.ofMinutes(1),
          ) {
              schedule.reserve()
              repository.save(schedule)
              scheduler.schedule(
                  { submitTask(schedule, handler) },
                  schedule.executeTs.atZone(ZoneId.systemDefault()).toInstant(),
              )
          }
      }
  }

4. mock 데이터 생성
mock 응답은 실제 제휴사 응답과 동일한 포맷으로 생성되어야 해요. 특히 상품명, 금리, 한도, 기간 등의 값은 토스 원장 데이터와 정합성 있게 주입되어야 하며, 이를 위해 다음과 같은 흐름으로 데이터를 생성합니다.

1. 예약어 기반 mock 템플릿 정의
각 제휴사별 응답 포맷에 따라 mock 템플릿을 사전에 정의합니다.
이 템플릿은 "{{amount}}", "{{productId}}"와 같은 예약어를 포함해요.
{
  "amount": "{{amount}}",
  "period": "{{period}}",
  "interestRate": "{{interestRate}}",
  "productId": "{{productId}}",
  "id": "{{id}}"
}



2. 예약어 치환
응답 JSON 내의 예약어를 실제 원장 데이터로 치환합니다.
이 때 JsonNode 객체를 순회하며 깊은 중첩 구조까지 치환되도록 설계했어요.
fun replace(
    replaceParams: Map<String, String>,
    node: JsonNode,
): JsonNode {
    when {
        node.isObject -> {
            val objectNode = node as ObjectNode
            objectNode.fields().forEach { (key, value) ->
                replaceParams.forEach { (keyword, replaceKeyword) ->
                    if (value.asText() == keyword) {
                        objectNode.put(key, replaceKeyword)
                    }
                }
                replace(replaceParams, value)
            }
        }
        node.isArray -> {
            val arrayNode = node as ArrayNode
            arrayNode.forEach { replace(replaceParams, it) }
        }
        node is Collection<*> -> {
            node.filterIsInstance<JsonNode>()
                .forEach { replace(replaceParams, it) }
        }
    }
    return node
}
예를 들어, "{{productId}}"는 실제 상품명으로 "{{amount}} 는 대출 한도로 치환됩니다.
{
  "amount": "10000000",
  "period": "12",
  "interestRate": "2.4",
  "productId": "OOO 자동차 담보 대출",
  "id": "{{id}}"
}

3. 상품명 → 원장 아이디 매핑 처리
각 원장에 매핑된 고유한 productId를 기반으로 다시 한 번 ID 매핑을 수행합니다.
loan_product_id_property_names 필드를 통해 각 제휴사마다 어떤 필드명이 상품명인지를 메타데이터로 관리하고 있기 때문에, 이를 기준으로 정확한 치환이 가능해요.
private fun replace(
    propertyNames: List<String>,
    keyword: String,
    replaceKeywordByPropertyNames: Map<String, String>,
    node: JsonNode,
) {
    when {
        node.isObject -> {
            val objectNode = node as ObjectNode
            val propertyName = propertyNames.firstNotNullOfOrNull { objectNode.get(it)?.asText() }

            // objectNode.fields.value 가 ObjectNode 일 수 있기 때문에 반드시 objectNode 의 전체 field 를 순회한다.
            objectNode.fields().forEach { (key, value) ->
                if (value.asText() == keyword) {
                    // keyword 를 templateValue 로 치환한다.
                    val templateValue = replaceKeywordByPropertyNames[propertyName]!!
                    objectNode.put(key, templateValue)
                }
                replace(propertyNames, keyword, replaceKeywordByPropertyNames, value)
            }
        }
        node is Collection<*> -> {
            node.filterIsInstance<JsonNode>()
                .forEach { replace(propertyNames, keyword, replaceKeywordByPropertyNames, it) }
        }
        node.isArray -> {
            val arrayNode = node as ArrayNode
            arrayNode.forEach { replace(propertyNames, keyword, replaceKeywordByPropertyNames, it) }
        }
    }
    return
}
예를 들어, “OOO 자동차 담보 대출” 상품명 에 맞는 거래번호 123456789가 치환됩니다.
{
  "amount": "10000000",
  "period": "12",
  "interestRate": "2.4",
  "productId": "OOO 자동차 담보 대출",
  "id": "123456789"
}

5. Relay 서버
mock 서버 는 아래 2가지 상황에 대해 relay 서버 역할을 해야 해요.
유저가 mock 응답 을 사용하지 않는 경우
제휴사 에서 콜백 API 를 호출하는 경우

유저가 mock 응답을 사용하지 않는 경우, 아래처럼 직접 제휴사 를 호출해 응답을 relay 합니다.
if (userStatus?.getPartnerResponseStatus(type) != null) {
  return getMockResponse()
}
val response = callPartner()

제휴사에서 콜백 API 를 호출하는 경우
제휴사에서 토스로 콜백 API 를 호출 하는 경우, api gateway를 통해 해당 요청이 인입돼요.
api gateway의 routing rule 을 신용대출 찾기 서버 에서 mock 서버로 수정해, mock 서버에서 콜백 API를 받고 이를 다시 신용대출 찾기 서버로 호출합니다.

6. 메신저봇 을 활용한 mock 설정
팀내에서 사용하고 있는 메신저봇에 mock 서버 설정 및 설정을 확인할 수 있는 기능을 추가합니다.


현재 제휴사, 퍼널 별 mock 설정 확인 버튼을 클릭해 현재 어떤 제휴사의 어떤 퍼널 에 대해 mock 데이터를 사용하고 있는지를 쉽게 알 수 있어요.



제휴사, 퍼널 mock 설정 버튼을 클릭해 특정 제휴사 의 어떤 퍼널에 대해 mock 데이터를 사용할지 쉽게 설정할 수 있습니다.


7. 유연한 연동 구조 제공
mock 서버는 토스 내 다양한 제휴사 연동 서비스들이 손쉽게 통합 및 활용할 수 있도록 확장 가능하고 유연한 아키텍처를 제공해요. 제휴사 연동 서비스는 검색, 신청, 취소, 상태 조회의 크게 네 가지 기능을 수행합니다.

모듈 구조
mock 서버는 모듈화된 구조를 통해 서비스별로 손쉽게 연동할 수 있도록 설계되었어요. 각 서비스에서 mock 서버를 연동할 경우, 해당 서비스 전용 모듈만 추가하면 되는 구조입니다.
mock-server-api : 각 서비스로부터 요청을 수신하는 API 모듈
mock-server-base : 콜백, 치환 기능 등 모든 서비스에서 공통적으로 사용할 수 있는 기능 및 추상화된 Handler를 제공하는 기반 모듈
mock-server-serviceA : 특정 서비스의 비즈니스 로직을 담은 모듈
mock-server-serviceA-admin : 특정 서비스의 어드민 기능을 포함한 모듈

Multi DataSource 지원
서비스 모듈마다 별도의 데이터 소스(DataSource)를 사용해야 하는 경우가 있어, Spring 기반에서 Multi DataSource를 구성할 수 있는 세 가지 방식 중 아래와 같은 특징을 고려해 Class 기반 정의 방식을 채택했어.
base package 기준 정의
annotation 기반 정의
class 기반 정의 ✅

채택 사유:
1. Repository 상속 구조에 불편함
admin 모듈은 어드민 특화 쿼리를 별도로 정의합니다.
동시에 기존 서비스 모듈의 공통 Repository 기능도 재사용해야 합니다.
따라서 admin 모듈의 repository 클래스는 서비스 모듈의 repository를 상속하는 구조입니다.
2. 어노테이션 중복 선언 문제
어노테이션 기반(@ServiceARepository) 으로 설정할 경우, 서비스 모듈의 repository 클래스와 어드민 모듈의 repository 클래스 양쪽에 동일한 어노테이션을 선언해야 하는 번거로움이 발생합니다.
이는 유지보수 시 의도치 않은 설정 누락 혹은 중복을 유발할 수 있고, 설정 관리가 복잡해집니다.
3. 패키지 구조의 자율성 확보
모듈 단위로 동일한 패키지 구조를 사용할 수 있기 때문에 base package 스캔 방식 역시 적용이 어렵습니다.

프로퍼티 설정 전략
각 모듈에서 필요한 설정은 모듈 내부의 application-{service}.properties 파일을 통해 정의해요.
기존에는 mock-server-base의 application.properties에 모든 설정을 통합할 수도 있었지만, 각 설정이 어떤 서비스에 영향을 미치는지를 명확히 구분하고 관리하기 어려운 점을 고려하여 모듈별로 분리하는 방식을 선택했어요.
최종적으로는 base 모듈의 application.properties에서 spring-cloud-config 및 각 서비스의 설정 파일(application-{service}.properties)을 import하여, 모든 프로퍼티를 통합적으로 로딩할 수 있도록 구성합니다.

마치며
대외 기관과의 연동을 다루는 많은 회사들이 저희와 유사한 어려움을 겪고 있을 거라 생각해요.
토스의 신용대출 찾기 서비스 팀은 mock 서버와 relay 기능을 결합한 테스트 환경을 누구나 쉽게 이용할 수 있게 구축함으로써, 테스트 효율성과 신뢰성을 모두 확보할 수 있었습니다.
이 글이 유사한 문제를 고민하고 있는 개발자분들께 실질적인 도움이 되었으면 좋겠습니다. 감사합니다.


안녕하세요, 토스 신용대출 찾기 서비스 팀 Server Developer 류경린입니다.
신용대출 찾기 서비스는 다양한 제휴사의 대출 상품을 연동하여, 고객이 보다 편리하게 대출 상품을 탐색하고 신청할 수 있도록 돕는 서비스입니다. 
이번 글에서는 신규 제휴사 연동 이후 제휴사의 테스트 서버가 유효한 응답을 주지 않거나, 

대출 연동 테스트의 안정성과 효율성을 극대화하는 mock 서버 개발기를 공유합니다.

신용대출 찾기 서비스 제휴사 mock 서버 개발기

Simplicity 4 세션, 잘 즐기셨나요?
이번 글에서는 Simplicity 4 세션 속 시각 자료 제작기를 이야기해보려 해요. 처음에는 단순히 관련 화면을 캡처하거나 녹화해 보여주면 충분할 거라고 생각했어요. 하지만 막상 작업에 들어가 보니, 시청 흐름과 정보 전달까지 고려해야 할 게 정말 많더라고요.
Simplicity 4는 짧고 몰입도 높은 숏폼 형식의 세션으로 구성되었어요. 길이가 짧은 만큼, 짧은 문장에 많은 정보를 담아야 했고, 연사의 말만으로는 충분히 설명되지 않는 경우도 많았죠. 그래서 세션 자료는 단순히 재미나, 심미성을 위한 장치가 아니라, 텍스트에 담기지 않은 맥락까지 설명해주는 ‘시각적 해설자’ 역할을 해야 했어요. 단순히 텍스트를 보조하는 것이 아니라, 동등한 수준으로 메시지를 전하는 시각적 콘텐츠가 필요했던 거죠.


좋은 세션 자료의 두 가지 조건
1. 숏폼 콘텐츠에 어울리는 시각적 흐름 만들기
우리가 숏폼 콘텐츠를 볼 때 자막보다 이미지나 시각적 흐름에 먼저 반응하잖아요. 음성만 듣고 자막은 스킵하는 경우도 많고요. Simplicity 4의 세션 자료도 마찬가지였어요.
자료는 텍스트보다 먼저 사용자의 시선을 사로잡고, 어떤 요소가 중요하고 어디에 먼저 주목해야 하는지 자연스럽게 안내해야 했죠. 여러 요소가 한 화면에 평면적으로 나열되면, 정보의 우선순위가 모호해져 시선이 흩어지고 텍스트와 이미지가 따로 노는 것처럼 느껴지기 쉽거든요.
그래서 강조하고 싶은 부분엔 살짝 기울인 원근감을 주고, 덜 중요한 정보는 흐림(blur) 효과를 적용해 시선을 정리했어요. 이렇게 시각적 위계를 설계하면, 사용자는 자료를 따로 해석하지 않아도 중요한 정보를 자연스럽게 먼저 받아들이고, 빠르게 이해할 수 있는 구조를 경험할 수 있어요. 단순한 시각 효과지만, 집중도와 몰입도를 높이는 데 꽤 효과적이었답니다.


2. 어떤 기기에서도 자연스럽게 읽히도록
이번에는 PC와 모바일 환경 모두에서 콘텐츠를 편하게 볼 수 있도록 최적화 하는 게 중요했어요. 하나의 자료를 두 환경에서 최대한 공통으로 활용하는 방식으로 접근했는데, PC와 모바일은 화면 비율이 많이 달라서 고민이 많았죠. 그래서 하나의 자료가 양쪽 환경에서 모두 읽히도록 최적화하는 작업이 필요했어요.
PC 화면은 넓고 모바일은 작다 보니, 동일한 세션 자료를 보여줄 때 특히 모바일에서는 많은 부분이 잘리더라고요. 상단에는 제목이나 공유 버튼 같은 요소들이 있어 그 아래에 위치한 중요한 정보가 가려질 수 있었죠. 
그래서 어떤 기기에서 보더라도 핵심 정보가 화면 중앙에 잘 보이도록 모아서 배치했어요. PC 화면을 그대로 보여주는 방식은 작은 모바일 화면에선 가독성이 떨어질 수 있기 때문에, 작은 모바일 화면에서도 잘 보이도록 웹사이트 창처럼 보이게 디자인하기도 했어요. 


누구나 제작할 수 있는 환경 만들기
Simplicity는 한 번 하고 끝나는 이벤트가 아니라 시즌마다 반복되는 컨퍼런스예요. 그만큼 제작 효율성과 지속가능성을 함께 고려해야 했어요.이번 시즌부터는 새 사이트를 만드는 대신, 하나의 플랫폼에 콘텐츠를 업데이트하는 방식으로 구조를 전환했고, 이에 따라 자료도 재사용 할 수 있도록 템플릿을 만드는 게 필요했죠.
토스에서 그래픽이나 브랜딩을 섬세하게 다루는 직군이 아니라면 포토샵이나 일러스트레이터 같은 툴은 잘 사용하지 않는데요. 정적인 이미지는 포토샵 없이도 쉽게 제작할 수 있어야 한다고 생각했어요. 비디자인 직군도 자주 사용하는 툴인 ‘피그마’를 활용해보기로 했죠. 피그마의 다양한 플러그인을 활용하면, 디자인 경험이 많지 않더라도 누구나 제작할 수 있는 환경이 만들어지더라고요. 

원근감을 줄 수 있는 플러그인
특정 부분을 흐리게 해주는 블러 플러그인
그림자를 넣어주는 플러그인
그리고 이 제작법을 가이드로 정리해 내부에서 누구나 참고할 수 있도록 했어요. 지속 가능한 Simplicity 제작을 위한 기반을 마련한 셈이죠. 실제로 이번 Simplicity에서는 정적인 세션 자료를 모두 피그마로 제작했어요.


앞으로의 세션 자료
Simplicity 같은 온라인 컨퍼런스에서 세션 자료는 단순한 보조물이 아니라 콘텐츠의 일부예요. 세션을 자연스럽게 이해하도록 도와주는 역할을 하죠. 좋은 세션 자료는 사용자가 ‘자료를 보고 있다’는 인식 없이도 내용을 자연스럽게 받아들이게 만들어준다고 생각해요. 
그런 자료를 만들기 위해서는 치열한 고민이 필요하고, 그만큼 디자인의 역할도 중요해요. 이런 고민들이 앞으로의 Simplicity나 다른 온라인 컨퍼런스에서도 잘 이어져서, 정보를 쉽게 전달하는 아름다운 자료들이 계속 만들어지기를 바라요.


Simplicity 4 세션, 잘 즐기셨나요?
이번 글에서는 Simplicity 4 세션 속 시각 자료 제작기를 이야기해보려 해요. 처음에는 단순히 관련 화면을 캡처하거나 녹화해 보여주면 충분할 거라고 생각했어요. 하지만 막상 작업에 들어가 보니, 시청 흐름과 정보 전달까지 고려해야 할 게 정말 많더라고요.
Simplic

Simplicity의 모든 세션 속 시각 자료들은 겉보기엔 평범하지만 세심한 설계를 통해 만들어졌어요. 누구나 정보를 쉽고 아름답게 전달하는 자료를 만들 수 있도록 고민한 방법을 들려드릴게요.

아름답고 이해하기 쉬운 세션 자료 만들기 | Simplicity 4 제작기 #5

안녕하세요, Simplicity 4에서 인터랙션 디자인을 맡은 Interaction Designer 백송은입니다. 
이번 심플리시티를 디자인하면서 고민한 것들을 인터랙션 디자이너의 시선에서 하나씩 나눠보려고 해요.
사실 저는 2023년 첫 온라인 심플리시티 프로젝트에 어시스턴트로 참여했었어요. 그때는 단순히 QA를 돕는 역할 정도였는데, 입사 두 달 만에 메인 인터랙션 디자이너로 전사 프로젝트에 참여하게 됐어요. 인터랙션 전반의 방향을 직접 이끌어야 하는 상황이었는데, 가장 먼저 이런 생각이 들었어요.
‘온라인에서도 오프라인처럼 몰입하게 하려면, 어떻게 설계해야할까?’
이번 시즌의 인터랙션은 이런 고민에서 시작했죠.

Simplicity 4의 핵심, 인터랙션
온라인 컨퍼런스에서 가장 중요한 건 무엇일까요? 저는 지루하지 않게 끝까지 볼 수 있는 환경을 만드는 것이라고 생각해요. 오프라인 공간도, 연사자 얼굴도 없이 오직 화면과 소리만으로 몰입을 유지해야 하니까요. 
사실 지난 Simplicity에서는 중간 이탈률이 높았는데요. 그건 곧 사용자가 콘텐츠에 집중하지 못했다는 의미였어요. 4가지가 원인이라고 생각했죠.

한 화면에 콘텐츠가 너무 많아 어디서부터 봐야 할지 헷갈린다.
데스크탑 중심 구성이라서 모바일에서는 보기 불편하다.
세션 길이도 평균 20~25분으로 부담스럽다.
자막이 한 번에 길게 노출돼 집중력을 유지하기 어렵다.


Simplicity 4에서 가장 중요했던 과제는 이 문제들을 해결해 ‘몰입감 있는 시청 흐름’을 만드는 것이었어요. 단순히 콘텐츠의 내용을 바꾸는 것이 아니라, 사용자가 콘텐츠를 어떻게 따라가게 할지를 설계하는 ‘인터랙션 디자인’이 핵심이었죠.

이렇게 디자인했어요
1) 모바일과 데스크탑, 각각의 경험을 고려한 인터랙션
같은 콘텐츠라도 어떤 디바이스에서 보느냐에 따라 사용자 흐름이 달라질 수 있다는 점을 반영했어요.
홈 화면

모바일
초기에는 세로 스크롤, 그리드 레이아웃 등 여러 가지 시안을 테스트해봤어요. 직접 프로토타입까지 만들어보면서 비교해보니, 가로와 세로 스크롤을 조합해 프리뷰 영상을 보여주는 방식이 숏폼처럼 짧고 빠르게 넘기며 훑어보는 감성과 가장 잘 맞더라고요.

그래서 최종적으로는 가로 · 세로 스크롤을 조합하고, 세션이 포커스되면 프리뷰 영상이 자동 재생되는 구조로 구성했어요.


데스크탑
데스크탑에서는 모바일의 가로 · 세로 스크롤을 그대로 가져가기엔 활용할 수 있는 화면 면적이 너무 넓다는 고민이 있었어요. 
그래서 여러 시도를 해봤죠. 리스트를 한 번에 다 보여주고, 호버하면 정보가 뜨게 하기도 했고, 세로스크롤만 사용해서 큰 화면에 세션 하나하나를 자세히 보여주는 시안도 그려봤어요. 막상 직접 그려보니, 호버 액션은 너무 정신없고, 세로 스크롤 방식은 세션이 하나씩만 보여서 오히려 답답하게 느껴졌어요.
그래서 시도해본 게 가로 스크롤 기반의 포커싱 구조였어요. 
여러 세션 썸네일이 한눈에 보이면서도, 스크롤할 때마다 세션 하나하나에 자연스럽게 시선이 머무는 흐름이 만들어졌고, 덕분에 한 번에 하나의 정보 흐름에 집중하면서도 시야가 확 트인 개방감을 유지할 수 있었어요.


세션 UI

모바일
세션 콘텐츠에 완전히 몰입할 수 있도록, 목차와 사운드 버튼, 홈 버튼, 재생바 등 주요 기능을 모두 상단에 배치했어요. 화면 중앙은 콘텐츠에만 집중할 수 있게 설계한 거죠.
데스크탑
데스크탑에서도 모바일과 동일한 기능은 유지하되, 터치이펙트, 호버 액션등 데스크탑 환경에 맞는 인터랙션을 별도로 디자인했어요.


세션 전환

모바일
숏폼 콘텐츠처럼 다음 세션으로 자연스럽게 스크롤되면서 자동 재생되도록 구성했어요.
사용자는 별도의 조작 없이도 끊김 없는 흐름으로 콘텐츠를 이어볼 수 있어요.
데스크탑
넓은 화면에서는 모바일처럼 스크롤로 전환하면 시선이 분산되는 느낌이 있었어요. 그래서 세션이 전활될 때 그라디언트를 활용한 전환 효과를 더해, 몰입감을 유지하면서 자연그럽게 다음 콘텐츠로 넘어갈 수 있도록 설계했어요.



2) 모바일 기준 설계

이번 시즌은 모바일 기준으로 먼저 설계하고 데스크탑는 그에 맞춰 최적화했어요. 지난 시즌 데이터를 봤을 때, 모바일 시청자가 점차 늘어났거든요. 가장 큰 변화는 화면을 좌우·중앙 3분할해 터치 위치에 따라 장면을 빠르게 넘길 수 있게 한 점이에요.


초기에는 데스크탑에서도 모바일과 마찬가지로, 화면을 클릭해서 씬을 넘기는 방식으로 프로토타입을 만들어봤어요. 그런데 막상 사용해보니, 마우스 커서를 왼쪽과 오른쪽으로 계속 움직여야 하는 게 생각보다 불편하더라고요. 그래서 하단에 버튼을 배치하고, 키보드로도 조작할 수 있게 인터랙션을 수정했어요.



3) 첫 화면 몰입 설계
사용자가 이야기에 완전히 빠져들면 좋겠다고 생각했어요. 그래서 세션에 진입하는 순간부터 몰입이 시작될 수 있도록 세심하게 구성했어요. 홈에서 세션 카드를 클릭하면, 카드가 확대되고 배경 그래픽이 점점 커지며 화면을 꽉 채워요. 이어서 제목과 연사자 정보, AI 디스크립션이 순차적으로 등장해요. 이 흐름을 자연스럽게 이어지도록 해서, ‘이제 집중할 차례야’라는 감정적 전환을 유도하고자 했어요. 





4) 12개의 세션 템플릿

총 16개의 템플릿을 기획하고, 실제 사용성과 개발 공수를 고려해 12개로 구성했어요. 단순한 콘텐츠 프레임이 아니라, 정보 구조와 인터랙션의 방식까지 함께 정해진 설계 단위였죠.


각 템플릿마다 텍스트 등장 방식과 배경 전환 효과를 다르게 구성했어요. 영상 전체가 하나의 패턴으로 반복되지 않고, ‘다음은 뭘까?’ 하는 기대감을 불러일으키고 싶었거든요. 같은 템플릿이라도 옵션에 따라 다르게 활용할 수 도록, 내용에 맞게 UI를 디자인하고 자연스럽게 연결되는 인터랙션도 함께 설계했어요. 씬마다 다른 템플릿을 적용해서 지루함 없이 몰입감을 유지할 수 있었죠.


무엇보다 중요한 건, 이 12개의 템플릿이 Simplicity의 콘텐츠 제작을 ‘시스템화’했다는 점이에요. 누구나 이 템플릿을 조합해 세션을 만들 수 있게 되었고, 다음 시즌에도 그대로 활용 가능한 구조가 된 거죠.
Simplicity는 매 시즌 새로운 콘텐츠를 만드는데요. 처음부터 디자인하고 개발하는 방식은 리소스가 너무 많이 들고, 지속 가능하지 않았어요. 이번 시즌은 재사용이 가능한 구조적인 전환이 이뤄졌다는 점에서, 콘텐츠 제작 방식의 큰 전환점이었어요.



5) 슬릭한 자막효과 

이전 시즌에서는 자막이 한꺼번에 너무 많이 노출되는 게 아쉬웠거든요. 그래서 이번 시즌에서는 연사의 음성과 타이밍을 맞춰 자막이 한 줄씩 점진적으로 채워지는 방식을 적용했어요. 정보를 강제로 읽게 만드는 대신, 자연스럽게 따라가는 리듬감 있는 흐름을 만들고 싶었어요. 


자막이 채워지는 효과에도 작은 디테일이 숨어있어요. 초기 시안에서는 문장이 채워질 때 마지막 부분이 딱 끊기듯이 멈춰서 조금 어색한 느낌이 있었어요. 팀 안에서 여러 방식으로 테스트하는 과정을 거치면서 지금처럼 자연스럽고 완성도 높은 형태로 다듬을 수 있었어요.



마무리하며
사실, 처음엔 부담이 정말 컸어요. ‘내가 심플리시티를 디자인한다고..?’ 하는 마음에 스스로도 얼떨떨했죠.
메인 인터랙션 디자이너로 프로젝트를 이끌면서 느낀 점은, 단순히 디자인 방향을 잡고 시안을 만드는 일만이 다가 아니라는 거예요. 여러 시안을 직접 프로토타입해보고 최종안을 결정하는 과정, 동료들과의 커뮤니케이션, 일정 조율까지 디자인 외적인 프로젝트 리딩 역량도 정말 많이 필요하더라고요.
초반엔 어디서부터 시작해야 할지, 또 어떻게 팀을 리드하며 조율해나가야 할지 감이 안 잡혀서 ‘내가 정말 이걸 해낼 수 있을까?’ 싶은 막막함과 불안감도 있었어요.
하지만 저 역시 심플리시티를 보고 토스에 입사를 결심했던 사람이거든요. 이번 시즌을 계기로 또 다른 누군가가 입사를 결심할 수 있다면, 그 결심의 순간이 좋은 기억으로 남길 바라는 마음으로 책임감을 갖고 디자인에 몰입했어요.
이번 시즌은 저에게도 큰 도전이자 배움의 시간이었어요. 저의 고민과 몰입이 담긴 이번 심플리시티가 여러분에게 작은 시작점이 되어줬다면, 그보다 더 기쁜 일은 없을 것 같아요.


안녕하세요, Simplicity 4에서 인터랙션 디자인을 맡은 Interaction Designer 백송은입니다. 
이번 심플리시티를 디자인하면서 고민한 것들을 인터랙션 디자이너의 시선에서 하나씩 나눠보려고 해요.
사실 저는 2023년 첫 온라인 심플리시티 프로젝트에 어시스턴트로 참여했었어요. 그때는 단순히 QA를 돕는 

아티클 시리즈