Este artículo detalla los pasos esenciales para establecer un proyecto básico con MyBatis, desde la configuración del entorno hasta la ejecución de la primera consulta. Se cubrirán la preparación de la base de datos, la gestión de dependencias con Maven, la configuración del archivo principal de MyBatis, la creación de componentes clave (POJO, interfaz DAO, mapper XML) y la verificación mediante una prueba unitaria.

1. Configuración del Entorno

1.1. Preparación de la Base de Datos

Iniciamos con la creación de una base de datos y una tabla de ejemplo para nuestros datos de usuario. Utilizaremos MySQL.

CREATE DATABASE IF NOT EXISTS `mi_aplicacion_db`;
USE `mi_aplicacion_db`;

CREATE TABLE IF NOT EXISTS `tbl_usuarios` (
  `id_usuario` INT(11) NOT NULL PRIMARY KEY AUTO_INCREMENT,
  `nombre_completo` VARCHAR(50) DEFAULT NULL,
  `hash_contrasena` VARCHAR(60) DEFAULT NULL
) ENGINE=INNODB DEFAULT CHARSET=utf8mb4;

INSERT INTO `tbl_usuarios`(`id_usuario`, `nombre_completo`, `hash_contrasena`) VALUES
(1, 'Andrea García', 'claveSecreta1'),
(2, 'Juan Pérez', 'claveSecreta2'),
(3, 'María López', 'claveSecreta3');

1.2. Configuración del Proyecto Maven

Crearemos un proyecto Maven estándar y configuraremos sus dependencias y la gestión de recursos.

1.2.1. Creación del Proyecto y Estructura

Cree un nuevo proyecto Maven y, si lo desea, puede eliminar la carpeta src inicial para reconstruir la estructura manualmente o mantenerla y añadir sus paquetes.

1.2.2. Inclusión de Dependencias

Añada las siguientes dependencias a su archivo pom.xml. Es crucial incluir el conector JDBC de MySQL, la librería de MyBatis y JUnit para las pruebas.

<dependencies>
    <!-- Conector JDBC para MySQL -->
    <dependency>
        <groupId>mysql</groupId>
        <artifactId>mysql-connector-java</artifactId>
        <version>8.0.28</version>
    </dependency>

    <!-- Core de MyBatis -->
    <dependency>
        <groupId>org.mybatis</groupId>
        <artifactId>mybatis</artifactId>
        <version>3.5.9</version>
    </dependency>

    <!-- Framework de pruebas JUnit -->
    <dependency>
        <groupId>junit</groupId>
        <artifactId>junit</artifactId>
        <version>4.13.2</version>
        <scope>test</scope>
    </dependency>
</dependencies>

1.2.3. Configuración de Recursos Maven

Para asegurar que los archivos de configuración y los mappers XML de MyBatis sean correctamente incluidos en el classpath durante la compilación, es necesario añadir la siguiente configuración en la sección <build> de su pom.xml.

<build>
    <resources>
        <resource>
            <directory>src/main/resources</directory>
            <includes>
                <include>**/*.properties</include>
                <include>**/*.xml</include>
            </includes>
            <filtering>false</filtering>
        </resource>
        <resource>
            <directory>src/main/java</directory>
            <includes>
                <include>**/*.properties</include>
                <include>**/*.xml</include>
            </includes>
            <filtering>false</filtering>
        </resource>
    </resources>
</build>

2. Implementación de Componentes MyBatis

2.1. Archivo de Configuración Principal de MyBatis

Cree el archivo configuracion-mybatis.xml en la carpeta src/main/resources. Este archivo contendrá la información de conexión a la base de datos y la configuración del entorno.

<?xml version="1.0" encoding="UTF-8" ?>

<configuration>
    <environments default="desarrollo">
        <environment id="desarrollo">
            <transactionManager type="JDBC"/>
            <dataSource type="POOLED">
                <property name="driver" value="com.mysql.cj.jdbc.Driver"/>
                <!-- Si encuentra problemas de conexión (por ejemplo, con SSL o timezone), pruebe a configurar useSSL=false y serverTimezone -->
                <property name="url" value="jdbc:mysql://localhost:3306/mi_aplicacion_db?useSSL=false&useUnicode=true&characterEncoding=UTF-8&serverTimezone=UTC"/>
                <property name="username" value="root"/>
                <property name="password" value="su_contraseña_db"/>
            </dataSource>
        </environment>
    </environments>
    
    <!-- IMPORTANTE: Registre aquí sus archivos mapper XML -->
    <mappers>
        <mapper resource="mappers/UsuarioMapper.xml"/>
    </mappers>
