<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
                             https://maven.apache.org/xsd/maven-4.0.0.xsd">
 
    <modelVersion>4.0.0</modelVersion>
 
    <!--
        The parent BOM (Bill of Materials) manages compatible versions
        for ALL Spring dependencies. You almost never need to specify
        versions for spring-* dependencies when this parent is present.
    -->
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.5</version>
        <relativePath/>
    </parent>
 
    <!-- Project coordinates - used as the artifact identifier -->
    <groupId>com.company</groupId>
    <artifactId>ecommerce-service</artifactId>
    <version>1.0.0-SNAPSHOT</version>
    <name>ecommerce-service</name>
    <description>E-Commerce Backend Service</description>
    <packaging>jar</packaging>
 
    <properties>
        <java.version>17</java.version>
        <mapstruct.version>1.5.5.Final</mapstruct.version>
        <lombok.version>1.18.30</lombok.version>
        <testcontainers.version>1.19.3</testcontainers.version>
    </properties>
 
    <dependencies>
 
        <!-- ===<mark class="obsidian-highlight"> CORE WEB </mark>=<mark class="obsidian-highlight"> -->
        <!-- Includes: Spring MVC, Tomcat, Jackson (JSON), Validation -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
 
        <!-- </mark>=<mark class="obsidian-highlight"> DATA LAYER </mark>=<mark class="obsidian-highlight"> -->
        <!-- Includes: Spring Data JPA, Hibernate, HikariCP connection pool -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-data-jpa</artifactId>
        </dependency>
 
        <!-- Bean Validation (Jakarta Validation API + Hibernate Validator) -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-validation</artifactId>
        </dependency>
 
        <!-- </mark>=<mark class="obsidian-highlight"> SECURITY </mark>=<mark class="obsidian-highlight"> -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-security</artifactId>
        </dependency>
 
        <!-- </mark>=<mark class="obsidian-highlight"> DATABASE DRIVER </mark>=== -->
        <!--
            scope=runtime: Only needed at runtime, not compile time.
            This prevents accidental use of driver-specific classes in your code.
        -->
        <dependency>
            <groupId>com.mysql</groupId>
            <artifactId>mysql-connector-j</artifactId>
            <scope>runtime</scope>
        </dependency>
 
        <!-- ===<mark class="obsidian-highlight"> DATABASE MIGRATION </mark>=<mark class="obsidian-highlight"> -->
        <!-- flyway-mysql includes MySQL-specific support -->
        <dependency>
            <groupId>org.flywaydb</groupId>
            <artifactId>flyway-mysql</artifactId>
        </dependency>
 
        <!-- </mark>=<mark class="obsidian-highlight"> DEVELOPER PRODUCTIVITY </mark>=== -->
        <!--
            Lombok generates boilerplate: getters, setters, constructors,
            builders, equals/hashCode, toString, logging.
            optional=true means it is NOT included in the final jar.
        -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
 
        <!--
            MapStruct generates type-safe DTO <-> Entity mapping code at compile time.
            Much faster and safer than reflection-based mappers like ModelMapper.
        -->
        <dependency>
            <groupId>org.mapstruct</groupId>
            <artifactId>mapstruct</artifactId>
            <version>${mapstruct.version}</version>
        </dependency>
 
        <!-- ===<mark class="obsidian-highlight"> CONFIGURATION </mark>=== -->
        <!--
            optional=true: Generates metadata for @ConfigurationProperties.
            Enables IDE autocomplete for your custom application.yml properties.
        -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-configuration-processor</artifactId>
            <optional>true</optional>
        </dependency>
 
        <!-- ===<mark class="obsidian-highlight"> OBSERVABILITY </mark>=<mark class="obsidian-highlight"> -->
        <!-- Provides /actuator/health, /actuator/info, /actuator/metrics -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-actuator</artifactId>
        </dependency>
 
        <!-- </mark>=<mark class="obsidian-highlight"> TESTING </mark>=== -->
        <!-- Includes JUnit 5, Mockito, AssertJ, Spring Test, MockMvc -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
 
        <!-- Security test support -->
        <dependency>
            <groupId>org.springframework.security</groupId>
            <artifactId>spring-security-test</artifactId>
            <scope>test</scope>
        </dependency>
 
        <!--
            TestContainers: Spins up a REAL MySQL Docker container for integration tests.
            This is the gold standard for testing database code.
        -->
        <dependency>
            <groupId>org.testcontainers</groupId>
            <artifactId>mysql</artifactId>
            <scope>test</scope>
        </dependency>
 
        <dependency>
            <groupId>org.testcontainers</groupId>
            <artifactId>junit-jupiter</artifactId>
            <scope>test</scope>
        </dependency>
 
    </dependencies>
 
    <build>
        <plugins>
 
            <!-- Spring Boot Maven Plugin: creates executable fat jar -->
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <configuration>
                    <!-- Exclude Lombok from final jar - it is compile-time only -->
                    <excludes>
                        <exclude>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                        </exclude>
                    </excludes>
                </configuration>
            </plugin>
 
            <!--
                CRITICAL: Maven Compiler must be configured when using
                both Lombok AND MapStruct together.
                Lombok MUST appear BEFORE MapStruct in annotationProcessorPaths.
                If MapStruct runs first, it cannot see Lombok-generated methods
                and all mapping will fail silently.
            -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <source>17</source>
                    <target>17</target>
                    <annotationProcessorPaths>
                        <!-- Lombok FIRST -->
                        <path>
                            <groupId>org.projectlombok</groupId>
                            <artifactId>lombok</artifactId>
                            <version>${lombok.version}</version>
                        </path>
                        <!-- MapStruct SECOND -->
                        <path>
                            <groupId>org.mapstruct</groupId>
                            <artifactId>mapstruct-processor</artifactId>
                            <version>${mapstruct.version}</version>
                        </path>
                        <!-- Configuration processor THIRD -->
                        <path>
                            <groupId>org.springframework.boot</groupId>
                            <artifactId>spring-boot-configuration-processor</artifactId>
                        </path>
                    </annotationProcessorPaths>
                    <compilerArgs>
                        <!-- Makes MapStruct use Lombok builder if present -->
                        <arg>-Amapstruct.defaultComponentModel=spring</arg>
                    </compilerArgs>
                </configuration>
            </plugin>
 
        </plugins>
    </build>
 
