Spring Boot Best Practices

Project Structure (Domain-Driven Design)

src/main/java/com/example/ ├── {domain}/ # One package per domain │ ├── domain/ # Domain layer - entities and repository interfaces │ │ ├── {Entity}.java # JPA entity │ │ └── {Entity}Repository.java # Spring Data JPA repository interface │ ├── application/ # Application layer - business logic │ │ └── {Entity}ApplicationService.java │ └── interfaces/ # Interface layer - REST controllers │ └── rest/ │ ├── {Entity}Controller.java │ └── {Entity}Mapper.java ├── shared/ # Cross-cutting concerns │ ├── application/ │ ├── domain/ │ └── interfaces/rest/ └── api/generated/ # OpenAPI generated code (do not edit)

Transaction Management

Minimize Transaction Scope

Only wrap the actual database operation in a transaction, not the entire method:

// Good - minimal transaction scope public EntityDto updateEntity(String ref, UpdateEntityRequestDto request) { Entity entity = refResolver.resolve(ref);

if (request.getTitle() != null) {
    entity.setTitle(request.getTitle());
}
// ... other field updates

Entity saved = transactionTemplate.execute(status -> entityRepository.save(entity));
return entityMapper.toDto(saved);

}

// Bad - entire method in transaction public EntityDto updateEntity(String ref, UpdateEntityRequestDto request) { return transactionTemplate.execute(status -> { Entity entity = refResolver.resolve(ref); // Read doesn't need transaction // ... field updates don't need transaction Entity saved = entityRepository.save(entity); // Only this needs transaction return entityMapper.toDto(saved); }); }

Use TransactionTemplate, Not @Transactional

Prefer TransactionTemplate over @Transactional annotation for explicit control:

@Service @RequiredArgsConstructor public class EntityApplicationService { private final TransactionTemplate transactionTemplate; private final EntityRepository entityRepository;

public void deleteEntity(String ref) {
    Entity entity = refResolver.resolve(ref);
    transactionTemplate.executeWithoutResult(status -> entityRepository.delete(entity));
}

}

When Full Transaction Is Needed

Keep full transaction scope when operations must be atomic:

// Create needs full transaction for sequence number atomicity public EntityDto createEntity(CreateEntityRequestDto request) { return transactionTemplate.execute(status -> { int sequenceNumber = getNextSequenceNumber(); // Read Entity entity = new Entity(..., sequenceNumber, ...); // Must be atomic return entityMapper.toDto(entityRepository.save(entity)); // Write }); }

Lombok Usage

Use @RequiredArgsConstructor for Dependency Injection

Never write constructors manually for Spring beans:

// Good @Service @RequiredArgsConstructor public class EntityApplicationService { private final EntityRepository entityRepository; private final RefResolver refResolver; private final EntityMapper entityMapper; }

// Bad @Service public class EntityApplicationService { private final EntityRepository entityRepository;

public EntityApplicationService(EntityRepository entityRepository) {
    this.entityRepository = entityRepository;
}

}

Standard Lombok Annotations for Entities

@Entity @Table(name = "entities") @Getter @Setter @NoArgsConstructor(access = AccessLevel.PROTECTED) // JPA requires no-arg constructor public class Entity { // fields...

// Required-args constructor for creating new instances
public Entity(String publicId, int sequenceNumber, ...) {
    // initialization
}

}

OpenAPI Generated Code

DTO Suffix Convention

All generated model classes have Dto suffix to distinguish from domain entities:

• Domain: Entity , Project , Task

• DTOs: EntityDto , ProjectDto , TaskDto , CreateEntityRequestDto

Never Import with Wildcards

Always use explicit imports:

// Good import com.example.api.generated.model.EntityDto; import com.example.api.generated.model.CreateEntityRequestDto;

// Bad import com.example.api.generated.model.*;

Controller Implementation

Controllers implement generated API interfaces:

@RestController @RequiredArgsConstructor public class EntityController implements EntitiesApi { private final EntityApplicationService entityApplicationService;

@Override
public ResponseEntity<EntityDto> createEntity(CreateEntityRequestDto request) {
    EntityDto created = entityApplicationService.createEntity(request);
    return ResponseEntity.status(HttpStatus.CREATED).body(created);
}

}

Mapper Pattern

Mappers convert between domain entities and DTOs:

