Camada Controller: o ponto de entrada da API

A camada Controller em uma aplicação ASP.NET Core representa o ponto de entrada das requisições HTTP. Ela é responsável por receber, interpretar e encaminhar as chamadas realizadas pelo cliente, como navegadores, aplicativos móveis ou ferramentas de integração, para o serviços apropriados da aplicação. Os controllers devem ser simples e diretos, delegando toda a lógica de negócio a camada de serviços (Application). Essa separação de responsabilidades mantém o código limpo, testável e aderente aos princípios da arquitetura em camadas. Além disso, cada método do controller é geralmente associado a uma rota e um verbo HTTP(GET, POST, PUT, DELETE), formando os chamados endpoints RESTful.

Implementando a UserController: expondo os endpoints da API

A classe UserController é responsável por expor os endpoints HTTP da nossa API REST, funcionando como o ponto de entrada das operações relacionadas a usuários. Cada método corresponde a uma ação do CRUD, utilizando os verbos HTTP apropriados (GET, POST, PUT, DELETE) e delegando as operações à camada de serviço (IUserService). Essa estrutura mantém o controller enxuto e focado apenas em receber requisições, validar a estrutura dos dados e retornar respostas HTTP padronizadas. A lógica de negócio permanece encapsulada no serviço, garantindo separação de responsabilidade e alinhamento com os princípios da arquitetura em camadas.

using Microsoft.AspNetCore.Mvc;
using OracleCrud.Sp.Api.Application.Interfaces;
using OracleCrud.Sp.Api.Domain.Dtos;

namespace OracleCrud.Sp.Api.Controllers;

[ApiController]
[Route("api/[controller]")]
public class UserController : ControllerBase
{
    private readonly IUserService _userService;

    public UserController(IUserService userService)
    {
        _userService = userService;
    }

    [HttpGet]
    public async Task<ActionResult<IEnumerable<UserDto>>> GetAll()
    {
        var users = await _userService.GetAllAsync();
        return Ok(users);
    }

    [HttpPost]
    public async Task<ActionResult<string>> Insert([FromBody] CreateUserDto user)
    {
        if (!ModelState.IsValid)
            return BadRequest(ModelState);

        var result = await _userService.InsertAsync(user);
        return Ok(result);
    }

    [HttpPut]
    public async Task<ActionResult<string>> Update([FromBody] UserDto user)
    {
        if (!ModelState.IsValid)
            return BadRequest(ModelState);

        var result = await _userService.UpdateAsync(user);
        return Ok(result);
    }

    [HttpDelete("{id}")]
    public async Task<ActionResult<string>> Delete(string id)
    {
        var result = await _userService.DeleteAsync(id);
        return Ok(result);
    }
}

Program.cs: configurando o pipeline e a injeção de dependências

O arquivo Program.cs é o ponto de entrada da aplicação ASP.NET Core. Nele configuramos o pipeline de execução da aplicação, os serviços que serão injetados via dependência e os middlewares que vão atuar nas requisições HTTP. É nesse local que registramos o IUserService e o IUserRepository para que o ASP.NET Core saiba como instanciar essas dependências sempre que forem solicitadas, por exemplo, dentro da UserController. Também configuramos o Swagger, que facilita o teste manual da API, e definimos o ambiente da aplicação. Essa organização centralizada torna o ciclo de vida da aplicação mais transparente e controlado, seguindo boas práticas modernas de desenvolvimento com .NET.

Injeção de Dependência: conectando interfaces e implementações

No Program.cs, realizamos o registro das interfaces IUserService e IUserRepository com suas respectivas implementações UserService e UserRepository utilizando o método AddScoped. Essa abordagem segue o padrão de injeção de dependência nativo do ASP.NET Core, permitindo que o framework forneça automaticamente as instâncias, como nos controllers. O uso do Scoped garante que uma nova instância será criada por requisição HTTP, o que é ideal para serviços que acessam o banco de dados. Essa prática promove desacoplamento, facilidade de testes e clareza na manutenção, sendo um dos pilares da arquitetura limpa adotada no projeto.

builder.Services.AddControllers();

builder.Services.AddScoped<IUserService, UserService>();
builder.Services.AddScoped<IUserRepository, UserRepository>();

Testando o endpoint GET /api/User no Postman

Ao executar o projeto em ambiente de desenvolvimento, o ASP.NET Core gera automaticamente uma URL com porta dinâmica, neste caso http://localhost:5219, conforme definido no launchSettings.json. É importante destacar que, no seu ambiente, essa porta pode ser diferente, como 5000, ou 7048, dependendo da configuração ou do que o Visual Studio ou SDK do .NET escolherem no momento da execução. Utilizando o Postman, realizamos uma requisição GET para o endpoint /api/User, que é responsável por listar todos os usuários cadastrados. A resposta retornou com status 200 OK, indicando que o endpoint está ativo e funcional. No entanto, o corpo da resposta foi um array vazio ([]), o que significa que nenhum usuário está presente no banco de dados no momento, o que é um comportamento esperado em em um ambiente recém iniciado, antes de qualquer inserção

Testando o endpoint POST /api/User no Postman