</project>

package com.company.ecommerce;
 
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.data.jpa.repository.config.EnableJpaAuditing;
import org.springframework.scheduling.annotation.EnableAsync;
import org.springframework.transaction.annotation.EnableTransactionManagement;
 
import com.company.ecommerce.common.config.AppProperties;
 
/*
 * @SpringBootApplication is a meta-annotation that combines:
 *   @Configuration          - This class is a source of bean definitions
 *   @EnableAutoConfiguration - Auto-configure based on classpath
 *   @ComponentScan           - Scan this package and ALL sub-packages
 *
 * PLACEMENT MATTERS: This class must be in the ROOT package.
 * If placed in a sub-package, sibling packages will NOT be scanned.
 */
@SpringBootApplication
@EnableJpaAuditing(auditorAwareRef = "auditorAware")  // Enables @CreatedBy, @LastModifiedBy
@EnableAsync                                           // Enables @Async methods
@EnableTransactionManagement                           // Enables @Transactional
@EnableConfigurationProperties(AppProperties.class)    // Enables @ConfigurationProperties beans
public class EcommerceApplication {
 
    public static void main(String[] args) {
        SpringApplication.run(EcommerceApplication.class, args);
    }
}

# application.yml
# This file contains defaults and settings shared across ALL profiles.
# Profile-specific files override only what needs to change.
 
