docsEstructura

Estructura del Proyecto

El proyecto sigue una arquitectura limpia y modular, organizando el código por funcionalidades (módulos) y capas.

Organización de Módulos

src/
├── auth/                  # Módulo de autenticación
│   ├── controllers/      # Controladores y DTOs
│   └── service/          # Servicios de autenticación y JWT
├── config/               # Configuración global
│   ├── exceptions/       # Manejo centralizado de errores
│   └── models/          # Modelos base (ej: AuditEntity)
├── privilege/           # Módulo de privilegios
│   └── repositories/    # Acceso a datos de privilegios
├── role/               # Módulo de roles
│   └── repositories/   # Acceso a datos de roles
└── user/               # Módulo de usuarios
    ├── controllers/    # API REST de usuarios
    ├── mappers/       # Convertidores de entidades
    ├── repositories/  # Acceso a datos
    └── services/      # Lógica de negocio

Módulos Principales

1. Autenticación (auth/)

  • controllers/: Endpoints de autenticación
    • AuthController: Login, registro y refresh token
    • dtos/: Objetos de transferencia para auth
  • service/: Lógica de autenticación
    • JwtTokenService: Generación y validación de tokens
    • CustomUserDetailsService: Implementación de UserDetailsService

2. Configuración (config/)

  • exceptions/: Sistema de manejo de errores
    • GlobalExceptionHandler: Manejo centralizado de excepciones
    • ErrorResponse: Formato estándar de errores
  • SecurityConfig: Configuración de Spring Security
  • SwaggerConfig: Configuración de OpenAPI
  • JpaConfig: Configuración de JPA y auditoría

3. Privilegios (privilege/)

  • repositories/:
    • Privilege: Entidad de privilegios
    • PrivilegeRepository: Acceso a datos

4. Roles (role/)

  • repositories/:
    • Role: Entidad de roles
    • RoleRepository: Acceso a datos

5. Usuarios (user/)

  • controllers/: API REST
    • UserController: Endpoints de usuario
    • dtos/: DTOs para requests/responses
  • services/: Lógica de negocio
    • UserService: Interface del servicio
    • DefaultUserService: Implementación
  • repositories/: Acceso a datos
    • User: Entidad principal
    • UserRepository: Operaciones de BD
  • mappers/:
    • UserMapper: Conversión entre Entity y DTO

Patrones de Diseño

Capa de Presentación (Controllers)

@RestController
@RequestMapping("/v1/users")
public class UserController {
    private final UserService userService;
    // Endpoints REST
}

Capa de Servicio

public interface UserService {
    UserDTO getCurrentUser();
    UserDTO updateUser(UserUpdateDTO updateDTO);
}

Capa de Repositorio

@Repository
public interface UserRepository extends JpaRepository<User, Long> {
    Optional<User> findByEmail(String email);
}

Mejores Prácticas

  1. Separación de Responsabilidades:

    • Controllers: Solo manejo de HTTP y validación
    • Services: Lógica de negocio
    • Repositories: Acceso a datos

  2. DTOs:

    • Request/Response separados
    • Validación en DTOs
    • Mappers dedicados

  3. Interfaces:

    • Servicios definidos por interfaces
    • Implementaciones intercambiables
    • Facilita testing

  4. Nomenclatura:

    • Controllers: Sufijo Controller
    • Services: Sufijo Service
    • Repositories: Sufijo Repository
    • DTOs: Sufijos Request/Response

  5. Paquetes:

    • Organización por función
    • Subpaquetes por capa
    • Modelos próximos a su uso
API ReferenceSwagger