Preparação do Ambiente de Desenvolvimento

Para iniciar o desenvolvimento, é recomendável utilizar uma versão estável do IntelliJ IDEA (como a 2022.x ou superior) para evitar problemas de compatibilidade com plugins e frameworks. Além disso, configure o Apache Maven (versão 3.6.x ou superior) e defina um espelho (mirror) para acelerar o download das dependências.

No arquivo settings.xml do Maven, adicione a configuração do repositório espelho:

<mirrors>
    <mirror>
        <id>aliyun-maven</id>
        <mirrorOf>central</mirrorOf>
        <name>Aliyun Nexus Mirror</name>
        <url>https://maven.aliyun.com/repository/public</url>
    </mirror>
</mirrors>

Criação e Configuração do Projeto Spring Boot

Gere um novo projeto Spring Boot utilizando o Spring Initializr. Selecione o JDK 8 (ou 11/17, ajustando as versões do Spring Boot de acordo) e adicione as dependências iniciais: Spring Web, Lombok e Spring Boot DevTools.

Ajuste o arquivo pom.xml para incluir o MyBatis-Flex, o driver do MySQL e um pool de conexões como o Druid ou HikariCP:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" 
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>
    
    <groupId>br.com.exemplo</groupId>
    <artifactId>mybatis-flex-demo</artifactId>
    <version>1.0.0</version>
    <name>MyBatis Flex Integration</name>
    
    <properties>
        <java.version>1.8</java.version>
        <spring-boot.version>2.7.18</spring-boot.version>
        <mybatis-flex.version>1.8.8</mybatis-flex.version>
    </properties>
    
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-dependencies</artifactId>
                <version>${spring-boot.version}</version>
                <type>pom</type>
                <scope>import</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        
        <!-- MyBatis-Flex Core -->
        <dependency>
            <groupId>com.mybatis-flex</groupId>
            <artifactId>mybatis-flex-spring-boot-starter</artifactId>
            <version>${mybatis-flex.version}</version>
        </dependency>
        <dependency>
            <groupId>com.mybatis-flex</groupId>
            <artifactId>mybatis-flex-processor</artifactId>
            <version>${mybatis-flex.version}</version>
            <scope>provided</scope>
        </dependency>

        <!-- Database & Pool -->
        <dependency>
            <groupId>mysql</groupId>
            <artifactId>mysql-connector-java</artifactId>
            <scope>runtime</scope>
        </dependency>
        <dependency>
            <groupId>com.alibaba</groupId>
            <artifactId>druid-spring-boot-starter</artifactId>
            <version>1.2.20</version>
        </dependency>

        <!-- Utilities -->
        <dependency>
            <groupId>org.projectlombok</groupId>
            <artifactId>lombok</artifactId>
            <optional>true</optional>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
                <version>${spring-boot.version}</version>
            </plugin>
        </plugins>
    </build>
</project>

Validação da Aplicação

Antes de conectar ao banco de dados, crie um controlador simples para garantir que o servidor web está operando corretamente.

package br.com.exemplo.controller;

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

import java.util.Collections;
import java.util.Map;

@RestController
public class StatusController {

    @GetMapping("/api/status")
    public Map<String, String> checkHealth() {
        return Collections.singletonMap("status", "Aplicação operando normalmente");
    }
}

Execute a classe principle da aplicação e acesse http://localhost:8080/api/status no navegador para confirmar a resposta JSON.

Integração com o Banco de Dados via MyBatis-Flex

Crie uma tabela no seu banco de dados MySQL para armazenar os registros. Neste exemplo, utilizaremoss a tabela customers:

CREATE TABLE customers (
    id BIGINT AUTO_INCREMENT PRIMARY KEY,
    full_name VARCHAR(100) NOT NULL,
    years_old INT,
    date_of_birth DATE
);

Configure as credenciais e a URL do banco de dados no arquivo application.properties:

server.port=8080

spring.datasource.url=jdbc:mysql://localhost:3306/seu_banco_de_dados?useSSL=false&serverTimezone=UTC
spring.datasource.username=root
spring.datasource.password=sua_senha_secreta
spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

Definição da Entidade e do Mapper

Crie a classe de entidade mapeando os campos da tabela. O MyBatis-Flex utilizará anotações para entender a estrutura.

package br.com.exemplo.entity;

import com.mybatisflex.annotation.Id;
import com.mybatisflex.annotation.KeyType;
import com.mybatisflex.annotation.Table;
import lombok.Data;
import java.time.LocalDate;

@Data
@Table("customers")
public class Customer {
    
    @Id(keyType = KeyType.Auto)
    private Long id;
    
    private String fullName;
    private Integer yearsOld;
    private LocalDate dateOfBirth;
}

Em seguida, defina a interface do repositório estendendo o BaseMapper do MyBatis-Flex:

package br.com.exemplo.mapper;

import br.com.exemplo.entity.Customer;
import com.mybatisflex.core.BaseMapper;
import org.apache.ibatis.annotations.Mapper;

@Mapper
public interface CustomerMapper extends BaseMapper<Customer> {
}

Execução de Consultas e Testes

Para validar a extração de dados, crie uma classe de teste que utilize o QueryWrapper para filtrar registros específicos, como clientes com idade igual a 21 anos.

package br.com.exemplo;

import br.com.exemplo.entity.Customer;
import br.com.exemplo.mapper.CustomerMapper;
import com.mybatisflex.core.query.QueryWrapper;
import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.SpringBootTest;

import javax.annotation.Resource;
import java.util.List;

import static br.com.exemplo.entity.table.CustomerTableDef.CUSTOMER;

@SpringBootTest
class CustomerRepositoryTests {

    @Resource
    private CustomerMapper customerMapper;

    @Test
    void fetchCustomersByAge() {
        QueryWrapper query = QueryWrapper.create()
                .select(CUSTOMER.ID, CUSTOMER.FULL_NAME, CUSTOMER.YEARS_OLD)
                .where(CUSTOMER.YEARS_OLD.eq(21))
                .orderBy(CUSTOMER.FULL_NAME.asc());
                
        List<Customer> youngCustomers = customerMapper.selectListByQuery(query);
        
        youngCustomers.forEach(customer -> 
            System.out.println("Cliente encontrado: " + customer.getFullName())
        );
    }

    @Test
    void fetchAllCustomers() {
        List<Customer> allCustomers = customerMapper.selectAll();
        System.out.println("Total de registros: " + allCustomers.size());
    }
}

Resolução de Problemas Comuns

Durante a configuração do MyBatis-Flex com Spring Boot, alguns erros frequentes podem impedir a inicialização ou a execução das consultas:

• Falha no Escaneamento de Pacotes: Certifique-se de que as interfaces do Mapper e as classes de Entidade estejam localizadas em subpacotes da classe principal anotada com @SpringBootApplication. Caso estejam em pacotes distintos, utilize a anotação @MapperScan na classe principal para indicar o caminho correto.
• Incompatibilidade de Nomes: Verifique se os nomes das colunas no banco de dados correspondem exatamente aos atributos da entidade (respeitando a convenção de nomenclatura, como snake_case para camelCase). Um erro de digitação no nome da tabela na anotação @Table resultará em exceções de SQL.
• Problemas de Conexão: Confirme se o serviço do MySQL está ativo e se as credenciais no application.properties estão corretas. Adicione ?useSSL=false&serverTimezone=UTC à URL do JDBC para evitar avisos de fuso horário e SSL em ambientes de desenvolvimento.