Neste teste, utilizamos o Postman para enviar uma requisição POST ao endpoint /api/User, com o objetivo de cadastrar um novo usuário. A requisição foi feita com o corpo no formato JSON, contendo os campos name e email, conforme esperado pelo DTO CreateUserDto. O endpoint respondeu com status 200 OK e a mensagem “Usuário inserido com sucesso.”, indicando que a operação foi executada corretamente e os dados foram persistidos no banco de dados via stored procedure. Assim como no exemplo anterior, a URL utilizada foi http://localhost:5219, porém é importante lembrar que essa porta pode variar de acordo com o ambiente de execução de cada desenvolvedor, conforme definido no launchSettings.json. Se no seu projeto a porta for diferente, isso é completamente normal e não afeta o funcionamento da API.

Reexecutando o GET /api/User para consultar o novo registro

Após a inserção bem sucedida de um novo usuário com o endpoint POST /api/User, realizamos novamente a requisição GET /api/User para verificar se o dado foi persistido corretamente no banco. Desta vez, o retorno trouxe uma lista contendo o objeto recém cadastrado, incluindo seu id gerado automaticamente, além dos campos name e email. O status 200 OK confirma que a requisição foi processada com sucesso e que o fluxo de inserção e leitura está funcionando conforme esperado. Esse tipo de verificação é essencial para garantir a integridade dos dados e validar que o repositório está acessando corretamente a base Oracle via stored procedures.

Testando o endpoint PUT /api/User para atualizar um usuário

Neste teste, utilizamos o Postman para enviar uma requisição PUT ao endpoint /api/User, com o objetivo de atualizar os dados de um usuário já existente. No corpo da requisição, foi informado o id do usuário previamente inserido, juntamente com os novos valores para os campos name e email. A resposta retornou com status 200 OK e a mensagem "Usuário atualizado com sucesso.", confirmando que a operação foi concluída com êxito. Isso demonstra que a comunicação com a stored procedure sp_update_user está funcionando corretamente e que a aplicação está atualizando registros no banco de dados conforme esperado. Lembre-se de que, se o id informado não existir, a própria procedure retorna uma mensagem apropriada, garantindo um controle confiável de validação no nível de banco.

Verificando a atualização com uma nova chamada GET

Após a requisição de atualização com sucesso, reexecutamos o endpoint GET /api/User para verificar se os dados do usuário foram realmente modificados no banco. A resposta confirmou a alteração, retornando o nome atualizado com “Flavio Update” e o nomes e-mail previamente cadastrado. Isso demonstra que o processo de persistência com stored procedure está funcionando corretamente, refletindo imediatamente as mudanças realizadas.

Testando o endpoint DELETE /api/User para remover um usuário

Neste teste, utilizamos o Postman para enviar uma requisição DELETE ao endpoint /api/User/{id}, informando diretamente na URL o id do usuário que havia sido previamente inserido e atualizado. A resposta retornou com status 200 OK e a mensagem "Usuário excluído com sucesso.", confirmando que a operação foi concluída corretamente. Essa resposta é gerada pela stored procedure sp_delete_user, que também valida se o id existe no banco e retorna mensagens específicas em caso de erro. Com isso, completamos o ciclo do CRUD (Create, Read, Update, Delete), validando que todas as operações estão integradas corretamente com o banco Oracle.

Conclusão

Na terceira parte da série Construindo uma API REST em .NET com Oracle XE e Stored Procedures [Parte 3], implementamos a camada de controllers da aplicação e realizamos testes práticos dos principais endpoints do CRUD: GET, POST, PUT e DELETE. Exploramos como os controllers se comunicam com a camada de serviços, como configurar corretamente a injeção de dependência no Program.cs e validamos toda a integração com o banco de dados Oracle por meio de chamadas HTTP usando o Postman. Com isso, nossa API já é capaz de executar todas as operações básicas com segurança e organização. Na Parte 4, concluiremos a aplicação com um resumo geral do que construímos até aqui, consolidando o aprendizado e reforçando os principais conceitos abordados ao longo da série.

A camada Application e sua função na organização da Regra de Negócio

A Camada Application é responsável por orquestrar a lógica da aplicação, fazendo a ponte entre os controladores e a infraestrutura. É aqui que centralizamos as interfaces e sua implementações concretas, como a UserService, que aplica regras básicas e delega persistência ao IUserRepository, sem depender diretamente do banco de dados.

Seguimos os princípios da Clean Architecture, mantendo a separação de responsabilidade e favorecendo testabilidade e desacoplamento. Embora a Application esteja organizada como uma pasta dentro do projeto principal, ela poderia facilmente ser movida para uma class library separada, o que é comum em aplicações maiores.

Vale ressaltar que, embora tenhamos optado por uma estrutura mais enxuta e direta, sem o uso de padrões como Command Handlers, Use Cases explícitos ou Value Objects, esse modelo é comum em muitos projetos reais e funciona bem em contextos onde a complexidade do domínio é moderada. A escolha visa manter o foco nos fundamentos, com uma organização clara, de fácil leitura e alinhada aos princípios modernos da arquitetura em camadas.

Implementando a Classe UserService

Com a estrutura da camada Application definida, seguimos para a implementação da classe UserService, que é a implementação concreta da interface IUserService, e tem como responsabilidade orquestrar as operações relacionadas a usuários. Ela atua como intermediária entre o controlador e o repositório, garantindo que a lógica de negócio permaneça desacoplada da infraestrutura.