spring:
  application:
    name: ecommerce-service
 
  # ===<mark class="obsidian-highlight"> JPA / HIBERNATE </mark>===
  jpa:
    # NEVER use 'update' or 'create' in production.
    # 'validate' checks that your entities match the schema - great safety net.
    # 'none' when you fully trust Flyway to manage the schema.
    hibernate:
      ddl-auto: validate
 
    # CRITICAL: Disable Open Session In View.
    # When true (default), Hibernate session stays open during HTTP request processing
    # including serialization. This causes lazy loading outside service layer,
    # hidden N+1 queries, and connections held longer than necessary.
    open-in-view: false
 
    show-sql: false # Override to true in dev profile
 
    properties:
      hibernate:
        # MySQL dialect for Hibernate 6
        dialect: org.hibernate.dialect.MySQLDialect
 
        # Format SQL for readability (useful with show-sql=true in dev)
        format_sql: true
 
        # All datetimes stored as UTC in MySQL
        jdbc:
          time_zone: UTC
 
        # JDBC batch processing - improves bulk insert/update performance
        jdbc.batch_size: 25
        order_inserts: true # Group inserts of same type together for batching
        order_updates: true # Group updates of same type together for batching
 
        # Default batch fetch size - reduces N+1 queries
        default_batch_fetch_size: 25
 
  # ===<mark class="obsidian-highlight"> DATASOURCE </mark>===
  # Override url, username, password in profile-specific files.
  # NEVER hardcode credentials here.
  datasource:
    url: jdbc:mysql://localhost:3306/ecommerce?useSSL=false&serverTimezone=UTC&characterEncoding=UTF-8&rewriteBatchedStatements=true
    username: ${DB_USERNAME}
    password: ${DB_PASSWORD}
    driver-class-name: com.mysql.cj.jdbc.Driver
 
    # ===<mark class="obsidian-highlight"> HIKARICP CONNECTION POOL </mark>===
    hikari:
      pool-name: EcommerceHikariPool
      # Formula: (core_count * 2) + effective_spindle_count
      # For 4-core machine with SSD: (4 * 2) + 1 = 9, round to 10
      maximum-pool-size: 10
      minimum-idle: 2
      # How long a connection can sit idle before being removed
      idle-timeout: 300000 # 5 minutes in milliseconds
      # Maximum lifetime of a connection in the pool (must be < MySQL wait_timeout)
      max-lifetime: 1800000 # 30 minutes
      # How long to wait for a connection from the pool before throwing an exception
      connection-timeout: 30000 # 30 seconds
      validation-timeout: 5000 # 5 seconds
      # Log a warning if connection is held longer than this (useful for detecting leaks)
      leak-detection-threshold: 60000 # 1 minute
 
  # ===<mark class="obsidian-highlight"> FLYWAY MIGRATION </mark>=<mark class="obsidian-highlight">
  flyway:
    enabled: true
    locations: classpath:db/migration
    baseline-on-migrate: false # Set true ONLY for first migration on existing DB
    validate-on-migrate: true # Validate checksums before migrating
    out-of-order: false # Prevent out-of-order migrations in production
 
# </mark>=<mark class="obsidian-highlight"> ACTUATOR (Health, Metrics) </mark>=<mark class="obsidian-highlight">
management:
  endpoints:
    web:
      exposure:
        include: health,info,metrics,prometheus
  endpoint:
    health:
      show-details: when_authorized # Only show DB health details when authenticated
 
# </mark>=<mark class="obsidian-highlight"> LOGGING </mark>===
logging:
  level:
    com.company.ecommerce: INFO
    org.springframework.web: WARN
    org.hibernate.SQL: WARN
    org.hibernate.type.descriptor.sql.BasicBinder: WARN

# application-dev.yml
# Activated with: SPRING_PROFILES_ACTIVE=dev
 
spring:
  jpa:
    show-sql: true
    properties:
      hibernate:
        format_sql: true
 
  datasource:
    url: jdbc:mysql://localhost:3306/ecommerce_dev?useSSL=false&serverTimezone=UTC&characterEncoding=UTF-8
 
  flyway:
    out-of-order: true # Allow out-of-order in dev (not prod!)
 
logging:
  level:
    com.company.ecommerce: DEBUG
    # Show actual SQL query parameters (WARNING: exposes data in logs)
    org.hibernate.SQL: DEBUG
    org.hibernate.type.descriptor.sql.BasicBinder: TRACE

# application-prod.yml
# Activated with: SPRING_PROFILES_ACTIVE=prod
# Credentials come from AWS Parameter Store / Secrets Manager via environment variables
 
spring:
  jpa:
    show-sql: false
    hibernate:
      ddl-auto: validate # Validate, never modify
 
  datasource:
    # AWS RDS endpoint injected at runtime
    url: jdbc:mysql://${RDS_ENDPOINT}:3306/${RDS_DB_NAME}?useSSL=true&requireSSL=true&serverTimezone=UTC&characterEncoding=UTF-8&connectTimeout=5000&socketTimeout=30000&rewriteBatchedStatements=true
    username: ${RDS_USERNAME}
    password: ${RDS_PASSWORD}
 
    hikari:
      maximum-pool-size: 20 # Higher for production load
      minimum-idle: 5
      max-lifetime: 1800000
 
management:
  endpoint:
    health:
      show-details: never # Never expose internals publicly in production
 
logging:
  level:
    root: WARN
    com.company.ecommerce: WARN

# Option 1: Environment variable (RECOMMENDED for production and Docker/Kubernetes)
SPRING_PROFILES_ACTIVE=prod java -jar app.jar
 
# Option 2: JVM system property
java -Dspring.profiles.active=prod -jar app.jar
 
# Option 3: In application.yml (use ONLY for local development default)
# spring:
#   profiles:
#     active: dev

package com.company.ecommerce.common.config;
 
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.context.annotation.Profile;
 
@Configuration
public class EmailConfig {
 
    /*
     * In non-production environments, use a fake email service
     * that logs the email instead of sending it.
     * The ! prefix means "NOT prod profile".
     */
    @Bean
    @Profile("!prod")
    public EmailService mockEmailService() {
        return new MockEmailService();
    }
 
    /*
     * In production, use the real AWS SES implementation.
     */
    @Bean
    @Profile("prod")
    public EmailService awsSesEmailService(AppProperties appProperties) {
        return new SesEmailService(appProperties.getAws().getSesRegion());
    }
}

# application.yml
spring:
  profiles:
    group:
      prod: "prod,aws,security-strict"
      staging: "staging,aws,security-relaxed"

package com.company.ecommerce.common.config;
 
import jakarta.validation.Valid;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.Positive;
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.validation.annotation.Validated;
 
/*
 * @ConfigurationProperties binds properties with prefix "app" to this class.
 * @Validated enables Bean Validation on the bound values at startup.
 * If jwt-secret is empty, the application FAILS TO START with a clear error message.
 * This is much better than failing at runtime when the first JWT operation is attempted.
 */
@Data
@Validated
@ConfigurationProperties(prefix = "app")
public class AppProperties {
 
    @NotBlank(message = "Application name must not be blank")
    private String name;
 
    @Valid
    private Security security = new Security();
 
    @Valid
    private Aws aws = new Aws();
 
    @Valid
    private Email email = new Email();
 
    @Data
    public static class Security {
 
        @NotBlank(message = "JWT secret must be configured")
        private String jwtSecret;
 
        @Positive
        private long jwtExpirationMs = 86400000L;  // 24 hours default
 
        private boolean requireHttps = true;
    }
 
    @Data
    public static class Aws {
        private String region = "us-east-1";
 
        @NotBlank(message = "S3 bucket name must be configured")
        private String s3BucketName;
 
        private String sqsOrderQueueUrl;
        private String sesRegion = "us-east-1";
    }
 
    @Data
    public static class Email {
        private String fromAddress = "noreply@company.com";
        private boolean enabled = true;
    }
}

# application.yml - Corresponding YAML
app:
  name: Ecommerce Service
  security:
    jwt-secret: ${JWT_SECRET} # From environment variable
    jwt-expiration-ms: 86400000
    require-https: true
  aws:
    region: us-east-1
    s3-bucket-name: ${S3_BUCKET_NAME}
    sqs-order-queue-url: ${SQS_QUEUE_URL}
  email:
    from-address: noreply@company.com
    enabled: true

// Usage in any Spring-managed class
@Service
@RequiredArgsConstructor
public class JwtTokenService {
 
    // Clean, type-safe injection - no magic strings
    private final AppProperties appProperties;
 
    public String generateToken(String username) {
        return Jwts.builder()
            .setSubject(username)
            .setExpiration(new Date(System.currentTimeMillis()
                + appProperties.getSecurity().getJwtExpirationMs()))
            .signWith(Keys.hmacShaKeyFor(
                appProperties.getSecurity().getJwtSecret().getBytes()))
            .compact();
    }
}

<groupId>com.company</groupId>
<artifactId>ecommerce-parent</artifactId>
<version>1.0.0-SNAPSHOT</version>
<packaging>pom</packaging>  <!-- pom packaging for parent -->
 
<modules>
    <module>ecommerce-domain</module>
    <module>ecommerce-service</module>
    <module>ecommerce-api</module>
    <module>ecommerce-infrastructure</module>
    <module>ecommerce-app</module>
</modules>

<!-- ecommerce-service/pom.xml -->
<parent>
    <groupId>com.company</groupId>
    <artifactId>ecommerce-parent</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</parent>
 
<artifactId>ecommerce-service</artifactId>
 
<dependencies>
    <!-- Service depends on Domain module -->
    <dependency>
        <groupId>com.company</groupId>
        <artifactId>ecommerce-domain</artifactId>
        <version>${project.version}</version>
    </dependency>
</dependencies>

// Exclude when you want full control (e.g., multiple data sources)
@SpringBootApplication(exclude = {
    DataSourceAutoConfiguration.class,
    HibernateJpaAutoConfiguration.class
})
public class EcommerceApplication { }

logging:
  level:
    org.springframework.boot.autoconfigure: DEBUG

package com.company.ecommerce.common.config;
 
import jakarta.annotation.PostConstruct;
import jakarta.annotation.PreDestroy;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Component;
 
@Component
@RequiredArgsConstructor
@Slf4j
public class ApplicationStartupValidator {
 
    private final AppProperties appProperties;
 
    /*
     * @PostConstruct: Called AFTER constructor and @Autowired injection.
     * Use for: validation, warm-up, initialization logic.
     * If this method throws an exception, the application fails to start.
     * This is ideal for catching misconfiguration early.
     */
    @PostConstruct
    public void validateConfiguration() {
        log.info("Starting {} - validating configuration...",
            appProperties.getName());
 
        if (appProperties.getSecurity().getJwtSecret().length() < 32) {
            throw new IllegalStateException(
                "JWT secret must be at least 32 characters for security");
        }
 
        log.info("Configuration validation passed.");
    }
 
    /*
     * @PreDestroy: Called BEFORE the bean is removed from the context.
     * Use for: releasing resources, flushing caches, graceful shutdown.
     */
    @PreDestroy
    public void onShutdown() {
        log.info("Application shutting down gracefully...");
    }
}

// BAD - Field Injection
@Service
public class OrderService {
    @Autowired  // Hidden dependency, cannot be final, hard to test
    private OrderRepository orderRepository;
 
    @Autowired
    private ProductService productService;
}

// GOOD - Constructor Injection (manual)
@Service
public class OrderService {
    private final OrderRepository orderRepository;
    private final ProductService productService;
 
    // Dependencies are explicit, field is final (immutable), easy to test
    public OrderService(OrderRepository orderRepository,
                        ProductService productService) {
        this.orderRepository = orderRepository;
        this.productService = productService;
    }
}

// BEST - Constructor Injection with Lombok
@Service
@RequiredArgsConstructor  // Generates constructor for all final fields
@Slf4j                    // Generates: private static final Logger log = ...
public class OrderService {
 
    private final OrderRepository orderRepository;
    private final ProductService productService;
    private final UserService userService;
    private final AppProperties appProperties;
 
    // Clean, readable, all dependencies visible and final
}

# application.properties - repetitive
spring.jpa.hibernate.ddl-auto=validate
spring.jpa.show-sql=false
spring.datasource.url=jdbc:mysql://...
spring.datasource.username=user

# application.yml - clear hierarchy
spring:
  jpa:
    hibernate:
      ddl-auto: validate
    show-sql: false
  datasource:
    url: jdbc:mysql://...
    username: user

spring:
  datasource:
    password: ${DB_PASSWORD} # Injected at runtime
 
app:
  security:
    jwt-secret: ${JWT_SECRET}

spring:
  datasource:
    hikari:
      # Do not fail immediately on a brief RDS blip
      connection-timeout: 30000
      # Kick out connections that are no longer valid
      max-lifetime: 1800000 # Must be less than MySQL wait_timeout (28800 by default)
      # Prevent stale connections
      keepalive-time: 300000 # Send keepalive every 5 minutes

<dependency>
    <groupId>net.logstash.logback</groupId>
    <artifactId>logstash-logback-encoder</artifactId>
    <version>7.4</version>
</dependency>

spring:
  jpa:
    open-in-view: false # Disable OSIV - forces you to be explicit about what you fetch

# DANGEROUS - Hibernate will try to alter your production schema
spring:
  jpa:
    hibernate:
      ddl-auto: update  # NEVER do this in production
 
# SAFE
spring:
  jpa:
    hibernate:
      ddl-auto: validate  # Checks entities match schema. Use with Flyway.

// BAD - only com.company.ecommerce.core.* will be scanned
package com.company.ecommerce.core;
 
@SpringBootApplication
public class EcommerceApplication { }

// GOOD - all sub-packages will be scanned
package com.company.ecommerce;
 
@SpringBootApplication
public class EcommerceApplication { }

// BAD - @Configuration classes should configure beans, not do business logic
@Configuration
public class AppConfig {
    @Bean
    public OrderService orderService() {
        // Processing logic here is wrong
        OrderService service = new OrderService();
        service.processAllPendingOrders();  // WRONG
        return service;
    }
}

spring:
  flyway:
    locations: classpath:db/migration,classpath:db/migration/${spring.profiles.active}

spring:
  main:
    lazy-initialization: true # Beans initialized on first use, not at startup

@Component
public class DataInitializer implements ApplicationRunner {
 
    private final RoleRepository roleRepository;
 
    @Override
    public void run(ApplicationArguments args) {
        // This runs AFTER full application context is ready
        // Safe to access database here
        if (roleRepository.count() == 0) {
            roleRepository.save(new Role("ADMIN"));
            roleRepository.save(new Role("CUSTOMER"));
        }
    }
}