[JAVA] Spring Boot와 MongoDB 연동하기 – 실무 중심 입문 가이드

관계형 데이터베이스(RDBMS)만 써오던 프로젝트에서 NoSQL인 MongoDB를 도입해야 할 때, 가장 많이 사용하는 조합 중 하나가 Spring Boot + MongoDB입니다.
MongoDB의 설치부터 Spring Boot 연동, 간단한 CRUD까지 정리해 보겠습니다. 

---

1. MongoDB 설치 또는 Docker 실행

로컬 설치를 권장하지 않는다면 Docker로 실행하는 것이 가장 간편합니다.

docker run --name mongo \
  -p 27017:27017 \
  -d mongo:6.0

MongoDB Compass 또는 Robo 3T 같은 GUI 도구를 함께 설치하면 확인이 편리합니다.

 

2. 프로젝트에 의존성 추가 (Maven)

spring-boot-starter-data-mongodb만으로 대부분 기능이 지원됩니다.

<dependency>
  <groupId>org.springframework.boot</groupId>
  <artifactId>spring-boot-starter-data-mongodb</artifactId>
</dependency>

 

3. application.yml 또는 properties 설정

MongoDB 연결 정보를 application.yml에 설정합니다.

spring:
  data:
    mongodb:
      uri: mongodb://localhost:27017/springboot_mongo

기본 포트는 27017이며, DB 이름은 springboot_mongo로 설정했습니다.

 

4. 도메인 모델 (@Document)

MongoDB는 테이블이 아닌 컬렉션을 사용하므로 @Entity 대신 @Document를 사용합니다.

@Document(collection = "users")
public class User {
  @Id
  private String id;

  private String name;
  private String email;

  // 기본 생성자, getter, setter 생략
}

 

5. Repository 생성

MongoRepository를 상속받기만 하면 기본 CRUD 메서드는 자동 제공됩니다.

public interface UserRepository extends MongoRepository<User, String> {
    Optional<User> findByEmail(String email);
}

 

6. 테스트용 Controller 작성

간단한 REST API를 작성해 실제 동작을 테스트합니다.

@RestController
@RequestMapping("/users")
public class UserController {

  private final UserRepository userRepository;

  public UserController(UserRepository userRepository) {
    this.userRepository = userRepository;
  }

  @PostMapping
  public User createUser(@RequestBody User user) {
    return userRepository.save(user);
  }

  @GetMapping("/{id}")
  public ResponseEntity<User> getUser(@PathVariable String id) {
    return userRepository.findById(id)
        .map(ResponseEntity::ok)
        .orElse(ResponseEntity.notFound().build());
  }
}

 

7. MongoDB와 RDB의 차이

• MongoDB는 스키마가 없습니다. 유연한 구조의 데이터 저장이 가능합니다.
• Join이 어렵지만, 빠른 조회와 수평 확장이 용이합니다.
• 트랜잭션은 RDB보다 제한적이며, 설계 시 그에 맞는 구조를 고려해야 합니다.

 

8. 실무에서의 팁

• ObjectId → String으로 매핑하는 것이 간단하게 처리하기 좋습니다.
• 컬렉션 이름은 명시적으로 지정해 주는 것이 MongoDB 관리에 유리합니다.
• MongoTemplate를 이용하면 더 복잡한 쿼리도 작성할 수 있습니다.

 

마무리

Spring Boot와 MongoDB는 빠른 프로토타이핑이나 문서 기반 저장소로서 매우 잘 어울리는 조합입니다.
기본 연동만 익혔다면, 다음 단계로 Aggregation 파이프라인이나 MongoTemplate 기반의 복잡한 쿼리도 익혀보세요