Spring 기반 멀티모듈 프로젝트 환경변수 설정 방법

요약: 이 글은 Spring 기반 멀티모듈 프로젝트에서 환경변수를 설정하는 다양한 방법을 비교하고, 가장 적합한 방식을 선택하는 과정을 설명합니다. Spring 환경에서 spring.config.import, spring.profiles.include, @PropertySource, @Profile을 활용한 설정 방식의 장단점을 분석하고, 최종적으로 @Profile과 @PropertySource를 조합한 방법을 선택한 이유를 제시합니다. 결론적으로 환경변수 설정을 체계적으로 관리하고 유지보수성을 높이는 방안을 공유하는 것이 핵심입니다.

💡 리뷰어 한줄평

roy.ce 카카오페이 서버 개발자가 알려주는 Spring 멀티모듈 환경변수 설정 노하우! 멀티모듈 프로젝트의 복잡성을 줄이고 효율적인 환경 설정을 원한다면 꼭 읽어보세요!

zeta.wan 멀티모듈을 잘 활용하면 불필요한 설정을 최소화할 수 있다는 것을 느꼈습니다. 글을 읽는 여러분도 더 나은 방식이 무엇일지 고민하는 시간이 되면 좋겠습니다.

시작하며

안녕하세요. 파트너플랫폼파티에서 서버 개발을 하고 있는 그루(Geuru)입니다. 카카오페이에서는 Spring 기반 멀티모듈 프로젝트로 서비스를 개발하고 있습니다. 그 이유는 요구사항이 여러 가지 추가되면서 특정 목적을 위한 애플리케이션이 필요하거나, 도메인의 확장에 따라 모듈을 추가하기 때문입니다. 모듈을 추가함에 따라 각 모듈별로 필요한 환경변수 설정을 위해 yml 또는 properties 파일을 작성하고 있습니다.

입사하고 파트너 도메인에 익숙해지기 위해 여러 프로젝트를 리뷰하면서 알게 된 사실이 있습니다. 팀 내 프로젝트마다 환경변수 설정하는 방법이 미묘하게 다르다는 사실입니다. 더 크게는 팀마다 환경변수 설정하는 방법이 다르고, 취향 차이도 있다는 것입니다.

이번 글에서는 제가 사내 여러 프로젝트를 경험해 보면서 알게 된 환경변수 설정방법은 어떤 것들이 있는지 소개해보려고 합니다. 먼저 멀티모듈에서의 환경변수 설정 고민을 말씀드리고, 그 고민을 해결할 수 있는 환경변수 설정 방법 4가지를 알려드리려고 합니다. 그래서 최종적으로 저희는 그 4가지 방법 중 어떤 방법을 선택했으며, 그 이유는 무엇인지 말씀드리려고 합니다.

이 글을 읽으시는 독자분께서는 각자의 프로젝트의 환경변수 설정 방법과 본 글에서 소개하는 설정방법을 비교해 보면서, 본인은 어떤 방식을 적용하고 있는지 알아보고 싶은 분들께 이 글을 추천합니다. 또, 이것 외에 다른 방법이 있으면 코멘트도 남겨주세요 😀

멀티모듈과 환경변수

멀티모듈의 정의와 장점

멀티모듈 프로젝트는 여러 개의 모듈로 구성된 프로젝트로, 각 모듈은 독립적으로 빌드되고 배포될 수 있습니다. 멀티모듈로 프로젝트를 구성하는 이유는 코드의 재사용성을 높이고, 모듈 간의 의존성을 명확히 하여 유지보수성을 향상하기 위함입니다.

예를 들어, 위와 같이 머니 송금 API를 사용하는 internal-api(사내용 API 모듈), external-api(서비스용 API 모듈)가 있다고 가정하겠습니다. 만약 internal-api, external-api가 각각 단일 모듈로 프로젝트를 구성한다면, 각 프로젝트마다 머니송금용 RestTemplate과 HttpClient 코드와 같은 구현체를 두 번이나 작성하게 될 것입니다.

