🎓 Roteiro de Aprendizagem: Arquitetura Vertical Slice com .NET 9

📚 Índice

1. Introdução
2. O que é Vertical Slice Architecture?
3. Estrutura do Projeto
4. Conceitos Fundamentais
5. Explorando o Código
6. Atividade Prática
7. Entrega
8. Referências Adicionais

---

🎯 Introdução

Bem-vindo ao roteiro de aprendizagem sobre Vertical Slice Architecture! Este projeto foi criado para ajudá-lo a entender e aplicar esta arquitetura moderna usando .NET 9 e C#.

O que você vai aprender:

• ✅ Conceitos fundamentais da Vertical Slice Architecture
• ✅ Como organizar código por funcionalidades ao invés de camadas técnicas
• ✅ Como criar endpoints RESTful seguindo este padrão
• ✅ Como trabalhar com Entity Framework Core
• ✅ Como implementar novas funcionalidades do zero

Pré-requisitos:

• .NET 9 SDK instalado
• Visual Studio 2022, VS Code ou Rider
• Conhecimentos básicos de C# e ASP.NET Core
• Conhecimentos básicos de APIs REST

---

🏗️ O que é Vertical Slice Architecture?

Arquitetura Tradicional em Camadas (Layered Architecture)

Na arquitetura tradicional, organizamos o código por camadas técnicas:

📁 Projeto
├── 📁 Controllers
│   ├── ProdutoController.cs
│   └── CategoriaController.cs
├── 📁 Services
│   ├── ProdutoService.cs
│   └── CategoriaService.cs
├── 📁 Repositories
│   ├── ProdutoRepository.cs
│   └── CategoriaRepository.cs
└── 📁 Models
    ├── Produto.cs
    └── Categoria.cs

Problema: Quando precisamos adicionar ou modificar uma funcionalidade, precisamos mexer em arquivos espalhados por várias camadas diferentes.

Vertical Slice Architecture

Na Vertical Slice Architecture, organizamos o código por funcionalidades de negócio:

📁 Projeto
├── 📁 Funcionalidades
│   ├── 📁 Produtos
│   │   ├── Produto.cs
│   │   ├── 📁 ObterTodosProdutos
│   │   │   ├── ObterTodosProdutosHandler.cs
│   │   │   └── ObterTodosProdutosEndpoint.cs
│   │   ├── 📁 CriarProduto
│   │   │   ├── CriarProdutoHandler.cs
│   │   │   └── CriarProdutoEndpoint.cs
│   │   └── ...
│   └── 📁 Categorias
│       ├── Categoria.cs
│       └── ...
└── 📁 Infraestrutura
    └── BancoDeDados.cs

Vantagens:

1. ✅ Alta Coesão: Todo código relacionado a uma funcionalidade fica junto
2. ✅ Baixo Acoplamento: Funcionalidades são independentes entre si
3. ✅ Fácil Manutenção: Para modificar uma funcionalidade, você sabe exatamente onde ir
4. ✅ Facilita o Trabalho em Equipe: Diferentes desenvolvedores podem trabalhar em diferentes slices sem conflitos
5. ✅ Código mais Simples: Cada slice resolve apenas um problema específico

Quando usar?

✅ Bom para:

• Aplicações com muitas funcionalidades diferentes
• Times grandes trabalhando no mesmo projeto
• Quando as funcionalidades mudam com frequência
• Projetos que crescem com o tempo

❌ Talvez não seja ideal para:

• Aplicações muito pequenas e simples
• Quando há muita lógica compartilhada entre funcionalidades

---

📂 Estrutura do Projeto

Este projeto demonstra a Vertical Slice Architecture com um sistema simples de catálogo de produtos:

AprendizadoVerticalSlice/
├── 📁 Funcionalidades/
│   ├── 📁 Produtos/
│   │   ├── Produto.cs                                    # Entidade Produto
│   │   ├── 📁 ObterTodosProdutos/
│   │   │   ├── ObterTodosProdutosHandler.cs             # Lógica de negócio
│   │   │   └── ObterTodosProdutosEndpoint.cs            # Configuração do endpoint
│   │   ├── 📁 ObterProdutoPorId/
│   │   │   ├── ObterProdutoPorIdHandler.cs
│   │   │   └── ObterProdutoPorIdEndpoint.cs
│   │   ├── 📁 CriarProduto/
│   │   │   ├── CriarProdutoHandler.cs
│   │   │   └── CriarProdutoEndpoint.cs
│   │   ├── 📁 AtualizarProduto/
│   │   │   ├── AtualizarProdutoHandler.cs
│   │   │   └── AtualizarProdutoEndpoint.cs
│   │   └── 📁 ExcluirProduto/
│   │       ├── ExcluirProdutoHandler.cs
│   │       └── ExcluirProdutoEndpoint.cs
│   └── 📁 Categorias/
│       ├── Categoria.cs                                  # Entidade Categoria
│       ├── 📁 ObterTodasCategorias/
│       │   ├── ObterTodasCategoriasHandler.cs
│       │   └── ObterTodasCategoriasEndpoint.cs
│       └── 📁 CriarCategoria/
│           ├── CriarCategoriaHandler.cs
│           └── CriarCategoriaEndpoint.cs
├── 📁 Infraestrutura/
│   └── BancoDeDados.cs                                   # Contexto do EF Core
├── Program.cs                                            # Configuração da aplicação
└── appsettings.json                                      # Configurações

Componentes de cada Slice:

1. Entidade (Produto.cs, Categoria.cs): Representa a entidade do domínio
2. Handler (*Handler.cs): Contém a lógica de negócio da funcionalidade
3. Endpoint (*Endpoint.cs): Define e configura o endpoint HTTP
4. Records de Request/Response: Definem os contratos de entrada e saída

---

💡 Conceitos Fundamentais

1. Handler (Manipulador)

O Handler é o coração de cada slice. Ele contém toda a lógica de negócio para executar uma funcionalidade específica.

Características:

• Tem uma responsabilidade única e bem definida
• Recebe as dependências via construtor (Injeção de Dependência)
• Retorna um resultado específico para aquela operação
• Pode fazer validações, transformações e chamadas ao banco de dados

Exemplo:

public class CriarProdutoHandler
{
    private readonly BancoDeDados _bancoDeDados;

    public CriarProdutoHandler(BancoDeDados bancoDeDados)
    {
        _bancoDeDados = bancoDeDados;
    }

    public async Task<Resultado> Executar(CriarProdutoRequisicao requisicao)
    {
        // Toda a lógica para criar um produto fica aqui
        // Validações, transformações, persistência, etc.
    }
}

2. Endpoint

O Endpoint é responsável por configurar a rota HTTP que expõe a funcionalidade.

Características:

• Define o método HTTP (GET, POST, PUT, DELETE)
• Define a rota (URL)
• Mapeia parâmetros de entrada
• Chama o Handler apropriado
• Retorna a resposta HTTP adequada

Exemplo:

public static class CriarProdutoEndpoint
{
    public static IEndpointRouteBuilder MapCriarProduto(this IEndpointRouteBuilder endpoints)
    {
        endpoints.MapPost("/api/produtos", async (
            [FromBody] CriarProdutoRequisicao requisicao,
            [FromServices] CriarProdutoHandler handler) =>
        {
            var resultado = await handler.Executar(requisicao);
            return Results.Created($"/api/produtos/{resultado.Id}", resultado);
        });

        return endpoints;
    }
}

3. Records de Request e Response

Records são estruturas imutáveis perfeitas para representar dados que trafegam pela API.

Request Record: Define o que o cliente envia

public record CriarProdutoRequisicao(
    string Nome,
    decimal Preco,
    int CategoriaId
);

Response Record: Define o que a API retorna

public record ProdutoResposta(
    int Id,
    string Nome,
    decimal Preco
);

4. Injeção de Dependência

Cada Handler é registrado no container de DI do ASP.NET Core:

// No Program.cs
builder.Services.AddScoped<CriarProdutoHandler>();

Isso permite que:

• O framework crie instâncias automaticamente
• As dependências sejam injetadas
• O gerenciamento de ciclo de vida seja automático

---

🔍 Explorando o Código

Slice Completa: Criar Produto

Vamos analisar como funciona a funcionalidade de Criar Produto passo a passo.

1. O Handler (CriarProdutoHandler.cs)

public class CriarProdutoHandler
{
    private readonly BancoDeDados _bancoDeDados;

    public CriarProdutoHandler(BancoDeDados bancoDeDados)
    {
        _bancoDeDados = bancoDeDados;
    }