Ao receber um CreateUserDto, a UserService utiliza a biblioteca Flavio.Santos.NetCore.ObjectMapping para convertê-lo em um UserDto, e adiciona um Id gerado com Guid.NewGuid(). Esse processo mantém o código limpo e evita duplicação. Em seguida, a instância convertida é repassada para o repositório via IUserRepository, que realiza a persistência no banco.

Os métodos GetAllAsync(), UpdateAsync() e DeleteAsync() seguem o mesmo padrão: aplicam regras simples, quando necessário, e delegam as ações ao repositório. Essa abordagem reforça a separação de responsabilidade e contribui para uma arquitetura modular, mantendo a aplicação mais organizada, testável e alinhada aos princípios da Clean Architecture.

using OracleCrud.Sp.Api.Application.Interfaces;
using OracleCrud.Sp.Api.Domain.Dtos;
using FDS.NetCore.ObjectMapping.Extensions;

namespace OracleCrud.Sp.Api.Application.Services;

public class UserService : IUserService
{
    private readonly IUserRepository _repository;

    public UserService(IUserRepository repository)
    {
        _repository = repository;
    }

    public async Task<IEnumerable<UserDto>> GetAllAsync()
    {
        return await _repository.GetAllAsync();
    }

    public async Task<string> InsertAsync(CreateUserDto user)
    {
        var userDto = user
            .MapTo<UserDto>()
            .Apply(t => t.Id = Guid.NewGuid().ToString());

        return await _repository.InsertAsync(userDto);
    }

    public async Task<string> UpdateAsync(UserDto user)
    {
        return await _repository.UpdateAsync(user);
    }

    public async Task<string> DeleteAsync(string id)
    {
        return await _repository.DeleteAsync(id);
    }
}

Instalando e utilizando a biblioteca Flavio.Santos.NetCore.ObjectMapping

Para facilitar o mapeamento entre objetos com estrutura semelhante, utilizamos a biblioteca Flavio.Santos.NetCore.ObjectMapping. Ela oferece uma abordagem fluente, simples e sem configuração para converter objetos entre tipos diferentes com propriedades compatíveis, como no caso de CreateUserDto para UserDto.

A instalação pode ser feita diretamente via terminal do projeto:

dotnet add package Flavio.Santos.NetCore.ObjectMapping

Ou se preferir, pelo gerenciador de pacotes do Visual Studio Manage Nuget Packages.

Exemplo prático de uso da biblioteca de mapeamento

Para compreender melhor como a biblioteca Flavio.Santos.NetCore.ObjectMapping facilita a transformação de objetos, vejamos o seguinte cenário comum: ao receber dados de um cliente via API, é comum utilizar um DTO de entrada (CreateUserDto). Esse objeto, então, precisa ser transformado em um DTO interno ou persistido, como o UserDto.

Estrutura dos objetos:

// Objeto recebido via requisição HTTP
public class CreateUserDto
{
    public string Name { get; set; } = default!;
    public string Email { get; set; } = default!;
}

// Objeto utilizado internamente ou para persistência
public class UserDto
{
    public string Id { get; set; } = default!;
    public string Name { get; set; } = default!;
    public string Email { get; set; } = default!;
}

Transformação usando MapTo() e Apply():

CreateUserDto user = new CreateUserDto
{
    Name = "João",
    Email = "joao@email.com"
};

var userDto = user
    .MapTo<UserDto>()
    .Apply(u => u.Id = Guid.NewGuid().ToString());

Neste exemplo:

• O método MapTo<UserDto>() copia automaticamente as propriedades com nomes e tipos compatíveis (Name e Email).

• O método Apply(…) adiciona o valor Id, permitindo estender o objeto de maneira fluente, sem criar código repetitivo.

Esse tipo de abordagem é especialmente útil em serviços de aplicação e camadas intermediárias, reduzindo o acoplamento e aumentando a clareza do código.

A camada Infrastructure e seu Papel na Arquitetura

A camada Infrastructure é responsável por implementar os detalhes técnicos da aplicação, como o acesso ao banco de dados, chamadas externas, serviços de terceiros ou qualquer outra dependência que envolva infraestrutura. No nosso caso, ela abriga a implementação concreta da interface IUserRepository, utilizando a biblioteca Oracle.ManagedDataAccess.Client para executar a stored procedures no banco de dados Oracle XE. Essa separação permite que o restante da aplicação (como os serviços e controladores) dependa apenas de contratos (interfaces), mantendo o sistema mais flexível, testável e aderente ao princípio da inversão de dependência. Em projetos maiores, essa camada pode ser estruturada como uma class library separada, reforçando o desacoplamento entre regras de negócio e detalhes de infraestrutura.

Implementando a Classe UserRepository

A classe UserRepository é responsável por concretizar o contrato definido pela interface IUserRepository, realizando o acesso direto ao banco de dados Oracle. Esta implementação reside na camada Infrastructure, que tem como função lidar com aspectos externos à aplicação, como persistência de dados, acesso a serviços de terceiros ou recursos do sistema.

Neste projeto, optamos por utilizar a biblioteca Oracle.ManagedDataAccess.Client em vez de ORMs como Entity Framework ou Dapper. Essa abordagem proporciona maior controle sobre a execução de comandos SQL e chamadas a Stored Procedures, sendo particularmente adequada quando se deseja os recursos específicos do Oracle ou seguir diretrizes de legado da empresa.

