전자정부표준프레임워크 v5.0 배치 예제 타 IDE 실행 시 빈 주입 오류 해결

Eclipse 기반의 eGovFrame IDE 외의 환경(VS Code, IntelliJ 등)에서 전자정부표준프레임워크 v5.0 배치(Batch) 예제 프로젝트를 실행할 때 발생하는 빈 주입 오류(UnsatisfiedDependencyException)의 원인과 해결 방법을 정리한 가이드입니다.

예제 프로젝트 (Github)

https://github.com/lantoolblog/egov-v5-batch-tutorial/tree/master/lab601-batch

🚨 문제 발생

다른 IDE나 일반 Maven 빌드로 예제 프로젝트를 구동할 때 다음과 같은 오류가 발생하며 애플리케이션 시작에 실패합니다.

org.springframework.beans.factory.UnsatisfiedDependencyException: 
  Error creating bean with name 'delimitedToDelimitedJob' 
  defined in egovframework.example.bat.job.DelimitedToDelimitedJobConfig: 
    Unsatisfied dependency expressed through method 'delimitedToDelimitedJob' 
    parameter 0: No qualifying bean of type 'org.springframework.batch.core.Step' 
    available: expected single matching bean but found 4: 
      delimitedToDelimitedStep,
      fixedLengthToFixedLengthStep,
      fixedLengthToJdbcStep,
      fixedLengthToMybatisStep
    ...

문제가 발생한 코드를 살펴보면 다음과 같습니다.

@Bean  
public Job delimitedToDelimitedJob(Step delimitedToDelimitedStep) {
    return new JobBuilder("delimitedToDelimitedJob", jobRepository)
        .start(delimitedToDelimitedStep)
        .build();
}

@Bean
public Step delimitedToDelimitedStep( ... ) {
    ...
}

스프링 프레임워크는 타입(Step)이 일치하는 빈이 4개나 존재하므로 어떤 빈을 주입해야 할지 알 수 없다고 에러를 내뿜습니다. 빈 메서드 이름과 파라미터 이름을 일치시켰지만 매칭이 되지 않은 현상입니다.

그렇다면 “왜 전자정부표준프레임워크 IDE(Eclipse)에서는 잘 되었을까?” 하는 의문이 생깁니다.

🔍 원인 파악

Java(JDK 8 이상) 컴파일러는 기본적으로 메서드의 파라미터 이름 정보를 컴파일된 클래스 파일(.class)에 저장하지 않습니다. 파라미터 이름이 지워지면 스프링은 파라미터 변수명(delimitedToDelimitedStep)을 통해 빈을 찾을 수 없게 되어 타입이 중복된 빈 중 무엇을 선택할지 결정하지 못합니다.

eGovFrame IDE(Eclipse) 환경: 내부적으로 사용하는 Eclipse JDT 컴파일러나 IDE 설정에서 파라미터 이름 정보를 유지하도록 처리되어 있어서 문제가 발생하지 않았습니다.
VS Code, IntelliJ 및 기본 Maven 빌드: 기본값으로 파라미터 이름을 지우고 컴파일하기 때문에 스프링이 파라미터 이름 기반으로 매칭하지 못하고 오류가 발생합니다. VS Code의 Java 확장 설정에서 파라미터 정보를 저장하도록 체크하더라도, 해당 설정이 Maven 빌드(pom.xml) 설정과 완벽하게 연동되지 않고 별개로 동작하기(따로 놀기) 때문에 결국 런타임에 오류가 발생하게 됩니다.

💡 해결 방법

이 문제를 해결하는 가장 쉬운 방법은 Maven 컴파일러 플러그인에 <parameters>true</parameters> 옵션을 명시적으로 추가하여 파라미터 이름이 클래스 파일에 유지되도록 하는 것입니다.

pom.xml 파일을 열고 다음과 같이 maven-compiler-plugin 설정을 수정(또는 추가)합니다.

<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-compiler-plugin</artifactId>
    <version>3.11.0</version> <!-- 버전은 프로젝트에 맞게 지정 -->
    <configuration>
        <!-- Java 8 이상부터 지원하는 파라미터 이름 보존 옵션 -->
        <parameters>true</parameters>
    </configuration>
</plugin>

이렇게 설정하면 컴파일 후에도 delimitedToDelimitedStep 이라는 파라미터 이름이 보존되며, 스프링이 이를 인식해 동일한 이름의 빈을 정상적으로 주입하게 됩니다.

참고: 각 파라미터에 명시적으로 @Qualifier("delimitedToDelimitedStep") 어노테이션을 추가하여 해결할 수도 있습니다. 하지만 Spring Batch를 다루는 프로젝트 특성상 Job이 Step을 주입받을 때뿐만 아니라, Step 내부에서도 다양한 Reader와 Writer 빈을 주입받는 경우가 매우 많습니다. 이 모든 의존성 주입부마다 일일이 @Qualifier를 붙이는 것보다 컴파일러 옵션(<parameters>true</parameters>)을 한 번 추가하여 전역적으로 해결하는 것이 훨씬 효율적입니다.

✅ 실행 성공

빌드를 다시 진행하고 실행(Run)하면, 빈 주입 오류가 사라지고 Batch Job이 정상적으로 구동되는 것을 확인할 수 있습니다.

📌 별첨: Gradle 프로젝트인 경우

만약 Maven 대신 Gradle을 기반으로 프로젝트를 구성하신 경우, build.gradle 파일에 다음과 같이 자바 컴파일러 옵션을 추가하여 동일하게 문제를 해결할 수 있습니다.

tasks.withType(JavaCompile) {
    options.compilerArgs << '-parameters'
}

// 또는 아래와 같이 작성할 수도 있습니다.

compileJava {
    options.compilerArgs << '-parameters'
}

lantool...