같은 코드 작성 두 번 정도야 할 수 있습니다. 유지보수하거나 신규 서비스 개발 시에는 어떨까요? 만약 머니 송금 API를 사용하는 admin-api(운영자용 API 모듈) 같은 애플리케이션이 늘어난다면, 한 번 더 구현체를 작성해야겠죠? 또, API 버전이 V1에서 V2로 변경되는 스펙 변경이 발생한다면 각 프로젝트마다 해당 내용을 반영해야 합니다.

아까 말씀드린 상황을 해결하기 위해 멀티모듈로 구성하게 되면, 위와 같이 한 프로젝트 내에 admin-api, internal-api, external-api, client(머니 송금 API 스펙을 구현한 모듈)와 같이 4개의 모듈로 구성할 것입니다.

다시 말해 각 api 모듈(admin-api, internal-api, external-api)의 build.gradle을 통해 client 모듈을 implementation으로 의존성을 명시할 것입니다. 그래서 API 버전이 V1에서 V2로 변경되는 API 스펙 변경의 작업의 경우, client 모듈만 수정하면 api 모듈 3개 각각은 단순하게 빌드를 통해 client 모듈의 변경사항을 반영하여 애플리케이션을 재빠르게 배포할 수 있습니다.

멀티모듈에서의 환경변수 파일에 대한 고민

아까 위에서 말씀드린 예시에서 API 스펙이 V1에서 V2로 단순하게 path만 변경됐다고 가정하겠습니다. API path 같은 경우, 코드로 선언하여 넣을 수도 있지만 저희 팀의 경우 API에서 변경될 수 있는 host, path, token과 같은 정보들은 yml 또는 properties와 같은 환경변수 파일로 관리하고 있습니다. 해당 환경변수 파일은 어떤 모듈에 있어야 할까요? Spring 애플리케이션이 있는 api 모듈에 있어야 할까요? 아니면 client 모듈에 있어야 할까요?

API 스펙 변경과 가장 관련 있는 모듈이 무엇인지 생각해 보면, client 모듈일 것 같습니다. 그렇다면 client 모듈 내 환경변수 파일을 만들어야 할 것 같은데, 이 파일의 이름은 어떻게 지어야 할까요? 더 나아가서, Spring 애플리케이션에서 활성화된 프로필(Profile)마다 host가 달라져야 하는 경우도 있을 텐데 이럴 때는 어떻게 하죠?

그 고민을 해결할 수 있도록 아래 챕터에서는 환경변수 설정 방법인 spring.config.import, spring.profiles.include, @PropertySource, @Profile과 @PropertySource 에 대해 설명드리려고 합니다. 그리고 왜 저희 팀에서는 그 4가지 방법 중 @Profile과 @PropertySource을 선택했는지 말씀드리겠습니다.

환경변수 설정 방법

예시 프로젝트 환경 구성

본격적인 환경변수 설정 방법 설명에 들어가기 앞서, 독자분들의 빠른 이해를 위해 예시 프로젝트로 설명드리려고 합니다.

예시 프로젝트는 internal-api, client라는 모듈 2가지가 있습니다. internal-api 모듈은 build.gradle을 통해 client 모듈을 implementation으로 의존성을 명시하고 있습니다. 만약 client 모듈이 재사용성이 없다면 구현 내용을 internal-api 모듈 내 구현하겠지만, 다른 모듈(external-api)에서도 재사용될 것으로 가정하여 client 모듈은 별도 모듈로 구현했습니다.

client 모듈에서 필요한 환경변수는 host, transfer-money-path와 같은 머니 송금 API 요청을 하기 위한 변수입니다. 아래부터는 이러한 환경변수 값을 주입하는 방법 4가지에 대해 알아보겠습니다.

자세한 구현 내용은 제가 만든 깃허브 레포지토리를 통해서 보시면 되겠습니다!

1. spring.config.import를 이용하여 환경변수 설정

저희가 첫 번째로 살펴볼 spring.config.import로 환경변수 설정하는 방법은 직관적입니다. 먼저, 애플리케이션을 실행할 모듈의 application.yml에 spring.config.import를 추가합니다. 그리고 그 아래 추가하고 싶은 모듈의 yml을 명시해 주면 됩니다.

앞서 말씀드린 예시 프로젝트 환경에서는 internal-api 모듈에서 client 모듈을 가져다 사용하고 있습니다. 그래서 client 모듈의 yml 파일을 internal-api 모듈 내 application.yml에 spring.config.import의 값으로 작성 후, 애플리케이션을 실행해야 합니다.