A classe encapsula operações como GetAllAsync(), InsertAsync(), UpdateAsync() e DeleteAsync(), comunicando-se com o banco por meio de views e procedures previamente definidas. O uso de comandos parametrizados garante segurança contra SQL Injection, além de promover clareza e previsibilidade no comportamento do repositório.

É importante observar que o UserRepository permanece completamente desacoplado da lógica de aplicação e de transformação de dados, sendo consumido exclusivamente pela UserService. Essa separação de responsabilidade está alinhada com os princípios da Clean Architecture, ainda que de forma simplificada e pragmática neste projeto.

using Oracle.ManagedDataAccess.Client;
using OracleCrud.Sp.Api.Application.Interfaces;
using OracleCrud.Sp.Api.Domain.Dtos;
using System.Data;

namespace OracleCrud.Sp.Api.Infrastructure.Repositories;

public class UserRepository : IUserRepository
{
    private readonly string _connectionString;

    public UserRepository(IConfiguration configuration)
    {
        _connectionString = configuration.GetConnectionString("OracleDb")!;
    }

    public async Task<IEnumerable<UserDto>> GetAllAsync()
    {
        var users = new List<UserDto>();

        using var connection = new OracleConnection(_connectionString);
        using var command = new OracleCommand("SELECT id, name, email FROM vw_users", connection);

        await connection.OpenAsync();
        using var reader = await command.ExecuteReaderAsync();

        while (await reader.ReadAsync())
        {
            users.Add(new UserDto
            {
                Id = reader.GetString(0),
                Name = reader.GetString(1),
                Email = reader.GetString(2)
            });
        }

        return users;
    }

    public async Task<string> InsertAsync(UserDto user)
    {
        using var connection = new OracleConnection(_connectionString);
        using var command = new OracleCommand("app_user.sp_insert_user", connection)
        {
            CommandType = CommandType.StoredProcedure
        };

        command.Parameters.Add("p_id", OracleDbType.Varchar2).Value = user.Id;
        command.Parameters.Add("p_name", OracleDbType.Varchar2).Value = user.Name;
        command.Parameters.Add("p_email", OracleDbType.Varchar2).Value = user.Email;

        var resultParam = new OracleParameter("p_result", OracleDbType.Varchar2, 4000)
        {
            Direction = ParameterDirection.Output
        };
        command.Parameters.Add(resultParam);

        await connection.OpenAsync();
        await command.ExecuteNonQueryAsync();

        return resultParam.Value?.ToString() ?? "Erro ao inserir usuário.";
    }

    public async Task<string> UpdateAsync(UserDto user)
    {
        using var connection = new OracleConnection(_connectionString);
        using var command = new OracleCommand("app_user.sp_update_user", connection)
        {
            CommandType = CommandType.StoredProcedure
        };

        command.Parameters.Add("p_id", OracleDbType.Varchar2).Value = user.Id;
        command.Parameters.Add("p_name", OracleDbType.Varchar2).Value = user.Name;
        command.Parameters.Add("p_email", OracleDbType.Varchar2).Value = user.Email;

        await connection.OpenAsync();
        await command.ExecuteNonQueryAsync();

        return "Usuário atualizado com sucesso.";
    }

    public async Task<string> DeleteAsync(string id)
    {
        using var connection = new OracleConnection(_connectionString);
        using var command = new OracleCommand("app_user.sp_delete_user", connection)
        {
            CommandType = CommandType.StoredProcedure
        };

        command.Parameters.Add("p_id", OracleDbType.Varchar2).Value = id;

        await connection.OpenAsync();
        await command.ExecuteNonQueryAsync();

        return "Usuário excluído com sucesso.";
    }
}

Conclusão

Concluímos nesta segunda parte da série a implementação das camadas Application e Infrastructure, elementos essenciais para estruturar a lógica de negócios e o acesso a dados de forma organizada e desacoplada. Criamos a classe UserService, responsável por orquestrar as operações da aplicação, e a classe UserRepository, que efetua a comunicação direta com o banco Oracle por meio de Stored Procedures, utilizando a biblioteca Oracle.ManagedDataAccess.Client.

Também introduzimos o uso da biblioteca Flavio.Santos.NetCore.ObjectMapping, que nos permitiu mapear objetos de forma simples e fluente, eliminando a necessidade de código repetitivo para transformação de DTOs.

Com essas camadas implementadas, a base do projeto está bem estruturada e pronta para receber a camada de apresentação.

Na Parte 3, vamos desenvolver os Controllers, expondo os endpoints da API e finalizando a aplicação com testes manuais via HTTP. Se você acompanhou até aqui, parabéns, estamos quase lá !!!

Embora as arquiteturas modernas privilegiem regras de negócio na aplicação e sigam princípios como DDD e Clean Architecture, ainda existem cenários legítimos em que Stored Procedures são utilizadas para encapsular lógica diretamente no banco de dados. Isso pode acontecer por motivos como:

Restrições técnicas de sistemas legados;

Demandas específicas de performance;

Políticas internas de segurança ou governança;

Decisões estratégicas da equipe ou da empresa.

