Biss.Solutions.MicroService.Template.Net9 2.0.0

Biss Solutions - Microservice Template (.NET 9)

Versão 2.0.0

✨ Introdução

Este template cria a estrutura base para um Microservice moderno em .NET 9, utilizando padrões e boas práticas de Clean Architecture, CQRS, Domain-Driven Design e Specification Pattern.

Projetado para ajudar desenvolvedores a criarem APIs escaláveis, seguras, observáveis e bem organizadas rapidamente.

🏗️ Visão Geral da Solução

A solução é dividida em 5 camadas principais, seguindo os princípios de Clean Architecture:

📦 Camadas principais

• Api: Responsável por receber as requisições HTTP, aplicar validações iniciais, gerenciar middlewares e devolver as respostas formatadas.
• Application: Orquestra a lógica de negócios, gerencia Commands, Queries, Specifications e utiliza padrões como CQRS e Mediator.
• Infrastructure: Implementa o acesso a dados e a comunicação com serviços externos (por exemplo: SQL Server via EF Core).
• Domain: Define as entidades de domínio, enums, interfaces, specifications e regras de negócio puras.
• CrossCutting: Contém utilitários e configurações compartilhadas entre todas as camadas (como injeções de dependência, logs, validações, health checks).

🛠️ Tecnologias e Bibliotecas Utilizadas

• .NET 9: Última versão do framework da Microsoft com todas as funcionalidades mais recentes.
• Entity Framework Core 9.0.6: Persistência de dados no banco de dados relacional (SQL Server).
• AutoMapper 15.0.0: Mapeamento automático entre objetos (DTOs e entidades).
• MediatR 13.0.0: Implementação do padrão Mediator para Commands e Queries.
• FluentValidation 12.0.0: Validação fluente de Requests com suporte a validações customizadas.
• Swagger/OpenAPI: Documentação automática da API com anotações completas.
• HealthChecks: Monitoramento detalhado da saúde da API, banco de dados e dependências externas.
• Biss.MultiSinkLogger: Logging estruturado com suporte a múltiplos sinks (Console, File, SQL Server).
• Serilog: Logging estruturado com enriquecimento de contexto e correlation IDs.
• XUnit e Moq: Testes unitários de infraestrutura, aplicação e API.
• FluentAssertions: Assertions expressivas para testes mais legíveis.
• Bogus: Geração de dados de teste realistas.

🚀 Recursos do Template

🏛️ Arquitetura e Padrões

• Estrutura com suporte a CQRS (Command Query Responsibility Segregation).
• Clean Architecture organizada em camadas independentes.
• Domain-Driven Design com foco no domínio de negócio.
• Specification Pattern para validação de regras de negócio.
• Repository Pattern com interfaces genéricas.
• SOLID Principles aplicados em todo o código.

📊 Observabilidade e Monitoramento

• Biss.MultiSinkLogger para logging multi-destino configurável.
• Health Checks detalhados (API, Database, External Dependencies).
• Global Exception Handler com tratamento centralizado de exceções.
• Correlation IDs para rastreamento de requisições.
• Structured Logging com enriquecimento de contexto.
• HTTP Logging para captura de requisições e respostas.

🛡️ Segurança e Configuração

• CORS configurado por ambiente (Development/Production).
• Configuração robusta de localização (pt-BR, en-US, es).
• Validação de entrada com FluentValidation.
• Tratamento de exceções com ErrorResponse estruturado.
• Headers de segurança configurados.

📝 Response Builders e Handlers

• IResponseBuilder com métodos padronizados.
• ResponseBuilder para construção de respostas consistentes.
• BaseResponse, PagedResponse e ErrorResponse.
• HandleResponseHelper para tratamento de respostas.
• BaseControllerHandle com lógica centralizada.

🧪 Testes e Qualidade

• Testes unitários com XUnit e Moq.
• FluentAssertions para assertions expressivas.
• Bogus para geração de dados de teste.
• Cobertura de código com coverlet.
• Testes organizados por camada (API, Application, Infrastructure).

🔍 Specifications e Validações

• ISpecification e IAsyncSpecification interfaces.
• SpecificationHandler para execução de regras.
• CustomerEmailMustBeUniqueSpecification.
• CustomerDocumentMustBeUniqueSpecification.
• CustomerMustExistSpecification.
• Validação assíncrona de regras de negócio.

📋 Paginação e Filtros

• Paginação avançada com BaseRequest.
• Filtros dinâmicos por múltiplos campos.
• Ordenação flexível com System.Linq.Dynamic.Core.
• Paginação com informações de navegação.
• Headers de paginação (X-Total-Count).

🌐 Internacionalização

• Suporte a múltiplos idiomas (pt-BR, en-US, es).
• Resource files para localização.
• Accept-Language header support.
• Configuração de cultura por requisição.

🔄 Middlewares e Extensões

• GlobalExceptionHandlerMiddleware.
• ConfigureServicesExtension com DI.
• ConfigureMiddlewaresExtension.
• LoggingExtension com Serilog.
• MigrationExtension para EF Core.

📚 Documentação

• Swagger com anotações completas.
• XML documentation em todos os endpoints.
• Exemplos de uso com curl.
• README detalhado com instruções.
• Documentação de arquitetura.

🏗️ Infraestrutura

• AppDbContext com configurações otimizadas.
• ContextMappings para Entity Framework.
• Migrations automáticas aplicadas no startup.
• Serialização JSON configurada.
• Dependency Injection organizado.

🎯 Exemplos Práticos

• CRUD completo de Customers.
• Endereços relacionados.
• Validações de negócio.
• Tratamento de erros.
• Logs estruturados.
• Testes Unitários com xUnit.

🔧 Melhorias Técnicas

• Performance otimizada.
• Código limpo e manutenível.
• Padrões de projeto modernos.
• Boas práticas de desenvolvimento.
• Estrutura escalável.

📦 Como Usar

Após instalar o template:

dotnet new biss-microservice-net9 -n MeuProjeto.Microservice

Isso criará um novo projeto com toda a estrutura pronta para uso.

🚀 Execução Rápida

# Restaurar dependências
dotnet restore

# Executar testes
dotnet test

# Executar a aplicação
dotnet run --project src/MeuProjeto.Microservice.Api

# Acessar Swagger
# https://localhost:7094/swagger

# Acessar Health Checks
# https://localhost:7094/health

📜 Notas da Versão 2.0.0

✨ Novas Funcionalidades

• Specification Pattern implementado para validação de regras de negócio.
• Response Builders padronizados para respostas consistentes.
• Biss.MultiSinkLogger para logging multi-destino.
• Health Checks avançados com verificações detalhadas.
• Paginação e filtros dinâmicos com ordenação flexível.
• Correlation IDs para rastreamento de requisições.
• Global Exception Handler com ErrorResponse estruturado.
• Internacionalização completa com suporte a múltiplos idiomas.

🔧 Melhorias Técnicas

• Performance otimizada em todas as camadas.
• Código mais limpo e manutenível.
• Testes mais robustos com FluentAssertions e Bogus.
• Documentação aprimorada com exemplos práticos.
• Configurações flexíveis por ambiente.

🐛 Correções

• Compatibilidade melhorada com .NET 9.
• Estabilidade aprimorada em todas as operações.
• Bugs conhecidos corrigidos.

🧾 Licença

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

🔗 Informações Adicionais

Empresa: Biss Solutions Contato: contato@biss.com.br Website: https://biss.com.br/

Desenvolvido com ❤️ pela equipe de desenvolvimento da Biss Solutions