추가하는 방법은 아래 예시로 확인해 보시면 되겠습니다.

• internal-api 모듈 > resources/application.yml

spring:
  config:
    import:
      - 'classpath:spring-config-import.yml'

• client 모듈 > resources/spring-config-import.yml

spring-config-import:
  properties:
    host: https://partner.kakaopay.com
    transfer-money-path: /v1/transfer/money/by-spring-config-import

• client 모듈 > EnvFromSpringConfigImport.kt

@Configuration
@ConfigurationProperties(prefix = "spring-config-import")
class EnvFromSpringConfigImport {
   lateinit var properties: Map<String, String>
}

• client 모듈 > TransferClient.kt

@Component
class TransferClient(
   private val envFromSpringConfigImport: EnvFromSpringConfigImport
) {
   @PostConstruct
   fun postConstruct() {
      println("TransferClient initialized")
      println("envFromSpringConfigImport: ${envFromSpringConfigImport.properties}")
   }
}

위와 같이 각 모듈에 파일을 작성하고 InternalApiApplication을 실행해 봅니다. TransferClient가 bean으로 생성되고, 의존성 주입이 완료됐을 때 @PostConstruct가 붙어있는 메서드가 실행됩니다.

TransferClient initialized
envFromSpringConfigImport: {host=https://partner.kakaopay.com, transfer-money-path=/v1/transfer/money/by-spring-config-import}

결과는 위와 같고, 저희의 의도와 맞게 환경변수가 잘 주입된 것을 확인하실 수 있습니다. 다만 internal-api 모듈의 application.yml에 spring.config.import로 명시해야 하는 client 모듈의 yml 파일들을 명시해야 하는 과정이 조금 번거롭게 느껴질 수도 있을 것 같습니다.

예를 들어, 메시지 전송 클라이언트가 추가되고 메시지 전송 클라이언트의 yml 파일을 만든다고 가정하겠습니다. 메시지 전송 클라이언트를 사용하는 애플리케이션의 application.yml에 spring.config.import 의 값으로 메시지 전송 클라이언트의 yml 파일을 명시해야 합니다.

예시와 같이 요구사항 추가로 인해 클라이언트 개수가 늘어남에 따라 yml 파일도 늘어나고, 여러 클라이언트 구현체를 애플리케이션에서 사용하게 된다면, 애플리케이션의 application.yml 파일에 의도치 않게 누락하는 yml 파일이 생길 수 있습니다. 만약 애플리케이션에 import 해야 하는 yml 파일들을 명시하는 부분을 놓치면, 환경변수가 알맞게 설정되지 않아서 운영 서비스에서 예상치 못한 오류가 발생할 수도 있습니다.

2. spring.profiles.include를 이용하여 환경변수 설정

Spring 애플리케이션을 실행할 때, 활성화(spring.profiles.active) 또는 포함(spring.profiles.include)되는 프로필에 따라 yml 파일을 불러온다는 사실을 아셨나요? [naming convention 참고]

예를 들어, 어떤 모듈의 환경변수 파일을 application-sandbox.yml이라고 지으면, 해당 모듈을 참조하고 있는 애플리케이션의 프로필에 sandbox가 활성화 또는 포함될 때 해당 파일의 환경변수 값을 불러옵니다.

다시 말해, 실행하려는 애플리케이션의 application.yml에 spring.profiles.include 값으로 특정 프로필을 명시한다면, 그 프로필이 포함됩니다. 따라서 포함된 프로필에 해당하는 yml 파일을 불러오게 됩니다.

말씀드린 과정은 아래 예시를 보시면 쉽게 이해하실 것 같습니다.

• internal-api 모듈 > resources/application.yml

spring:
  profiles:
    include: spring-profiles-include

• client 모듈 > application-spring-profiles-include.yml

spring-profiles-include:
  properties:
    host: https://partner.kakaopay.com
    transfer-money-path: /v1/transfer/money/by-spring-profiles-include

• client 모듈 > EnvFromSpringProfilesInclude.kt

@Configuration
@ConfigurationProperties(prefix = "spring-profiles-include")
class EnvFromSpringProfilesInclude {
   lateinit var properties: Map<String, String>
}

• client 모듈 > TransferClient.kt

@Component
class TransferClient(
   private val envFromSpringProfilesInclude: EnvFromSpringProfilesInclude
) {
   @PostConstruct
   fun postConstruct() {
      println("TransferClient initialized")
      println("envFromSpringProfilesInclude: ${envFromSpringProfilesInclude.properties}")
   }
}

아까처럼 각 모듈에 파일을 작성하고, InternalApiApplication을 실행해 봅니다. TransferClient가 bean으로 생성되고, 의존성 주입이 완료됐을 때 @PostConstruct가 붙어있는 메서드가 실행됩니다.

TransferClient initialized
envFromSpringProfilesInclude: {host=https://partner.kakaopay.com, transfer-money-path=/v1/transfer/money/by-spring-profiles-include}

결과는 위와 같고, 이번에도 저희의 의도와 맞게 환경변수들이 잘 주입된 것을 확인하실 수 있습니다. 어떤 과정으로 이런 결과가 나왔는지 다시 한번 살펴보겠습니다.

1. internal-api 모듈에서 기본으로 읽어오는 application.yml을 통해 spring-profiles-include라는 프로필이 포함됩니다.
2. internal-api 모듈은 client 모듈을 참조하고 있습니다.
3. spring-profiles-include라는 프로필이 포함되었으니, naming convention에 부합하는 client 모듈의 appliction-spring-profiles-include.yml 파일을 환경변수 설정을 위해 읽어오게 됩니다.

이러한 과정을 통해 환경변수를 설정할 수 있지만, 이 방법 역시 internal-api 모듈의 application.yml에 spring.profiles.include로 명시해야 하는 프로필 때문에 spring.config.import를 이용하여 환경변수 설정 과정에서 소개한 것과 같은 단점이 있어 보입니다. 또, client 모듈의 yml 파일의 이름을 naming convention에 따라 application-${프로필 이름}.yml(예시에서는 application-spring-profiles-include.yml)로 지어야 한다는 사실을 미리 숙지하고 있어야만, 환경변수가 의도대로 적용되기 때문에 아쉽습니다.

3. @PropertySource를 이용하여 환경변수 설정

이번 챕터에서는 @PropertySource로 환경변수 설정하는 방법을 알아보겠습니다. @PropertySource 어노테이션은 value에 명시한 properties 파일의 내용이 환경변수로 등록되도록 도와주는 어노테이션입니다.

예를 들어, me.team=partnerplatform 작성한 properties 파일을 만들고, 이 파일을 @PropertySource의 value에 명시해 주면, 해당 애플리케이션의 me.team에 대한 환경변수 값은 partnerplatform이 됩니다.

말씀드린 과정은 아래 예시를 보시면 쉽게 이해하실 것 같습니다.

• client 모듈 > resources/transfer-client/property-source-default.properties

property-source.properties.host=https://default-partner.kakaopay.com
property-source.properties.transfer-money-path=/v1/transfer/money/by-property-source

• client 모듈 > EnvFromPropertySource.kt

@Configuration
@ConfigurationProperties(prefix = "property-source")
class EnvFromPropertySource {
   lateinit var properties: Map<String, String>
}

• client 모듈 > ProfileConfig.kt

class ProfileConfig {
   @Configuration
   @PropertySource("classpath:/transfer-client/property-source-default.properties") // 불러오고 싶은 properties 파일의 path
   class DefaultConfig
}

• client 모듈 > TransferClient.kt

@Component
class TransferClient(
   private val envFromPropertySource: EnvFromPropertySource
) {
   @PostConstruct
   fun postConstruct() {
      println("TransferClient initialized")
      println("envFromPropertySource: ${envFromPropertySource.properties}")
   }
}

아까처럼 각 모듈에 파일을 작성하고, InternalApiApplication을 실행해 봅니다. TransferClient가 bean으로 생성되고, 의존성 주입이 완료됐을 때 @PostConstruct가 붙어있는 메서드가 실행됩니다.

TransferClient initialized
envFromPropertySource: {host=https://default-partner.kakaopay.com, transfer-money-path=/v1/transfer/money/by-property-source}

위와 같이 클라이언트 모듈의 resources/transfer-client 폴더에 위치하고 있는 property-source-default.properties 파일의 환경변수 값을 알맞게 잘 불러왔습니다.

4. @Profile과 @PropertySource를 이용하여 환경변수 설정

이번 챕터에서는 저희가 실제 운영하고 있는 환경에서의 상황을 하나 더 추가하겠습니다. 카카오페이에서는 안정적인 서비스 운영을 위해 테스트하는 환경이 여러 개 있습니다. 팀마다 테스트하는 환경이 조금씩 다르지만, 보통 개발자 환경(dev), 샌드박스 환경(sandbox), 베타 환경(beta), 운영 환경(production)이 있습니다.

카카오페이에서는 각 환경마다 호출해야 하는 API의 host가 다르기 때문에, 각 환경마다 환경변수 설정을 해줘야 합니다. 이를 위해 저희 팀의 경우, 샌드박스 환경에서 Spring 애플리케이션을 실행시킬 때, -Dspring.profiles.active=sandbox와 같이 프로필 활성화 옵션을 주고 실행시킵니다. 이 옵션은 애플리케이션 실행 시, 활성화 할 프로필이 sandbox라는 말이고, 샌드박스 환경을 위한 환경변수를 설정하기 위한 옵션입니다.

이러한 배경에 따라 이번 챕터에서는 활성화되는 프로필마다 환경변수가 다르게 설정되어야 한다는 요구사항을 추가하겠습니다. 다시 말해, 추가된 요구사항은 샌드박스 환경(sandbox), 운영 환경(production) 마다 머니 송금 API의 host가 달라야 하는 것입니다.

이 요구사항을 구현한 코드는 아래 예시를 한번 확인해 보시면 되겠습니다!

• client 모듈 > resources/transfer-client/property-source-default.properties

property-source.properties.host=https://default-partner.kakaopay.com
property-source.properties.transfer-money-path=/v1/transfer/money/by-property-source

• client 모듈 > resources/transfer-client/property-source-sandbox.properties

property-source.properties.host=https://sandbox-partner.kakaopay.com
property-source.properties.transfer-money-path=/v1/transfer/money/by-property-source

• client 모듈 > resources/transfer-client/property-source-production.properties

property-source.properties.host=https://production-partner.kakaopay.com
property-source.properties.transfer-money-path=/v1/transfer/money/by-property-source

• client 모듈 > EnvFromPropertySource.kt

@Configuration
@ConfigurationProperties(prefix = "property-source")
class EnvFromPropertySource {
   lateinit var properties: Map<String, String>
}

• client 모듈 > ProfileConfig.kt

class ProfileConfig {
   @Configuration
   @Profile("sandbox")
   @PropertySource("classpath:/transfer-client/property-source-sandbox.properties")
   class SandboxConfig

   @Configuration
   @Profile("production")
   @PropertySource("classpath:/transfer-client/property-source-production.properties")
   class ProductionConfig

   @Configuration
   @Profile("!sandbox && !production")
   @PropertySource("classpath:/transfer-client/property-source-default.properties")
   class DefaultConfig
}

• client 모듈 > TransferClient.kt

@Component
class TransferClient(
   private val envFromPropertySource: EnvFromPropertySource
) {
   @PostConstruct
   fun postConstruct() {
      println("TransferClient initialized")
      println("envFromPropertySource: ${envFromPropertySource.properties}")
   }
}

아까처럼 각 모듈에 파일을 작성하고, InternalApiApplication을 실행해 봅니다. TransferClient가 bean으로 생성되고, 의존성 주입이 완료됐을 때 @PostConstruct가 붙어있는 메서드가 실행됩니다.

# 어떠한 프로필도 설정하지 않고 실행 시
TransferClient initialized
envFromPropertySource: {host=https://default-partner.kakaopay.com, transfer-money-path=/v1/transfer/money/by-property-source}

# 샌드박스(sandbox) 프로필로 실행 시 (-Dspring.profiles.active=sandbox)
TransferClient initialized
envFromPropertySource: {host=https://sandbox-partner.kakaopay.com, transfer-money-path=/v1/transfer/money/by-property-source}

# 운영(production) 프로필로 실행 시 (-Dspring.profiles.active=production)
TransferClient initialized
envFromPropertySource: {host=https://production-partner.kakaopay.com, transfer-money-path=/v1/transfer/money/by-property-source}

결과를 보시면 프로필에 따라 애플리케이션 실행 시 불러오는 환경변수 값이 달라진 것을 확인하실 수 있습니다. 이것이 어떻게 가능할까요?

@Profile 어노테이션은 특정 프로필이 활성화 또는 포함되었을 때 빈(bean) 등록을 조건부로 허용하는 어노테이션입니다. 프로필마다 등록되는 빈이 달라지는 것에 따라 @PropertySource를 통해 불러오는 환경변수 파일이 달라지게 되어, 프로필에 따라 애플리케이션 실행 시 불러오는 환경변수 값이 달라집니다.

예를 들어, sandbox 프로필을 활성화하면 SandboxConfig가 빈으로 등록되고, production 프로필을 활성화하면 ProductionConfig가 빈으로 등록됩니다. 만약 어떠한 프로필도 활성화하지 않으면, 표현식(“!sandbox && !production”)에 따라 DefaultConfig가 빈으로 등록됩니다.

이와 같이, 프로필마다 등록되는 빈이 달라지는 것을 명시적으로 선언하게 된다면, 각 프로필마다 환경변수 파일도 이름 규칙이나 파일 위치 제한 없이 생성할 수 있게 됩니다. 해당 구성의 장점은 유지보수 할 때, 어떤 위치의 어떤 파일을 수정해야 할지 명확해집니다.

예를 들어, sandbox 프로필에서 client 모듈의 환경변수인 path 값을 바꾼다고 가정하겠습니다. 이 경우, 예시 기준으로 ProfileConfig를 찾아서 sandbox 프로필에는 어떤 properties 파일이 @PropertySource의 value로 명시되어 있는지 확인합니다. 그 후, 해당 파일로 이동하여 path 값을 바꾸기만 하면 됩니다 😎

혹시 환경마다 생성되는 ProfileConfig 내 클래스가 번거로우시다면, 아래와 같이 구성하시면 됩니다.

@Configuration
@PropertySource("classpath:/transfer-client/property-source-\${spring.profiles.active}.properties")
class ProfileConfig

하지만 위 방법은 프로필을 여러 개 활성화하는 경우, spring.profiles.active에 의도치 않은 값이 들어가기 때문에 애플리케이션이 정상 동작하지 않을 수 있습니다. 그래서 저희 팀의 경우, 이런 문제를 방지하고자 어떤 프로필에서 어떤 properties 파일을 불러와야 하는지 명시적으로 알기 위해 예시로 들었던 SandboxConfig, ProductionConfig와 같은 클래스를 프로필마다 만들어 프로젝트를 구성하였습니다.

마치며

이번 글에서는 Spring 멀티모듈 프로젝트에서 환경변수를 설정하는 방법에 대해 알아보았습니다. 지금까지 소개한 방법들은 어떤 특징이 있는지 한번 정리해 볼까요?

소개드린 것 외에도 환경변수를 설정하는 다른 방법(모든 모듈의 yml 파일을 스캔하는 yaml-importer 등)도 있지만, 이번 글에서는 저희 팀의 환경변수 설정 방법을 소개드리고자 그 외 방법의 설명은 제외했습니다.

앞으로 각자 속하고 계신 회사 또는 단체가 성장하면서 복잡한 문제를 해결하기 위해 담당하고 계신 도메인에서 여러 가지 애플리케이션을 개발하게 되고, 그로 인해 복잡도가 높아지는 상황을 겪으실 것입니다. 복잡도가 높아짐에 따라 멀티모듈 프로젝트 구성을 고민하시고, 그에 따라 환경변수 설정을 어떻게 할지 고민도 하실 것 같습니다.

이번 글이 그러한 고민에 도움이 되어 각자의 프로젝트에 적합한 환경변수 설정 방식을 선택하셨으면 좋겠습니다. 앞으로 저는 프로젝트의 복잡성을 줄이기 위한 고민과 시도를 거듭하며, 이번처럼 독자분들께서 고민해보실 법한 주제에 대한 경험을 풀어내는 것으로 또 찾아뵙겠습니다. 감사합니다.

참고 자료

• https://docs.spring.io/spring-boot/reference/features/external-config.html
• https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/context/annotation/PropertySource.html