Spring Boot Educational API Guide

This skill provides guidance for working with an educational Spring Boot 3.5.6 REST API project that demonstrates modern Java development practices including three-layer architecture, Bean Validation, transactional operations, and OpenAPI integration.

Project Overview

Educational Spring Boot REST API for user management with comprehensive JavaDoc documentation in Spanish. Uses Java 17 with Gradle build system and H2 in-memory database. Target audience is computer science students learning Spring Boot architecture and best practices.

Build & Run Commands

When executing build commands:

1. **Platform-Specific Commands**: On Windows, use `gradlew.bat` instead of `./gradlew`

2. **Common Operations**:

- Run application: `./gradlew bootRun`

- Run with dev profile: `./gradlew bootRun --args='--spring.profiles.active=dev'`

- Build project: `./gradlew build`

- Build executable JAR: `./gradlew bootJar`

- Run tests: `./gradlew test`

- Clean build: `./gradlew clean build`

- Generate JavaDoc: `./gradlew javadoc`

3. **JAR Execution**:

- Run: `java -jar build/libs/usuarios-api.jar`

- With dev profile: `java -jar build/libs/usuarios-api.jar --spring.profiles.active=dev`

Application runs on `http://localhost:8080`

Architecture Guidelines

When working with or modifying code:

Three-Layer Architecture

1. **Controller Layer** (`controller/`):

- REST endpoints at `/api/usuarios`

- Use `ResponseEntity<>` for explicit HTTP status control (201 CREATED, 200 OK, 204 NO CONTENT)

2. **Service Layer** (`service/`):

- Business logic with `@Transactional` on ALL write operations

- Validate entity existence before updates/deletes to prevent race conditions

- Methods: crearUsuario, actualizarUsuario, eliminarUsuario

3. **Repository Layer** (`repository/`):

- Data access using Spring Data JPA

- Extends JpaRepository for automatic CRUD operations

DTO Pattern

1. **UsuarioRequestDTO**:

- Input validation with Jakarta Bean Validation (@NotBlank, @Email, @Size)

- Used for both create and update operations

- Implemented as Java record for immutability

2. **UsuarioResponseDTO**:

- Output mapping, excludes sensitive fields (password)

- Static factory method `fromEntity()` converts entities to DTOs

- Separates internal entity representation from API contracts

Transaction Management & Race Condition Prevention

ALWAYS use `@Transactional` for write operations:

```java

@Transactional

public void eliminarUsuario(Long id) {

// CORRECT: Uses findById() + delete() with same entity instance

Usuario usuario = repository.findById(id)

.orElseThrow(() -> new IllegalArgumentException("No existe usuario"));

repository.delete(usuario);

}

// NEVER use this pattern (race condition):

// if (repository.existsById(id)) {

// repository.deleteById(id);

// }

```

Global Exception Handling

Use `@ControllerAdvice` pattern with standardized `ErrorDTO` responses:

Code Conventions

When writing or modifying code:

1. **Lombok Usage**:

- `@Data`: For entity getters/setters/toString/equals/hashCode

- `@Builder`: For fluent object construction

- `@RequiredArgsConstructor`: For constructor injection of `final` fields

- `@AllArgsConstructor / @NoArgsConstructor`: Required by JPA

2. **Java Records**:

- Use for immutable DTOs

- Automatic constructor/getters/equals/hashCode generation

3. **Streams & Functional Programming**:

- Use Streams API with method references

- Example: `.map(UsuarioResponseDTO::fromEntity)`

4. **JPA Entities**:

- Use @Entity, @Table, @Id annotations

- Explicit @Column constraints (nullable, length, unique)

- All fields `nullable=false`, email has `unique=true`

5. **Factory Method Pattern**:

- Static factory methods for Entity→DTO conversion

- Centralizes conversion logic

API Structure

Base path: `/api/usuarios`

Important URLs

- JDBC URL: `jdbc:h2:mem:usuariosdb`

- User: `sa`

- Password: (empty)

Database Configuration

H2 in-memory database:

CORS Configuration

CORS configured in `config/WebConfig.java`:

**Allowed Origins**:

**Configuration**: All methods (GET, POST, PUT, DELETE, OPTIONS), credentials enabled, 3600s preflight cache

⚠️ Update allowed origins in `WebConfig.java` before production deployment.

Security Considerations

⚠️ **Educational project only - NOT production-ready**

Current limitations:

For production, implement: BCrypt/Argon2 password encryption, JWT/OAuth2, HTTPS, restricted CORS, rate limiting, audit trails, persistent database.

Package Structure

```

org.jcr.usuariosenmemoria/

├── UsuariosEnMemoriaApplication.java # Main Spring Boot class

├── config/ # Configuration (OpenAPI, CORS)

├── controller/ # REST Controllers

├── service/ # Business Logic

├── repository/ # Data Access (JPA)

├── model/ # JPA Entities

├── dto/ # Data Transfer Objects

└── exception/ # Exception handling

```

Testing

Run tests:

```bash

./gradlew test

./gradlew test --info

./gradlew test --continuous

./gradlew test --tests "org.jcr.usuariosenmemoria.UsuariosEnMemoriaApplicationTests"

```

Current coverage: Basic application context load test (minimal - educational project).

Environment Variables

Override configuration:

Or use dev profile: `--spring.profiles.active=dev`

Documentation

Generate JavaDoc HTML documentation:

```bash

./gradlew javadoc

```

Output: `build/docs/javadoc/index.html`

All source files contain extensive educational JavaDoc in Spanish explaining architecture concepts, design patterns, Spring annotations, transaction management, and HTTP semantics.

Key Implementation Patterns

Data Flow

```

HTTP JSON Request

↓

UsuarioRequestDTO (validated with @Valid)

↓

Usuario entity (built with @Builder)

↓

Database persistence

↓

Usuario entity (fetched)

↓

UsuarioResponseDTO (password excluded)

↓

HTTP JSON Response

```

Security Decision

`UsuarioResponseDTO` intentionally excludes password field to prevent sensitive data exposure in API responses.