</configuration>

Nota importante sobre la conexión: Si experimenta un error de conexión (por ejemplo, "Communications link failure" o problemas con SSL), a menudo se resuelve añadiendo useSSL=false y serverTimezone=UTC a la URL de conexión de MySQL.

2.2. Clase de Utilidad para SqlSession

Cree la clase SqlSessionManager en el paquete com.ejemplo.mybatis.util. Esta clase se encargará de inicializar la SqlSessionFactory y proporcionar instancias de SqlSession, que son la interfaz principal para interactuar con la base de datos en MyBatis.

package com.ejemplo.mybatis.util;

import org.apache.ibatis.io.Resources;
import org.apache.ibatis.session.SqlSession;
import org.apache.ibatis.session.SqlSessionFactory;
import org.apache.ibatis.session.SqlSessionFactoryBuilder;

import java.io.IOException;
import java.io.InputStream;

public class SqlSessionManager {
    private static SqlSessionFactory fabricaSesiones;

    static {
        try {
            String archivoConfiguracion = "configuracion-mybatis.xml";
            InputStream flujoEntrada = Resources.getResourceAsStream(archivoConfiguracion);
            fabricaSesiones = new SqlSessionFactoryBuilder().build(flujoEntrada);
        } catch (IOException e) {
            System.err.println("Error al inicializar SqlSessionFactory: " + e.getMessage());
            throw new RuntimeException("Fallo al construir la SqlSessionFactory.", e);
        }
    }

    /**
     * Obtiene una nueva instancia de SqlSession.
     * Es responsabilidad del llamador cerrar la sesión cuando ya no sea necesaria.
     * @return Una nueva SqlSession.
     */
    public static SqlSession obtenerSesionSql() {
        return fabricaSesiones.openSession();
    }
}

2.3. Modelo de Datos (POJO)

Defina la clase POJO Usuario en el paquete com.ejemplo.mybatis.modelo. Sus propiedades deben coincidir con los nombres de las cloumnas de la tabla (o puede usar alias en el mapper XML).

package com.ejemplo.mybatis.modelo;

public class Usuario {
    private int idUsuario;
    private String nombreCompleto;
    private String hashContrasena;

    // Constructor vacío es necesario para MyBatis
    public Usuario() {
    }

    public Usuario(int idUsuario, String nombreCompleto, String hashContrasena) {
        this.idUsuario = idUsuario;
        this.nombreCompleto = nombreCompleto;
        this.hashContrasena = hashContrasena;
    }

    // Getters y Setters
    public int getIdUsuario() {
        return idUsuario;
    }

    public void setIdUsuario(int idUsuario) {
        this.idUsuario = idUsuario;
    }

    public String getNombreCompleto() {
        return nombreCompleto;
    }

    public void setNombreCompleto(String nombreCompleto) {
        this.nombreCompleto = nombreCompleto;
    }

    public String getHashContrasena() {
        return hashContrasena;
    }

    public void setHashContrasena(String hashContrasena) {
        this.hashContrasena = hashContrasena;
    }

    @Override
    public String toString() {
        return "Usuario{" +
                "idUsuario=" + idUsuario +
                ", nombreCompleto='" + nombreCompleto + '\'' +
                ", hashContrasena='" + hashContrasena + '\'' +
                '}';
    }
}

2.4. Interfaz DAO (Repositorio)

Cree la interfaz RepositorioUsuarios en el paquete com.ejemplo.mybatis.dao. Esta interfaz declarará los métodos para las operaciones de base de datos que MyBatis implementará.

package com.ejemplo.mybatis.dao;

import com.ejemplo.mybatis.modelo.Usuario;
import java.util.List;

public interface RepositorioUsuarios {
    /**
     * Recupera una lista de todos los usuarios de la base de datos.
     * @return Una lista de objetos Usuario.
     */
    List<Usuario> obtenerTodosLosUsuarios();
}

2.5. Mapper XML para Operaciones SQL

Cree el archivo UsuarioMapper.xml dentro de una nueva carpeta mappers en src/main/resources (ej. src/main/resources/mappers/UsuarioMapper.xml). Este archivo contiene las consultas SQL y su mapeo a los métodos de la interfaz DAO.

