Spring Boot + Spring Batch 프로젝트 생성부터 실행까지 완벽 가이드

안녕하세요.

새로운 기술을 배울 때 가장 큰 진입 장벽은 “환경 설정”입니다. 코드를 짜기도 전에 빨간 에러 메시지를 보면 의욕이 꺾이기 마련이죠.
특히 Spring Boot 3.x와 Spring Batch 5.x로 넘어오면서 설정 방식에 꽤 많은 변화가 있었습니다.

오늘은 빈 프로젝트에서 시작해서, “Hello World” 배치를 실행하기까지의 과정을 가장 최신 트렌드(Spring Boot 3.2+ / Java 17+)에 맞춰 단계별로 정리해 드리겠습니다.

1. 프로젝트 생성 (Spring Initializr)

가장 먼저 Spring Initializr(start.spring.io)를 통해 뼈대를 만듭니다.

• Project: Gradle – Groovy
• Language: Java
• Spring Boot: 3.2.x (LTS)
• Packaging: Jar
• Java: 17 이상 (Spring Batch 5 필수 요구사항)

필수 의존성 (Dependencies)

• Spring Batch: 핵심 라이브러리
• Spring Data JPA: DB 접근용 (선택이지만, 실무 필수)
• H2 Database: 로컬 테스트 및 메타 데이터 저장용
• Lombok: 보일러플레이트 코드 제거

2. build.gradle 설정

프로젝트를 열고 build.gradle을 확인합니다. 혹시 빠진 것이 있다면 아래와 같이 추가해 주세요.

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.2.1'
    id 'io.spring.dependency-management' version '1.1.4'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'

java {
    sourceCompatibility = '17'
}

configurations {
    compileOnly {
        extendsFrom annotationProcessor
    }
}

repositories {
    mavenCentral()
}

dependencies {
    // 1. Spring Batch
    implementation 'org.springframework.boot:spring-boot-starter-batch'

    // 2. Database (메타 데이터 저장용)
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    runtimeOnly 'com.h2database:h2'

    // 3. Lombok
    compileOnly 'org.projectlombok:lombok'
    annotationProcessor 'org.projectlombok:lombok'

    // 4. Test
    testImplementation 'org.springframework.boot:spring-boot-starter-test'
    testImplementation 'org.springframework.batch:spring-batch-test'
}

3. application.yml 설정

src/main/resources/application.properties 파일 이름을 application.yml로 변경하고(가독성이 더 좋습니다), 기본 설정을 추가합니다.

spring:
  datasource:
    url: jdbc:h2:mem:testdb;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE
    driver-class-name: org.h2.Driver
    username: sa
    password:

  batch:
    jdbc:
      initialize-schema: always # 앱 실행 시 배치 메타 테이블 자동 생성
    job:
      enabled: true # 앱 실행 시 등록된 Job 자동 시작

  jpa:
    hibernate:
      ddl-auto: update # 엔티티 테이블 자동 생성
    show-sql: true # 실행되는 쿼리 로그 출력

Expert Tip: spring.batch.jdbc.initialize-schema 옵션은 always (항상 생성), embedded (내장 DB일 때만 생성), never (생성 안 함) 중 선택할 수 있습니다. 로컬 개발 시에는 always가 편합니다.

4. 메인 애플리케이션 및 Job 설정

4.1 메인 클래스

별다른 설정 없이 @SpringBootApplication만 있으면 됩니다. 과거에 쓰던 @EnableBatchProcessing은 Spring Boot 3의 자동 구성을 방해할 수 있으므로 제거하는 것이 권장됩니다.

@SpringBootApplication
public class BatchApplication {
    public static void main(String[] args) {
        SpringApplication.run(BatchApplication.class, args);
    }
}

4.2 첫 번째 Job 작성 (HelloJobConfig)

com.example.batch.job 패키지를 만들고 설정 클래스를 작성합니다.

@Slf4j
@Configuration
@RequiredArgsConstructor
public class HelloJobConfig {

    private final JobRepository jobRepository;
    private final PlatformTransactionManager transactionManager;

    // 1. Job 생성
    @Bean
    public Job helloJob() {
        return new JobBuilder("helloJob", jobRepository)
                .start(helloStep())
                .build();
    }

    // 2. Step 생성
    @Bean
    public Step helloStep() {
        return new StepBuilder("helloStep", jobRepository)
                .tasklet((contribution, chunkContext) -> {
                    log.info("=========================");
                    log.info(" >> Hello Spring Batch! ");
                    log.info("=========================");
                    return RepeatStatus.FINISHED;
                }, transactionManager)
                .build();
    }
}

5. 실행 및 검증

IDE에서 BatchApplication의 main 메서드를 실행합니다.

콘솔 출력 확인:

INFO ... HelloJobConfig : =========================
INFO ... HelloJobConfig :  >> Hello Spring Batch! 
INFO ... HelloJobConfig : =========================
INFO ... SimpleJobLauncher : Job: [SimpleJob: [name=helloJob]] completed with the following parameters: [{}] and the following status: [COMPLETED]

위 로그가 보인다면 성공입니다! H2 데이터베이스에 배치 실행 이력이 저장되었고, 여러분의 첫 배치가 정상적으로 수행되었습니다.

6. 마치며

이제 프로젝트의 뼈대가 완성되었습니다. 여기에 비즈니스 로직을 담은 Step을 하나씩 추가해 나가면 그것이 바로 엔터프라이즈 배치 애플리케이션이 됩니다.
다음 포스트에서는 이 프로젝트를 기반으로 H2 DB를 활용한 효율적인 테스트 환경 구축 방법을 알아보겠습니다.