Excel Fluent API

Uma biblioteca Java moderna e intuitiva para importar e exportar arquivos Excel usando a biblioteca Fast Excel com uma interface Fluent API.

Características

• ✅ Fluent API: Interface intuitiva e encadeável
• ✅ Fast Excel: Biblioteca de alto desempenho para processamento de Excel
• ✅ Múltiplos formatos de saída: Arrays, Mapas, Objetos Java
• ✅ Mapeamento automático: Reflexão para mapear dados para objetos
• ✅ Configuração flexível: Personalização completa do comportamento
• ✅ Filtros e transformações: Processamento de dados durante importação/exportação
• ✅ Suporte a múltiplas planilhas: Importação e exportação de várias abas
• ✅ Tratamento de erros: Exceções personalizadas e informativas

Dependências

• Java 11+
• Fast Excel 0.19.0
• Jackson 2.15.2
• Apache Commons Lang 3.12.0
• Apache Commons IO 2.11.0

Instalação

Baixe o projeto, e reutilize o pacote.

Uso Rápido

Exportação Simples

// Criar dados
List<Map<String, Object>> dados = Arrays.asList(
    Map.of("Nome", "João Silva", "Idade", 30, "Cidade", "São Paulo"),
    Map.of("Nome", "Maria Santos", "Idade", 25, "Cidade", "Rio de Janeiro")
);

// Exportar para Excel
ExcelFluentAPI api = ExcelFluentAPI.create();
File arquivo = api.exportTo(dados)
        .withHeaders("Nome", "Idade", "Cidade")
        .toSheet("Pessoas")
        .toFile("pessoas.xlsx")
        .export();

Importação Simples

// Importar dados do Excel
List<Map<String, String>> dados = api.importFrom("pessoas.xlsx")
        .fromSheet("Pessoas")
        .hasHeader(true)
        .asMaps();

// Processar dados
dados.forEach(row -> {
    System.out.println("Nome: " + row.get("Nome") + ", Idade: " + row.get("Idade"));
});

Guia Completo

1. Configuração

A API permite configuração personalizada para diferentes cenários:

// Configuração padrão
ExcelConfig config = ExcelConfig.create();

// Configuração otimizada para importação
ExcelConfig configImport = ExcelConfig.forImport()
    .skipEmptyRows(true)
    .skipHeaderRow(false)
    .validateData(true);

// Configuração otimizada para exportação
ExcelConfig configExport = ExcelConfig.forExport()
    .createHeaderRow(true)
    .autoResizeColumns(true)
    .withDateFormat("dd/MM/yyyy");

// Criar API com configuração
ExcelFluentAPI api = ExcelFluentAPI.create(config);

2. Exportação

Exportação Básica

List<Map<String, Object>> dados = // seus dados aqui

File arquivo = api.exportTo(dados)
    .withHeaders("Coluna1", "Coluna2", "Coluna3")
    .toSheet("MinhaPlanilha")
    .toFile("arquivo.xlsx")
    .export();

Exportação com Mapeamento Personalizado

List<Produto> produtos = // lista de produtos

File arquivo = api.exportTo(produtos, produto -> Map.of(
        "Nome", produto.getNome(),
        "Preço", produto.getPreco(),
        "Preço com Imposto", produto.getPreco() * 1.1
    ))
    .withHeaders("Nome", "Preço", "Preço com Imposto")
    .toFile("produtos.xlsx")
    .export();

Exportação para OutputStream

try (FileOutputStream fos = new FileOutputStream("arquivo.xlsx")) {
    api.exportTo(dados)
        .withHeaders("Coluna1", "Coluna2")
        .toStream(fos)
        .export();
}

3. Importação

Importação como Arrays

List<String[]> linhas = api.importFrom("arquivo.xlsx")
    .fromSheet("Planilha1")
    .startingFromRow(2)  // começar da linha 2
    .endingAtRow(100)    // parar na linha 100
    .hasHeader(true)
    .asStringArrays();

Importação como Mapas

List<Map<String, String>> dados = api.importFrom("arquivo.xlsx")
    .fromSheet("Planilha1")
    .hasHeader(true)
    .asMaps();

Importação com Mapeamento para Objetos