Nesta série de artigos sobre a construção de uma API REST com Stored Procedures, o objetivo não é incentivar o uso indiscriminado dessa abordagem, mas sim mostrar como aplicá-la de forma estruturada e organizada quando ela for necessária. Em muitos projetos reais, é preciso adaptar a solução à realidade do ambiente, respeitando restrições e práticas já existentes.

Criando um Novo Projeto no Visual Studio 2022

Para começarmos a construção da nossa API REST com .NET 8, o primeiro passo é criar um novo projeto no Visual Studio 2022. Essa será a IDE utilizada em toda a implementação. Siga os passos abaixo para chegar até a tela de seleção de templates:

1. Com o Visual Studio 2022 aberto, clique no menu File > New - Project;

2. Isso abrirá uma nova janela com o título “Create a new project” ou “Add a new project” (dependendo da sua versão/idioma).

3. No campo de busca, digite “API” e selecione o template “ASP.NET Core Web API”;

4. Verifique se a linguagem está definida como C#;

5. Clique em Next para prosseguir com a configuração do projeto.

Esta etapa define a base de nossa aplicação que será uma API REST desacoplada utilizando Stored Procedures com Oracle XE 21c.

Configurando o Nome do Projeto

Após selecionar o template ASP.NET Core Web API, o Visual Studio exibirá a tela “Configure your new project”. Essa etapa é responsável por definir o nome do seu projeto e o local onde ele será salvo.

• Em Project name, insira um nome descritivo. Neste exemplo, utilizamos, OracleCrud.Sp.Api, indicando que o projeto é um CRUD com Oracle utilizando Stored Procedures;

• Em Location, escolha a pasta onde o projeto será armazenado. No nosso caso, estamos organizando dentro da estrutura src/ do repositório.

Após configurar, clique em Next para prosseguir com a escolha da versão do .NET.

Definindo as Configurações Adicionais do Projeto

Na última etapa da criação do projeto, temos a tela “Additional information”, onde configuramos detalhes importantes da nossa ASP.NET Core Web API. Veja abaixo as opções recomendadas para o nosso cenário com .NET 8 e Oracle XE:

• Framework: Selecione o .NET 8 (Long Term Support), que oferece suporte de longo prazo e é ideal para novos projetos.

• Authentication type: Marque como None, já que neste exemplo não implementamos autenticação.

• Configure for HTTPS: Mantenha marcado para garantir a segurança nas requisições.

• Enable OpenAPI support: Marque essa opção para que o Swagger seja configurado automaticamente, facilitando testes na API.

• Use controllers: Certifique-se de que está marcado, pois usaremos controllers no estilo tradicional (e não minimal APIs).

Por fim, clique em Create para gerar sua API REST. Pronto! Agora temos a estrutura inicial do nosso projeto ASP.NET Core com suporte a Swagger e pronto para integrar com Oracle via Stored Procedures.

Limpando a Estrutura Inicial do Projeto

Após a criação da PAI, o Visual Studio gera alguns arquivos de exemplo que não serão utilizados no projeto. Para manter a organização e focar apenas no que é essencial, recomendamos excluir os seguites arquivos:

Arquivos a serem removidos:

• OracleCrud.Sp.Api.http: Usado para testes HTTP via Visual Studio, mas será desnecessário no nosso fluxo.

• Controllers/WeatherForecastController.cs: Um controller gerado automaticamente com lógica fictícia.

• WeatherForecast.cs: Classe modelo de exemplo que não utilizaremos.

Para excluir, no Solution Explorer, clique com o botão direito do mouse em cada arquivo, selecione a opção Delete e confirme a exclusão se solicitado.

Separando responsabilidades com DTOs distintos

Para manter a clareza e a responsabilidade única de cada classe em nossa API, utilizamos dois Data Transfer Objects (DTOs) distintos: O CreateUserDto e o UserDto. O CreateUserDto é usado exclusivamente para representar os dados recebidos do frontend no momento da criação de um novo usuário. Ele não inclui o Id, pois esse campo é gerado internamente pela API ou pelo banco de dados. Já o UserDto, representa o objeto completo, incluindo o Id, e é utilizado nas respostas ou em operações internas onde o identificador já está presente. Essa separação melhora a coesão do código e facilita a manutenção e os testes da aplicação.

// DTO recebido do Frontend (para criação de usuário)
namespace OracleCrud.Sp.Api.Domain.Dtos;

public class CreateUserDto
{
    public string Name { get; set; } = default!;
    public string Email { get; set; } = default!;
}

// DTO utilizado internamente (com Id)
namespace OracleCrud.Sp.Api.Domain.Dtos;

public class UserDto
{
    public string Id { get; set; } = default!;
    public string Name { get; set; } = default!;
    public string Email { get; set; } = default!;
}

Por que os DTOs estão na pasta Domain?

Colocamos os DTOs na pasta Domain porque, nesse projeto, não estamos utilizando entidades de domínio mapeadas com ORM como o Entity Framework. Em vez disso, nossos objetos centrais de comunicação com a API(como UserDto e CreateUserDto) representam o “contrato” de dados que a aplicação conhece e manipula, sendo parte da camada de domínio. Isso reforça a ideia de que o domínio não é só composto por entidades persistidas, mas também pelos tipos que expressam regras e estruturas de negócio, mesmo que simplificadas.