@Component public class EntityMapper {

public EntityDto toDto(Entity domain) {
    EntityDto dto = new EntityDto();
    dto.setPublicId(domain.getPublicId());
    dto.setTitle(domain.getTitle());
    dto.setStatus(toApiStatus(domain.getStatus()));
    // ... map all fields
    return dto;
}

public EntityStatus toDomainStatus(EntityStatusDto apiStatus) {
    return switch (apiStatus) {
        case ACTIVE -> EntityStatus.ACTIVE;
        case INACTIVE -> EntityStatus.INACTIVE;
        case ARCHIVED -> EntityStatus.ARCHIVED;
    };
}

private EntityStatusDto toApiStatus(EntityStatus domainStatus) {
    return switch (domainStatus) {
        case ACTIVE -> EntityStatusDto.ACTIVE;
        case INACTIVE -> EntityStatusDto.INACTIVE;
        case ARCHIVED -> EntityStatusDto.ARCHIVED;
    };
}

}

Reference Resolution Pattern

Use RefResolver for looking up entities by publicId or displayKey:

@Component @RequiredArgsConstructor public class RefResolver { private final EntityRepository entityRepository;

public Entity resolve(String ref) {
    return entityRepository.findByPublicId(ref)
        .or(() -> entityRepository.findByKey(ref))
        .orElseThrow(() -> new EntityNotFoundException("Entity", ref));
}

// For optional references (can be null or empty string to clear)
public Entity resolveOptional(String ref) {
    if (ref == null || ref.isBlank()) {
        return null;
    }
    return resolve(ref);
}

}

Exception Handling

Custom Exceptions

public class EntityNotFoundException extends RuntimeException { public EntityNotFoundException(String entityType, String reference) { super(entityType + " not found: " + reference); } }

public class ResourceConflictException extends RuntimeException { public ResourceConflictException(String message) { super(message); } }

Global Exception Handler

@RestControllerAdvice public class GlobalExceptionHandler {

@ExceptionHandler(EntityNotFoundException.class)
public ResponseEntity<ErrorResponseDto> handleNotFound(EntityNotFoundException ex) {
    ErrorResponseDto error = new ErrorResponseDto();
    error.setCode("NOT_FOUND");
    error.setMessage(ex.getMessage());
    return ResponseEntity.status(HttpStatus.NOT_FOUND).body(error);
}

@ExceptionHandler(MethodArgumentNotValidException.class)
public ResponseEntity<ErrorResponseDto> handleValidation(MethodArgumentNotValidException ex) {
    ErrorResponseDto error = new ErrorResponseDto();
    error.setCode("VALIDATION_ERROR");
    error.setMessage("Validation failed");
    error.setDetails(ex.getBindingResult().getFieldErrors().stream()
        .map(fe -> {
            FieldErrorDto fieldError = new FieldErrorDto();
            fieldError.setField(fe.getField());
            fieldError.setMessage(fe.getDefaultMessage());
            return fieldError;
        })
        .toList());
    return ResponseEntity.badRequest().body(error);
}

}

Testing Patterns

Integration Tests with Schema Isolation

@AutoConfigureMockMvc @Transactional class EntityControllerTest extends AbstractIntegrationTest {

private static final String SCHEMA_NAME = "entity_controller_test";

@DynamicPropertySource
static void configureSchema(DynamicPropertyRegistry registry) {
    AbstractIntegrationTest.configureSchema(registry, SCHEMA_NAME);
}

@Autowired private MockMvc mockMvc;
@MockitoBean private CurrentUserService currentUserService;

@BeforeEach
void setUp() {
    testUser = userRepository.save(new User(...));
    when(currentUserService.getCurrentUser()).thenReturn(testUser);
}

@Test
@WithMockUser(username = "user")
void createEntity_shouldReturnCreatedEntity() throws Exception {
    CreateEntityRequestDto request = new CreateEntityRequestDto();
    request.setTitle("Test Entity");

    mockMvc.perform(post("/entities")
            .contentType(MediaType.APPLICATION_JSON)
            .content(objectMapper.writeValueAsString(request)))
        .andExpect(status().isCreated())
        .andExpect(jsonPath("$.title").value("Test Entity"));
}

}

Code Style

Checkstyle Rules

• No star imports (import x.y.* )

• No unused imports

• No redundant imports

Spotless Formatting

Run mvn spotless:apply before committing.

Switch Expressions

Use modern switch expressions:

// Good private EntityStatusDto toApiStatus(EntityStatus status) { return switch (status) { case ACTIVE -> EntityStatusDto.ACTIVE; case INACTIVE -> EntityStatusDto.INACTIVE; case ARCHIVED -> EntityStatusDto.ARCHIVED; }; }

// Bad private EntityStatusDto toApiStatus(EntityStatus status) { switch (status) { case ACTIVE: return EntityStatusDto.ACTIVE; case INACTIVE: return EntityStatusDto.INACTIVE; case ARCHIVED: return EntityStatusDto.ARCHIVED; default: throw new IllegalArgumentException(); } }

Build Commands

Generate OpenAPI code

mvn generate-sources

Format code

mvn spotless:apply

Check style

mvn checkstyle:check

Run tests

mvn test

Full build

mvn clean verify