springboot-enhancement

Spring Boot Enhancement Protocol

Quality Gate Thresholds (ENFORCED)

Gate	Threshold	Status
Compile	0 errors	REQUIRED
Tests	100% pass (0 failures)	REQUIRED
Coverage	≥ 80% line coverage	REQUIRED
Checkstyle	0 violations	REQUIRED (if configured)

⛔ BLOCKING: Enhancement is NOT complete until ALL gates pass.

Step 0: Verify Coverage Configuration ⚠️ PREREQUISITE

Before ANY enhancement, verify JaCoCo is configured:

grep -l "jacoco-maven-plugin" pom.xml

If NOT configured, add JaCoCo plugin to pom.xml first (see springboot-testing skill for full configuration).

The Enhancement Workflow

When adding to EXISTING code (not building from scratch):

┌─────────────────────────────────────────────────────────────┐
│  STEP 0: VERIFY COVERAGE CONFIGURATION                       │
│  - Check: grep "jacoco-maven-plugin" pom.xml                 │
│  - If missing → Configure JaCoCo FIRST                       │
│  - ⛔ Do NOT proceed without coverage configuration          │
│                                                              │
│  STEP 1: READ EXISTING CODE FIRST                            │
│  - Read the existing controller/service/repository          │
│  - Understand current patterns, naming, structure            │
│  - Note: endpoint paths, method names, error handling style  │
│                                                              │
│  STEP 2: IDENTIFY PATTERNS TO FOLLOW                         │
│  - How are existing endpoints structured?                    │
│  - What naming convention is used?                           │
│  - How is error handling done?                               │
│  - How are tests organized?                                  │
│                                                              │
│  STEP 3: WRITE NEW TESTS ONLY                                │
│  - Add NEW test methods — don't modify existing tests        │
│  - Follow existing test naming patterns                      │
│  - Cover: happy path, error cases, edge cases                │
│                                                              │
│  STEP 4: IMPLEMENT FOLLOWING EXISTING PATTERNS               │
│  - Match existing code style exactly                         │
│  - Use same error handling approach                          │
│  - Follow same layer conventions                             │
│                                                              │
│  STEP 5: VERIFY NO REGRESSIONS                               │
│  - Run FULL test suite (existing + new)                      │
│  - All existing tests must still pass                        │
│  - No changes to existing behavior                           │
└─────────────────────────────────────────────────────────────┘

Read Before Write Checklist

Before adding ANY code, read and note:

# Read the existing controller
Read src/main/java/.../TodoController.java
# Note: @RequestMapping base path, method patterns, response types

# Read the existing service
Read src/main/java/.../TodoService.java
# Note: Method naming, transaction usage, exception handling

# Read the existing repository
Read src/main/java/.../TodoRepository.java
# Note: Query patterns, return types

# Read existing tests
Read src/test/java/.../TodoControllerTest.java
# Note: Test naming, setup patterns, assertion style

# Read existing DTOs
Read src/main/java/.../dto/
# Note: Which DTOs exist, can you reuse them?

Pattern Recognition Checklist

Aspect	Question to Answer
Base Path	/api/v1/todos or /todos or something else?
ID in Path	/{id} or /{todoId} or query param?
Response Wrapper	Raw entity, ResponseEntity, custom wrapper?
Error Format	ErrorResponse DTO? Map? String?
Naming	findAll() or getAll() or list()?
Test Naming	should_X_whenY() or testX() or xTest()?
Mock Style	@MockBean or @Mock + @InjectMocks?

Adding a New Endpoint Example

Existing Code Analysis

// EXISTING TodoController.java
@RestController
@RequestMapping("/api/v1/todos")
@RequiredArgsConstructor
public class TodoController {
    private final TodoService todoService;

    @GetMapping
    public ResponseEntity<List<TodoResponse>> getAll() {
        return ResponseEntity.ok(todoService.findAll());
    }

    @PostMapping
    public ResponseEntity<TodoResponse> create(
            @Valid @RequestBody CreateTodoRequest request) {
        return ResponseEntity.status(HttpStatus.CREATED)
            .body(todoService.create(request));
    }

    @GetMapping("/{id}")
    public ResponseEntity<TodoResponse> getById(@PathVariable Long id) {
        return ResponseEntity.ok(todoService.findById(id));
    }
}

Patterns Identified

• Base path: /api/v1/todos
• ID style: /{id} as @PathVariable Long
• Response: ResponseEntity<TodoResponse>
• Service method naming: findAll(), create(), findById()