<?xml version="1.0" encoding="UTF-8" ?>

<mapper namespace="com.ejemplo.mybatis.dao.RepositorioUsuarios">
    <!-- Define la consulta para obtener todos los usuarios -->
    <!-- El 'id' debe coincidir con el nombre del método en la interfaz RepositorioUsuarios -->
    <select id="obtenerTodosLosUsuarios" resultType="com.ejemplo.mybatis.modelo.Usuario">
        SELECT
            id_usuario AS idUsuario,
            nombre_completo AS nombreCompleto,
            hash_contrasena AS hashContrasena
        FROM tbl_usuarios
    </select>
</mapper>

Alias en la consulta: Es importante usar alias (AS) en la consulta SQL cuando los nombres de las columnas de la base de datos difieren de los nombres de las propiedades del POJO (ej. id_usuario AS idUsuario).

3. Realización de Pruebas

3.1. Clase de Prueba

Cree la clase PruebaOperacionesUsuario en el paquete com.ejemplo.mybatis.test para verificar el funcionamiento de MyBatis. Utilizaremos JUnit para ejecutar la prueba.

package com.ejemplo.mybatis.test;

import com.ejemplo.mybatis.dao.RepositorioUsuarios;
import com.ejemplo.mybatis.modelo.Usuario;
import com.ejemplo.mybatis.util.SqlSessionManager;
import org.apache.ibatis.session.SqlSession;
import org.junit.Test;

import java.util.List;

import static org.junit.Assert.assertNotNull;
import static org.junit.Assert.assertFalse;
import static org.junit.Assert.fail;

public class PruebaOperacionesUsuario {

    @Test
    public void probarListadoDeUsuarios() {
        SqlSession sesion = null;
        try {
            // 1. Obtener una sesión SQL a través de nuestro gestor
            sesion = SqlSessionManager.obtenerSesionSql();

            // 2. Obtener la implementación del mapper/repositorio a partir de la sesión
            RepositorioUsuarios repositorio = sesion.getMapper(RepositorioUsuarios.class);

            // 3. Ejecutar la operación para obtener la lista de usuarios
            List<Usuario> listaDeUsuarios = repositorio.obtenerTodosLosUsuarios();

            // 4. Realizar aserciones para verificar los resultados
            assertNotNull("La lista de usuarios no debería ser nula.", listaDeUsuarios);
            assertFalse("La lista de usuarios no debería estar vacía.", listaDeUsuarios.isEmpty());

            // 5. Imprimir los resultados en consola
            System.out.println("--- Lista de Usuarios Recuperados ---");
            for (Usuario user : listaDeUsuarios) {
                System.out.println(user);
            }
            System.out.println("-------------------------------------");

        } catch (Exception e) {
            System.err.println("Ocurrió un error durante la prueba de usuarios: " + e.getMessage());
            e.printStackTrace();
            fail("La prueba falló debido a una excepción: " + e.getMessage());
        } finally {
            // 6. Asegurarse de cerrar la sesión SQL para liberar recursos
            if (sesion != null) {
                sesion.close();
            }
        }
    }
}

4. Solución de Problemas Comunes

4.1. Error: org.apache.ibatis.binding.BindingException: Type interface com.ejemplo.mybatis.dao.RepositorioUsuarios is not known to the MapperRegistry.

Este error indica que MyBatis no ha podido encontrar o registrar la interfaz de su DAO (Mapper). La causa más común es olvidar registrar el archivo XML del mapper en el archivo de configuración principal de MyBatis (configuracion-mybatis.xml).

Solución: Asegúrese de que el tag <mapper resource="..."/> esté presente en la sección <mappers> de configuracion-mybatis.xml, apuntando correctamente a su archivo UsuarioMapper.xml. Por ejemplo:

<mappers>
    <mapper resource="mappers/UsuarioMapper.xml"/>
</mappers>

4.2. Problemas con Archivos de Recursos no Encontrados (XML/Properties)

Si sus archivos XML de configuración o los mappers no son encontrados por MyBatis, especialmente cuando están en carpetas de origen (como src/main/java) o src/main/resources, es probable que Maven los esté ignorando.

Solución: Verifique la configuración de recursos en su pom.xml, como se detalla en la sección 1.2.3. Configuración de Recursos Maven. Esta configuración le indica a Maven que incluya archivos .properties y .xml de las carpetas especificadas durante el proceso de construcción.