    public async Task<(bool Sucesso, string? Erro, CriarProdutoResposta? Produto)> 
        Executar(CriarProdutoRequisicao requisicao)
    {
        // 1. Validações
        if (string.IsNullOrWhiteSpace(requisicao.Nome))
            return (false, "O nome do produto é obrigatório.", null);

        if (requisicao.Preco <= 0)
            return (false, "O preço deve ser maior que zero.", null);

        // 2. Validação de relacionamento
        var categoriaExiste = await _bancoDeDados.Categorias
            .AnyAsync(c => c.Id == requisicao.CategoriaId);

        if (!categoriaExiste)
            return (false, $"Categoria não encontrada.", null);

        // 3. Criação da entidade
        var novoProduto = new Produto
        {
            Nome = requisicao.Nome,
            Preco = requisicao.Preco,
            // ... outros campos
        };

        // 4. Persistência
        _bancoDeDados.Produtos.Add(novoProduto);
        await _bancoDeDados.SaveChangesAsync();

        // 5. Retorno
        var resposta = new CriarProdutoResposta(
            novoProduto.Id,
            novoProduto.Nome,
            novoProduto.Preco
        );

        return (true, null, resposta);
    }
}

O que está acontecendo:

1. ✅ Recebe o banco de dados via construtor
2. ✅ Valida os dados de entrada
3. ✅ Verifica se a categoria existe (regra de negócio)
4. ✅ Cria a entidade
5. ✅ Salva no banco de dados
6. ✅ Retorna o resultado

2. O Endpoint (CriarProdutoEndpoint.cs)

public static class CriarProdutoEndpoint
{
    public static IEndpointRouteBuilder MapCriarProduto(this IEndpointRouteBuilder endpoints)
    {
        endpoints.MapPost("/api/produtos", async (
            [FromBody] CriarProdutoRequisicao requisicao,
            [FromServices] CriarProdutoHandler handler) =>
        {
            var (sucesso, erro, produto) = await handler.Executar(requisicao);

            if (!sucesso)
                return Results.BadRequest(new { mensagem = erro });

            return Results.Created($"/api/produtos/{produto!.Id}", produto);
        })
        .WithName("CriarProduto")
        .WithTags("Produtos")
        .Produces<CriarProdutoResposta>(201)
        .Produces(400);

        return endpoints;
    }
}

O que está acontecendo:

1. ✅ Define uma rota POST em /api/produtos
2. ✅ Recebe a requisição do body
3. ✅ Chama o Handler
4. ✅ Trata o resultado (sucesso ou erro)
5. ✅ Retorna a resposta HTTP adequada (201 Created ou 400 Bad Request)

3. Registro no Program.cs

// Registra o Handler
builder.Services.AddScoped<CriarProdutoHandler>();

// Mapeia o Endpoint
app.MapCriarProduto();

Comparando com Camadas Tradicionais

Vertical Slice:

CriarProduto/
├── CriarProdutoHandler.cs      ← Toda lógica aqui
└── CriarProdutoEndpoint.cs     ← Configuração HTTP aqui

✅ Tudo relacionado a "Criar Produto" está em um único lugar!

Camadas Tradicionais:

Controllers/ProdutoController.cs       ← Endpoint
Services/ProdutoService.cs             ← Lógica
Repositories/ProdutoRepository.cs      ← Acesso a dados
Validators/ProdutoValidator.cs         ← Validações

❌ Para entender "Criar Produto", preciso abrir 4+ arquivos diferentes!

---

🚀 Como Executar o Projeto

1. Clonar o Repositório

git clone <url-do-repositorio>
cd AprendizadoVerticalSlice

2. Restaurar Pacotes

dotnet restore

3. Executar a Aplicação

dotnet run

4. Acessar a Documentação da API

Abra seu navegador em:

http://localhost:5156/scalar/v1

(A porta pode variar - verifique no console)

A interface Scalar oferece uma documentação interativa moderna onde você pode:

• Ver todos os endpoints disponíveis
• Testar as requisições diretamente no navegador
• Ver exemplos de request e response

5. Testar os Endpoints

Obter todas as categorias:

GET /api/categorias

Criar um produto:

POST /api/produtos
Content-Type: application/json

{
  "nome": "Mouse Gamer",
  "descricao": "Mouse gamer RGB",
  "preco": 150.00,
  "qu