Step 1: Write NEW Tests (Don't Modify Existing)

// ADD to existing TodoControllerTest.java - DO NOT MODIFY existing tests

@Test
void should_return204_whenDeleteExistingTodo() {
    // Given
    doNothing().when(todoService).delete(1L);

    // When & Then
    mockMvc.perform(delete("/api/v1/todos/1"))
        .andExpect(status().isNoContent());

    verify(todoService).delete(1L);
}

@Test
void should_return404_whenDeleteNonExistentTodo() {
    // Given
    doThrow(new TodoNotFoundException(999L)).when(todoService).delete(999L);

    // When & Then
    mockMvc.perform(delete("/api/v1/todos/999"))
        .andExpect(status().isNotFound());
}

Step 2: Implement Following Existing Patterns

// ADD to existing TodoController.java - follow existing style

@DeleteMapping("/{id}")
public ResponseEntity<Void> delete(@PathVariable Long id) {
    todoService.delete(id);
    return ResponseEntity.noContent().build();
}

// ADD to existing TodoService.java - follow existing style

public void delete(Long id) {
    if (!todoRepository.existsById(id)) {
        throw new TodoNotFoundException(id);
    }
    todoRepository.deleteById(id);
}

Step 3: Run Full Suite

mvn test  # ALL tests: existing + new must pass

Backward Compatibility Rules

Adding Fields to DTOs (SAFE)

// EXISTING
public record TodoResponse(Long id, String title, boolean completed) {}

// ENHANCED - ADD fields only
public record TodoResponse(
    Long id,
    String title,
    boolean completed,
    Instant updatedAt      // NEW - backward compatible (additive)
) {}

Adding Optional Parameters (SAFE)

// EXISTING
@GetMapping
public ResponseEntity<List<TodoResponse>> getAll() { ... }

// ENHANCED - optional params
@GetMapping
public ResponseEntity<List<TodoResponse>> getAll(
        @RequestParam(required = false) Boolean completed) { ... }

BREAKING Changes (AVOID)

// BREAKING: Removing field
// Before: {"id": 1, "title": "...", "priority": 5}
// After:  {"id": 1, "title": "..."}  // priority removed!

// BREAKING: Renaming field
// Before: {"todoId": 1}
// After:  {"id": 1}  // field renamed!

// BREAKING: Changing type
// Before: {"id": "abc-123"}  // String
// After:  {"id": 123}         // Long

// BREAKING: Changing endpoint path
// Before: GET /api/v1/todos
// After:  GET /api/v2/tasks

What NOT To Do

// DON'T rename existing methods
// Before: findAll() → After: getAllTodos()  ❌

// DON'T change existing method signatures
// Before: findById(Long id)
// After: findById(Long id, boolean includeDeleted)  ❌

// DON'T modify existing tests
// If existing test expects X and you need Y, that's a
// breaking change, not an enhancement  ❌

// DON'T remove existing fields from responses
// Before: {"id": 1, "title": "...", "priority": 5}
// After: {"id": 1, "title": "..."}  ❌

// DON'T change existing error response shapes
// Clients may depend on the current format  ❌

Enhancement Checklist

Before declaring done:

• Read all existing code in the area?
• Identified naming patterns?
• Identified error handling patterns?
• Wrote NEW tests only (no modifications to existing)?
• Implementation follows existing patterns exactly?
• Full test suite passes (existing + new)?
• No changes to existing behavior verified?
• No breaking changes to API contract?
• DTOs are additive only (no removals/renames)?
• Coverage ≥ 80%? ⚠️ MANDATORY

Coverage Verification ⚠️ MANDATORY

Before marking enhancement complete:

# Generate coverage report
mvn test jacoco:report

# Check coverage
open target/site/jacoco/index.html

Metric	Minimum Threshold
Line Coverage	80%
Branch Coverage	75%

If coverage < 80%:

1. Identify uncovered lines in JaCoCo report
2. Add tests for new code paths
3. Re-run mvn test jacoco:report
4. Repeat until ≥ 80%

⛔ Do NOT mark complete if coverage < 80%

A pre-completion hook enforces this requirement automatically.

Common Enhancement Scenarios

Adding a Field to Response

1. Add field to response DTO (at end)
2. Update mapping method to populate new field
3. Update tests to verify new field
4. Existing tests should still pass (they ignore unknown fields)

Adding a New Endpoint

1. Write controller test
2. Write service test
3. Add controller method following existing pattern
4. Add service method following existing pattern
5. Add repository method if needed
6. Run full suite

Adding Optional Filtering

1. Add @RequestParam with required=false
2. Update service to handle filter
3. Add tests for filtered and unfiltered cases
4. Verify existing tests still pass (they don't send param)