Backend Patterns

Backend Component — Patterns

Controller Pattern

Controllers must be annotated with @RestController and @Observed. Endpoints should use standard mapping annotations (@GetMapping, @PutMapping, etc.) and return DTOs or ResponseEntity.

@RestController
@RequestMapping("/api/resource")
@AllArgsConstructor
@Observed
public class ResourceController {
    private final ResourceService service;

    @GetMapping("/{id}")
    public ResourceDto getResource(@PathVariable String id) {
        return service.findById(id).orElseThrow(NotFoundException::new);
    }
}

DTO Pattern

DTOs are implemented as Java records to ensure immutability and concise syntax. They should have a Dto suffix.

public record ResourceDto(
    String id,
    String name,
    List<String> tags
) {}

Service Pattern

Services contain business logic and are annotated with @Service. Methods performing write operations must be marked @Transactional.

@Service
@Observed
@RequiredArgsConstructor
public class ResourceService {
    private final ResourceRepository repository;

    @Transactional
    public void updateResource(String id, ResourceDto dto) {
        // logic
    }
}

Error Handling

Exceptions should either use @ResponseStatus or extend ResponseStatusException. Generic exceptions like NotFoundGenericException are preferred for common scenarios.

@ResponseStatus(value = HttpStatus.NOT_FOUND)
public class ResourceNotFoundException extends ResponseStatusException {
    public ResourceNotFoundException() {
        super(HttpStatus.NOT_FOUND, "Resource not found");
    }
}