Definindo Contratos com Interfaces: Separando Regras de Negócio e Persistência

Na estrutura desta API, criamos duas interfaces fundamentais para garantir a separação de responsabilidade IUserService e IUserRepository. A IUserService representa o contrato da camada de serviço, responsável por orquestrar as regras de negócio da aplicação. Já a IUserRepository define o contrato da camada de persistência de dados, isolando a forma como acessamos o Oracle Database através de stored procedures.

using OracleCrud.Sp.Api.Domain.Dtos;

namespace OracleCrud.Sp.Api.Application.Interfaces;

public interface IUserService
{
    Task<IEnumerable<UserDto>> GetAllAsync();
    Task<string> InsertAsync(CreateUserDto user);
    Task<string> UpdateAsync(UserDto user);
    Task<string> DeleteAsync(string id);
}

Ambas as interfaces foram posicionadas na pasta Application/Interfaces, pois essa camada representa a lógica da aplicação (application layer), isto é , o ponto de comunicação entre as regras de negócio e as implementações concretas.

using OracleCrud.Sp.Api.Domain.Dtos;

namespace OracleCrud.Sp.Api.Application.Interfaces;

public interface IUserRepository
{
    Task<IEnumerable<UserDto>> GetAllAsync();
    Task<string> InsertAsync(UserDto user);
    Task<string> UpdateAsync(UserDto user);
    Task<string> DeleteAsync(string id);
}

Manter as interfaces nesse local centraliza os contratos da aplicação, facilitando a leitura, os testes e futuras substituições de implementação (por exemplo, trocar Oracle por outro banco, sem impactar as camadas superiores). Essa decisão segue os princípios da arquitetura limpa promovendo uma baixo acoplamento e e facilitando a manutenção da solução.

Conclusão

Nesta Parte 1 da série Construindo a API REST em .NET com Oracle XE e Stored Procedures, iniciamos o desenvolvimento da aplicação partindo totalmente do zero. Realizamos a seguintes etapas:

• Criamos o projeto com o template ASP.NET Core Web API no Visual Studio 2022;

• Limpamos a estrutura inicial removendo arquivos de exemplo como WeatherForecast.cs e WeatherForecastController.cs;

• Organizamos a base do projeto como uma estrutura em camadas: Domain, Application, Infrastructure e Controllers;

• Definimos os DTOs CreateUserDto e UserDto, explicando seus papéis e porque estão posicionados dentro da camada de domínio;

• Criamos as interfaces IUserService e IUserRepository, que representam os contratos da camada de aplicação.

• Justificamos a separação das interfaces em Application/Interfaces, mantendo o foco em uma arquitetura limpa e desacoplada.

Na Parte 2, vamos dar continuidade à implementação, criando os repositórios concretos, integrando com o banco Oracle XE por meio de Stored Procedures e finalizando os endpoints da nossa API REST.

Criação do Volume

No Docker, volumes são usados para armazenar dados de forma persistente fora do ciclo de vida dos containers. No caso do Oracle XE, isso significa garantir que os dados do banco não se percam ao reiniciar ou remover o container. O comando abaixo cria um volume nomeado chamado oracle-xe-data, que será utilizado para armazenar os arquivos do banco Oracle de forma durável:

docker volume create oracle-xe-data

Esse volume será montando no container posteriormente, garantindo que os dados persistam entre reinicializações e recriações do ambiente.

Criando o Container

Após criar o volume para persistência dos dados, o próximo passo é iniciar o container do Oracle XE. Isso é feito por meio do comando docker run, que define diversas configurações importantes para o ambiente do banco de dados, como nome do container, portas de acesso, senha do usuário administrador e o volume a ser utilizado. Esse comando também garante que o banco de dados seja reiniciado automaticamente sempre que o Docker (ou o sistema, como o WSL2) for reiniciado. Abaixo está o comando completo que realiza essa configuração:

docker run -d \
  --name oracle-xe \
  --restart unless-stopped \
  -p 1521:1521 \
  -p 5500:5500 \
  -e ORACLE_PWD=MinhaSenha123 \
  -v oracle-xe-data:/opt/oracle/oradata \
  container-registry.oracle.com/database/express:21.3.0-xe

O que esse comando faz:

• -name oracle-exe: Nome do container;

• -p 1521:1521: Expõe a porta padrão do Oracle;

• -p 5500:5500: Acesso ao Enterprise Manager (Gui web);

• -e ORACLE_PWD=...: Define a senha do usuário system;

• -v oracle-xe-data:/opt/oracle/oradata: Monta o volume nomeado oracle-xe-data no diretório onde o Oracle XE armazena os dados. Isso garante que as informações do banco sejam preservadas mesmo após reiniciar o container, o WSL2 ou o sistema operacional.

• Última linha: Define a imagem Oracle XE 21c.

Conectando ao Oracle XE com o DBeaver Community

O DBeaver Community é uma ferramenta gráfica gratuita e de código aberto utilizada para acessar e gerenciar bancos de dados. Compatível com uma variedade de SGBDs (incluindo Oracle, MySQL, PostgreSQL, SQL Server, entre outros), essa ferramenta oferece uma interface intuitiva que facilita a execução de comandos SQL, criação de objetos no banco (como tabelas, procedures e views), além de visualização e edição de dados.

