Java Spring Boot

npx degit stratpoint-engineering/golden-paths/backend/java-springboot/reference my-app
cd my-app
cp .env.example .env
docker compose up -d

# application-dev.yml
spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/appdb
    username: postgres
    password: postgres
  jpa:
    hibernate:
      ddl-auto: validate
    show-sql: false
  profiles:
    active: dev
 
logging:
  level:
    root: INFO
    com.company.app: DEBUG
  pattern:
    console: '{"timestamp":"%d","level":"%p","traceId":"%X{traceId}","message":"%m"}%n'

@Service("myService")
public class MyServiceImpl implements MyService {
    private final MyComponent myAction;
    private final MyComponent myApproach;
 
    public MyServiceImpl(
        @Qualifier("myAction") MyComponent myAction,
        @Qualifier("myApproach") MyComponent myApproach
    ) {
        this.myAction = myAction;
        this.myApproach = myApproach;
    }
 
    public String testMe() {
        return myAction.doIt() + " " + myApproach.doIt();
    }
}
 
@Component("myAction")
public class MyActionImpl implements MyComponent {
    public String doIt() {
        return "I'm ready for best practices!";
    }
}
 
@Component("myApproach")
public class MyApproachImpl implements MyComponent {
    public String doIt() {
        return "Constructor Injection!";
    }
}

// Custom Annotation
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
public @interface CheckUserSession {
    String requiredRole() default "USER";
}
 
// Aspect
@Aspect
@Component
public class SessionProxyAspect {
    private final HttpServletRequest request;
    private final RedisService redisService;
 
    public SessionProxyAspect(
        @Autowired HttpServletRequest request,
        @Qualifier("redisService") RedisService redisService
    ) {
        this.request = request;
        this.redisService = redisService;
    }
 
    @Around("@annotation(checkSession)")
    public Object validateSession(ProceedingJoinPoint joinPoint, CheckUserSession checkSession) throws Throwable {
        String sessionId = request.getHeader("X-Session-ID");
        String currentRole = redisService.getSessionRole(sessionId);
        if (currentRole == null || !currentRole.equals(checkSession.requiredRole())) {
            throw new UnauthorizedAccessException("Required role: " + checkSession.requiredRole());
        }
        return joinPoint.proceed();
    }
}
 
@Service
public class SensitiveDataService {
    @CheckUserSession(requiredRole = "ADMIN")
    public Data getFinancialReports() {
        // Business logic only — no session checks needed here
        return repository.fetchSecretData();
    }
}

public interface NotificationProvider {
    void send(String recipient, String message);
}
 
@Service("SMS")
public class SmsNotificationService implements NotificationProvider {
    @Override public void send(String r, String m) { /* ... */ }
}
 
@Service("EMAIL")
public class EmailNotificationService implements NotificationProvider {
    @Override public void send(String r, String m) { /* ... */ }
}
 
@Service("PUSH")
public class PushNotificationService implements NotificationProvider {
    @Override public void send(String r, String m) { /* ... */ }
}
 
@Service("notificationServiceFactory")
public class NotificationFactory {
    // Spring DI automatically maps all classes implementing NotificationProvider
    private final Map<String, NotificationProvider> providers;
 
    public NotificationFactory(Map<String, NotificationProvider> providers) {
        this.providers = providers;
    }
 
    public void notify(String type, String recipient, String message) {
        NotificationProvider provider = providers.get(type.toUpperCase());
        if (provider == null) {
            throw new UnsupportedOperationException("No provider found for: " + type);
        }
        provider.send(recipient, message);
    }
}

@Configuration
@EnableAsync
@EnableTransactionManagement
public class AsyncEventConfig {
    @Bean
    public Executor taskExecutor() {
        return Executors.newVirtualThreadPerTaskExecutor();
    }
}
 
// Event payload as a Record (immutable, thread-safe)
public record UserRegistrationEvent(
    Long userId,
    String email,
    String status,
    LocalDateTime timestamp
) {}

@Component
@Slf4j
public class UserObserver {
 
    @Async
    @EventListener(condition = "#event.status == 'PENDING'")
    public void logAuditAttempt(UserRegistrationEvent event) {
        log.info("[AUDIT] Registration attempt for User ID: {}", event.userId());
    }
 
