Saltar al contenido principal

Capítulo 1: Inicio con GitHub Codespaces

Objetivos​

  • Configurar un entorno de desarrollo en la nube con GitHub Codespaces
  • Lanzar el proyecto e-contact-backend
  • Comprender la estructura del proyecto
  • Realizar las primeras pruebas de la API

🌐 ¿Qué es GitHub Codespaces?​

GitHub Codespaces es un entorno de desarrollo en la nube que permite:

  • Desarrollar directamente desde el navegador
  • Tener un entorno preconfigurado
  • Evitar problemas de instalación local
  • Colaborar fácilmente
Ventaja Principal

¡No necesita instalar Java, Maven, PostgreSQL ni ninguna otra herramienta en su máquina!

Requisitos previos​

  • Cuenta de GitHub (gratuita)
  • Navegador web moderno

Pasos de Configuración​

Paso 1: Acceder al Repositorio​

  1. Abrir el repositorio principal:
Repositorio

URL: https://github.com/hrhouma1/inskillflow-docs-formation-spring-boot-projet-e-contact-backend

Paso 2: Crear un Codespace​

  1. Hacer clic en el botón verde Code
  2. Seleccionar la pestaña Codespaces
  3. Hacer clic en Create codespace on main
┌─────────────────────────────────────────┐
│  Code ▼                                 │
├─────────────────────────────────────────┤
│  Local    │  Codespaces               │
│           │                            │
│           │  ┌──────────────────────┐  │
│           │  │ + Create codespace   │  │
│           │  │   on main            │  │
│           │  └──────────────────────┘  │
└─────────────────────────────────────────┘

Paso 3: Esperar la Inicialización​

El Codespace va a:

  1. Crear una máquina virtual
  2. Clonar el repositorio
  3. Instalar las dependencias
  4. Abrir VS Code en el navegador

⏱️ Tiempo estimado: 2-3 minutos

Paso 4: Verificar el Entorno​

Una vez que el Codespace esté listo, abra la terminal y verifique:

# Verificar Java
java -version
# Esperado: openjdk 17.x.x o superior

# Verificar Maven
./mvnw -version
# Esperado: Apache Maven 3.x.x

🏃 Lanzar la Aplicación​

Comando de Inicio​

En la terminal del Codespace:

./mvnw spring-boot:run

Salida Esperada​

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/
 :: Spring Boot ::                (v3.2.x)

...
Started EContactApplication in X.XXX seconds

Acceder a la Aplicación​

Cuando la aplicación se inicia, Codespaces muestra una notificación:

┌──────────────────────────────────────────────────┐
│  Your application running on port 8080 is       │
│  available.                                      │
│                                                  │
│  [Open in Browser]  [Make Public]               │
└──────────────────────────────────────────────────┘

Haga clic en Open in Browser para acceder a la API.

🔍 Explorar la Estructura del Proyecto​

inskillflow-docs-formation-spring-boot-projet-e-contact-backend/
│
├── 📁 src/main/java/com/example/econtact/
│   │
│   ├── 📄 EContactApplication.java      # Punto de entrada
│   │
│   ├── 📁 config/
│   │   ├── SecurityConfig.java          # Configuración de seguridad
│   │   └── CorsConfig.java              # Configuración CORS
│   │
│   ├── 📁 controller/
│   │   ├── ContactController.java       # Endpoint público /api/contact
│   │   ├── AuthController.java          # Endpoints de autenticación
│   │   └── AdminController.java         # Endpoints de administración protegidos
│   │
│   ├── 📁 model/
│   │   ├── Lead.java                    # Entidad Contacto/Lead
│   │   ├── User.java                    # Entidad Usuario
│   │   └── enums/                       # RequestType, LeadStatus, Role
│   │
│   ├── 📁 dto/
│   │   ├── ContactRequest.java          # DTO formulario de contacto
│   │   ├── LoginRequest.java            # DTO autenticación
│   │   └── LeadResponse.java            # DTO respuesta lead
│   │
│   ├── 📁 repository/
│   │   ├── LeadRepository.java
│   │   └── UserRepository.java
│   │
│   ├── 📁 service/
│   │   ├── LeadService.java
│   │   ├── UserService.java
│   │   └── EmailService.java
│   │
│   └── 📁 security/
│       ├── JwtService.java              # Generación/validación JWT
│       ├── JwtAuthenticationFilter.java # Filtro de autenticación
│       └── UserDetailsServiceImpl.java
│
├── 📁 src/main/resources/
│   └── application.yml                   # Configuración
│
├── 📁 frontend/                          # Frontend de prueba
│
├── 📁 troubleshooting/                   # Guías de resolución de problemas
│
└── 📁 cours/                             # Documentación y cursos

Primeras Pruebas de la API​

Prueba 1: Verificar que la API está accesible​

curl http://localhost:8080/api/health

Respuesta esperada:

{"status": "UP"}

Prueba 2: Enviar un Contacto (Endpoint Público)​

curl -X POST http://localhost:8080/api/contact \
  -H "Content-Type: application/json" \
  -d '{
    "fullName": "Jean Dupont",
    "email": "jean.dupont@example.com",
    "company": "Ma Société",
    "phone": "514-555-1234",
    "requestType": "INFO",
    "message": "Je voudrais plus d'\''informations sur vos services."
  }'

Respuesta esperada:

{
  "id": 1,
  "fullName": "Jean Dupont",
  "email": "jean.dupont@example.com",
  "status": "NEW",
  "createdAt": "2025-02-02T12:00:00"
}

Prueba 3: Acceder a un Endpoint Protegido (Sin Token)​

curl http://localhost:8080/api/admin/leads

Respuesta esperada:

{
  "status": 401,
  "error": "Unauthorized"
}

⚠️ Problemas Comunes​

Puerto 8080 ya en uso​

# Identificar el proceso
lsof -i :8080

# O usar otro puerto
./mvnw spring-boot:run -Dspring-boot.run.arguments="--server.port=8081"

Error de base de datos​

Verifique que la configuración H2 esté activa para desarrollo en application.yml.

Codespace se desconecta​

Los Codespaces gratuitos tienen un límite de tiempo. Reinicie si es necesario.

Recursos de Troubleshooting​

Para más detalles sobre los pasos y la resolución de problemas:

Guías Detalladas

📖 Carpeta de Troubleshooting Completa

Checklist de Validación​

Antes de pasar al siguiente capítulo, verifique que haya:

  • Creado un Codespace con éxito
  • Lanzado la aplicación Spring Boot
  • Probado el endpoint /api/contact
  • Comprendido la estructura del proyecto

⏭️ Siguiente Paso​

Capítulo 2: Troubleshooting →

Volver al índice del módulo