Spring Boot es una forma ordenada de crear aplicaciones Java que reciben pedidos, aplican reglas y responden.

Por ejemplo: una app que recibe un ticket de venta, valida el total, lo guarda en una base de datos y responde si el pago fue aceptado.

No necesitás entender todo Spring el primer día. Al principio alcanza con esta idea:

Valores sugeridos

• Project: Maven
• Language: Java
• Spring Boot: versión estable disponible
• Group: com.example
• Artifact: ticket-api
• Packaging: Jar
• Java: 21

Dependencias iniciales

# Dependencias para empezar
Spring Web
Validation
Spring Boot Actuator
H2 Database       # para aprender sin instalar DB
Spring Data JDBC  # opcional, se usa luego

Para el primer día, solo necesitás Spring Web. El resto entra cuando el concepto ya existe.

package com.example.ticketapi;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
public class HelloController {

    @GetMapping("/hello")
    public String hello() {
        return "Spring Boot funciona";
    }
}

Probar

$ mvn spring-boot:run
$ curl http://localhost:8080/hello

public record TicketResponse(
    Long id,
    String status,
    java.math.BigDecimal total
) {}

@GetMapping("/tickets/{id}")
public TicketResponse getTicket(@PathVariable Long id) {
    return new TicketResponse(id, "OPEN",
        new BigDecimal("123.45"));
}

Respuesta esperada

{
  "id": 1,
  "status": "OPEN",
  "total": 123.45
}

DTO significa Data Transfer Object. Es el objeto que cruza la frontera de la API. No expongas entidades internas sin pensar.

@Service
public class TicketService {
  private final TicketRepository repository;

  public TicketService(TicketRepository repository) {
    this.repository = repository;
  }

  public Ticket create(TicketRequest request) {
    if (request.total().signum() <= 0) {
      throw new IllegalArgumentException("total must be positive");
    }
    return repository.save(Ticket.open(request.total()));
  }
}

Qué mirar

• Constructor injection, no field injection.
• La regla de negocio está en el service.
• El controller no decide cómo crear un ticket.
• El repository no valida reglas de negocio.

@Repository
public class InMemoryTicketRepository
    implements TicketRepository {

  private final Map<Long, Ticket> data = new ConcurrentHashMap<>();
  private final AtomicLong ids = new AtomicLong();

  public Ticket save(Ticket ticket) {
    Long id = ids.incrementAndGet();
    Ticket saved = ticket.withId(id);
    data.put(id, saved);
    return saved;
  }
}

public record CreateTicketRequest(
  @NotNull
  @DecimalMin("0.01")
  BigDecimal total,

  @NotBlank
  String terminal
) {}

@PostMapping("/tickets")
public TicketResponse create(
    @Valid @RequestBody CreateTicketRequest request) {
  return service.create(request);
}

Principio

La API no puede confiar en el cliente. Cualquier campo puede venir vacío, negativo, mal formado o directamente ausente.

@RestControllerAdvice
public class ApiExceptionHandler {

  @ExceptionHandler(TicketNotFoundException.class)
  public ResponseEntity<ApiError> notFound(
      TicketNotFoundException ex) {
    return ResponseEntity.status(404)
        .body(new ApiError("TICKET_NOT_FOUND", ex.getMessage()));
  }
}

Status codes mínimos

@Test
void rejectsNegativeTotal() {
  TicketRepository repo = new InMemoryTicketRepository();
  TicketService service = new TicketService(repo);

  CreateTicketRequest req = new CreateTicketRequest(
      new BigDecimal("-1.00"), "POS-1");

  assertThatThrownBy(() -> service.create(req))
      .isInstanceOf(IllegalArgumentException.class);
}

Comandos mínimos

# Elegí una carpeta de trabajo
cd C:\Work

# Clonar el repo desde GitHub
git clone https://github.com/usuario/ticket-api-spring-boot.git

# Entrar al proyecto
cd ticket-api-spring-boot

# Verificar estado
git status

# Abrir en VS Code, si lo usás
code .

Qué deberías ver

• Una carpeta nueva con el nombre del repo.
• Una carpeta oculta .git: ahí vive el historial.
• git status debería decir que no hay cambios pendientes.
• El proyecto queda listo para abrir en IDE o para trabajar con Codex/Claude.

El circuito sano

• Editar: cambiar código o docs.
• Test: ejecutar mvn test.
• Diff: mirar qué cambió antes de guardar.
• Commit: guardar un checkpoint local.
• Push: subir ese checkpoint a GitHub.

Comandos

# 1. Ver archivos modificados
git status

# 2. Ver cambios concretos
git diff

# 3. Ejecutar tests
mvn test

# 4. Preparar archivos para commit
git add .

# 5. Crear checkpoint local
git commit -m "feat: agregar endpoint de tickets"

# 6. Subir a GitHub
git push origin main

Comandos

# Dentro de la carpeta del proyecto
git init

git add .

git commit -m "chore: proyecto inicial Spring Boot"

# Conectar con el repo vacío creado en GitHub
git remote add origin https://github.com/usuario/ticket-api-spring-boot.git

# Definir rama principal y subir
git branch -M main
git push -u origin main

Antes de subir, revisar

• Existe .gitignore.
• No se suben carpetas target/, .idea/, .vscode/ si no corresponde.
• No se suben claves, passwords, tokens ni archivos .env.
• El proyecto compila con mvn test.