Repository navigation
Design Patterns
Esta é a página central de estudo da wiki. Cada padrão usado no PolicyDesk é apresentado com a mesma estrutura:
- Intenção: o que o padrão resolve, em uma frase.
- O problema: como o código ficaria sem ele.
- No PolicyDesk: o código real e onde encontrá-lo.
- Por que funciona: a ideia por trás.
- Custos e alternativas: nenhum padrão é gratuito.
- Para praticar: um exercício curto.
Uma nota antes de começar. Padrões não são objetivos; são vocabulário. Ninguém deveria abrir um projeto pensando "vou usar o padrão X". O caminho é o inverso: você encontra um problema, reconhece que ele já foi resolvido antes e usa o nome do padrão para comunicar a solução. Leia cada seção começando pelo problema.
Arquitetura
- Clean Architecture (camadas e regra de dependência)
- Injeção de Dependência e Inversão de Controle
- Composition Root e Extension Methods de registro
Domínio
- Domínio Rico vs. Domínio Anêmico
- Entity e Layer Supertype
- Always-Valid Entity e Guard Clauses
- Máquina de Estados com transições protegidas
- Encapsulamento de coleção de regras: validadores estáticos
- Aggregate e referência por identidade
Aplicação
Persistência
- Repository
- Repositórios segregados (ISP + CQS)
- Unit of Work
- Optimistic Offline Lock (concorrência otimista)
- Soft Delete com Global Query Filter
- Upsert atômico
- Exception Translation
API e infraestrutura transversal
- Pipeline de Middlewares (Chain of Responsibility)
- Exception Filter e mapeamento exceção → HTTP
- Problem Details (RFC 9457)
- Correlation ID
- Options Pattern com validação na inicialização
- Relógio injetável (
TimeProvidereBusinessClock) - Source-Generated Logging (catálogo de eventos)
- Health Check
- Cooperative Cancellation
- Normalização na borda (JSON Converter)
Testes
- Test Data Builder
- Object Mother
- Fluent Mock Builder
- Shared Fixture com Testcontainers
- Arrange-Act-Assert e nomenclatura de testes
Fechamento
Intenção. Organizar o código em círculos concêntricos, em que as dependências apontam sempre para dentro, protegendo as regras de negócio de detalhes técnicos.
O problema. Em uma aplicação "tudo no controller", o mesmo método valida JSON, monta SQL, aplica regra de negócio e escolhe o status HTTP. Para testar a regra "só sinistros aprovados podem ser pagos", você precisa subir um servidor web e um banco. Trocar o banco significa mexer em todas as regras.
No PolicyDesk.
flowchart TB
subgraph L4[" "]
API[Api]
INF[Infrastructure]
subgraph L3[" "]
APP[Application]
subgraph L2[" "]
DOM[Domain]
end
end
end
| Círculo | Projeto | Pode depender de |
|---|---|---|
| Entidades | Domain |
Nada de framework |
| Casos de uso | Application |
Domain |
| Adaptadores |
Infrastructure, Api
|
Application, Domain
|
O detalhe essencial é a inversão da dependência de persistência. Intuitivamente, a regra de negócio "usa" o banco, então deveria depender dele. Mas é o contrário:
Domain declara IClaimsUpdateOnlyRepository (interface)
Infrastructure implementa ClaimsRepository : IClaimsUpdateOnlyRepository
O domínio define a porta; a infraestrutura fornece o adaptador. Por isso a Clean Architecture também é chamada de Ports and Adapters.
Por que funciona. Código que muda por razões diferentes fica em lugares diferentes. Regras de negócio mudam quando o negócio muda; o ORM muda quando a tecnologia muda. Separá-los evita que uma mudança arraste a outra.
Custos e alternativas.
- Mais projetos, mais interfaces, mais "cerimônia". Para um CRUD simples, pode ser exagero.
-
Vertical Slice Architecture (Jimmy Bogard) é a alternativa mais citada: organiza por funcionalidade (cada slice tem seu endpoint, handler e acesso a dados), aceitando duplicação em troca de independência entre funcionalidades. O PolicyDesk já tem um "sabor" de slices dentro da
Application(Claims/Approve/,Claims/Deny/...).
Para praticar. Abra PolicyDesk.Domain.csproj e confirme que ele não referencia nenhum pacote do EF Core nem do ASP.NET. Depois tente usar DbContext dentro de Claim.cs: o projeto não compila. A arquitetura é garantida pelo compilador.
Intenção. Uma classe recebe as dependências de que precisa, em vez de criá-las.
O problema.
// ❌ Sem DI
public class ApproveClaimUseCase
{
public async Task ExecuteAsync(Guid id)
{
var db = new PolicyDeskDbContext(new DbContextOptionsBuilder()...); // acoplado ao EF e à config
var repo = new ClaimsRepository(db);
// ...
}
}Essa classe não pode ser testada sem banco, não pode trocar de implementação e decide sozinha o tempo de vida do DbContext.
No PolicyDesk.
internal class ApproveClaimUseCase(
IClaimsUpdateOnlyRepository claimsUpdateOnlyRepository,
IUnitOfWork unitOfWork,
ILogger<ApproveClaimUseCase> logger) : IApproveClaimUseCase
{
public async Task ExecuteAsync(Guid claimId, CancellationToken cancellationToken = default)
{
var claim = await claimsUpdateOnlyRepository.GetByIdForUpdateAsync(claimId, cancellationToken)
?? throw new NotFoundException(ResourcesMessageException.CLAIM_NOT_FOUND);
claim.Approve();
await unitOfWork.CommitAsync(cancellationToken);
logger.ClaimApproved(claim.Id);
}
}Observe três técnicas combinadas:
- Injeção por construtor, com a sintaxe de primary constructor do C# 12. Os parâmetros viram campos capturados.
-
Dependência de abstrações (
IClaimsUpdateOnlyRepository), não de classes concretas. É o D do SOLID (Dependency Inversion Principle). -
Classe
internal: ninguém fora do assembly consegue instanciarApproveClaimUseCase. A única porta de entrada é a interfaceIApproveClaimUseCase, resolvida pelo contêiner.
Nos controllers, a injeção é por método:
[HttpPost("sinistros/{id:guid}/aprovacao")]
public async Task<IActionResult> Approve(
[FromRoute] Guid id,
[FromServices] IApproveClaimUseCase useCase,
CancellationToken cancellationToken)O ClaimsController tem sete actions. Com injeção por construtor, cada requisição resolveria os sete casos de uso (e as dependências deles) para usar só um. Com [FromServices], cada action recebe exatamente o que usa.
Por que funciona. A Inversão de Controle tira da classe a responsabilidade de montar o próprio mundo. Quem monta é o contêiner (IServiceProvider), configurado em um único lugar. Nos testes, quem monta é o próprio teste, passando mocks.
Tempos de vida.
| Tempo de vida | Uma instância por... | Uso no PolicyDesk |
|---|---|---|
Transient |
resolução | — |
Scoped |
requisição HTTP | Casos de uso, repositórios, UnitOfWork, DbContext
|
Singleton |
aplicação | Infraestrutura do framework (logging, options) |
A regra de ouro: um serviço nunca deve depender de outro com tempo de vida mais curto. Um Singleton que recebe um DbContext (Scoped) o "captura" para sempre (captive dependency), compartilhando-o entre requisições e threads. O ASP.NET detecta isso em Development (ValidateScopes).
Custos e alternativas. O grafo de dependências fica implícito: para saber o que roda, você precisa olhar o registro. Service Locator (pedir serviceProvider.GetService<T>() dentro da classe) é a alternativa considerada antipadrão, porque esconde as dependências. O único uso legítimo dele no projeto está na borda (DatabaseMigration, executado uma vez na inicialização).
Para praticar. Registre IUnitOfWork como Singleton e rode os testes de integração. Observe os erros e explique por que eles acontecem.
Intenção. Montar o grafo de objetos em um único ponto, o mais perto possível da entrada da aplicação.
No PolicyDesk. Cada camada expõe um método de extensão que registra o que ela sabe registrar:
// Program.cs (a raiz de composição)
builder.Services.AddInfrastructure(builder.Configuration);
builder.Services.AddApplication();// Infrastructure/DependencyInjectionExtension.cs
public static class DependencyInjectionExtension
{
public static void AddInfrastructure(this IServiceCollection services, IConfiguration configuration)
{
services.AddScoped<IClaimsReadOnlyRepository, ClaimsRepository>();
// ...
}
}A
Applicationsegue a mesma forma (AddApplication(this IServiceCollection services)). As duas camadas usavam sintaxes diferentes; hoje ambas usam o método de extensão clássico, por consistência.
Por que funciona. As implementações continuam internal. O Program.cs não sabe que existe uma classe ClaimsRepository; ele só pede "adicione a infraestrutura". Cada camada é dona do próprio registro.
Para praticar. Encontre o teste DependencyInjectionTests na Infrastructure.Tests. Ele verifica que AddInfrastructure falha na inicialização, com mensagem explicativa, quando a connection string não existe. Escreva um teste adicional que monte o ServiceProvider com AddApplication() e AddInfrastructure() e resolva todos os casos de uso. Que tipo de erro esse teste pegaria antes da produção?
Intenção. Colocar o comportamento junto dos dados que ele manipula.
O problema: o Modelo Anêmico. Martin Fowler chamou de Anemic Domain Model o antipadrão em que as entidades são só propriedades públicas e toda a lógica vive em "services":
// ❌ Anêmico
public class Claim
{
public ClaimStatus Status { get; set; }
public DateTime? PaidAt { get; set; }
}
public class ClaimService
{
public void Pay(Claim claim)
{
if (claim.Status != ClaimStatus.Approved) throw ...;
claim.Status = ClaimStatus.Paid;
claim.PaidAt = DateTime.UtcNow;
}
}
// Em outro lugar, alguém esquece a regra:
claim.Status = ClaimStatus.Paid; // compila, e o sinistro foi pago sem aprovaçãoA regra existe, mas nada obriga ninguém a passar por ela.
No PolicyDesk.
public class Claim : Entity
{
public ClaimStatus Status { get; private set; } = ClaimStatus.Pending;
public DateTime? PaidAt { get; private set; }
public void RegisterPayment()
{
EnsureStatus(ClaimStatus.Approved, ResourcesMessageException.CLAIM_MUST_BE_APPROVED_FOR_PAYMENT);
Status = ClaimStatus.Paid;
PaidAt = DateTime.UtcNow;
UpdatedAt = PaidAt;
}
}E o caso de uso fica trivial:
claim.RegisterPayment();
await unitOfWork.CommitAsync(cancellationToken);Por que funciona. O encapsulamento (setters privados) transforma a regra em uma restrição do compilador. O caso de uso faz o que se espera de um orquestrador: busca, delega, persiste. Esse é o princípio Tell, Don't Ask: em vez de perguntar o status e decidir fora, você manda a entidade pagar e ela decide se pode.
Custos e alternativas. Entidades ricas exigem cuidado com ORMs (construtores privados, setters privados mapeados). Para sistemas majoritariamente CRUD, o modelo anêmico com Transaction Script (Fowler) pode ser mais simples e honesto.
Para praticar. Procure no código algum lugar fora de Claim.cs que atribua Status. Você não vai encontrar. Agora tente escrever claim.Status = ClaimStatus.Paid; em um caso de uso e veja o erro de compilação.
Intenção. Entity (Eric Evans, DDD): um objeto definido pela identidade, não pelos atributos. Layer Supertype (Fowler, PoEAA): uma classe base que concentra o comportamento comum a todos os objetos de uma camada.
No PolicyDesk.
public abstract class Entity
{
public Guid Id { get; private set; } = Guid.NewGuid();
public DateTime CreatedAt { get; private set; } = DateTime.UtcNow;
public DateTime? UpdatedAt { get; protected set; }
}Dois sinistros com a mesma descrição, valor e data continuam sendo sinistros diferentes, porque têm Ids diferentes. Isso os distingue de um Value Object (como um CPF ou um valor monetário), que é definido apenas pelos atributos.
Decisões de design.
-
Id gerado pela aplicação (
Guid.NewGuid()): a entidade é completa antes de ser salva, e os casos de uso não precisam de um round-trip ao banco para saber o Id. -
abstract: não faz sentido existir umaEntity"genérica".
Custos e alternativas.
- GUIDs aleatórios (v4) fragmentam índices B-Tree. O .NET 9+ oferece
Guid.CreateVersion7(), ordenado por tempo, que reduz esse problema. É uma melhoria possível. - Uma evolução comum é sobrescrever
Equals/GetHashCodena base para comparar porId. O PolicyDesk não faz isso, então duas instâncias carregadas separadamente com o mesmoIdnão são==.
Para praticar. Implemente Equals e GetHashCode em Entity comparando tipo e Id. Que cuidados são necessários com proxies do EF Core?
Intenção. Always-Valid: uma entidade nunca existe em estado inválido. Guard Clause: verificar pré-condições no início do método e sair cedo (com exceção) se não forem atendidas.
O problema. Se uma entidade pode ser construída inválida, todo código que a usa precisa se defender: "e se a descrição estiver vazia?", "e se o valor for negativo?". A validação se espalha e, inevitavelmente, algum lugar esquece.
No PolicyDesk.
public Policy(Guid policyholderId, string description, decimal coverageAmount,
decimal premiumAmount, DateOnly startDate, DateOnly endDate)
{
if (policyholderId == Guid.Empty)
throw new DomainRuleException(ResourcesMessageException.POLICYHOLDER_REQUIRED);
if (string.IsNullOrWhiteSpace(description))
throw new DomainRuleException(ResourcesMessageException.DESCRIPTION_REQUIRED);
if (coverageAmount <= 0)
throw new DomainRuleException(ResourcesMessageException.COVERAGE_AMOUNT_MUST_BE_POSITIVE);
// ...
if (endDate <= startDate)
throw new DomainRuleException(ResourcesMessageException.POLICY_END_DATE_MUST_BE_AFTER_START_DATE);
PolicyholderId = policyholderId;
// ...
}As guard clauses estão alinhadas à esquerda, uma por regra, sem if aninhados. O "caminho feliz" fica no final, sem indentação.
Por que funciona. Se existe uma instância de Policy, ela é válida. O resto do sistema pode confiar nisso. Essa é a ideia de Design by Contract (Bertrand Meyer): pré-condições verificadas na entrada, invariantes preservadas por todos os métodos.
Uma sutileza importante: o construtor do ORM. O EF Core usa o construtor privado sem parâmetros, que não valida. Veja Modelo de Domínio › O construtor privado para entender por que isso é intencional.
Custos e alternativas.
- Exceções para validação são criticadas por custo e por serem "fluxo de controle". A alternativa é o Result Pattern (
Result<Policy>com sucesso ou lista de erros), popular em bibliotecas comoFluentResultseErrorOr. O PolicyDesk escolheu exceções porque, no domínio, uma violação de invariante é excepcional: a aplicação já validou a entrada antes (veja o Notification Pattern). - Bibliotecas como
Ardalis.GuardClausesoferecemGuard.Against.NullOrWhiteSpace(...). O projeto usaifexplícitos, que não exigem dependência.
Para praticar. Escreva um teste que tente criar new Claim(policyId, "x", -10m, DateTime.UtcNow) e verifique a mensagem. Depois procure esse teste em ClaimsTests.cs.
Intenção. Restringir as mudanças de estado de um objeto a um conjunto explícito de transições válidas.
No PolicyDesk. O sinistro é uma máquina de estados finita:
stateDiagram-v2
direction LR
[*] --> Pending
Pending --> InAnalysis: StartAnalysis()
InAnalysis --> Approved: Approve()
InAnalysis --> Denied: Deny()
Approved --> Paid: RegisterPayment()
Cada transição é um método com uma guarda (o estado de origem exigido):
public void StartAnalysis()
{
EnsureStatus(ClaimStatus.Pending, ResourcesMessageException.CLAIM_MUST_BE_PENDING_FOR_ANALYSIS);
Status = ClaimStatus.InAnalysis;
UpdatedAt = DateTime.UtcNow;
}
private void EnsureStatus(ClaimStatus expected, string error)
{
if (Status != expected)
throw new DomainRuleException(error);
}Comparação com o padrão State (GoF). O padrão State clássico cria uma classe por estado (PendingState, InAnalysisState...), cada uma implementando os métodos da interface e decidindo a transição:
// Padrão State (GoF), apenas para comparação
interface IClaimState
{
IClaimState Approve(Claim claim);
IClaimState Pay(Claim claim);
}
class InAnalysisState : IClaimState
{
public IClaimState Approve(Claim c) => new ApprovedState();
public IClaimState Pay(Claim c) => throw new DomainRuleException("...");
}| Critério | Enum + métodos com guarda (PolicyDesk) | Padrão State (GoF) |
|---|---|---|
| Número de classes | 1 | 1 por estado + interface |
| Persistência | Trivial (um int) |
Exige converter estado ↔ classe |
| Comportamento que varia muito por estado | Viraria muitos if/switch
|
Natural, cada classe cuida do seu |
| Legibilidade com 5 estados e 4 transições | Alta | Excessiva |
Para uma máquina pequena, com comportamento simples em cada transição, o enum com guardas é a escolha mais proporcional. O padrão State compensa quando o mesmo método se comporta de forma muito diferente em cada estado.
Para praticar. Adicione um status Reopened, que permita voltar de Denied para InAnalysis com uma justificativa. Quantos lugares você precisou alterar? Escreva os testes antes (veja ClaimsTests.cs).
Intenção. Concentrar as regras de formato de um conceito (CPF, e-mail, telefone) em um único lugar reaproveitável.
No PolicyDesk. Classes estáticas com a tríade Normalize / IsValid / NormalizeOrThrow:
public static class CpfValidator
{
public static string Normalize(string? cpf) => ...; // "529.982.247-25" → "52998224725"
public static bool IsValid(string? cpf) => ...; // nunca lança
public static string NormalizeOrThrow(string? cpf) => ...; // lança DomainRuleException
}Por que funciona. Cada consumidor escolhe o modo de falha de que precisa: a aplicação usa IsValid para acumular erros; a entidade usa NormalizeOrThrow para garantir a invariante.
Custos e alternativas: Value Objects. A evolução natural seria transformar CPF em um Value Object:
public sealed record Cpf
{
public string Value { get; }
private Cpf(string value) => Value = value;
public static Cpf Create(string? raw) =>
new(CpfValidator.NormalizeOrThrow(raw));
}Com isso, Policyholder.Cpf seria do tipo Cpf, e seria impossível atribuir uma string não validada. É o combate ao Primitive Obsession (usar string para tudo). O custo é o mapeamento extra no EF Core (HasConversion ou complex types).
Para praticar. Implemente o Value Object Email e use-o em Policyholder. Configure o mapeamento com HasConversion(e => e.Value, v => Email.Create(v)).
Intenção. Aggregate (Evans): um conjunto de objetos tratado como unidade de consistência, acessado por uma raiz. Agregados se referenciam apenas por Id.
No PolicyDesk.
public class Claim : Entity
{
public Guid PolicyId { get; private set; } // ✅ referência por Id
// public Policy Policy { get; set; } // ❌ não existe navegação
}O relacionamento existe no banco (chave estrangeira com DeleteBehavior.Restrict), mas não no modelo de objetos:
builder.HasOne<Policy>()
.WithMany()
.HasForeignKey(claim => claim.PolicyId)
.OnDelete(DeleteBehavior.Restrict);Por que funciona.
- Cada transação altera, em regra, um agregado. As fronteiras de consistência ficam claras.
- Não há lazy loading acidental nem grafos enormes carregados para mudar um campo.
-
Restrictimpede apagar uma apólice com sinistros: o histórico é protegido pelo banco.
A consequência. Regras que cruzam agregados ("valor do sinistro ≤ cobertura da apólice") ficam no caso de uso, que carrega os dois e compara. Em um modelo maior, isso poderia virar um Domain Service.
Uma exceção controlada. RegisterPolicyUseCase altera dois agregados na mesma transação: cria a Policy e chama policyholder.RegisterPolicy(). Isso é proposital, para proteger a invariante "segurado inativo não tem apólice vigente" contra concorrência. Veja Optimistic Offline Lock.
Intenção. Representar cada operação de negócio como uma unidade explícita, que orquestra o domínio e a infraestrutura sem conter regra de negócio própria.
No PolicyDesk. Uma interface e uma classe por operação:
Application/Claims/
├── Approve/
│ ├── IApproveClaimUseCase.cs
│ └── ApproveClaimUseCase.cs
├── Deny/
│ ├── IDenyClaimUseCase.cs
│ └── DenyClaimUseCase.cs
...
Todos seguem o mesmo roteiro:
flowchart LR
A[1. Validar entrada] --> B[2. Carregar entidades]
B --> C[3. Delegar ao domínio]
C --> D[4. Commit]
D --> E[5. Log de negócio]
E --> F[6. Mapear resposta]
public async Task<ResponseCreatedJson> ExecuteAsync(Guid policyId, RequestClaimJson request, CancellationToken ct)
{
Validate(request, clock.Today); // 1
var policy = await policiesUpdateOnlyRepository.GetByIdForUpdateAsync(policyId, ct) // 2
?? throw new NotFoundException(ResourcesMessageException.POLICY_NOT_FOUND);
if (policy.IsCancelled) throw ...; // regras entre agregados
if (!policy.IsInForce(request.DataOcorrencia)) throw ...;
var committedAmount = await claimsReadOnlyRepository.SumCommittedAmountAsync(policy.Id, ct);
policy.RegisterClaim(request.Valor, committedAmount); // 3
var claim = new Claim(policy.Id, request.Descricao, request.Valor, request.DataOcorrencia);
await claimsWriteOnlyRepository.AddAsync(claim);
await unitOfWork.CommitAsync(ct); // 4
logger.ClaimRegistered(claim.Id, policy.Id, claim.Amount); // 5
return new ResponseCreatedJson { Id = claim.Id }; // 6
}Relação com o padrão Command. Cada caso de uso tem praticamente um único método (ExecuteAsync). É uma forma do padrão Command (GoF), em que uma operação vira um objeto. Um dos casos de uso se chamava, literalmente, UpdatePolicyholderCommand; foi renomeado para UpdatePolicyholderUseCase, seguindo o padrão dos demais.
Por que funciona.
-
Single Responsibility:
ApproveClaimUseCasemuda por um único motivo, a regra de aprovação. - Testabilidade: cada caso de uso tem poucos colaboradores, todos mockáveis.
- Descoberta: a estrutura de pastas é o índice das funcionalidades.
Custos e alternativas.
- Muitas classes pequenas. Para quem vem de services grandes (
ClaimServicecom 15 métodos), parece fragmentado. - A alternativa popular é o Mediator (biblioteca MediatR): os controllers enviam
new ApproveClaimCommand(id)e um handler trata. Isso traz pipeline behaviors (validação, log e transação aplicados a todos os handlers), mas adiciona uma indireção que dificulta a navegação no código (o "ir para definição" para noSend). O PolicyDesk optou pela chamada direta à interface, que é mais explícita.
Para praticar. Escreva um caso de uso ReopenClaimUseCase seguindo exatamente o roteiro acima. Use o Tutorial como guia.
Intenção. Acumular todos os erros de validação e reportá-los juntos, em vez de falhar no primeiro.
O problema. Um formulário com cinco campos errados. Se a API devolve só o primeiro erro, o usuário corrige, envia, recebe o segundo, corrige, envia... cinco idas e voltas.
No PolicyDesk.
internal static class PolicyholderDataValidator
{
public static List<string> Validate(string? name, DateOnly birthDate, string? email, string? phone, DateOnly today)
{
var errors = new List<string>();
if (string.IsNullOrWhiteSpace(name))
errors.Add(ResourcesMessageException.POLICYHOLDER_NAME_REQUIRED);
else if (FieldLimits.Exceeds(name, FieldLimits.PolicyholderName))
errors.Add(FieldLimits.PolicyholderNameTooLong);
if (!EmailValidator.IsValid(email))
errors.Add(ResourcesMessageException.INVALID_EMAIL);
// ...
return errors;
}
}if (errors.Count > 0)
throw new ErrorOnValidationException(errors); // carrega a lista inteiraResposta ao cliente:
{
"status": 400,
"errors": [
"O nome é obrigatório.",
"Email inválido.",
"O telefone é obrigatório."
]
}Validação em duas camadas: redundância proposital. A mesma regra ("nome obrigatório") é verificada na aplicação e na entidade. Não é duplicação acidental:
| Camada | Objetivo | Estilo |
|---|---|---|
| Aplicação | Experiência do usuário: todos os erros de uma vez | Notification (acumula) |
| Domínio | Integridade: nunca existir entidade inválida | Guard Clause (falha rápido) |
Se amanhã alguém criar um novo caso de uso e esquecer de validar, o domínio ainda protege os dados. A aplicação melhora a experiência; o domínio garante a correção.
Custos e alternativas. A biblioteca FluentValidation é a forma mais comum de implementar esse padrão em .NET (RuleFor(x => x.Name).NotEmpty().MaximumLength(150)). O PolicyDesk usa validação manual, sem dependência externa e com as mesmas constantes do domínio.
Para praticar. Envie um POST /api/segurados com todos os campos vazios e conte os erros devolvidos. Depois envie com CPF inválido e e-mail duplicado ao mesmo tempo: o e-mail duplicado aparece? Por quê? (Dica: a verificação de unicidade depende do banco e só roda depois que o formato é válido.)
Intenção. Data Transfer Object (Fowler): um objeto simples, sem comportamento, que define o formato dos dados que cruzam uma fronteira.
No PolicyDesk. O projeto Communication contém só DTOs:
public class RequestClaimJson
{
public string Descricao { get; set; } = string.Empty;
public decimal Valor { get; set; }
public DateOnly DataOcorrencia { get; set; }
}E o mapeamento de entidade para resposta é manual, dentro do caso de uso:
private static ResponseClaimJson MapToResponse(Domain.Entities.Claim claim) => new()
{
Id = claim.Id,
ApoliceId = claim.PolicyId,
Descricao = claim.Description,
Valor = claim.Amount,
Status = claim.Status.ToContract(), // ClaimStatus.InAnalysis → StatusSinistro.EmAnalise
// ...
};Os status têm enums próprios no contrato (StatusSinistro, StatusApolice), em português, e o StatusMapping converte nos dois sentidos. O Communication não referencia o Domain: um cliente .NET pode usar os contratos sem levar o domínio junto, e renomear um valor do domínio não muda a API.
Por que não expor a entidade diretamente?
-
Segurança: a entidade tem campos internos (como a versão de concorrência) que não devem vazar. Aceitar a entidade como entrada permitiria mass assignment (o cliente enviar
"status": "Paid"). - Estabilidade do contrato: renomear uma propriedade da entidade não quebra os clientes.
-
Formas diferentes: a entrada de criação, a de atualização e a saída têm campos diferentes (
RequestUpdatePolicyholderJsonnão tem CPF, porque CPF não muda).
Mapeamento manual vs. AutoMapper. O mapeamento manual é verboso, mas é verificado pelo compilador, fácil de depurar e não tem "mágica" por convenção. Uma propriedade renomeada quebra a compilação, não a produção. Bibliotecas geradas em tempo de compilação, como Mapperly, são um meio-termo.
Contratos padronizados. Todos os requests e responses usam nomes em português (Nome, Telefone, ValorCobertura, CriadoEm), enquanto o domínio fica em inglês. O DTO é a fronteira onde a tradução acontece. As listagens paginadas usam um envelope genérico, ResponsePagedJson<T> (itens, pagina, tamanhoPagina, totalItens, totalPaginas).
Intenção. (Fowler, PoEAA) "Mediar entre o domínio e a camada de mapeamento de dados usando uma interface semelhante a uma coleção de objetos de domínio."
No PolicyDesk.
// Domínio: o contrato
public interface IClaimsReadOnlyRepository
{
Task<Claim?> GetByIdAsync(Guid id, CancellationToken cancellationToken = default);
Task<IEnumerable<Claim>> GetByPolicyId(Guid policyId, CancellationToken cancellationToken = default);
}
// Infraestrutura: a implementação
internal sealed class ClaimsRepository(PolicyDeskDbContext dbContext) : IClaimsReadOnlyRepository, ...
{
public async Task<IEnumerable<Claim>> GetByPolicyId(Guid policyId, CancellationToken ct)
{
return await dbContext.Claims
.AsNoTracking()
.Where(claim => claim.PolicyId == policyId)
.OrderBy(claim => claim.CreatedAt)
.ToListAsync(ct);
}
}"O DbContext já não é um repositório?" É uma discussão clássica. O DbSet<T> já é um Repository e o DbContext já é um Unit of Work. Por que criar outra camada?
| Argumento a favor da camada extra | Argumento contra |
|---|---|
| O domínio não referencia o EF Core | Mais código, mais indireção |
Consultas com nome de negócio (HasActiveOrFuturePolicy) |
Abstração "vazada": o domínio ainda assume certas semânticas do ORM |
| Casos de uso testáveis com mocks simples | Mockar DbSet é difícil, mas testes com banco real (Testcontainers) resolvem |
Permite SQL especializado (RegisterOrReactivate) sem expor isso |
— |
No PolicyDesk a camada se paga, principalmente pela regra de dependência (o domínio não conhece o EF) e pelas consultas com nome de negócio.
Retorno IEnumerable materializado, nunca IQueryable. Os repositórios chamam ToListAsync antes de retornar. Devolver IQueryable deixaria o chamador montar consultas arbitrárias, vazando o ORM para fora da infraestrutura.
Intenção. Dividir a interface de persistência de cada agregado por intenção de uso: ler, inserir ou alterar.
No PolicyDesk. Cada agregado tem três interfaces:
| Interface | Métodos típicos | Rastreamento no EF |
|---|---|---|
I...ReadOnlyRepository |
GetByIdAsync, GetPageAsync, consultas |
AsNoTracking() |
I...WriteOnlyRepository |
Add |
— |
I...UpdateOnlyRepository |
GetByIdForUpdate |
Com rastreamento |
E uma única classe implementa as três:
internal sealed class ClaimsRepository(PolicyDeskDbContext dbContext) :
IClaimsWriteOnlyRepository,
IClaimsReadOnlyRepository,
IClaimsUpdateOnlyRepositoryCompare as duas buscas por Id:
public Task<Claim?> GetByIdAsync(Guid id, CancellationToken ct) =>
dbContext.Claims.AsNoTracking().FirstOrDefaultAsync(c => c.Id == id, ct);
public Task<Claim?> GetByIdForUpdateAsync(Guid id, CancellationToken ct) =>
dbContext.Claims.FirstOrDefaultAsync(c => c.Id == id, ct);Por que funciona. Duas ideias se combinam:
-
Interface Segregation Principle (o I do SOLID): "nenhum cliente deve depender de métodos que não usa".
ListClaimsUseCaserecebe sóIClaimsReadOnlyRepository. Ele não consegue alterar um sinistro, porque não tem acesso a nenhum método que faça isso. -
Command-Query Separation (Bertrand Meyer): métodos ou consultam, ou alteram, nunca os dois. Aqui a separação vai até o EF Core:
- Consultas usam
AsNoTracking(): mais rápidas, menos memória, sem risco de uma alteração acidental ser salva. - Buscas para alteração usam rastreamento: o change tracker detecta o que mudou e gera o
UPDATE.
- Consultas usam
Só de olhar o construtor de um caso de uso, você sabe o que ele faz:
internal class ApproveClaimUseCase(
IClaimsUpdateOnlyRepository ..., // altera sinistros
IUnitOfWork ..., // confirmainternal class ListClaimsUseCase(
IClaimsReadOnlyRepository ..., // só lê sinistros
IPoliciesReadOnlyRepository ...) // só lê apólicesRelação com CQRS. Isso não é CQRS completo (modelos separados de leitura e escrita, possivelmente bancos separados), mas é o mesmo princípio em escala menor. É um bom primeiro passo, que permitiria, por exemplo, apontar as leituras para uma réplica sem mexer nos casos de uso.
Para praticar. Em GetByIdForUpdate, troque para AsNoTracking() e rode ApproveClaimUseCase em um teste de integração. O que acontece com a aprovação? Por quê?
Intenção. (Fowler) "Manter uma lista de objetos afetados por uma transação de negócio e coordenar a gravação das mudanças."
No PolicyDesk.
public interface IUnitOfWork
{
Task CommitAsync(CancellationToken cancellationToken = default);
}
internal class UnitOfWork(PolicyDeskDbContext dbContext) : IUnitOfWork
{
public async Task CommitAsync(CancellationToken cancellationToken = default)
{
try
{
await dbContext.SaveChangesAsync(cancellationToken);
}
catch (DbUpdateConcurrencyException)
{
throw new ConflictException(ResourcesMessageException.CONCURRENCY_CONFLICT);
}
catch (DbUpdateException exception) when (exception.InnerException is PostgresException
{ SqlState: PostgresErrorCodes.UniqueViolation, ConstraintName: ActiveEmailIndex })
{
throw new ErrorOnValidationException(ResourcesMessageException.POLICYHOLDER_ACTIVE_EMAIL_EXISTS);
}
}
}Por que funciona. Os repositórios não salvam. AddAsync só registra a entidade no contexto; GetByIdForUpdateAsync só a coloca sob rastreamento. Quem decide quando tudo vai para o banco é o caso de uso, chamando CommitAsync() uma vez, no final.
Em RegisterPolicyUseCase, isso garante que a nova apólice e a alteração no segurado são gravadas na mesma transação (o SaveChanges do EF Core é transacional). Ou as duas mudanças acontecem, ou nenhuma.
sequenceDiagram
participant UC as RegisterPolicyUseCase
participant PH as Policyholder (rastreado)
participant RP as PoliciesRepository
participant UoW as UnitOfWork
participant DB as PostgreSQL
UC->>PH: RegisterPolicy() (marca alterado)
UC->>RP: Add(policy) (marca adicionado)
UC->>UoW: CommitAsync()
UoW->>DB: BEGIN
UoW->>DB: INSERT INTO policies ...
UoW->>DB: UPDATE policyholders ... WHERE xmin = @v
UoW->>DB: COMMIT
Testes. Os testes de aplicação verificam explicitamente que o Commit não é chamado quando há erro:
await Should.ThrowAsync<NotFoundException>(() => useCase.ExecuteAsync(Guid.NewGuid()));
unitOfWork.Verify(work => work.CommitAsync(), Times.Never);Para praticar. Em RegisterClaimUseCase, mova o Commit para antes das validações de vigência. Que teste quebra? O que isso garante?
Intenção. (Fowler) Detectar conflitos entre transações concorrentes verificando, no momento da gravação, se o registro mudou desde a leitura. Em vez de bloquear (pessimista), assume-se que conflitos são raros e trata-se o conflito quando ele acontece.
O problema. Dois analistas abrem o mesmo sinistro em análise. Um aprova, o outro nega, quase ao mesmo tempo:
t1 Analista A lê sinistro (InAnalysis)
t2 Analista B lê sinistro (InAnalysis)
t3 A: claim.Approve() → UPDATE status = Approved
t4 B: claim.Deny() → UPDATE status = Denied ← sobrescreve a aprovação!
Cada requisição, isoladamente, passou na guarda EnsureStatus(InAnalysis). O resultado final é inconsistente: um sinistro negado com ApprovedAt preenchido. Isso se chama lost update.
No PolicyDesk. O PostgreSQL tem uma coluna de sistema, xmin, que muda a cada UPDATE da linha. O Npgsql permite usá-la como token de concorrência:
// ClaimMap.cs
builder.Property<uint>("Version").IsRowVersion();Version é uma shadow property: existe no modelo do EF, mas não na classe Claim. O domínio não fica poluído com um detalhe de persistência.
Com isso, o EF Core gera:
UPDATE claims SET status = 2, approved_at = ..., updated_at = ...
WHERE id = @id AND xmin = @versao_lida;Se outra transação já alterou a linha, o xmin mudou, o WHERE não encontra nada, 0 linhas são afetadas e o EF lança DbUpdateConcurrencyException. O UnitOfWork a traduz em ConflictException, que vira HTTP 409:
{
"status": 409,
"errors": ["O registro foi alterado por outra operação. Consulte novamente e repita a solicitação."]
}A linha do tempo passa a ser:
t3 A: UPDATE ... WHERE xmin = 100 → 1 linha ✅ (xmin vira 101)
t4 B: UPDATE ... WHERE xmin = 100 → 0 linhas ❌ → 409 Conflict
O teste ClaimConcurrencyTests.Deve_AceitarApenasUmaDecisao_Quando_AprovarENegarAoMesmoTempo dispara as duas requisições em paralelo e verifica que exatamente uma é aceita.
Há um caso mais sutil. A regra S9 diz: "não é possível inativar um segurado com apólice vigente". Considere:
t1 Inativação: verifica HasActiveOrFuturePolicy → false (ainda não há apólice)
t2 Emissão: verifica segurado.Active → true
t3 Emissão: INSERT apólice
t4 Inativação: UPDATE segurado SET active = false ← segurado inativo com apólice!
As duas operações tocam tabelas diferentes, então o token de versão da apólice não ajuda. A solução é fazer a emissão também alterar o segurado:
// Policyholder.cs
public void RegisterPolicy()
{
UpdatedAt = DateTime.UtcNow;
}Agora as duas operações escrevem na mesma linha de policyholders, e o xmin faz uma delas falhar com 409. É uma técnica conhecida como "touch" do agregado pai, ou concurrency token no agregado raiz.
Custos e alternativas.
| Abordagem | Como | Quando usar |
|---|---|---|
| Otimista (usado) | Token de versão, falha no conflito | Conflitos raros, leituras longas |
| Pessimista | SELECT ... FOR UPDATE |
Conflitos frequentes, transações curtas |
Isolamento SERIALIZABLE
|
O banco detecta anomalias | Regras complexas, aceita reprocessar |
| Restrição no banco |
CHECK, índice único, exclusion constraint
|
Quando a regra cabe em SQL |
O cliente que recebe 409 deve reler o recurso e decidir se repete a operação. A API não tenta de novo sozinha, porque a decisão do usuário pode mudar ao ver o novo estado.
Para praticar. Exponha a versão como um ETag no GET /api/sinistros/{id} e exija If-Match nas transições. Isso estende a concorrência otimista até o cliente (o caso "abri a tela há 10 minutos").
Intenção. Marcar registros como removidos em vez de apagá-los, e filtrá-los automaticamente das consultas.
No PolicyDesk.
// PolicyholderMap.cs
public const string ActiveFilter = "ActivePolicyholders";
builder.HasQueryFilter(ActiveFilter, policyholder => policyholder.Active);Toda consulta a Policyholders ganha um WHERE active = TRUE implícito. Quando é preciso ver os inativos, o filtro é desligado pelo nome:
public Task<Policyholder?> GetByIdIncludingInactiveAsync(Guid id, CancellationToken ct)
{
return dbContext.Policyholders
.IgnoreQueryFilters([PolicyholderMap.ActiveFilter])
.FirstOrDefaultAsync(p => p.Id == id, ct);
}Filtros nomeados são novidade do EF Core 10. Antes,
IgnoreQueryFilters()desligava todos os filtros da entidade de uma vez. Com nomes, um futuro filtro de multi-tenant continuaria ativo.
Por que existe GetByIdIncludingInactive? Para a mensagem de erro certa. Ao emitir uma apólice para um segurado inativo, a resposta deve ser "segurado está inativo" (400), e não "segurado não encontrado" (404).
Unicidade com soft delete. O índice de e-mail é filtrado:
builder.HasIndex(p => p.Email)
.HasDatabaseName("IX_policyholders_email_active")
.IsUnique()
.HasFilter("\"active\" = TRUE");Isso permite que um e-mail usado por um segurado inativo seja reutilizado, mas nunca por dois ativos. É um índice parcial do PostgreSQL.
Custos. É fácil esquecer que o filtro existe e se surpreender com um "não encontrado". Relatórios e joins precisam considerar os inativos de forma explícita.
Intenção. Inserir um registro ou, se ele já existir, atualizá-lo, em uma única instrução atômica.
O problema. A regra S8 diz que cadastrar o CPF de um segurado inativo o reativa. A implementação ingênua tem uma race condition:
// ❌ Check-then-act
var existing = await db.Policyholders.IgnoreQueryFilters().FirstOrDefaultAsync(p => p.Cpf == cpf);
if (existing is null) db.Add(novo); // duas requisições podem chegar aqui juntas
else if (!existing.Active) existing.Reactivate(...);
else throw CpfDuplicado;No PolicyDesk. O repositório usa o INSERT ... ON CONFLICT do PostgreSQL:
INSERT INTO policyholders (id, name, cpf, birth_date, email, phone, created_at, updated_at, active)
VALUES (...)
ON CONFLICT (cpf) DO UPDATE
SET name = EXCLUDED.name,
birth_date = EXCLUDED.birth_date,
email = EXCLUDED.email,
phone = EXCLUDED.phone,
active = TRUE,
updated_at = CURRENT_TIMESTAMP
WHERE policyholders.active = FALSE
RETURNING idO resultado é interpretado pelas linhas devolvidas pelo RETURNING:
| Situação | Linhas devolvidas | Resultado |
|---|---|---|
| CPF novo | 1 (INSERT), com o id novo | RegisteredOrReactivated |
| CPF de inativo | 1 (UPDATE), com o id original | RegisteredOrReactivated |
| CPF de ativo | 0 (o WHERE do UPDATE falha) |
ActiveCpfAlreadyExists |
| E-mail de outro ativo | exceção 23505 no índice de e-mail |
ActiveEmailAlreadyExists |
O repositório devolve um resultado, não lança exceção: PolicyholderRegistration(Result, PolicyholderId). O caso de uso decide a mensagem e responde o id gravado:
switch (registration.Result)
{
case PolicyholderRegistrationResult.ActiveCpfAlreadyExists:
throw new ErrorOnValidationException(ResourcesMessageException.POLICYHOLDER_ACTIVE_CPF_EXISTS);
case PolicyholderRegistrationResult.ActiveEmailAlreadyExists:
throw new ErrorOnValidationException(ResourcesMessageException.POLICYHOLDER_ACTIVE_EMAIL_EXISTS);
case PolicyholderRegistrationResult.RegisteredOrReactivated:
logger.PolicyholderRegisteredOrReactivated();
return new ResponseCreatedJson { Id = registration.PolicyholderId ?? policyholder.Id };
default:
throw new UnreachableException($"Resultado de cadastro inesperado: {registration.Result}");
}Detalhe de segurança. SqlQuery com string interpolada transforma cada {valor} interpolado em um parâmetro SQL, não em texto concatenado. Não há risco de SQL injection, mesmo com SQL escrito à mão.
Custos. SQL específico do PostgreSQL (não portável) e fora do change tracker. É um trade-off consciente: a atomicidade vale mais que a portabilidade.
Intenção. Converter exceções de uma camada inferior em exceções com significado para a camada superior, sem vazar detalhes de implementação.
No PolicyDesk. O UnitOfWork é o ponto de tradução:
| Exceção do EF/Npgsql | Significado técnico | Traduzida para | HTTP |
|---|---|---|---|
DbUpdateConcurrencyException |
0 linhas no UPDATE com versão | ConflictException |
409 |
PostgresException 23505 no IX_policyholders_email_active
|
Violação do índice único | ErrorOnValidationException |
400 |
O filtro when com pattern matching só captura a exceção exata:
catch (DbUpdateException exception) when (exception.InnerException is PostgresException
{ SqlState: PostgresErrorCodes.UniqueViolation, ConstraintName: ActiveEmailIndex })Qualquer outra violação continua sendo um erro inesperado (500), em vez de ser mascarada como erro do usuário.
Por que a verificação no banco, se o caso de uso já verifica? UpdatePolicyholderUseCase consulta ExistActivePolicyholdersWithEmailAsync antes de salvar. Mas duas atualizações simultâneas podem passar pela consulta ao mesmo tempo. O índice é a última linha de defesa, e a tradução garante que essa defesa produza a mesma mensagem amigável da verificação prévia.
Intenção. Processar uma requisição por uma sequência de componentes, em que cada um pode agir antes e depois do próximo, ou interromper a cadeia. É uma variação do padrão Chain of Responsibility (GoF), com características de Decorator.
No PolicyDesk.
app.UseCorrelationIdHeader();
app.UseHttpLogging();
app.UseErrorHandling();
app.UseRequestLocalization();
// ...
app.MapControllers();flowchart LR
R[Requisição] --> A[CorrelationId] --> B[HttpLogging] --> C[ExceptionHandler] --> D[Localization] --> E[Controller]
E -.resposta.-> D -.-> C -.-> B -.-> A -.-> S[Resposta]
Um middleware customizado, em forma mínima:
app.Use((context, next) =>
{
var traceId = Get(context);
context.Response.OnStarting(() =>
{
context.Response.Headers[HeaderName] = traceId;
return Task.CompletedTask;
});
return next(context); // passa adiante
});A ordem é semântica. O log de requisições envolve o tratamento de erros, então registra o status final. Se estivesse dentro, veria a exceção passar, mas não o 500 que o handler produz depois.
Detalhe técnico: OnStarting. O cabeçalho não é escrito imediatamente, mas no instante em que a resposta começa a ser enviada. Motivo: o UseExceptionHandler limpa os cabeçalhos antes de escrever o erro. Se o X-Trace-Id fosse escrito no início, desapareceria justamente nas respostas de erro, que são as que mais precisam dele.
Intenção. Centralizar a conversão de exceções em respostas HTTP, tirando try/catch dos controllers.
No PolicyDesk.
public class ExceptionFilter(ProblemDetailsFactory problemDetailsFactory, ILogger<ExceptionFilter> logger) : IExceptionFilter
{
public void OnException(ExceptionContext context)
{
switch (context.Exception)
{
case ErrorOnValidationException e: SetErrorResult(context, 400, e.GetErrors()); break;
case DomainRuleException e: SetErrorResult(context, 400, [e.Message]); break;
case NotFoundException e: SetErrorResult(context, 404, [e.Message]); break;
case ConflictException e: SetErrorResult(context, 409, [e.Message]); break;
case BadHttpRequestException e: SetErrorResult(context, e.StatusCode, [INVALID_REQUEST]); break;
case OperationCanceledException when context.HttpContext.RequestAborted.IsCancellationRequested:
context.Result = new StatusCodeResult(499); break;
default:
logger.UnhandledException(...);
SetErrorResult(context, 500, [UNKNOWN_ERROR]); break;
}
}
}Registrado globalmente:
builder.Services.AddControllers(options => options.Filters.Add<ExceptionFilter>());A hierarquia de exceções como linguagem.
classDiagram
Exception <|-- PolicyDeskException
PolicyDeskException <|-- ErrorOnValidationException
PolicyDeskException <|-- DomainRuleException
PolicyDeskException <|-- NotFoundException
PolicyDeskException <|-- ConflictException
class PolicyDeskException { <<abstract>> }
class ErrorOnValidationException { +GetErrors() List~string~ }
O domínio e a aplicação lançam exceções semânticas ("não encontrado", "conflito"), sem saber nada de HTTP. Só o filtro sabe que NotFoundException significa 404. Trocar a API REST por gRPC exigiria só um novo tradutor.
Segurança. No default, o detalhe da exceção vai só para o log. O cliente recebe uma mensagem genérica e o traceId. Expor stack traces revelaria a estrutura interna do sistema.
Filtro vs. middleware. O filtro só pega exceções lançadas dentro do MVC. Para exceções em middlewares, existe a rede de segurança UseExceptionHandler(). Uma alternativa moderna ao filtro é implementar IExceptionHandler (ASP.NET Core 8+), que funciona no nível do middleware.
Intenção. Usar um formato padronizado (RFC 9457, sucessora da RFC 7807) para descrever erros em APIs HTTP.
No PolicyDesk. Todas as respostas de erro, inclusive as geradas pelo próprio framework (404 de rota, 405, 415), seguem:
{
"type": "https://tools.ietf.org/html/rfc9110#section-15.5.5",
"title": "Not Found",
"status": 404,
"instance": "/api/sinistros/3fa85f64-5717-4562-b3fc-2c963f66afa6",
"errors": ["Sinistro não encontrado."],
"traceId": "4bf92f3577b34da6a3ce929d0e0e4736"
}errors e traceId são extensões permitidas pela RFC. A configuração em ProblemDetailsSetup garante três coisas:
-
CustomizeProblemDetailsadicionainstance,traceIdeerrorsa qualquer ProblemDetails gerado. -
InvalidModelStateResponseFactorysubstitui a resposta padrão de JSON malformado, que usariaerrorscomo dicionário, pela mesma lista das demais respostas. -
UseStatusCodePagesdá corpo às respostas que sairiam vazias (404 de rota, 405).
Por que um formato único? O cliente escreve um tratador de erro. Sem padronização, ele precisaria lidar com { "message": ... } em um endpoint, { "errors": { "Name": [...] } } em outro e corpo vazio em um terceiro.
Uma sutileza: PostConfigure.
services.PostConfigure<ApiBehaviorOptions>(options => options.InvalidModelStateResponseFactory = ...);AddControllers() registra a fábrica padrão. Um Configure comum poderia rodar antes e ser sobrescrito. PostConfigure roda depois de todos os Configure, garantindo a última palavra.
Intenção. Atribuir um identificador único a cada requisição e propagá-lo por logs, traces e respostas, para correlacionar tudo o que aconteceu nela.
No PolicyDesk. O identificador é o trace id do W3C Trace Context, o mesmo usado pelo OpenTelemetry:
public static string Get(HttpContext httpContext) =>
Activity.Current?.TraceId.ToHexString() ?? httpContext.TraceIdentifier;Ele aparece em três lugares:
| Lugar | Para quem |
|---|---|
Cabeçalho X-Trace-Id em toda resposta |
Cliente, suporte |
Campo traceId nos erros |
Cliente, ao reportar um problema |
| Logs e traces exportados | Equipe de operação |
O fluxo de suporte fica: o usuário informa o traceId → a equipe busca no Aspire Dashboard (ou Jaeger, Grafana Tempo...) → vê o trace completo, com as consultas SQL e o log do erro.
Por que reaproveitar o trace id em vez de gerar um GUID próprio? Porque assim é o mesmo valor em todas as ferramentas. Um ID próprio exigiria anexá-lo manualmente a cada log e trace.
Intenção. Representar uma seção de configuração como uma classe tipada, injetável e validável.
No PolicyDesk.
public sealed class DatabaseOptions
{
public const string SectionName = "ConnectionStrings";
public string DbConnection { get; init; } = string.Empty;
}services.AddOptions<DatabaseOptions>()
.Bind(configuration.GetSection(DatabaseOptions.SectionName))
.Validate(options => !string.IsNullOrWhiteSpace(options.DbConnection),
ResourcesMessageException.MISSING_CONNECTION_STRING)
.ValidateOnStart();
services.AddOptions<BusinessOptions>()
.Bind(configuration.GetSection(BusinessOptions.SectionName))
.Validate(options => !string.IsNullOrWhiteSpace(options.TimeZone) && TimeZoneInfo.TryFindSystemTimeZoneById(options.TimeZone, out _),
ResourcesMessageException.INVALID_BUSINESS_TIME_ZONE)
.ValidateOnStart();
services.AddDbContext<PolicyDeskDbContext>((serviceProvider, config) =>
config.UseNpgsql(serviceProvider.GetRequiredService<IOptions<DatabaseOptions>>().Value.DbConnection));ValidateOnStart: fail fast. Sem ele, a validação só aconteceria na primeira requisição que usasse o banco. Com ele, a aplicação nem sobe se a configuração estiver errada, e a mensagem explica como corrigir. Em um orquestrador como Kubernetes, o pod falha no deploy, não às 3 da manhã.
O fuso de negócio (Business:TimeZone) segue o mesmo caminho: a BusinessOptions valida que o identificador existe no sistema, e o BusinessClock é registrado a partir dela. Um America/Inexistente derruba a aplicação na subida, com a mensagem do .resx.
Por que não configuration["ConnectionStrings:DbConnection"] direto? Strings mágicas espalhadas, sem validação, sem tipo, sem um lugar óbvio para documentar a configuração.
Intenção. Tratar "agora" como uma dependência, em vez de uma chamada estática (DateTime.UtcNow), para que o tempo possa ser controlado e para que "hoje" seja calculado no fuso certo.
O problema. Uma regra como "a data de ocorrência não pode ser futura" com DateTime.UtcNow.Date tem dois defeitos: usa o dia em UTC (às 22h em Brasília, já é amanhã) e não pode ser testada em um horário específico sem esperar o relógio.
No PolicyDesk.
public sealed class BusinessClock(TimeProvider timeProvider, TimeZoneInfo timeZone)
{
public DateTime UtcNow => timeProvider.GetUtcNow().UtcDateTime;
public DateOnly Today => DateOnly.FromDateTime(TimeZoneInfo.ConvertTime(timeProvider.GetUtcNow(), timeZone).DateTime);
}services.TryAddSingleton(TimeProvider.System);
services.AddSingleton(serviceProvider => new BusinessClock(
serviceProvider.GetRequiredService<TimeProvider>(),
TimeZoneInfo.FindSystemTimeZoneById(serviceProvider.GetRequiredService<IOptions<BusinessOptions>>().Value.TimeZone)));- O
TimeProvideré a abstração de tempo do próprio .NET (8+). Em produção,TimeProvider.System; nos testes,FakeTimeProvider. - O
TryAddSingletondeixa o teste registrar o relógio falso antes, sem precisar remover o real. - O caso de uso pede
clock.Todaye passa o dia como parâmetro para a entidade e para o repositório. O domínio continua sem dependência de relógio:new Policyholder(..., today).
Alternativas. Uma interface própria (IClock, IDateTimeProvider) era o caminho comum antes do .NET 8. O Ambient Context (um SystemTime.Now estático e substituível) é mais curto, mas esconde a dependência e vaza estado entre testes paralelos.
Intenção. Definir os eventos de log como métodos tipados, com o código de logging gerado em tempo de compilação.
No PolicyDesk.
// Catálogo dos eventos de log de negócio.
// Faixas de EventId: 1xxx sinistros, 2xxx apólices, 3xxx segurados.
internal static partial class ApplicationLogs
{
[LoggerMessage(EventId = 1001, Level = LogLevel.Information,
Message = "Sinistro {ClaimId} registrado na apólice {PolicyId} no valor de {Amount}")]
public static partial void ClaimRegistered(this ILogger logger, Guid claimId, Guid policyId, decimal amount);
}Uso:
logger.ClaimRegistered(claim.Id, policy.Id, claim.Amount);Por que funciona.
| Benefício | Explicação |
|---|---|
| Desempenho | O gerador cria código que verifica o nível antes de tudo e evita boxing de Guid e decimal. logger.LogInformation($"...") aloca a string sempre, mesmo com o log desligado. |
| Logs estruturados |
{ClaimId} vira um campo pesquisável, não texto solto. |
| Catálogo | Todos os eventos ficam em um arquivo, com EventId único. A operação pode criar alertas por EventId = 9001. |
| Proteção de dados | O catálogo deixa claro o que é logado: só IDs e valores. Não há como "escapar" um CPF sem editar o catálogo. Repare que PolicyholderRegisteredOrReactivated não loga nem o Id. |
O analisador CA1848 do .NET, que existe desde o .NET 6 (junto com o gerador [LoggerMessage]), aponta qualquer chamada direta a LogInformation(...) e similares. Ele faz parte do conjunto latest-recommended como aviso, e com TreatWarningsAsErrors uma chamada direta quebra o build do PolicyDesk. Por isso nenhum log usa os métodos Log* diretamente: todos passam pelos catálogos.
Antes do .NET 6, a mesma otimização exigia LoggerMessage.Define, escrito à mão:
private static readonly Action<ILogger, Guid, Exception?> _claimApproved =
LoggerMessage.Define<Guid>(LogLevel.Information, new EventId(1003, "ClaimApproved"),
"Sinistro {ClaimId} aprovado");
public static void ClaimApproved(this ILogger logger, Guid claimId) =>
_claimApproved(logger, claimId, null);O gerador [LoggerMessage] produz esse código a partir da assinatura do método.
Intenção. Expor um endpoint que informa se a aplicação e suas dependências estão saudáveis.
No PolicyDesk.
services.AddHealthChecks().AddDbContextCheck<PolicyDeskDbContext>("database");
app.MapHealthChecks("/health");| Situação | Resposta |
|---|---|
| Banco acessível |
200 OK com corpo Healthy
|
| Banco fora |
503 Service Unavailable com corpo Unhealthy
|
Orquestradores (Docker, Kubernetes, load balancers) usam esse endpoint para decidir se mandam tráfego para a instância. Em produção, é comum separar liveness (o processo está vivo?) de readiness (consegue atender?), para que uma queda do banco não faça o orquestrador reiniciar instâncias saudáveis em loop.
Intenção. Permitir que uma operação longa seja interrompida quando seu resultado não é mais necessário.
No PolicyDesk. O ASP.NET injeta um CancellationToken ligado a HttpContext.RequestAborted. Ele é passado do controller até o banco:
Controller(cancellationToken)
→ useCase.ExecuteAsync(id, cancellationToken)
→ repository.GetByIdForUpdateAsync(id, cancellationToken)
→ FirstOrDefaultAsync(..., cancellationToken) ← o Npgsql cancela a consulta no servidor
→ unitOfWork.CommitAsync(cancellationToken)
Se o cliente fecha a conexão, a consulta é cancelada no PostgreSQL, liberando recursos. O filtro reconhece o caso e responde 499 (convenção do nginx para "cliente fechou a requisição"), registrando um log informativo, e não um erro:
case OperationCanceledException when context.HttpContext.RequestAborted.IsCancellationRequested:
logger.RequestCancelled(...);
context.Result = new StatusCodeResult(StatusClientClosedRequest);A condição when é importante: um OperationCanceledException sem o cliente ter desistido (um timeout interno, por exemplo) continua sendo tratado como erro 500.
Cooperativo significa que o cancelamento não interrompe a thread à força. Cada método decide repassar o token, e é por isso que ele precisa ser propagado manualmente por todas as camadas.
Intenção. Limpar os dados de entrada no ponto em que entram no sistema, para que nenhuma camada interna precise se preocupar com isso.
No PolicyDesk. Um JsonConverter<string> global:
public partial class StringConverter : JsonConverter<string>
{
public override string? Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
{
var value = reader.GetString()?.Trim();
return value is null ? value : RemoveExtraWhitespace().Replace(value, " ").Trim();
}
[GeneratedRegex(@"\s+")]
private static partial Regex RemoveExtraWhitespace();
}" Maria da Silva " chega ao caso de uso como "Maria da Silva". Isso vale para todas as strings de todos os requests.
[GeneratedRegex] é outro gerador de código: a expressão regular é compilada em C# no build, sem custo de interpretação em tempo de execução.
Intenção. (Nat Pryce, Growing Object-Oriented Software, Guided by Tests) Criar objetos de teste com valores padrão válidos, permitindo sobrescrever apenas o que importa para cada teste.
No PolicyDesk.
public static class RequestPolicyJsonBuilder
{
public static RequestPolicyJson Build(
Guid? policyholderId = null,
string? description = null,
decimal? coverageAmount = null,
decimal? premiumAmount = null,
DateOnly? startDate = null,
DateOnly? endDate = null)
{
var faker = new Faker();
var today = BusinessClockBuilder.DefaultToday;
return new RequestPolicyJson
{
SeguradoId = policyholderId ?? Guid.NewGuid(),
Descricao = description ?? faker.Commerce.ProductName(),
ValorCobertura = coverageAmount ?? faker.Finance.Amount(1000, 100000),
ValorPremio = premiumAmount ?? faker.Finance.Amount(10, 1000),
InicioVigencia = startDate ?? today.AddDays(-1),
FimVigencia = endDate ?? today.AddDays(30)
};
}
}Uso em um teste:
var request = RequestPolicyJsonBuilder.Build(coverageAmount: 0);Por que funciona. O teste diz só o que importa para ele ("cobertura zero"). Todo o resto é válido por padrão. Quando um campo obrigatório novo é adicionado ao request, só o builder muda, não os 50 testes que criam requests. Os dados aleatórios do Bogus ainda ajudam a revelar suposições escondidas (um teste que só passa com um valor específico).
Repare que este "builder" usa parâmetros opcionais nomeados, e não a interface fluente clássica (
.WithCoverage(0).Build()). Em C#, parâmetros opcionais entregam o mesmo resultado com menos código.
Intenção. Uma fábrica de objetos de teste prontos em configurações comuns e nomeadas.
No PolicyDesk.
// Leva o sinistro até o status pedido passando apenas por transições válidas
public static Claim BuildWithStatus(ClaimStatus status, Guid? policyId = null)
{
var claim = Build(policyId);
if (status == ClaimStatus.Pending)
return claim;
claim.StartAnalysis();
switch (status)
{
case ClaimStatus.Denied: claim.Deny("Not covered"); break;
case ClaimStatus.Approved: claim.Approve(); break;
case ClaimStatus.Paid: claim.Approve(); claim.RegisterPayment(); break;
}
return claim;
}O ponto mais importante. Como Status tem setter privado, o teste não pode simplesmente atribuir o status. O Object Mother percorre as transições reais. Isso significa que os próprios testes respeitam a máquina de estados: não existe teste com um sinistro "pago sem aprovação", porque esse estado é impossível de construir.
Intenção. Encapsular a configuração de mocks em uma API fluente e reaproveitável.
No PolicyDesk.
public class ClaimsUpdateOnlyRepositoryBuilder
{
private readonly Mock<IClaimsUpdateOnlyRepository> _repository = new();
public ClaimsUpdateOnlyRepositoryBuilder GetByIdForUpdate(Claim claim)
{
_repository.Setup(r => r.GetByIdForUpdateAsync(claim.Id, It.IsAny<CancellationToken>())).ReturnsAsync(claim);
return this; // fluente
}
public IClaimsUpdateOnlyRepository Build() => _repository.Object;
}Uso:
var repository = new ClaimsUpdateOnlyRepositoryBuilder().GetByIdForUpdate(claim).Build();O teste não precisa conhecer a sintaxe do Moq (Setup, It.IsAny, ReturnsAsync). Se a assinatura do repositório mudar (um parâmetro novo, por exemplo), o ajuste é feito em um lugar só.
Intenção. Shared Fixture (Gerard Meszaros, xUnit Test Patterns): compartilhar um recurso caro entre vários testes. Testcontainers: subir dependências reais em contêineres Docker descartáveis durante os testes.
No PolicyDesk.
public class PolicyDeskApplicationFactory : WebApplicationFactory<Program>, IAsyncLifetime
{
private readonly PostgreSqlContainer _database = new PostgreSqlBuilder("postgres:16-alpine")
.WithDatabase("policydesk_integration_tests")
.Build();
public async Task InitializeAsync() => await _database.StartAsync();
protected override void ConfigureWebHost(IWebHostBuilder builder)
{
builder.UseEnvironment("Testing");
builder.ConfigureAppConfiguration((_, configuration) =>
configuration.AddInMemoryCollection(new Dictionary<string, string?>
{
["ConnectionStrings:DbConnection"] = _database.GetConnectionString()
}));
}
}IClassFixture<PolicyDeskApplicationFactory> faz o xUnit criar uma factory (e um contêiner) por classe de teste.
Por que banco real, e não o provider InMemory do EF? O provider InMemory não é um banco relacional. Ele não executa SQL, não tem xmin, não respeita índices únicos filtrados, não tem ON CONFLICT e não tem transações reais. Os comportamentos mais importantes do PolicyDesk (concorrência, upsert, unicidade) simplesmente não existiriam nos testes. A própria documentação do EF Core desaconselha o InMemory para testes.
Substituição de serviços em teste. O teste de concorrência troca um caso de uso por uma versão que simula o conflito:
var client = Factory
.WithWebHostBuilder(builder => builder.ConfigureTestServices(services =>
services.AddScoped<IApproveClaimUseCase, ConflictingApproveClaimUseCase>()))
.CreateClient();Isso só é possível porque a aplicação depende de interfaces resolvidas pelo contêiner. A injeção de dependência paga dividendos também nos testes.
Intenção. Estruturar cada teste em três blocos: preparar, executar e verificar.
No PolicyDesk.
[Fact(DisplayName = nameof(Deve_AprovarEConfirmar_Quando_SinistroEstiverEmAnalise))]
[Trait("Application", "Claims - Approve")]
public async Task Deve_AprovarEConfirmar_Quando_SinistroEstiverEmAnalise()
{
// Arrange
var claim = ClaimBuilder.Build();
claim.StartAnalysis();
var (useCase, unitOfWork) = CreateUseCase(claim);
// Act
await useCase.ExecuteAsync(claim.Id);
// Assert
claim.Status.ShouldBe(ClaimStatus.Approved);
claim.ApprovedAt.ShouldNotBeNull();
unitOfWork.Verify(work => work.CommitAsync(), Times.Once);
}Convenção de nomes: Deve_<ResultadoEsperado>_Quando_<Condição>. O nome é uma frase de especificação. Uma lista de testes que falharam vira uma lista de regras quebradas:
❌ Deve_LancarValidacaoSemConfirmar_Quando_SinistroNaoEstiverEmAnalise
O [Trait] agrupa os testes por camada e funcionalidade no Test Explorer.
| Princípio | Significado | Exemplo no projeto |
|---|---|---|
| S — Single Responsibility | Uma classe, um motivo para mudar | Um caso de uso por operação; ExceptionFilter só traduz exceções; ObservabilitySetup só configura telemetria |
| O — Open/Closed | Aberto para extensão, fechado para modificação | Uma nova operação é uma nova classe de caso de uso, sem alterar as existentes. Um novo tipo de erro é uma nova subclasse de PolicyDeskException
|
| L — Liskov Substitution | Subtipos substituem o tipo base sem surpresas | Qualquer PolicyDeskException pode ser tratada como Exception com a mensagem correta (testado em ExceptionMessageTests). Os mocks de repositório substituem as implementações reais nos testes |
| I — Interface Segregation | Clientes não dependem do que não usam | Repositórios ReadOnly / WriteOnly / UpdateOnly
|
| D — Dependency Inversion | Dependa de abstrações | Domínio define IUnitOfWork; a infraestrutura implementa. Casos de uso recebem interfaces |
| Padrão | Onde ver |
|---|---|
| Clean Architecture | Estrutura de src/ e ProjectReference dos .csproj
|
| Injeção de Dependência |
Application/DependencyInjectionExtension.cs, Infrastructure/DependencyInjectionExtension.cs
|
| Composition Root | Api/Program.cs |
| Domínio rico / Always-Valid | Domain/Entities/*.cs |
| Layer Supertype | Domain/SeedWorks/Entity.cs |
| Máquina de estados | Domain/Entities/Claim.cs |
| Validadores de valor | Domain/Validations/*.cs |
| Use Case / Command | Application/**/*UseCase.cs |
| Notification |
Application/Policyholders/PolicyholderDataValidator.cs, ErrorOnValidationException
|
| DTO | Shared/PolicyDesk.Communication/ |
| Repository / ISP |
Domain/Repositories/, Infrastructure/DataAccess/Repositories/
|
| Unit of Work | Infrastructure/DataAccess/UnitOfWork.cs |
| Optimistic Lock |
Infrastructure/DataAccess/Mappings/*Map.cs (IsRowVersion) |
| Soft Delete |
PolicyholderMap.cs (HasQueryFilter) |
| Upsert | PolicyholdersRepository.RegisterOrReactivateAsync |
| Exception Translation | UnitOfWork.cs |
| Middleware Pipeline |
Program.cs, Observability/CorrelationId.cs
|
| Exception Filter | Api/Filters/ExceptionFilter.cs |
| Problem Details | Api/Errors/ProblemDetailsSetup.cs |
| Options Pattern |
Infrastructure/Configuration/DatabaseOptions.cs, BusinessOptions.cs
|
| Relógio injetável |
Domain/SeedWorks/BusinessClock.cs, Infrastructure/DependencyInjectionExtension.cs
|
| Source-Generated Logging |
Application/Logging/ApplicationLogs.cs, Api/Logging/ApiLogs.cs
|
| Test Data Builder / Object Mother | tests/src/CommonTestUtilities/ |
| Shared Fixture |
PolicyDeskApplicationFactory.cs, PostgreSqlInfrastructureFixture.cs
|
| Obra | Autor | Padrões relacionados |
|---|---|---|
| Design Patterns: Elements of Reusable Object-Oriented Software | Gamma, Helm, Johnson, Vlissides (GoF) | State, Command, Chain of Responsibility, Decorator |
| Patterns of Enterprise Application Architecture | Martin Fowler | Repository, Unit of Work, Optimistic Offline Lock, DTO, Layer Supertype, Transaction Script |
| Domain-Driven Design | Eric Evans | Entity, Value Object, Aggregate, Repository |
| Implementing Domain-Driven Design | Vaughn Vernon | Referência entre agregados por identidade |
| Clean Architecture | Robert C. Martin | Regra de dependência, SOLID, Screaming Architecture |
| Growing Object-Oriented Software, Guided by Tests | Freeman e Pryce | Test Data Builder |
| xUnit Test Patterns | Gerard Meszaros | Shared Fixture, Object Mother, Test Double |
| .NET Microservices: Architecture for Containerized .NET Applications | Microsoft | SeedWork, DDD em .NET |
| RFC 9457 — Problem Details for HTTP APIs | IETF | Problem Details |
| W3C Trace Context | W3C | Correlation ID |
| Anemic Domain Model | Martin Fowler | Domínio rico |
| Notification | Martin Fowler | Notification Pattern |
PolicyDesk · Distribuído sob a licença MIT · Repositório
Comece aqui
Como o sistema é feito
A API
Engenharia
Prática
Consulta