No contexto deste material, utilizamos o DBeaver para conectar ao Oracle XE rodando dentro WSL2 via Docker, permitindo uma interação simples e eficaz com o banco de dados diretamente da interface gráfica.

Configurando a conexão DBeaver para acessar o Oracle XE

Para que o DBeaver consiga se comunicar corretamente com o Oracle XE executando em um container Docker (via WSL2), é necessário configurar manualmente os parâmetros de conexão. essa etapa informa ao DBeaver onde o banco está rodando, quais portas estão expostas, qual serviço utilizar e quais credenciais devem ser fornecidas.

Passo a passo:

1. Abra o DBeaver;

2. Clique em Arquivo > Nova Conexão (ou no ícone de nova conexão);

3. Na lista de banco de dados, selecione Oracle e clique em Avançar;

4. Preencha os campos de conexão:

   1. Host: localhost;

   2. Porta: 1521;

   3. Serviço (Service): XEPDB1;

   4. Usuário: system (ou outro usuário criado, como app_user);

   5. Senha: a senha definida como parâmetro ORACLE_PWD no container (ex: MinhaSenha123).

5. Clique em “Testar Conexão” para validar a comunicação com o banco;

6. Se solicitado, permita o download do driver Oracle JDBC;

7. Clique em Concluir. A conexão será adicionada à barra lateral esquerda, pronta para ser utilizada.

Visualizando os containers de forma personalizada

O comando abaixo permite listar apenas as informações mais úteis dos containers em execução, com uma visualização mais limpa e organizada:

docker ps --format "table {{.ID}}\t{{.Names}}\t{{.CreatedAt}}\t{{.Status}}\t{{.Ports}}"

Esse comando usa a flag --format, que permite personalizar as colunas exibidas. Neste caso, estamos pedindo para mostrar os seguintes campos:

• {{.ID}}: O identificador único do container;

• {{.Names}}: O nome que você deu ao container (exemplo: oracle-xe);

• {{.CreatedAt}}: A data e hora em que o container foi criado;

• {{.Status}}: O estado atual do container (exemplo: “Up 5 minutes”);

• {{.Ports}}: Quais portas estão xpostas/mapeadas para o host.

A palavra table no início instrui o Docker a exibi os dados em formato tabular (com cabeçalho), e os \t inserem tabulações entre as colunas para melhorar a legibilidade. Esse formato é ideal para uso no terminal durante o desenvolvimento, especialmente quando você quer rapidamente visualizar o status de containers importantes sem excesso de informações.

Por que criar um usuário dedicado para o acesso da aplicação?

Ao trabalhar com banco de dados Oracle(ou qualquer outro), uma boa prática essencial é nunca usar usuários administradores como SYSTEM ou SYS em aplicações. Esses usuários possuem permissões elevadas e são voltados para administração do banco, não para uso em aplicações do dia a dia.

Criar um usuário dedicado, como app_user, traz várias vantagens:

• Segurança: Limita os acessos ao estritamente necessário, evitando alterações acidentais em objetos críticos do banco;

• Organização: Os objetos (tabelas, views, procedures) da aplicação ficam concentrados em um schema próprio;

• Facilidade de manutenção: Caso o acesso precise ser revogado, migrado ou auditado, tudo está isolado por usuário;

• Boas práticas de arquitetura: Em ambientes profissionais, é comum um banco de dados ter vários usuários(schemas), cada um representando um serviço ou módulo da aplicação.

O comando abaixo cria um novo usuário no banco com a senha app123 e concede permissões básicas para o usuário se conectar ao banco e criar objetos como tabelas, view e procedimentos.

-- Criação do usuário
CREATE USER app_user IDENTIFIED BY app123;

-- Permissões básicas para criar e usar tabelas
GRANT CONNECT, RESOURCE TO app_user;

GRANT CREATE VIEW TO app_user;

Você pode se conectar com esse usuário no DBeaver ou via backend .NET usando a seguinte string de conexão:

"User Id=app_user;Password=app123;Data Source=localhost:1521/XEPDB1;"

Abaixo a tabela de armazenamento de usuários:

CREATE TABLE users (
    id VARCHAR2(36) PRIMARY KEY,
    name VARCHAR2(100) NOT NULL,
    email VARCHAR2(150) NOT NULL
);

INSERT INTO users (id, name, email)
VALUES ('550e8400-e29b-41d4-a716-446655440000', 'Alice', 'alice@example.com');

Regras de Negócio no Banco de Dados

Em sistemas modernos, é comum que as regras de negócio sejam implementadas na camada do backend, onde frameworks e linguagens de programação oferecem maior flexibilidade e controle. No entanto ainda existem cenários em que parte ou toda a lógica é mantida no banco de dados, especialmente em sistemas legados, ambientes internos mais controlados ou soluções com baixa complexidade, onde centralizar a lógica no banco pode facilitar o controle de integridade e reduzir a dependência de outras camadas. Nesta seção, veremos um exemplo prático e didático de como encapsular regras de negócio diretamente no Oracle usando PL/SQL, com stored procedures responsáveis por operações como inserção, atualização, exclusão e consulta de dados.

Inserção com PL/SQL

A stored procedure sp_insert_user demonstra como implementar a inserção de dados com validação diretamente no banco de dados, centralizando a regra de negócio no Oracle. Embora essa abordagem não seja comum em arquiteturas modernas voltadas à alta escalabilidade, ela ainda pode ser útil em sistemas internos, legados ou como exercício didático para ilustrar o uso do PL/SQL para controle de integridade e regras no lado do banco.

CREATE OR REPLACE PROCEDURE app_user.sp_insert_user (
    p_id     IN VARCHAR2,
    p_name   IN VARCHAR2,
    p_email  IN VARCHAR2,
    p_result OUT VARCHAR2
) AS
BEGIN
    -- Validações básicas
    IF p_id IS NULL OR TRIM(p_id) IS NULL THEN
        p_result := 'O campo ID é obrigatório.';
        RETURN;
    ELSIF p_name IS NULL OR TRIM(p_name) IS NULL THEN
        p_result := 'O campo Nome é obrigatório.';
        RETURN;
    ELSIF p_email IS NULL OR TRIM(p_email) IS NULL THEN
        p_result := 'O campo E-mail é obrigatório.';
        RETURN;
    END IF;

    -- Inserção no banco
    INSERT INTO app_user.users (id, name, email)
    VALUES (p_id, p_name, p_email);

    p_result := 'Usuário inserido com sucesso.';

EXCEPTION
    WHEN OTHERS THEN
        p_result := 'Erro: ' || SQLERRM;
END;

Alteração

CREATE OR REPLACE PROCEDURE app_user.sp_update_user (
    p_id     IN VARCHAR2,
    p_name   IN VARCHAR2,
    p_email  IN VARCHAR2,
    p_result OUT VARCHAR2
)
IS
BEGIN
    -- Validações básicas
    IF p_id IS NULL OR TRIM(p_id) IS NULL THEN
        p_result := 'Erro: O campo ID é obrigatório.';
        RETURN;
    ELSIF p_name IS NULL OR TRIM(p_name) IS NULL THEN
        p_result := 'Erro: O campo Nome é obrigatório.';
        RETURN;
    ELSIF p_email IS NULL OR TRIM(p_email) IS NULL THEN
        p_result := 'Erro: O campo E-mail é obrigatório.';
        RETURN;
    END IF;

    -- Atualização no banco
    UPDATE app_user.users
    SET name = p_name,
        email = p_email
    WHERE id = p_id;

    -- Verifica se algum registro foi atualizado
    IF SQL%ROWCOUNT = 0 THEN
        p_result := 'Erro: Usuário não encontrado.';
    ELSE
        p_result := 'Usuário atualizado com sucesso.';
    END IF;
END;

exclusão

CREATE OR REPLACE PROCEDURE app_user.sp_delete_user (
    p_id     IN VARCHAR2,
    p_result OUT VARCHAR2
)
IS
BEGIN
    IF p_id IS NULL OR TRIM(p_id) IS NULL THEN
        p_result := 'Erro: O campo ID é obrigatório.';
        RETURN;
    END IF;

    DELETE FROM app_user.users
    WHERE id = p_id;

    IF SQL%ROWCOUNT = 0 THEN
        p_result := 'Erro: Usuário não encontrado.';
    ELSE
        p_result := 'Usuário excluído com sucesso.';
    END IF;
END;

View

CREATE OR REPLACE VIEW app_user.vw_users AS
SELECT
    id,
    name,
    email
FROM
    app_user.users;

Ao trabalhar com Git, é comum registrar tudo o que foi alterado no código por meio de commits. Para facilitar a leitura do histórico desses commits, muitos times seguem uma convenção chamada Conventional Commits, onde cada commit começa com uma palavra-chave que indica o tipo de mudança realizada. Um desses tipos é o chore.

A palavra chore vem do inglês e significa algo como “tarefa rotineira” ou “serviços doméstico”. No contexto do Git, ela é usada indicar mudanças que fazem parte da manutenção do projeto, mas que não afetam diretamente o código da aplicação ou o comportamento visível para o usuário.

Quando usar o (chore)?

Você deve usar o chore sempre que estiver fazendo alterações que não envolvem novas funcionalidades, correções de bugs ou melhorias diretas no código. Isso inclui, por exemplo:

• Adicionar ou atualizar arquivos como .gitignore, tsconfig.json, .editorconfig ou arquivos de ambiente;

• Alterar scripts de automação, como build, deploy ou testes automatizados;

• Atualizar dependências de ferramentas internas, mas sem impactar o funcionamento da aplicação;

• Mover pastas, renomear arquivos ou limpar código não utilizado.

Essas informações são importantes para manter o projeto saudável e bem organizado, mas não mudam “o que o sistema faz”. Por isso, eles recebem esse rótulo especial.

Exemplos de uso com (chore)

Aqui estão exemplos reais de mensagens de commit usando o prefixo chore, com o emoji 🛠️ para facilitar a leitura:

git commit -m "🛠️ chore: adiciona regra *.bkp ao .gitignore."
git commit -m "🛠️ chore: atualiza dependências internas do projeto."
git commit -m "🛠️ chore: remove arquivos temporários não utilizados."
git commit -m "🛠️ chore: reorganiza estrutura de diretórios."
git commit -m "🛠️ chore: ajusta script de build para ambiente local."

Esses exemplos mostram como o chore é usado para marcar tarefas que ajudam na manutenção do projeto, sem interferir diretamente no comportamento do software.