    @Async
    @TransactionalEventListener(phase = TransactionPhase.AFTER_COMMIT)
    public void sendWelcomeEmail(UserRegistrationEvent event) {
        log.info("[EXTERNAL] Sending Welcome Email to {}...", event.email());
        // Call Email Service / SMTP
    }
}

@Service
@RequiredArgsConstructor
public class RegistrationService {
    private final ApplicationEventPublisher eventPublisher;
    private final UserRepository userRepository;
 
    @Transactional
    public void registerNewUser(String email) {
        User user = userRepository.save(new User(email, "PENDING"));
        eventPublisher.publishEvent(new UserRegistrationEvent(
            user.getId(), email, user.getStatus(), LocalDateTime.now()
        ));
    }
}

@Getter
@NoArgsConstructor(access = AccessLevel.PROTECTED)
@AllArgsConstructor(access = AccessLevel.PRIVATE)
@Builder(toBuilder = true)
@JsonDeserialize(builder = UserAccountDTO.UserAccountDTOBuilder.class)
@ValidUserAccount
public class UserAccountDTO {
 
    @NotBlank(message = "Email is required")
    @Email(message = "Invalid email format")
    private String email;
 
    @NotBlank(message = "Mobile number is required")
    @Pattern(
        regexp = "^(\\+63-9|09)\\d{9}$",
        message = "Mobile must follow +63-9XXXXXXXXX or 09XXXXXXXXX format"
    )
    private String mobileNumber;
 
    @Setter(AccessLevel.PROTECTED)
    @Builder.Default
    private String status = "INACTIVE";
 
    // Self-validation on build
    public static class UserAccountDTOBuilder {
        public UserAccountDTO build() {
            UserAccountDTO dto = new UserAccountDTO(email, mobileNumber, status);
            ValidationUtils.validate(dto);
            return dto;
        }
    }
}

public class ValidationUtils {
    private static final Validator VALIDATOR =
        Validation.buildDefaultValidatorFactory().getValidator();
 
    public static <T> void validate(T object) {
        Set<ConstraintViolation<T>> violations = VALIDATOR.validate(object);
        if (!violations.isEmpty()) {
            throw new ConstraintViolationException(violations);
        }
    }
}

ExecutorService executor = Executors.newVirtualThreadPerTaskExecutor();
executor.submit(() -> System.out.println("Task running in virtual thread"));
executor.shutdown();

# application.yml
spring:
  task:
    execution:
      type: virtual
      pool:
        keep-alive: 60s
        max-size: 1000

public Response getProfile(String id) throws ExecutionException, InterruptedException {
    try (var scope = new StructuredTaskScope.ShutdownOnFailure()) {
        Subtask<User> user = scope.fork(() -> fetchUser(id));
        Subtask<Order> order = scope.fork(() -> fetchLatestOrder(id));
 
        scope.join();
        scope.throwIfFailed();
 
        return new Response(user.get(), order.get());
    }
}

# application.yml
resilience4j:
  circuitbreaker:
    instances:
      externalOrderService:
        registerHealthIndicator: true
        slidingWindowSize: 10
        failureRateThreshold: 50
        waitDurationInOpenState: 10000ms
        permittedNumberOfCallsInHalfOpenState: 3
        slidingWindowType: COUNT_BASED

@Service
@RequiredArgsConstructor
public class OrderService {
    private final ExternalApiClient apiClient;
 
    @CircuitBreaker(name = "externalOrderService", fallbackMethod = "handleApiFailure")
    public OrderResponse processOrder(OrderRequest request) {
        return apiClient.submit(request);
    }
 
    private OrderResponse handleApiFailure(OrderRequest request, Throwable t) {
        log.error("Circuit Breaker triggered. Reason: {}", t.getMessage());
        return OrderResponse.builder()
            .status("QUEUED_LOCAL")
            .message("Provider is down; order cached for retry.")
            .build();
    }
}

# .github/workflows/ci.yml
name: Java Spring Boot CI/CD
 
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]
 
jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
 
      - name: Set up JDK 21
        uses: actions/setup-java@v3
        with:
          java-version: '21'
          distribution: 'temurin'
          cache: 'maven'
 
      - name: Code quality checks
        run: mvn checkstyle:check pmd:check spotbugs:check
 
      - name: Dependency vulnerability check
        run: mvn dependency-check:check
 
      - name: Unit tests
        run: mvn test
 
      - name: Test coverage report
        run: mvn jacoco:report
 
      - name: Upload coverage to Codecov
        uses: codecov/codecov-action@v3
 
  build:
    needs: quality
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
 
      - name: Set up JDK 21
        uses: actions/setup-java@v3
        with:
          java-version: '21'
          distribution: 'temurin'
          cache: 'maven'
 
      - name: Build and integration tests
        run: mvn verify
 
      - name: Build Docker image
        run: docker build -t myapp:${{ github.sha }} .
 
      - name: Container security scan
        uses: aquasecurity/trivy-action@master
        with:
          image-ref: 'myapp:${{ github.sha }}'
          format: 'table'
          exit-code: '1'
          severity: 'CRITICAL,HIGH'
 
  deploy:
    needs: build
    if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || github.ref == 'refs/heads/develop')
    runs-on: ubuntu-latest
    environment:
      name: ${{ github.ref == 'refs/heads/main' && 'production' || 'staging' }}
    steps:
      - uses: actions/checkout@v3
 
      - name: Set up kubectl
        uses: azure/setup-kubectl@v3
 
      - name: Set Kubernetes context
        uses: azure/k8s-set-context@v2
        with:
          kubeconfig: ${{ secrets.KUBE_CONFIG }}
 
      - name: Deploy to environment
        run: |
          cd k8s/overlays/${{ github.ref == 'refs/heads/main' && 'prod' || 'staging' }}
          kustomize build | kubectl apply -f -
 
      - name: Verify deployment
        run: |
          kubectl rollout status deployment/myapp -n ${{ github.ref == 'refs/heads/main' && 'production' || 'staging' }}

management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus
  endpoint:
    health:
      show-details: always

# CLAUDE.md
 
## Stack
Java 21 · Spring Boot 3 · Spring Data JPA · Maven
 
## Project Structure
Layered architecture: controller → service (interface + impl) → repository → model (entity/dto/mapper)
Packages: config, controller/v1, model/entity, model/dto, model/mapper, repository,
          service, service/impl, exception, security, util
 
## Key Conventions
- PascalCase for classes, camelCase for methods/variables, UPPER_SNAKE_CASE for constants
- Suffix classes: UserRepository, UserService, UserController
- Constructor injection only — never @Autowired on fields
- Inject services via their interface type, not the concrete impl
 
## What to follow
- Use @RequiredArgsConstructor for constructor injection
- Use Java Records for event payloads (Observer pattern)
- Use @TransactionalEventListener(phase = AFTER_COMMIT) for external side-effects
- Use Executors.newVirtualThreadPerTaskExecutor() for @Async task executors
- Use @Builder with @AllArgsConstructor(access = PRIVATE) for DTOs
- Validate DTOs via ValidationUtils.validate() in the builder's build() method
 
## What to avoid
- Field injection with @Autowired
- @Transactional on read-only operations
- Slow I/O inside @Transactional methods
- Public setters on DTOs — use .toBuilder() instead
- Static factory methods that bypass the Spring Application Context
- Sharing a circuit breaker instance across different external APIs

## Role
You are a Java Spring Boot engineer on an enterprise Spring Boot 3 / Java 21 project at Stratpoint.

## Standards to follow
- Always use constructor injection. Never @Autowired on fields.
- Use @RequiredArgsConstructor (Lombok) to reduce boilerplate.
- Services must implement an interface; inject via the interface type.
- Use Java Records for event payloads. Use @Builder with private constructors for DTOs.
- Use @TransactionalEventListener(phase = AFTER_COMMIT) for external side-effects.
- Use Executors.newVirtualThreadPerTaskExecutor() for all @Async task executors.
- Never place slow I/O inside a @Transactional method.

## Code style
- PascalCase for classes, camelCase for methods/variables, UPPER_SNAKE_CASE for constants
- Suffix: UserRepository, UserService, UserController, UserMapper

## Always
- Write JUnit 5 tests alongside any new service or controller
- Validate DTOs using Bean Validation + custom validators
- Use structured JSON logging with SLF4J + Logback and include correlation IDs

## Never
- Use field injection (@Autowired on private fields)
- Use @Transactional on read-only service methods
- Hardcode secrets — use Spring profiles and environment variables
- Skip input validation at controller or service entry points