jabrena/plinth / skills/315-frameworks-spring-mongodb
315-frameworks-spring-mongodb
VerifiedUse when you need to design or implement MongoDB data access in Spring Boot — including document modeling, Spring Data Mongo repositories/templates, indexing, optimistic concurrency, and error handling. This should trigger for requests such as Add MongoDB in Spring Boot; Review Spring Data Mongo design; Improve error handling for Mongo writes; Model MongoDB documents for a Spring Boot service; Configure Spring Data MongoDB indexes or transactions. Part of Plinth Toolkit
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.1 KB |
| references/315-frameworks-spring-mongodb.md | markdown | 20.4 KB |
references/315-frameworks-spring-mongodb.md
View on GitHub---
name: 315-frameworks-spring-mongodb
description: Use when you need MongoDB with Spring Data MongoDB — including Maven dependencies, document modeling with @Document and @CompoundIndex, MongoRepository, MongoTemplate for complex queries, @Version optimistic locking, and explicit error handling for DuplicateKeyException and OptimisticLockingFailureException. This should trigger for requests such as Add MongoDB in Spring Boot; Review Spring Data Mongo repositories; Improve error handling for Mongo writes.
license: Apache-2.0
metadata:
author: Juan Antonio Breña Moral
version: 0.19.0
---
# Spring Boot — MongoDB
## Role
You are a Senior software engineer with extensive experience in Spring Boot and MongoDB
## Goal
Design clear document models, implement correct Spring Data MongoDB repositories and services, and handle MongoDB failures explicitly. Prefer immutable records for documents, explicit index declarations, and `@Version` for concurrency control. Never expose managed documents at API boundaries — map to DTOs. Guard against injection by using derived finders or `Criteria` — never string-concatenated query strings.
**What is covered in this Skill?**
- Maven `spring-boot-starter-data-mongodb` dependency aligned with the Spring Boot BOM
- Document design: `@Document`, `@Field`, `@CompoundIndex`, and `@Id` mapping
- Factory methods for new documents; `@Version` for optimistic locking
- `MongoRepository` with derived finders and explicit `@Query` methods
- `MongoTemplate` for complex aggregations and multi-condition queries
- Service-layer write/read boundaries; use `@Transactional` only when MongoDB multi-document atomicity is required and supported
- Error handling: `DuplicateKeyException`, `OptimisticLockingFailureException`, `DataAccessException`
- DTO projections: returning view types instead of leaking internal documents
- Testing with `@DataMongoTest`, `@SpringBootTest`, and Testcontainers MongoDB
**Scope:** Apply recommendations based on the reference rules and good/bad code examples.
## Constraints
Before applying any MongoDB changes, ensure the project compiles. Compilation failure is a BLOCKING condition.
- **MANDATORY**: Run `./mvnw compile` or `mvn compile` before applying any change
- **SAFETY**: If compilation fails, stop immediately
- **VERIFY**: Run `./mvnw clean verify` or `mvn clean verify` after applying improvements
- **INJECTION**: Never build query strings by concatenating user input — always use Criteria API or derived finders
- **BEFORE APPLYING**: Read the reference for detailed rules and good/bad patterns
- **EDGE CASE**: If the user goal is ambiguous, stop and ask a clarifying question before editing files
- **EDGE CASE**: If required context, files, or tools are missing, report the blocker explicitly
## Examples
### Table of contents
- Example 1: Maven dependency
- Example 2: Document design
- Example 3: Repository pattern
- Example 4: Service layer
- Example 5: MongoTemplate for complex queries
- Example 6: Error handling
- Example 7: Testing
- Example 8: Full context tests
### Example 1: Maven dependency
Title: Add the Spring Data MongoDB starter; version is managed by the Spring Boot BOM
Description: Spring Boot's BOM manages the `spring-boot-starter-data-mongodb` version. Declaring an explicit version risks classpath conflicts with the auto-configured `MongoAutoConfiguration`. Add the embedded Flapdoodle MongoDB only in `test` scope for slice tests when not using Testcontainers.
**Good example:**
```xml
<!-- pom.xml — Spring Boot BOM manages the version -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-mongodb</artifactId>
</dependency>
<!-- Spring Boot 4 / Testcontainers 2 artifact names; versions are managed by the Spring Boot BOM -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-testcontainers</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.testcontainers</groupId>
<artifactId>testcontainers-mongodb</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.testcontainers</groupId>
<artifactId>testcontainers-junit-jupiter</artifactId>
<scope>test</scope>
</dependency>
<!-- Optional alternative: embedded MongoDB for @DataMongoTest slices without Testcontainers -->
<dependency>
<groupId>de.flapdoodle.embed</groupId>
<artifactId>de.flapdoodle.embed.mongo.spring30x</artifactId>
<scope>test</scope>
</dependency>
```
**Bad example:**
```xml
<!-- Bad: pinned version fights the BOM -->
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-data-mongodb</artifactId>
<version>3.2.0</version>
</dependency>
<!-- Bad for Spring Boot 4 / Testcontainers 2: old artifact names are not managed here -->
<dependency>
<groupId>org.testcontainers</groupId>
<artifactId>mongodb</artifactId>
<scope>test</scope>
</dependency>
<dependency>
<groupId>org.testcontainers</groupId>
<artifactId>junit-jupiter</artifactId>
<scope>test</scope>
</dependency>
```
### Example 2: Document design
Title: @Document with explicit collection, @Field, @CompoundIndex, and factory method
Description: Annotate with `@Document` and name the collection explicitly to avoid case-sensitivity surprises across environments. Map field names with `@Field` when the Java property name differs from the stored field. Declare indexes on the entity with `@CompoundIndex` to keep schema intent alongside the model. Use a static factory method (`of(...)`) that leaves `id` null for new inserts.
**Good example:**
```java
import org.springframework.data.annotation.Id;
import org.springframework.data.annotation.Version;
import org.springframework.data.mongodb.core.index.CompoundIndex;
import org.springframework.data.mongodb.core.mapping.Document;
import org.springframework.data.mongodb.core.mapping.Field;
import java.time.Instant;
@Document(collection = "orders")
@CompoundIndex(name = "uk_order_number", def = "{'order_number': 1}", unique = true)
public record OrderDocument(
@Id String id,
@Field("order_number") String orderNumber,
@Field("customer_id") String customerId,
@Field("created_at") Instant createdAt,
@Version Long version
) {
public static OrderDocument of(String orderNumber, String customerId) {
return new OrderDocument(null, orderNumber, customerId, Instant.now(), null);
}
}
```
**Bad example:**
```java
// Bad: implicit collection name derived from class name; no indexes; mutable class
@Document
class OrderDocument {
@Id String id;
String orderNumber; // no unique index
String customerId;
// setters allow accidental mutation
public void setId(String id) { this.id = id; }
}
```
### Example 3: Repository pattern
Title: MongoRepository with derived finders; avoid string-concatenated queries
Description: Extend `MongoRepository` (or `ListCrudRepository` for `List<T>` return types). Use Spring Data's query derivation for simple lookups and `@Query` with named parameters for complex ones. Never build MongoDB JSON query strings from user input — use the Criteria API or `@Query` with `:?0` / `:#{[0]}` placeholders.
**Good example:**
```java
import org.springframework.data.mongodb.repository.MongoRepository;
import org.springframework.data.mongodb.repository.Query;
import org.springframework.stereotype.Repository;
import java.time.Instant;
import java.util.List;
import java.util.Optional;
@Repository
public interface OrderRepository extends MongoRepository<OrderDocument, String> {
Optional<OrderDocument> findByOrderNumber(String orderNumber);
List<OrderDocument> findByCustomerId(String customerId);
// Named @Query — binds the parameter safely
@Query("{ 'created_at': { $gte: ?0 } }")
List<OrderDocument> findCreatedAfter(Instant since);
}
```
**Bad example:**
```java
// Bad: raw string concatenation into a Mongo query — NoSQL injection risk
class OrderRepositoryBad {
@Autowired MongoTemplate mongoTemplate;
List<OrderDocument> findByCustomer(String customerId) {
String json = "{ 'customer_id': '" + customerId + "' }"; // injection-prone
return mongoTemplate.find(new BasicQuery(json), OrderDocument.class);
}
}
```
### Example 4: Service layer
Title: Constructor injection; transactions only when atomicity requires them
Description: Keep the repository out of REST controllers — route everything through a service. For simple single-document writes, an explicit repository call with exception translation is usually enough. Add `@Transactional` only when the use case needs multi-document atomicity and the MongoDB deployment supports transactions through a replica set.
**Good example:**
```java
import org.springframework.stereotype.Service;
import java.util.List;
import java.util.Optional;
@Service
class OrderService {
private final OrderRepository repository;
OrderService(OrderRepository repository) {
this.repository = repository;
}
Optional<OrderDocument> findByOrderNumber(String orderNumber) {
return repository.findByOrderNumber(orderNumber);
}
List<OrderDocument> findByCustomer(String customerId) {
return repository.findByCustomerId(customerId);
}
OrderDocument create(String orderNumber, String customerId) {
return repository.save(OrderDocument.of(orderNumber, customerId));
}
OrderDocument updateCustomer(String orderId, String newCustomerId) {
return repository.findById(orderId)
.map(o -> new OrderDocument(o.id(), o.orderNumber(), newCustomerId, o.createdAt(), o.version()))
.map(repository::save)
.orElseThrow(() -> new IllegalArgumentException("Order not found: " + orderId));
}
}
```
**Bad example:**
```java
// Bad: no transaction boundary; repository directly in REST controller leaks persistence
@RestController
class OrderController {
@Autowired OrderRepository repository;
@PostMapping("/orders")
OrderDocument create(String orderNumber) {
return repository.save(new OrderDocument(null, orderNumber, null, null, null));
}
}
```
### Example 5: MongoTemplate for complex queries
Title: Criteria API — type-safe and injection-free
Description: Use `MongoTemplate` with the `Criteria` and `Query` builder API when query derivation is insufficient (e.g. dynamic optional filters, aggregation pipelines). This keeps query logic readable, testable, and free of string concatenation risks.
**Good example:**
```java
import org.springframework.data.mongodb.core.MongoTemplate;
import org.springframework.data.mongodb.core.query.Criteria;
import org.springframework.data.mongodb.core.query.Query;
import org.springframework.stereotype.Repository;
import java.time.Instant;
import java.util.ArrayList;
import java.util.List;
@Repository
class OrderCustomRepository {
private final MongoTemplate mongoTemplate;
OrderCustomRepository(MongoTemplate mongoTemplate) {
this.mongoTemplate = mongoTemplate;
}
List<OrderDocument> search(String customerId, Instant since) {
var criteria = new ArrayList<Criteria>();
if (customerId != null) {
criteria.add(Criteria.where("customer_id").is(customerId));
}
if (since != null) {
criteria.add(Criteria.where("created_at").gte(since));
}
var query = criteria.isEmpty()
? new Query()
: new Query(new Criteria().andOperator(criteria.toArray(new Criteria[0])));
return mongoTemplate.find(query, OrderDocument.class);
}
}
```
**Bad example:**
```java
// Bad: building the JSON query document from user input
List<OrderDocument> search(String customerId) {
String json = "{ customer_id: '" + customerId + "' }"; // injection risk
return mongoTemplate.find(new BasicQuery(json), OrderDocument.class);
}
```
### Example 6: Error handling
Title: DuplicateKeyException, OptimisticLockingFailureException — translate at service boundary
Description: Catch MongoDB-specific Spring Data exceptions (`DuplicateKeyException`, `OptimisticLockingFailureException`) at the service layer and translate them into domain exceptions or meaningful HTTP status codes. Never let raw driver-level exceptions leak to the API. Avoid blanket `catch (Exception e)` which swallows the failure and loses context.
**Good example:**
```java
import org.springframework.dao.DuplicateKeyException;
import org.springframework.dao.OptimisticLockingFailureException;
import org.springframework.stereotype.Service;
import org.springframework.transaction.annotation.Transactional;
@Service
@Transactional(readOnly = true)
class OrderService {
private final OrderRepository repository;
OrderService(OrderRepository repository) {
this.repository = repository;
}
@Transactional
OrderDocument create(String orderNumber, String customerId) {
try {
return repository.save(OrderDocument.of(orderNumber, customerId));
} catch (DuplicateKeyException ex) {
throw new IllegalStateException("Order number already exists: " + orderNumber, ex);
}
}
@Transactional
OrderDocument updateCustomer(String orderId, String newCustomerId) {
try {
return repository.findById(orderId)
.map(o -> new OrderDocument(o.id(), o.orderNumber(), newCustomerId, o.createdAt(), o.version()))
.map(repository::save)
.orElseThrow(() -> new IllegalArgumentException("Order not found: " + orderId));
} catch (OptimisticLockingFailureException ex) {
throw new IllegalStateException("Concurrent update on order: " + orderId, ex);
}
}
}
```
**Bad example:**
```java
OrderDocument create(String orderNumber, String customerId) {
try {
return repository.save(OrderDocument.of(orderNumber, customerId));
} catch (Exception e) {
// Bad: generic catch + silent return null hides duplicate-key and network errors
return null;
}
}
```
### Example 7: Testing
Title: @DataMongoTest slice with Testcontainers for repository behaviour
Description: Use `@DataMongoTest` to spin up only the MongoDB slice — repositories, `MongoTemplate`, and auto-configurations — without the full web layer. Pair it with a `MongoDBContainer` from Testcontainers to run tests against the real dialect. Never mock the repository inside this test — the entire purpose is exercising real MongoDB behaviour.
**Good example:**
```java
import org.junit.jupiter.api.AfterEach;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.autoconfigure.data.mongo.DataMongoTest;
import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
import org.testcontainers.containers.MongoDBContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;
import java.util.Optional;
import static org.assertj.core.api.Assertions.assertThat;
@DataMongoTest
@Testcontainers
class OrderRepositoryIT {
@Container
@ServiceConnection
static MongoDBContainer mongo = new MongoDBContainer("mongo:7.0");
@Autowired
OrderRepository repository;
@AfterEach
void cleanup() { repository.deleteAll(); }
@Test
void save_generatesId() {
OrderDocument saved = repository.save(OrderDocument.of("ORD-001", "CUST-1"));
assertThat(saved.id()).isNotNull();
}
@Test
void findByOrderNumber_returnsDocument() {
repository.save(OrderDocument.of("ORD-002", "CUST-2"));
Optional<OrderDocument> found = repository.findByOrderNumber("ORD-002");
assertThat(found).isPresent();
assertThat(found.get().customerId()).isEqualTo("CUST-2");
}
}
```
**Bad example:**
```java
// Bad: @SpringBootTest loads full context; mocking repository adds no value
@SpringBootTest
class OrderRepositoryTest {
@MockBean OrderRepository repository;
@Test
void findByOrderNumber() {
when(repository.findByOrderNumber("ORD-001"))
.thenReturn(Optional.of(new OrderDocument("id", "ORD-001", "c", null, null)));
// verifies Mockito wiring only — tests nothing about real MongoDB
}
}
```
### Example 8: Full context tests
Title: Wire MongoDB for @SpringBootTest and ensure tests actually run
Description: After adding MongoDB auto-configuration, existing `@SpringBootTest` tests may try `localhost:27017` and log connection failures even when no repository operation is executed. Wire those tests to Testcontainers with `@ServiceConnection` or explicitly disable MongoDB for tests that do not need it. Also confirm naming: Maven Surefire runs `*Test` by default, while `*IT` usually requires Failsafe configuration.
**Good example:**
```java
import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.boot.testcontainers.service.connection.ServiceConnection;
import org.testcontainers.containers.MongoDBContainer;
import org.testcontainers.junit.jupiter.Container;
import org.testcontainers.junit.jupiter.Testcontainers;
@SpringBootTest
@Testcontainers
class ApplicationTests {
@Container
@ServiceConnection
static MongoDBContainer mongo = new MongoDBContainer("mongo:7.0");
@Test
void contextLoads() {
}
}
// If the project has no maven-failsafe-plugin configuration, name Mongo integration tests
// like SumControllerMongoTest so Surefire executes them during `mvn verify`.
```
**Bad example:**
```java
// Bad: passes without exercising MongoDB but logs localhost:27017 connection failures
@SpringBootTest
class ApplicationTests {
@Test
void contextLoads() {
}
}
// Bad unless maven-failsafe-plugin is configured: this class may not run in `mvn verify`.
class OrderRepositoryIT {
}
```
## Output Format
- **ANALYZE** MongoDB code: document mapping completeness, index declarations, repository query safety, service transaction placement, error handling specificity, and DTO vs document leakage
- **CATEGORIZE** issues by impact (SECURITY for injection risk, CORRECTNESS for missing @Version or transactions, PERFORMANCE for missing indexes or queries without explicit pagination and result limits, MAINTAINABILITY for mutable documents or missing factory methods)
- **APPLY** Spring Data MongoDB–aligned fixes: explicit collection, @Field, @CompoundIndex, @Version where appropriate, safe Criteria-based queries, bounded pagination with an explicit maximum page size, service-layer boundaries, exception translation
- **IMPLEMENT** changes so document model, indexes, repositories, and tests stay consistent
- **EXPLAIN** trade-offs (MongoRepository derived finders vs MongoTemplate Criteria, embedded Flapdoodle vs Testcontainers, single-document writes vs multi-document transactions)
- **TEST** repository behaviour with `@DataMongoTest` + Testcontainers and full flows with `@SpringBootTest` when needed; never mock repositories inside persistence slice tests
- **VALIDATE** with `./mvnw compile` before and `./mvnw clean verify` after changes
## Safeguards
- **BLOCKING SAFETY CHECK**: Run `./mvnw compile` before ANY MongoDB refactoring — compilation failure is a HARD STOP
- **CRITICAL VALIDATION**: Run `./mvnw clean verify` after changes; confirm repository tests pass before promoting
- **TEST DISCOVERY**: Confirm MongoDB tests are actually executed by the current Maven setup; use `*Test` naming for Surefire-only projects or configure Failsafe for `*IT` classes
- **INJECTION SAFETY**: Never concatenate user input into MongoDB query strings or `BasicQuery` objects — use Criteria API or `@Query` with bound parameters
- **ERROR HANDLING**: Catch `DuplicateKeyException` and `OptimisticLockingFailureException` at the service boundary and translate to domain exceptions; never swallow with a generic catch
- **FULL CONTEXT TESTS**: Existing `@SpringBootTest` tests need a MongoDB test connection or an explicit MongoDB exclusion to avoid accidental localhost:27017 connection attempts
- **OPTIMISTIC LOCKING**: Adding `@Version` to an existing document requires a planned rollout for existing documents; test stale-update behavior before enabling it in production
- **INDEXES**: Deploy index changes as coordinated background operations on large collections; avoid blocking foreground index builds in production
- **API BOUNDARIES**: Never return managed `@Document` entities directly from REST controllers — map to DTOs to keep API contracts stable and prevent field leakage
- **INCREMENTAL SAFETY**: Change one repository surface or document mapping at a time; verify with `@DataMongoTest` between stepsRelated skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |