# Building Web Applications with Spring Boot: A Complete Guide Let me walk you through Spring Boot from the ground up — not just the "how" but the "why" behind each piece. --- ## Part 1: Understanding What Spring Boot Actually Is Before Spring Boot, building a Spring web app meant writing hundreds of lines of XML configuration: declaring your DispatcherServlet, view resolvers, data sources, transaction managers, and hunting down compatible library versions. Spring Boot solves this with three core ideas: **1. Auto-configuration** — Spring Boot inspects your classpath and configures beans automatically. If it sees `spring-webmvc` on the classpath, it sets up a DispatcherServlet, embedded Tomcat, and Jackson JSON converters. If it sees an H2 driver, it configures an in-memory DataSource. **2. Starter dependencies** — Curated dependency bundles. `spring-boot-starter-web` pulls in Spring MVC, Jackson, validation, and Tomcat — all version-compatible. **3. Embedded servers** — Your app is a plain Java application with `main()`. Tomcat runs *inside* your JAR, not the other way around. This is what makes Spring Boot container-friendly. --- ## Part 2: Prerequisites Install these: - **JDK 17 or 21** (both LTS; Spring Boot 3.x requires 17 minimum) - **Maven** or **Gradle** (I'll use Maven) - **IntelliJ IDEA** (Community is fine) or **VS Code** with the Spring Boot Extension Pack Verify: ```bash java -version mvn -version ``` --- ## Part 3: Generating the Project Go to **[start.spring.io](https://start.spring.io)** and configure: | Setting | Value | |---|---| | Project | Maven | | Language | Java | | Spring Boot | 3.3.x (latest stable) | | Group | `com.example` | | Artifact | `taskmanager` | | Packaging | Jar | | Java | 21 | **Dependencies to add:** - Spring Web - Spring Data JPA - H2 Database - Validation - Spring Boot DevTools - Lombok Or generate from the CLI: ```bash curl https://start.spring.io/starter.zip \ -d dependencies=web,data-jpa,h2,validation,devtools,lombok \ -d bootVersion=3.3.4 \ -d groupId=com.example \ -d artifactId=taskmanager \ -d javaVersion=21 \ -d type=maven-project \ -o taskmanager.zip unzip taskmanager.zip && cd taskmanager ``` --- ## Part 4: Understanding the Generated Structure ``` taskmanager/ ├── pom.xml ├── mvnw / mvnw.cmd ← Maven wrapper (no local Maven needed) └── src/ ├── main/ │ ├── java/com/example/taskmanager/ │ │ └── TaskmanagerApplication.java │ └── resources/ │ ├── application.properties │ ├── static/ ← CSS, JS, images served at / │ └── templates/ ← Thymeleaf/Freemarker templates └── test/ └── java/com/example/taskmanager/ └── TaskmanagerApplicationTests.java ``` ### The pom.xml explained ```xml org.springframework.boot spring-boot-starter-parent 3.3.4 ``` This parent POM is critical. It provides a **dependency management** section listing ~200 curated library versions. That's why you can write dependencies without `` tags — the parent decides. ```xml org.springframework.boot spring-boot-maven-plugin ``` This plugin repackages your JAR into an **executable fat JAR** with a custom classloader that can read nested JARs from `BOOT-INF/lib/`. ### The main class explained ```java package com.example.taskmanager; import org.springframework.boot.SpringApplication; import org.springframework.boot.autoconfigure.SpringBootApplication; @SpringBootApplication public class TaskmanagerApplication { public static void main(String[] args) { SpringApplication.run(TaskmanagerApplication.class, args); } } ``` `@SpringBootApplication` is a meta-annotation combining three: - **`@SpringBootConfiguration`** — marks this as a config class (a `@Configuration` variant) - **`@EnableAutoConfiguration`** — triggers the auto-config machinery - **`@ComponentScan`** — scans this package *and all sub-packages* for `@Component`, `@Service`, `@Repository`, `@Controller` > ⚠️ **Critical gotcha:** Component scanning starts from the main class's package. If you put classes in a *sibling* package (e.g., `com.other.stuff`), they won't be found. Always keep your code under the main class's package. **What `SpringApplication.run()` does:** 1. Creates an `ApplicationContext` (specifically `AnnotationConfigServletWebServerApplicationContext` for web apps) 2. Loads `Environment` (properties, profiles, env vars, CLI args) 3. Runs auto-configuration: reads `META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports` from every JAR, evaluates `@Conditional` annotations 4. Instantiates and wires all beans 5. Starts the embedded web server 6. Fires `ApplicationReadyEvent` --- ## Part 5: The Layered Architecture We'll build a Task Manager API using this flow: ``` HTTP Request ↓ [Controller] ← handles HTTP, validates input, returns DTOs ↓ [Service] ← business logic, transactions ↓ [Repository] ← data access ↓ [Database] ``` **Why separate these?** Each layer has one reason to change. You can swap the database without touching business rules. You can add a GraphQL controller reusing the same service. You can unit-test services with mocked repositories. Create these packages: ``` com.example.taskmanager ├── TaskmanagerApplication.java ├── config/ ├── controller/ ├── dto/ ├── entity/ ├── exception/ ├── repository/ └── service/ ``` --- ## Part 6: The Entity Layer ```java package com.example.taskmanager.entity; import jakarta.persistence.*; import lombok.*; import java.time.Instant; @Entity @Table(name = "tasks", indexes = { @Index(name = "idx_task_status", columnList = "status") }) @Getter @Setter @NoArgsConstructor @AllArgsConstructor @Builder public class Task { @Id @GeneratedValue(strategy = GenerationType.IDENTITY) private Long id; @Column(nullable = false, length = 200) private String title; @Column(length = 2000) private String description; @Enumerated(EnumType.STRING) @Column(nullable = false, length = 20) private TaskStatus status = TaskStatus.PENDING; @Column(nullable = false, updatable = false) private Instant createdAt; private Instant updatedAt; @PrePersist void onCreate() { this.createdAt = Instant.now(); this.updatedAt = this.createdAt; } @PreUpdate void onUpdate() { this.updatedAt = Instant.now(); } } ``` ```java package com.example.taskmanager.entity; public enum TaskStatus { PENDING, IN_PROGRESS, COMPLETED, CANCELLED } ``` **Key decisions explained:** - **`jakarta.persistence`** not `javax.persistence` — Spring Boot 3 moved to Jakarta EE 9+. This is the #1 migration pain point. - **`@Enumerated(EnumType.STRING)`** — Never use the default `ORDINAL`. It stores enums as integers based on declaration order. Reorder your enum and your data silently corrupts. - **`@GeneratedValue(IDENTITY)`** — Uses the DB's auto-increment. Note: this disables JDBC batch inserts. For high-volume writes, use `SEQUENCE`. - **`@PrePersist`/`@PreUpdate`** — JPA lifecycle callbacks for timestamps. Alternatively use Spring's `@CreatedDate`/`@LastModifiedDate` with `@EnableJpaAuditing`. - **No `@Data` from Lombok** — `@Data` generates `equals`/`hashCode` from all fields, which breaks with JPA lazy loading and mutable IDs. Use `@Getter`/`@Setter` explicitly. --- ## Part 7: The Repository Layer ```java package com.example.taskmanager.repository; import com.example.taskmanager.entity.Task; import com.example.taskmanager.entity.TaskStatus; import org.springframework.data.domain.Page; import org.springframework.data.domain.Pageable; import org.springframework.data.jpa.repository.JpaRepository; import org.springframework.data.jpa.repository.Query; import org.springframework.data.repository.query.Param; import java.util.List; public interface TaskRepository extends JpaRepository { // Derived query — Spring parses the method name into SQL List findByStatus(TaskStatus status); Page findByTitleContainingIgnoreCase(String keyword, Pageable pageable); boolean existsByTitleIgnoreCase(String title); long countByStatus(TaskStatus status); // Custom JPQL when derived queries get unwieldy @Query(""" SELECT t FROM Task t WHERE t.status = :status AND t.createdAt >= :since ORDER BY t.createdAt DESC """) List findRecentByStatus(@Param("status") TaskStatus status, @Param("since") java.time.Instant since); } ``` **What's happening here:** You write an *interface* — no implementation. At startup, Spring Data creates a proxy implementation. For derived queries, it parses the method name (`findBy` + `Status`) into a criteria query. `JpaRepository` already gives you `save`, `findById`, `findAll`, `deleteById`, `count`, plus pagination and sorting. --- ## Part 8: DTOs — Why You Need Them Never expose entities directly from your API. Reasons: - **Security** — Entity fields leak internal structure; a `User` entity might expose `passwordHash` - **Coupling** — Rename a DB column, break every API client - **Lazy loading** — Serializing a lazy proxy outside a transaction throws `LazyInitializationException` - **Validation** — Create and update payloads often have different rules ```java package com.example.taskmanager.dto; import com.example.taskmanager.entity.TaskStatus; import jakarta.validation.constraints.*; public record TaskCreateRequest( @NotBlank(message = "Title is required") @Size(max = 200, message = "Title must not exceed 200 characters") String title, @Size(max = 2000) String description, TaskStatus status ) {} ``` ```java package com.example.taskmanager.dto; import com.example.taskmanager.entity.TaskStatus; import jakarta.validation.constraints.Size; public record TaskUpdateRequest( @Size(max = 200) String title, @Size(max = 2000) String description, TaskStatus status ) {} ``` ```java package com.example.taskmanager.dto; import com.example.taskmanager.entity.Task; import com.example.taskmanager.entity.TaskStatus; import java.time.Instant; public record TaskResponse( Long id, String title, String description, TaskStatus status, Instant createdAt, Instant updatedAt ) { public static TaskResponse from(Task task) { return new TaskResponse( task.getId(), task.getTitle(), task.getDescription(), task.getStatus(), task.getCreatedAt(), task.getUpdatedAt() ); } } ``` Java `record`s are ideal for DTOs — immutable, concise, with automatic `equals`/`hashCode`/`toString`. Jackson supports them natively. --- ## Part 9: The Service Layer ```java package com.example.taskmanager.service; import com.example.taskmanager.dto.*; import com.example.taskmanager.entity.Task; import com.example.taskmanager.entity.TaskStatus; import com.example.taskmanager.exception.DuplicateResourceException; import com.example.taskmanager.exception.ResourceNotFoundException; import com.example.taskmanager.repository.TaskRepository; import lombok.RequiredArgsConstructor; import lombok.extern.slf4j.Slf4j; import org.springframework.data.domain.Page; import org.springframework.data.domain.Pageable; import org.springframework.stereotype.Service; import org.springframework.transaction.annotation.Transactional; @Service @RequiredArgsConstructor @Slf4j @Transactional(readOnly = true) public class TaskService { private final TaskRepository taskRepository; public Page findAll(Pageable pageable) { return taskRepository.findAll(pageable).map(TaskResponse::from); } public TaskResponse findById(Long id) { return taskRepository.findById(id) .map(TaskResponse::from) .orElseThrow(() -> new ResourceNotFoundException("Task", id)); } public Page search(String keyword, Pageable pageable) { return taskRepository .findByTitleContainingIgnoreCase(keyword, pageable) .map(TaskResponse::from); } @Transactional public TaskResponse create(TaskCreateRequest request) { if (taskRepository.existsByTitleIgnoreCase(request.title())) { throw new DuplicateResourceException( "A task with title '" + request.title() + "' already exists"); } Task task = Task.builder() .title(request.title()) .description(request.description()) .status(request.status() != null ? request.status() : TaskStatus.PENDING) .build(); Task saved = taskRepository.save(task); log.info("Created task id={} title={}", saved.getId(), saved.getTitle()); return TaskResponse.from(saved); } @Transactional public TaskResponse update(Long id, TaskUpdateRequest request) { Task task = taskRepository.findById(id) .orElseThrow(() -> new ResourceNotFoundException("Task", id)); if (request.title() != null) task.setTitle(request.title()); if (request.description() != null) task.setDescription(request.description()); if (request.status() != null) task.setStatus(request.status()); // No explicit save() needed — the entity is managed within the transaction, // and Hibernate flushes dirty state on commit. return TaskResponse.from(task); } @Transactional public void delete(Long id) { if (!taskRepository.existsById(id)) { throw new ResourceNotFoundException("Task", id); } taskRepository.deleteById(id); log.info("Deleted task id={}", id); } } ``` **Important concepts:** - **Constructor injection via `@RequiredArgsConstructor`** — Lombok generates a constructor for all `final` fields. Spring auto-injects (no `@Autowired` needed for a single constructor). Constructor injection makes dependencies explicit, enables immutability, and works in plain unit tests. - **`@Transactional(readOnly = true)` at class level, `@Transactional` on writes** — Read-only transactions let Hibernate skip dirty-checking and let the DB optimize. Method-level annotations override class-level. - **Dirty checking in `update()`** — Inside a transaction, entities fetched from the repository are *managed*. Mutating them auto-persists on commit. This surprises people coming from other ORMs. - **`@Transactional` is proxy-based** — It only works on calls from *outside* the bean. Calling `this.someTransactionalMethod()` bypasses the proxy entirely, so no transaction starts. Refactor to a separate bean if you need this. --- ## Part 10: Exception Handling ```java package com.example.taskmanager.exception; public class ResourceNotFoundException extends RuntimeException { public ResourceNotFoundException(String resource, Object id) { super("%s not found with id: %s".formatted(resource, id)); } public ResourceNotFoundException(String message) { super(message); } } ``` ```java package com.example.taskmanager.exception; public class DuplicateResourceException extends RuntimeException { public DuplicateResourceException(String message) { super(message); } } ``` Now the global handler — this is what separates a professional API from a hobby project: ```java package com.example.taskmanager.exception; import lombok.extern.slf4j.Slf4j; import org.springframework.http.HttpStatus; import org.springframework.http.ProblemDetail; import org.springframework.validation.FieldError; import org.springframework.web.bind.MethodArgumentNotValidException; import org.springframework.web.bind.annotation.ExceptionHandler; import org.springframework.web.bind.annotation.RestControllerAdvice; import java.time.Instant; import java.util.LinkedHashMap; import java.util.Map; @RestControllerAdvice @Slf4j public class GlobalExceptionHandler { @ExceptionHandler(ResourceNotFoundException.class) ProblemDetail handleNotFound(ResourceNotFoundException ex) { ProblemDetail pd = ProblemDetail.forStatusAndDetail( HttpStatus.NOT_FOUND, ex.getMessage()); pd.setTitle("Resource Not Found"); pd.setProperty("timestamp", Instant.now()); return pd; } @ExceptionHandler(DuplicateResourceException.class) ProblemDetail handleDuplicate(DuplicateResourceException ex) { ProblemDetail pd = ProblemDetail.forStatusAndDetail( HttpStatus.CONFLICT, ex.getMessage()); pd.setTitle("Duplicate Resource"); pd.setProperty("timestamp", Instant.now()); return pd; } @ExceptionHandler(MethodArgumentNotValidException.class) ProblemDetail handleValidation(MethodArgumentNotValidException ex) { Map errors = new LinkedHashMap<>(); for (FieldError fe : ex.getBindingResult().getFieldErrors()) { errors.put(fe.getField(), fe.getDefaultMessage()); } ProblemDetail pd = ProblemDetail.forStatusAndDetail( HttpStatus.BAD_REQUEST, "Request validation failed"); pd.setTitle("Validation Error"); pd.setProperty("errors", errors); pd.setProperty("timestamp", Instant.now()); return pd; } @ExceptionHandler(Exception.class) ProblemDetail handleUnexpected(Exception ex) { log.error("Unhandled exception", ex); // log the detail... ProblemDetail pd = ProblemDetail.forStatusAndDetail( HttpStatus.INTERNAL_SERVER_ERROR, "An unexpected error occurred"); // ...but don't leak it pd.setTitle("Internal Server Error"); pd.setProperty("timestamp", Instant.now()); return pd; } } ``` `ProblemDetail` implements **RFC 7807** (Problem Details for HTTP APIs), added in Spring 6. It gives you a standard error shape: ```json { "type": "about:blank", "title": "Validation Error", "status": 400, "detail": "Request validation failed", "errors": { "title": "Title is required" }, "timestamp": "2024-06-15T10:30:00Z" } ``` > 🔒 **Security note:** Never return raw stack traces or exception messages to clients. Log them server-side, return generic messages. Leaked messages reveal DB schema, file paths, and library versions. --- ## Part 11: The Controller Layer ```java package com.example.taskmanager.controller; import com.example.taskmanager.dto.*; import com.example.taskmanager.service.TaskService; import jakarta.validation.Valid; import lombok.RequiredArgsConstructor; import org.springframework.data.domain.Page; import org.springframework.data.domain.Pageable; import org.springframework.data.domain.Sort; import org.springframework.data.web.PageableDefault; import org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.*; import org.springframework.web.util.UriComponentsBuilder; import java.net.URI; @RestController @RequestMapping("/api/v1/tasks") @RequiredArgsConstructor public class TaskController { private final TaskService taskService; @GetMapping public Page list( @RequestParam(required = false) String q, @PageableDefault(size = 20, sort = "createdAt", direction = Sort.Direction.DESC) Pageable pageable) { return (q == null || q.isBlank()) ? taskService.findAll(pageable) : taskService.search(q, pageable); } @GetMapping("/{id}") public TaskResponse getOne(@PathVariable Long id) { return taskService.findById(id); } @PostMapping public ResponseEntity create( @Valid @RequestBody TaskCreateRequest request, UriComponentsBuilder uriBuilder) { TaskResponse created = taskService.create(request); URI location = uriBuilder.path("/api/v1/tasks/{id}") .buildAndExpand(created.id()) .toUri(); return ResponseEntity.created(location).body(created); } @PatchMapping("/{id}") public TaskResponse update(@PathVariable Long id, @Valid @RequestBody TaskUpdateRequest request) { return taskService.update(id, request); } @DeleteMapping("/{id}") public ResponseEntity delete(@PathVariable Long id) { taskService.delete(id); return ResponseEntity.noContent().build(); } } ``` **Annotation breakdown:** | Annotation | Purpose | |---|---| | `@RestController` | `@Controller` + `@ResponseBody` — every return value is serialized to the body | | `@RequestMapping` | Base path for all methods in the class | | `@GetMapping` etc. | Shortcuts for `@RequestMapping(method = GET)` | | `@PathVariable` | Binds `{id}` from the URL | | `@RequestParam` | Binds query string params (`?q=foo`) | | `@RequestBody` | Deserializes JSON body into an object | | `@Valid` | **Triggers** Bean Validation. Without it, your `@NotBlank` annotations do nothing. | **REST conventions worth following:** - `POST` returns `201 Created` + `Location` header - `PUT` = full replace, `PATCH` = partial update - `DELETE` returns `204 No Content` - Version your API in the path (`/api/v1/`) - Use plural nouns for collections - Paginate list endpoints — always --- ## Part 12: Configuration Replace `application.properties` with `application.yml` (nesting is much more readable): ```yaml spring: application: name: taskmanager datasource: url: jdbc:h2:mem:taskdb;DB_CLOSE_DELAY=-1 username: sa password: driver-class-name: org.h2.Driver h2: console: enabled: true path: /h2-console jpa: hibernate: ddl-auto: update open-in-view: false # important — see note below properties: hibernate: format_sql: true jdbc: batch_size: 25 jackson: default-property-inclusion: non_null serialization: write-dates-as-timestamps: false server: port: 8080 error: include-message: never include-stacktrace: never logging: level: root: INFO com.example.taskmanager: DEBUG org.hibernate.SQL: DEBUG management: endpoints: web: exposure: include: health,info,metrics endpoint: health: show-details: when-authorized ``` **Two settings that matter a lot:** **`spring.jpa.open-in-view: false`** — By default Spring keeps a Hibernate session open for the entire HTTP request. This masks `LazyInitializationException` but causes DB connections to be held too long and triggers hidden N+1 queries in your view layer. Always disable it and fetch data explicitly in your service layer. **`ddl-auto`** — Options: `none`, `validate`, `update`, `create`, `create-drop`. - Dev: `update` is convenient - **Production: `validate` or `none`.** Never `update` — it can't drop columns, won't handle renames, and gives you zero migration history. Use **Flyway** or **Liquibase** instead. ### Property resolution order Spring Boot resolves properties from many sources. Later wins: 1. `application.yml` in JAR 2. `application-{profile}.yml` 3. OS environment variables (`SERVER_PORT=9090`) 4. Java system properties (`-Dserver.port=9090`) 5. Command-line args (`--server.port=9090`) This is why the same JAR works across environments — you override via env vars. ### Profiles `application-dev.yml`: ```yaml spring: jpa: hibernate: ddl-auto: create-drop logging: level: org.hibernate.SQL: DEBUG ``` `application-prod.yml`: ```yaml spring: datasource: url: ${DB_URL} username: ${DB_USERNAME} password: ${DB_PASSWORD} jpa: hibernate: ddl-auto: validate logging: level: root: WARN ``` Activate: `java -jar app.jar --spring.profiles.active=prod` > 🔒 Never commit secrets to `application.yml`. Use environment variables, HashiCorp Vault, AWS Secrets Manager, or Kubernetes Secrets. ### Type-safe custom config ```java package com.example.taskmanager.config; import org.springframework.boot.context.properties.ConfigurationProperties; import org.springframework.validation.annotation.Validated; import jakarta.validation.constraints.*; @Validated @ConfigurationProperties(prefix = "app.task") public record TaskProperties( @Min(1) @Max(1000) int maxPerUser, @NotBlank String defaultAssignee ) {} ``` Register it on the main class: ```java @SpringBootApplication @ConfigurationPropertiesScan public class TaskmanagerApplication { ... } ``` ```yaml app: task: max-per-user: 50 default-assignee: unassigned ``` Now inject `TaskProperties` anywhere. Invalid values fail at *startup*, not at 3 AM in production. --- ## Part 13: Running the Application ```bash ./mvnw spring-boot:run ``` You'll see the banner and: ``` Tomcat started on port 8080 (http) with context path '/' Started TaskmanagerApplication in 2.145 seconds ``` Test it: ```bash # Create curl -X POST http://localhost:8080/api/v1/tasks \ -H "Content-Type: application/json" \ -d '{"title":"Learn Spring Boot","description":"From scratch","status":"IN_PROGRESS"}' # List curl "http://localhost:8080/api/v1/tasks?page=0&size=10" # Get one curl http://localhost:8080/api/v1/tasks/1 # Partial update curl -X PATCH http://localhost:8080/api/v1/tasks/1 \ -H "Content-Type: application/json" \ -d '{"status":"COMPLETED"}' # Delete curl -X DELETE http://localhost:8080/api/v1/tasks/1 # Trigger validation error curl -X POST http://localhost:8080/api/v1/tasks \ -H "Content-Type: application/json" -d '{"title":""}' ``` Visit `http://localhost:8080/h2-console` (JDBC URL: `jdbc:h2:mem:taskdb`) to browse the database. --- ## Part 14: Adding a Real Database H2 disappears on restart. For PostgreSQL: ```xml org.postgresql postgresql runtime org.flywaydb flyway-core org.flywaydb flyway-database-postgresql ``` `docker-compose.yml`: ```yaml services: postgres: image: postgres:16-alpine environment: POSTGRES_DB: taskdb POSTGRES_USER: taskuser POSTGRES_PASSWORD: taskpass ports: ["5432:5432"] volumes: [pgdata:/var/lib/postgresql/data] volumes: pgdata: ``` ```yaml spring: datasource: url: jdbc:postgresql://localhost:5432/taskdb username: taskuser password: taskpass hikari: maximum-pool-size: 10 minimum-idle: 2 connection-timeout: 30000 jpa: hibernate: ddl-auto: validate database-platform: org.hibernate.dialect.PostgreSQLDialect flyway: enabled: true locations: classpath:db/migration ``` `src/main/resources/db/migration/V1__create_tasks.sql`: ```sql CREATE TABLE tasks ( id BIGSERIAL PRIMARY KEY, title VARCHAR(200) NOT NULL, description VARCHAR(2000), status VARCHAR(20) NOT NULL DEFAULT 'PENDING', created_at TIMESTAMPTZ NOT NULL, updated_at TIMESTAMPTZ ); CREATE INDEX idx_task_status ON tasks(status); ``` Flyway runs migrations at startup, tracks them in a `flyway_schema_history` table, and refuses to start if a previously-applied migration file has changed. **Never edit an applied migration** — always add a new one. --- ## Part 15: Testing ### Unit test — service layer with mocks ```java package com.example.taskmanager.service; import com.example.taskmanager.dto.TaskCreateRequest; import com.example.taskmanager.entity.Task; import com.example.taskmanager.entity.TaskStatus; import com.example.taskmanager.exception.ResourceNotFoundException; import com.example.taskmanager.repository.TaskRepository; import org.junit.jupiter.api.Test; import org.junit.jupiter.api.extension.ExtendWith; import org.mockito.*; import org.mockito.junit.jupiter.MockitoExtension; import java.util.Optional; import static org.assertj.core.api.Assertions.*; import static org.mockito.ArgumentMatchers.any; import static org.mockito.Mockito.*; @ExtendWith(MockitoExtension.class) class TaskServiceTest { @Mock TaskRepository taskRepository; @InjectMocks TaskService taskService; @Test void create_persistsTask_andReturnsResponse() { var request = new TaskCreateRequest("Write tests", "unit", TaskStatus.PENDING); when(taskRepository.existsByTitleIgnoreCase("Write tests")).thenReturn(false); when(taskRepository.save(any(Task.class))).thenAnswer(inv -> { Task t = inv.getArgument(0); t.setId(1L); return t; }); var result = taskService.create(request); assertThat(result.id()).isEqualTo(1L); assertThat(result.title()).isEqualTo("Write tests"); verify(taskRepository).save(any(Task.class)); } @Test void findById_throwsWhenMissing() { when(taskRepository.findById(99L)).thenReturn(Optional.empty()); assertThatThrownBy(() -> taskService.findById(99L)) .isInstanceOf(ResourceNotFoundException.class) .hasMessageContaining("99"); } } ``` Fast (milliseconds) — no Spring context, no database. ### Web layer test — `@WebMvcTest` ```java package com.example.taskmanager.controller; import com.example.taskmanager.dto.TaskResponse; import com.example.taskmanager.entity.TaskStatus; import com.example.taskmanager.exception.ResourceNotFoundException; import com.example.taskmanager.service.TaskService; import org.junit.jupiter.api.Test; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.test.autoconfigure.web.servlet.WebMvcTest; import org.springframework.boot.test.mock.mockito.MockBean; import org.springframework.http.MediaType; import org.springframework.test.web.servlet.MockMvc; import java.time.Instant; import static org.mockito.ArgumentMatchers.*; import static org.mockito.Mockito.when; import static org.springframework.test.web.servlet.request.MockMvcRequestBuilders.*; import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.*; @WebMvcTest(TaskController.class) class TaskControllerTest { @Autowired MockMvc mockMvc; @MockBean TaskService taskService; @Test void getOne_returns200() throws Exception { when(taskService.findById(1L)).thenReturn(new TaskResponse( 1L, "Test", "desc", TaskStatus.PENDING, Instant.now(), Instant.now())); mockMvc.perform(get("/api/v1/tasks/1")) .andExpect(status().isOk()) .andExpect(jsonPath("$.id").value(1)) .andExpect(jsonPath("$.title").value("Test")); } @Test void getOne_returns404_whenMissing() throws Exception { when(taskService.findById(99L)) .thenThrow(new ResourceNotFoundException("Task", 99L)); mockMvc.perform(get("/api/v1/tasks/99")) .andExpect(status().isNotFound()) .andExpect(jsonPath("$.title").value("Resource Not Found")); } @Test void create_returns400_onInvalidPayload() throws Exception { mockMvc.perform(post("/api/v1/tasks") .contentType(MediaType.APPLICATION_JSON) .content(""" {"title": "", "description": "x"} """)) .andExpect(status().isBadRequest()) .andExpect(jsonPath("$.errors.title").exists()); } } ``` `@WebMvcTest` loads *only* the web layer — controllers, filters, exception handlers. No database, no services. You mock the service with `@MockBean`. ### Integration test with Testcontainers ```xml org.springframework.boot spring-boot-testcontainers test org.testcontainers postgresql test ``` ```java package com.example.taskmanager; import com.example.taskmanager.dto.TaskCreateRequest; import com.example.taskmanager.dto.TaskResponse; import com.example.taskmanager.entity.TaskStatus; import org.junit.jupiter.api.Test; import org.springframework.beans.factory.annotation.Autowired; import org.springframework.boot.test.context.SpringBootTest; import org.springframework.boot.test.web.client.TestRestTemplate; import org.springframework.boot.testcontainers.service.connection.ServiceConnection; import org.springframework.http.HttpStatus; import org.testcontainers.containers.PostgreSQLContainer; import org.testcontainers.junit.jupiter.Container; import org.testcontainers.junit.jupiter.Testcontainers; import static org.assertj.core.api.Assertions.assertThat; @SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT) @Testcontainers class TaskIntegrationTest { @Container @ServiceConnection static PostgreSQLContainer postgres = new PostgreSQLContainer<>("postgres:16-alpine"); @Autowired TestRestTemplate restTemplate; @Test void createAndFetchTask() { var request = new TaskCreateRequest("Integration", "full stack", TaskStatus.PENDING); var createResponse = restTemplate.postForEntity( "/api/v1/tasks", request, TaskResponse.class); assertThat(createResponse.getStatusCode()).isEqualTo(HttpStatus.CREATED); assertThat(createResponse.getHeaders().getLocation()).isNotNull(); Long id = createResponse.getBody().id(); var fetched = restTemplate.getForEntity( "/api/v1/tasks/" + id, TaskResponse.class); assertThat(fetched.getBody().title()).isEqualTo("Integration"); } } ``` `@ServiceConnection` (Spring Boot 3.1+) auto-wires the container's JDBC URL into your DataSource. No manual `@DynamicPropertySource` needed. You test against **real PostgreSQL**, catching dialect bugs H2 would hide. Run: `./mvnw test` --- ## Part 16: Adding Security ```xml org.springframework.boot spring-boot-starter-security ``` Adding this alone locks down everything with HTTP Basic and a generated password. Configure it properly: ```java package com.example.taskmanager.config; import org.springframework.context.annotation.*; import org.springframework.http.HttpMethod; import org.springframework.security.config.Customizer; import org.springframework.security.config.annotation.web.builders.HttpSecurity; import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity; import org.springframework.security.config.http.SessionCreationPolicy; import org.springframework.security.core.userdetails.*; import org.springframework.security.crypto.bcrypt.BCryptPasswordEncoder; import org.springframework.security.crypto.password.PasswordEncoder; import org.springframework.security.provisioning.InMemoryUserDetailsManager; import org.springframework.security.web.SecurityFilterChain; @Configuration @EnableWebSecurity public class SecurityConfig { @Bean SecurityFilterChain filterChain(HttpSecurity http) throws Exception { http .csrf(csrf -> csrf.disable()) // safe ONLY for stateless token APIs .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS)) .authorizeHttpRequests(auth -> auth .requestMatchers("/actuator/health", "/actuator/info").permitAll() .requestMatchers(HttpMethod.GET, "/api/v1/tasks/**").hasAnyRole("USER", "ADMIN") .requestMatchers("/api/v1/tasks/**").hasRole("ADMIN") .anyRequest().authenticated() ) .httpBasic(Customizer.withDefaults()); return http.build(); } @Bean PasswordEncoder passwordEncoder() { return new BCryptPasswordEncoder(); } @Bean UserDetailsService users(PasswordEncoder encoder) { // In-memory for demo only — use a DB-backed UserDetailsService in production return new InMemoryUserDetailsManager( User.withUsername("user").password(encoder.encode("password")) .roles("USER").build(), User.withUsername("admin").password(encoder.encode("admin")) .roles("ADMIN").build() ); } } ``` **Security essentials:** - **CSRF:** Disable only for stateless APIs using tokens (JWT/OAuth). If you use cookies or sessions, **keep CSRF enabled**. - **Password hashing:** Always BCrypt/Argon2. Never MD5, SHA-1, or plaintext. - **HTTPS:** Terminate TLS at the load balancer; set `server.forward-headers-strategy: framework`. - **Production auth:** Use JWT (`spring-boot-starter-oauth2-resource-server`) or an OIDC provider (Keycloak, Auth0, Cognito). Rolling your own auth is a common source of vulnerabilities. --- ## Part 17: API Documentation ```xml org.springdoc springdoc-openapi-starter-webmvc-ui 2.6.0 ``` That's it — visit `http://localhost:8080/swagger-ui.html`. Enhance with annotations: ```java @Operation(summary = "Create a new task", description = "Creates a task and returns it with a generated ID") @ApiResponses({ @ApiResponse(responseCode = "201", description = "Created"), @ApiResponse(responseCode = "400", description = "Validation failed"), @ApiResponse(responseCode = "409", description = "Duplicate title") }) @PostMapping public ResponseEntity create(...) { ... } ``` --- ## Part 18: Serving HTML (Thymeleaf) If you want server-rendered pages instead of (or alongside) an API: ```xml org.springframework.boot spring-boot-starter-thymeleaf ``` ```java @Controller // NOT @RestController @RequestMapping("/tasks") @RequiredArgsConstructor public class TaskWebController { private final TaskService taskService; @GetMapping public String list(Model model, @PageableDefault Pageable pageable) { model.addAttribute("tasks", taskService.findAll(pageable)); return "tasks/list"; // resolves to templates/tasks/list.html } } ``` `src/main/resources/templates/tasks/list.html`: ```html Tasks

Tasks

ID	Title	Status

``` Note: `@Controller` returns a **view name**; `@RestController` returns **data**. Static files go in `src/main/resources/static/` and are served from the root path. --- ## Part 19: Production Readiness ### Actuator ```xml org.springframework.boot spring-boot-starter-actuator ``` Key endpoints: - `/actuator/health` — liveness/readiness for Kubernetes - `/actuator/metrics` — JVM, HTTP, DB pool metrics - `/actuator/prometheus` — scrape target (add `micrometer-registry-prometheus`) - `/actuator/info` — build info > ⚠️ Never expose `/actuator/**` publicly. It leaks env vars, beans, and heap dumps. Restrict to an internal port (`management.server.port`) and/or require admin auth. ### Dockerfile (multi-stage) ```dockerfile FROM maven:3.9-eclipse-temurin-21 AS build WORKDIR /app COPY pom.xml . RUN mvn dependency:go-offline -B COPY src ./src RUN mvn clean package -DskipTests -B FROM eclipse-temurin:21-jre-alpine RUN addgroup -S spring && adduser -S spring -G spring USER spring:spring WORKDIR /app COPY --from=build /app/target/*.jar app.jar EXPOSE 8080 ENV JAVA_OPTS="-XX:MaxRAMPercentage=75.0" ENTRYPOINT ["sh","-c","java $JAVA_OPTS -jar app.jar"] ``` Or use Spring Boot's built-in buildpacks (no Dockerfile): ```bash ./mvnw spring-boot:build-image -Dspring-boot.build-image.imageName=taskmanager:1.0 ``` **Container tips:** - Copy `pom.xml` before `src` so dependency layers cache - Run as non-root - Use `MaxRAMPercentage` instead of fixed `-Xmx` so the JVM respects container limits - Add health checks: ```yaml management: endpoint: health: probes: enabled: true # adds /actuator/health/liveness and /readiness ``` ### Graceful shutdown ```yaml server: shutdown: graceful spring: lifecycle: timeout-per-shutdown-phase: 30s ``` In-flight requests complete before the JVM exits — essential for zero-downtime deploys. --- ## Part 20: Common Pitfalls & Best Practices ### The N+1 query problem This is *the* most common Spring Data JPA performance bug: ```java List orders = orderRepository.findAll(); // 1 query for (Order o : orders) { o.getCustomer().getName(); // N more queries! } ``` **Fixes:** ```java // Option 1: JOIN FETCH @Query("SELECT o FROM Order o JOIN FETCH o.customer") List findAllWithCustomer(); // Option 2: Entity graph @EntityGraph(attributePaths = {"customer", "items"}) List findAll(); // Option 3: Batch fetching (application.yml) // spring.jpa.properties.hibernate.default_batch_fetch_size: 25 ``` Detect it by enabling `logging.level.org.hibernate.SQL: DEBUG` and counting queries, or use the `datasource-proxy` library to assert query counts in tests. ### Other frequent mistakes | Mistake | Why it hurts | Fix | |---|---|---| | `ddl-auto: update` in prod | No migration history, can't rename/drop | Flyway/Liquibase + `validate` | | Field injection (`@Autowired` on fields) | Hides deps, breaks immutability, hard to test | Constructor injection | | Returning entities from controllers | Leaks schema, lazy-loading errors | DTOs | | Forgetting `@Valid` | Validation silently skipped | Add `@Valid` to `@RequestBody` params | | Catching `Exception` and returning 200 | Clients can't detect failures | `@RestControllerAdvice` + proper status codes | | Unpaginated `findAll()` | OOM when the table grows | Always accept `Pageable` | | `@Transactional` on private/self-called methods | Proxy is bypassed; no transaction | Public methods, cross-bean calls | | Business logic in controllers | Untestable, unreusable | Push to service layer | | Blocking calls with no timeout | Thread pool exhaustion, cascading failure | Set connect/read timeouts on all clients | | `EnumType.ORDINAL` | Reordering enum corrupts data | `EnumType.STRING` | ### Architecture checklist - ✅ Constructor injection everywhere - ✅ DTOs at API boundaries, entities stay internal - ✅ Business logic in services, not controllers or repositories - ✅ `@Transactional` at the service layer only - ✅ Global exception handling with RFC 7807 `ProblemDetail` - ✅ Validation on all inbound DTOs - ✅ Pagination on every list endpoint - ✅ Structured logging with correlation IDs - ✅ `open-in-view: false` - ✅ Externalized config, secrets from env/vault - ✅ Flyway migrations, never auto-DDL in prod - ✅ Tests: unit (fast) + web slice + integration with Testcontainers --- ## Part 21: Where to Go Next Once you're comfortable with the above: **Data & performance** - Caching with `@Cacheable` + Redis - Query optimization, projections, `@EntityGraph` - Read replicas, connection pool tuning **Distributed systems** - Async processing with `@Async` and `@Scheduled` - Messaging with Kafka or RabbitMQ - Resilience4j for circuit breakers, retries, rate limits - Spring Cloud Config, service discovery, API gateways **Reactive** - Spring WebFlux + R2DBC for high-concurrency I/O-bound workloads (note: it's a different programming model, not a drop-in upgrade) **Modern JVM** - Virtual threads: `spring.threads.virtual.enabled: true` (Java 21) — gets you much of WebFlux's scalability with blocking-style code - GraalVM native images for sub-100ms startup and low memory **Observability** - Micrometer + Prometheus + Grafana - Distributed tracing with OpenTelemetry - Structured JSON logs shipped to Loki/ELK --- ## Summary: The Mental Model ``` start.spring.io → generate project with starters ↓ @SpringBootApplication → component scan + auto-configuration ↓ Entity ← Repository ← Service ← Controller ← HTTP (JPA) (Spring Data) (@Transactional) (@RestController) ↓ DTOs cross the boundary ↓ @RestControllerAdvice catches all exceptions → ProblemDetail ↓ application.yml + profiles + env vars → externalized config ↓ Tests: @ExtendWith(Mockito) → @WebMvcTest → @SpringBootTest+Testcontainers ↓ Flyway migrations + Actuator + Docker → production ``` The single most important habit: **understand what auto-configuration is doing for you.** Run with `--debug` to see the auto-configuration report showing which configs matched and why. That report demystifies Spring Boot faster than anything else. Start with the CRUD API above, get it running, then add one production concern at a time — validation, then error handling, then tests, then security, then a real database, then Docker. Each layer builds understanding you'll carry into every future project.

Best developer based system