// Usando reflexão automática
List<Funcionario> funcionarios = api.importFrom("funcionarios.xlsx")
    .fromSheet("Funcionarios")
    .hasHeader(true)
    .asObjects(Funcionario.class);

// Usando mapper personalizado
List<Funcionario> funcionarios = api.importFrom("funcionarios.xlsx")
    .fromSheet("Funcionarios")
    .hasHeader(true)
    .asObjects(rowData -> {
        Funcionario f = new Funcionario();
        f.setNome(rowData.get("Nome"));
        f.setIdade(Integer.parseInt(rowData.get("Idade")));
        return f;
    });

4. Filtros e Transformações

Filtro de Linhas

List<String[]> dados = api.importFrom("arquivo.xlsx")
    .filterRows(row -> {
        // Manter apenas linhas onde a primeira coluna não está vazia
        return row[0] != null && !row[0].trim().isEmpty() ? row : null;
    })
    .asStringArrays();

Transformação de Células

List<String[]> dados = api.importFrom("arquivo.xlsx")
    .transformCells(value -> {
        // Converter para maiúsculas
        return value != null ? value.toUpperCase() : value;
    })
    .asStringArrays();

5. Classes de Exemplo

Classe Funcionario

public class Funcionario {
    private String nome;
    private int idade;
    private String cargo;
    private double salario;
    
    // Construtores, getters e setters
}

Classe Produto

public class Produto {
    private String nome;
    private double preco;
    private String categoria;
    
    // Construtores, getters e setters
}

Exemplos Avançados

Processamento de Múltiplos Arquivos

List<File> arquivos = Arrays.asList(
    new File("arquivo1.xlsx"),
    new File("arquivo2.xlsx"),
    new File("arquivo3.xlsx")
);

List<Funcionario> todosFuncionarios = new ArrayList<>();

for (File arquivo : arquivos) {
    List<Funcionario> funcionarios = api.importFrom(arquivo)
        .fromSheet("Funcionarios")
        .hasHeader(true)
        .asObjects(Funcionario.class);
    
    todosFuncionarios.addAll(funcionarios);
}

// Exportar todos os funcionários consolidados
api.exportTo(todosFuncionarios)
    .withHeaders("Nome", "Idade", "Cargo", "Salario")
    .toFile("funcionarios_consolidados.xlsx")
    .export();

Validação de Dados

List<Funcionario> funcionarios = api.importFrom("funcionarios.xlsx")
    .fromSheet("Funcionarios")
    .hasHeader(true)
    .asObjects(Funcionario.class)
    .stream()
    .filter(f -> f.getIdade() >= 18 && f.getIdade() <= 65)
    .filter(f -> f.getSalario() > 0)
    .collect(Collectors.toList());

Exportação com Formatação

ExcelConfig config = ExcelConfig.forExport()
    .withDateFormat("dd/MM/yyyy")
    .withNumberFormat("#,##0.00")
    .autoResizeColumns(true);

ExcelFluentAPI api = ExcelFluentAPI.create(config);

api.exportTo(dados)
    .withHeaders("Data", "Valor", "Descrição")
    .toSheet("Relatório")
    .toFile("relatorio_formatado.xlsx")
    .export();

Tratamento de Erros

A API lança ExcelProcessingException para erros específicos:

try {
    List<Funcionario> funcionarios = api.importFrom("arquivo.xlsx")
        .fromSheet("Funcionarios")
        .asObjects(Funcionario.class);
} catch (ExcelProcessingException e) {
    System.err.println("Erro ao processar arquivo Excel: " + e.getMessage());
    e.printStackTrace();
}

Performance

• Fast Excel: Biblioteca de alto desempenho para processamento de arquivos grandes
• Streaming: Processamento eficiente de memória para arquivos grandes
• Configuração otimizada: Configurações pré-definidas para diferentes cenários

Limitações

• Suporte apenas para arquivos Excel (.xlsx)
• Mapeamento por reflexão requer construtores padrão
• Algumas funcionalidades avançadas do Excel não são suportadas

Contribuição

1. Fork o projeto
2. Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
3. Commit suas mudanças (git commit -m 'Add some AmazingFeature')
4. Push para a branch (git push origin feature/AmazingFeature)
5. Abra um Pull Request

Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

Suporte

Para suporte e dúvidas, abra uma issue no repositório do projeto.