DEV Community: Fred Amaral

lições aprendidas na construção de uma sdk financeira: onde termina o backend e começa o cliente?

Fred Amaral — Fri, 11 Apr 2025 18:30:57 +0000

nas últimas semanas, embarcamos em um desafio por aqui: construir a primeira SDK para o Midaz, nosso ledger para core banking (disponível open-source aqui). o que parecia ser um projeto de simples -- afinal, openapi documentation e uma infinidade de ferramentas para generation --, rapidamente se transformou em um rabbit hole técnico bem profundo. colocar a primeira versão em produção trouxe à tona uma discussão fundamental: qual é a fronteira entre as responsabilidades do servidor e do cliente?

fronteiras de responsabilidade

quando começamos a desenvolver a SDK para o Midaz (em Go), a pergunta que constantemente nos perseguia era: até onde a API do backend deve ir e onde começa a responsabilidade de integração/implementação do cliente? ou seja, onde termina o backend e começa o colo do cliente?

esta pergunta aparentemente simples esconde uma complexidade enorme. tradicionalmente, muitos desenvolvedores consideram que:

Backend: responsável pela lógica de negócio, persistência, segurança, validações
Cliente/SDK: responsável apenas por fazer requisições HTTP, serializar/deserializar dados

mas será que essa divisão simplista funciona bem na prática? especialmente quando falamos de sistemas financeiros com requisitos rigorosos de consistência, performance e resiliência?

por que uma SDK robusta importa? ou pq qualquer generation tool não funcionou conosco

durante o desenvolvimento, percebemos que uma SDK financeira precisa ir muito além de simplesmente fazer o wrapping de endpoints REST. ela precisa ser uma camada que:

Protege o servidor contra inputs inválidos (validação do lado cliente)
Torna a integração mais resiliente (retries, rate limiting, circuit breaking)
Oferece performance mesmo em condições adversas (batching, paralelismo)
Simplifica operações complexas (abstraindo detalhes de implementação [que o backend precisa manter detalhado])
Proporciona uma experiência de desenvolvimento fluida (tipos fortemente definidos, erros descritivos)

vamos explorar cada um desses aspectos detalhadamente, com exemplos práticos do que implementamos na nossa primeira SDK.

validação no cliente: evitando viagens desnecessárias

uma das primeiras decisões que tomamos foi implementar validações robustas no lado cliente. por quê? simples: por que enviar ao servidor uma requisição que sabemos que vai falhar?

// Exemplo de validação de transação financeira no lado cliente
func ValidateTransactionDSL(input TransactionDSLValidator) error {
    if input == nil {
        return fmt.Errorf("transaction input cannot be nil")
    }

    // Valida código do ativo
    asset := input.GetAsset()
    if asset == "" {
        return fmt.Errorf("asset code is required")
    }
    if !assetCodePattern.MatchString(asset) {
        return fmt.Errorf("invalid asset code format: %s (must be 3-4 uppercase letters)", asset)
    }

    // Valida valor
    if input.GetValue() <= 0 {
        return fmt.Errorf("transaction amount must be greater than zero")
    }

    // Validações adicionais de contas e consistência...
}

implementamos validações para:

formatos de código de ativos (USD, BRL, BTC, Gado, Caixas de Remédio, whatever)
montantes e escalas de transações
estrutura de contas e operações
metadados e payloads auxiliares

isso traz múltiplos benefícios:

feedback instantâneo para o desenvolvedor
redução de latência (evitando roundtrips desnecessários)
menor carga no servidor
mensagens de erro mais contextualizadas e úteis

a validação no cliente não substitui a validação no servidor (que continua essencial por razões de segurança), mas cria uma experiência de desenvolvimento superior e reduz o tráfego de rede.

resiliência através de retry intelligente

sistemas distribuídos falham. esta é uma realidade, não uma possibilidade. quando trabalhamos com operações financeiras, essas falhas são ainda mais críticas e podem ter consequências significativas.

por isso, implementamos mecanismos sofisticados de retry com exponential backoff:

// Configuração de retry com backoff exponencial
client, err := client.New(
    client.WithAuthToken("your-auth-token"),
    client.WithTimeout(30 * time.Second),
    client.WithRetries(3, 100*time.Millisecond, 1*time.Second),
    client.UseAllAPIs(), // by the way, isso é um caso a parte aqui: pra que expor o que não precisa ser exposto?
)

nosso sistema de retry:

utiliza backoff exponencial para evitar sobrecarregar servidores em problemas
adiciona jitter (variação aleatória) para prevenir thundering herd e, sinceramente se eu fingir normalidade escrevendo isso aqui, é mentira. aqui foi um rabbit hole a parte, e estudamos bastante para entender o conceito que era aplicado em outras enterprise-grade APIs
categoriza erros entre "retryable" e "non-retryable"
respeita limites de timeout especificados pelo usuário
permite personalização completa de estratégias

este código parece simples na interface, mas por trás dele há uma implementação robusta que considera diversos cenários de falha:

// Trecho da implementação de retry com backoff
func doWithOptions(ctx context.Context, fn func() error, options *Options) error {
    var err error
    for attempt := 0; attempt <= options.MaxRetries; attempt++ {
        // Check if context is done before executing
        if ctx.Err() != nil {
            return fmt.Errorf("operation cancelled: %w", ctx.Err())
        }

        // Execute the function
        err = fn()
        if err == nil {
            // Success, return immediately
            return nil
        }

        // Check if this is the last attempt
        if attempt == options.MaxRetries {
            break
        }

        // Check if the error is retryable
        if !IsRetryableError(err, options) {
            return err
        }

        // Calculate delay with jitter
        delay := calculateBackoff(attempt, options)
        delayWithJitter := addJitter(delay, options.JitterFactor)

        // Wait for the calculated delay or until context is done
        timer := time.NewTimer(delayWithJitter)
        select {
        case <-ctx.Done():
            timer.Stop()
            return fmt.Errorf("operation cancelled during retry: %w", ctx.Err())
        case <-timer.C:
            // Continue to next retry attempt
        }
    }

    return fmt.Errorf("operation failed after %d retries: %w", options.MaxRetries, err)
}

um dos aprendizados mais interessantes foi identificar quais erros deveriam ser tentados novamente e quais não. por exemplo, erros de validação nunca devem ter retry, enquanto problemas de rede temporários são candidatos ideais. esse modelo de listing by exception é um conceito que foi estudado bastante, e foi aplicado em outras enterprise-grade APIs (exemplo interessante é a da AWS).

// Definição de erros retryable padrão
var DefaultRetryableErrors = []string{
    "connection reset by peer",
    "connection refused",
    "timeout",
    "deadline exceeded",
    "too many requests",
    "rate limit",
    "service unavailable",
}

// Códigos HTTP que merecem retry
var DefaultRetryableHTTPCodes = []int{
    http.StatusRequestTimeout,      // 408
    http.StatusTooManyRequests,     // 429
    http.StatusInternalServerError, // 500
    http.StatusBadGateway,          // 502
    http.StatusServiceUnavailable,  // 503
    http.StatusGatewayTimeout,      // 504
}

gerenciamento avançado de configurações

a modularidade da configuração foi um ponto crítico do design. utilizamos o padrão de opções funcionais (não são 100% fluentes como pede o figurin) para permitir uma configuração limpa e extensível:

// Padrão de options funcionais para configuração flexível
client, err := client.New(
    // Configurações básicas
    client.WithAuthToken("your-auth-token"),
    client.WithEnvironment(config.EnvironmentProduction),

    // Opções avançadas de performance
    client.WithTimeout(30 * time.Second),
    client.WithRetries(3, 200*time.Millisecond, 2*time.Second),

    // Observabilidade
    client.WithObservability(true, true, true),

    // Quais APIs utilizar
    client.UseAllAPIs(),
)

este padrão permite:

configuração incremental com defaults sensatos
melhor legibilidade e manutenção
extensibilidade futura sem quebrar compatibilidade
configurações específicas por domínio

além disso, implementamos suporte para configuração via variáveis de ambiente:

// Variáveis de ambiente que o cliente reconhece
MIDAZ_AUTH_TOKEN=seu-token // implementaremos a sdk de access management lançada ontem logo logo
MIDAZ_ENVIRONMENT=production
MIDAZ_ONBOARDING_URL=https://api.exemplo.com/v1
MIDAZ_TRANSACTION_URL=https://transactions.exemplo.com/v1
MIDAZ_DEBUG=true
MIDAZ_MAX_RETRIES=5

isto permite uma integração mais suave com diferentes ambientes de deploy, especialmente em contextos de containers e kubernetes.

performance otimizada para JSON

em sistemas financeiros, performance não é luxo, é requisito. um dos pontos de maior otimização foi o processamento JSON, que pode rapidamente se tornar um gargalo:

// Exemplo de nossa implementação de pooling de buffers para JSON
type JSONPerformance struct {
    encoderPool sync.Pool
    decoderPool sync.Pool
    bufferPool  sync.Pool
}

func NewJSONPerformance() *JSONPerformance {
    return &JSONPerformance{
        encoderPool: sync.Pool{
            New: func() interface{} {
                return json.NewEncoder(io.Discard)
            },
        },
        decoderPool: sync.Pool{
            New: func() interface{} {
                return json.NewDecoder(strings.NewReader(""))
            },
        },
        bufferPool: sync.Pool{
            New: func() interface{} {
                return new(bytes.Buffer)
            },
        },
    }
}

func (jp *JSONPerformance) Marshal(v interface{}) ([]byte, error) {
    buf := jp.bufferPool.Get().(*bytes.Buffer)
    buf.Reset()
    defer jp.bufferPool.Put(buf)

    enc := jp.encoderPool.Get().(*json.Encoder)
    enc.SetEscapeHTML(false)
    oldWriter := enc.Linter
    enc.SetWriter(buf)
    defer func() {
        enc.SetWriter(oldWriter)
        jp.encoderPool.Put(enc)
    }()

    if err := enc.Encode(v); err != nil {
        return nil, err
    }

    // Copy to avoid returning a reference to the pooled buffer
    result := make([]byte, buf.Len())
    copy(result, buf.Bytes())
    return result, nil
}

esta abordagem reduziu alocações de memória em nossos benchmarks, principalmente quando fazíamos em conjunto com o pooling de buffers, o que é crucial para sistemas financeiros de alto volume que processam milhões de transações.

paginação inteligente e universal

lidar com grandes conjuntos de dados é um desafio comum em operações financeiras. por isso, desenvolvemos um sistema de paginação universal que funciona com diferentes endpoints e paradigmas:

// Interface genérica para qualquer tipo de paginador
type Paginator[T any] interface {
    HasNext() bool
    Next() (*ListResponse[T], error)
    Reset() 
}

// Exemplo de uso para listar transações com paginação automática
paginator := client.Entity.Transactions.GetTransactionPaginator(
    ctx, "org-id", "ledger-id", &models.ListOptions{Limit: 100},
)

totalTransactions := 0
for paginator.HasNext() {
    page, err := paginator.Next()
    if err != nil {
        return err
    }

    for _, tx := range page.Items {
        // Processar cada transação
        processTransaction(tx)
        totalTransactions++
    }
}
fmt.Printf("Processadas %d transações no total\n", totalTransactions)

nossa implementação suporta:

paginação por offset/limit (mais comum)
paginação por cursor (mais eficiente para grandes datasets)
prefetching para melhor performance
preservação de filtros e ordenação entre páginas
adaptação automática ao tipo de paginação do endpoint

concorrência controlada para alto volume

para lidar com os requisitos de alta performance, investimos pesadamente em modelos de concorrência bem controlados:

// Worker pool genérico com controle fino de concorrência
func WorkerPool[T, R any](
    ctx context.Context,
    items []T,
    workFn func(context.Context, T) (R, error),
    opts ...PoolOption,
) []Result[T, R] {
    // Config default
    options := defaultPoolOptions()
    for _, opt := range opts {
        opt(options)
    }

    resultCh := make(chan Result[T, R], len(items))
    var wg sync.WaitGroup

    // Semáforo para controlar concorrência
    sem := make(chan struct{}, options.workers)

    // Rate limiter se especificado
    var limiter <-chan time.Time
    if options.rateLimit > 0 {
        ticker := time.NewTicker(time.Second / time.Duration(options.rateLimit))
        defer ticker.Stop()
        limiter = ticker.C
    }

    for i, item := range items {
        // Respeita cancelamento pelo context
        if ctx.Err() != nil {
            break
        }

        // Rate limiting se ativo
        if limiter != nil {
            select {
            case <-ctx.Done():
                break
            case <-limiter:
                // Continue quando o rate limiter permitir
            }
        }

        // Adquire slot no semáforo
        sem <- struct{}{}

        wg.Add(1)
        go func(idx int, item T) {
            defer wg.Done()
            defer func() { <-sem }() // Libera o semáforo ao final

            // Cria um timeout interno se necessário
            execCtx := ctx
            if options.timeout > 0 {
                var cancel context.CancelFunc
                execCtx, cancel = context.WithTimeout(ctx, options.timeout)
                defer cancel()
            }

            // Executa a função de trabalho
            result, err := workFn(execCtx, item)

            // Envia o resultado
            resultCh <- Result[T, R]{
                Index: idx,
                Item:  item,
                Value: result,
                Error: err,
            }
        }(i, item)
    }

    // Fecha o canal de resultados quando todo trabalho estiver concluído
    go func() {
        wg.Wait()
        close(resultCh)
    }()

    // Coleta resultados
    var results []Result[T, R]
    for result := range resultCh {
        results = append(results, result)
    }

    // Ordena resultados se necessário
    if options.ordered {
        sort.Slice(results, func(i, j int) bool {
            return results[i].Index < results[j].Index
        })
    }

    return results
}

esta implementação permite:

controle preciso de concorrência para evitar sobrecarregar a API
rate limiting para respeitar limites da API
ordenação opcional de resultados
cancelamento gracioso de operações em andamento
timeouts individuais para tarefas

tratamento avançado de erros financeiros

em um sistema financeiro, os erros são parte crítica da experiência do desenvolvedor. investimos em um sistema sofisticado de tratamento de erros:

// Exemplo de uso de erros especializados
switch {
case errors.IsValidationError(err):
    // Trata erro de validação
    fmt.Println("Erro de validação:", err)

    // Extrai erros por campo
    fieldErrors := errors.GetFieldErrors(err)
    for _, fieldErr := range fieldErrors {
        fmt.Printf("Campo %s: %s\n", fieldErr.Field, fieldErr.Message)
    }

case errors.IsInsufficientBalanceError(err):
    // Trata erro específico financeiro
    fmt.Println("Saldo insuficiente:", err)

case errors.IsRateLimitExceededError(err):
    // Implementa backoff e retry
    fmt.Println("Limite de requisições excedido, aguardando:", err)
    time.Sleep(exponentialBackoff(attempt))

case errors.IsAuthenticationError(err):
    // Problema com autenticação
    fmt.Println("Erro de autenticação, renovando token:", err)
    renewToken()
}

adicionalmente, nossos erros incluem:

categorização clara (validação, autenticação, rede, etc)
detalhes específicos por domínio financeiro (saldo insuficiente, limites, etc)
códigos de erro e status HTTP associados
sugestões de correção para o desenvolvedor
integração com observabilidade (geração de span de erro)

testes de stress e verificação de escalabilidade

uma característica distintiva da nossa SDK foi o desenvolvimento de uma suite robusta de testes de stress:

// Trecho do código da suite de stress testing
func (st *StressTest) Run(ctx context.Context) error {
    logger := st.observability.GetLogger()
    logger.Info("Iniciando teste de stress", "workers", st.config.ConcurrentWorkers)

    // Preparar ambiente de teste
    if err := st.SetupTestEnvironment(ctx); err != nil {
        return fmt.Errorf("falha ao configurar ambiente: %w", err)
    }

    // Executar até interrupção ou duração configurada
    var wg sync.WaitGroup
    ctx, cancel := context.WithCancel(ctx)
    defer cancel()

    // Inicia monitoramento de métricas
    st.metrics = NewMetricsCollector(st.observability)
    go st.metrics.Start(ctx)

    // Inicia workers para gerar carga
    for i := 0; i < st.config.ConcurrentWorkers; i++ {
        wg.Add(1)
        go func(workerID int) {
            defer wg.Done()
            st.runWorker(ctx, workerID)
        }(i)
    }

    // Aguarda conclusão
    wg.Wait()
    logger.Info("Teste de stress concluído", "transações", st.metrics.TotalTransactions())

    return nil
}

esta suite nos permitiu:

validar o comportamento sob carga extrema (50.000+ tx/s ou modelos de 1:1 em conta com 10000+ tx/s)
identificar e corrigir bottlenecks antes do lançamento
verificar o comportamento de mecanismos de retry e resiliência
testar a degradação graceful sob falhas parciais
validar limites de recursos (memória, CPU, conexões, e o próprio sistema distribuído)

no ponto específico de validar limites de recursos e do sistema distribuído, utilizamos o pumba para simular cenários de caos (em docker), e isso nos ajudou a identificar pontos interessantes na implementação do próprio backend.

documentação dirigida por exemplos

percebemos que bons exemplos são mais valiosos que documentação abstrata. por isso, demos ênfase especial a exemplos práticos:

// Exemplo completo de transferência entre contas
func ExampleTransferBetweenAccounts() {
    // Inicializar cliente
    c, err := client.New(
        client.WithAuthToken(os.Getenv("MIDAZ_TOKEN")),
        client.UseAllAPIs(),
    )
    if err != nil {
        log.Fatalf("Erro inicializando cliente: %v", err)
    }

    // Definir detalhes da transação
    input := &models.TransactionDSLInput{
        Description: "Transferência para pagamento de aluguel",
        Send: &models.DSLSend{
            Asset: "BRL",
            Value: 150000, // R$ 1.500,00
            Scale: 2,
            Source: &models.DSLSource{
                From: []models.DSLFromTo{
                    {
                        Account: "conta-origem-123",
                        Amount: &models.DSLAmount{
                            Asset: "BRL",
                            Value: 150000,
                            Scale: 2,
                        },
                    },
                },
            },
            Distribute: &models.DSLDistribute{
                To: []models.DSLFromTo{
                    {
                        Account: "conta-destino-456",
                        Amount: &models.DSLAmount{
                            Asset: "BRL",
                            Value: 150000,
                            Scale: 2,
                        },
                    },
                },
            },
        },
        Metadata: map[string]any{
            "referencia": "aluguel-julho-2025",
            "categoria": "moradia",
        },
    }

    // Executar a transação
    tx, err := c.Entity.Transactions.CreateTransactionWithDSL(
        context.Background(),
        "org-exemplo",
        "ledger-principal",
        input,
    )
    if err != nil {
        log.Fatalf("Erro na transferência: %v", err)
    }

    fmt.Printf("Transferência realizada com sucesso! ID: %s\n", tx.ID)
}

cada exemplo está acompanhado de comentários detalhados e cobrimos todos os cenários principais:

criação de entidades (organizações, contas, etc)
operações financeiras (transferências, depósitos, saques)
consultas e relatórios (balanços, extratos, histórico)
workflows completos (onboarding, transações)

a vantagem da unificação de interface

falando um pouco sobre a vantagem de unificar múltiplas APIs de backend sob uma interface coerente: no mundo financeiro, frequentemente temos APIs separadas para diferentes domínios:

API de onboarding (organizações, contas)
API de transactions (transferências, saldos)
API de compliance (KYC, AML)
API de reporting (relatórios, extratos)
etc etc etc

cada uma com suas peculiaridades e convenções. nossa SDK unifica todas sob uma única interface consistente:

// Mesmo padrão para todas as APIs, independente do backend
// API de onboarding
organization, err := client.Entity.Organizations.CreateOrganization(ctx, input)

// API de transactions 
transaction, err := client.Entity.Transactions.CreateTransaction(ctx, orgID, ledgerID, input)

// API de balanços
balance, err := client.Entity.Accounts.GetBalance(ctx, orgID, ledgerID, accountID)

esta unificação traz benefícios significativos para o desenvolvedor em si:

reduz a curva de aprendizado para novos desenvolvedores
abstrai as diferenças de implementação entre serviços
permite evolução independente do backend e frontend
facilita migração entre diferentes versões de APIs

a discussão sobre fronteiras: o que aprendemos

voltando à questão inicial sobre as fronteiras de responsabilidade entre servidor e cliente, concluímos que a resposta não é binária. em vez disso, é um espectro que depende do contexto:

Validação: tanto cliente quanto servidor devem validar - cliente para UX e DevEx, servidor para segurança
Resiliência: principalmente responsabilidade do cliente, com suporte do servidor (idempotência, o que nossa API também trata com uma option específica de WithIdempotency())
Performance: responsabilidade compartilhada, com otimizações específicas em cada lado
Domínio: o servidor define o modelo, mas o cliente pode enriquecê-lo com abstrações úteis

o que ficou claro é que SDKs não são meros wrappers de API - elas são produtos completos que precisam considerar toda a experiência do desenvolvedor e os requisitos específicos do domínio.

trade-offs e desafios de design importantes

durante o desenvolvimento da SDK, nos confrontamos com vários trade-offs importantes que impactam diretamente desenvolvedores e usuários:

validação no cliente vs. sincronização com o servidor

a implementação de validações robustas no cliente traz benefícios claros de performance e experiência do desenvolvedor, mas também introduz um desafio:

// Se estas regras de validação mudam no servidor...
if !assetCodePattern.MatchString(asset) {
    return fmt.Errorf("invalid asset code format: %s (must be 3-4 uppercase letters)", asset)
}

// ...e o cliente não atualiza a SDK, teremos inconsistências

este é um trade-off significativo:

Vantagem: redução de latência e feedback instantâneo
Desvantagem: potencial divergência entre regras cliente/servidor se os clientes não atualizarem a SDK

nossa solução foi documentar claramente a necessidade de atualizações regulares e fornecer testes que ajudam a detectar divergências de validação, além de fazer um robusto linking entre models do cliente e do servidor.

filosofia de tratamento de erros: o que tratar automaticamente?

uma decisão crítica foi determinar quais erros a SDK deveria tratar automaticamente versus quais deveriam ser expostos para o backend:

// Erros tratados automaticamente pela SDK
if errors.IsTemporaryNetworkError(err) || errors.IsRateLimitExceeded(err) {
    // Aplicar retry automaticamente
    return retry.Do(ctx, operation)
}

// Erros que são propagados ao aplicativo
if errors.IsBusinessRuleViolation(err) || errors.IsValidationError(err) {
    // O desenvolvedor precisa tratar estes casos explicitamente
    return err
}

adotamos a filosofia de que:

erros transientes de infraestrutura/rede são tratados pela SDK
erros de domínio financeiro ou validação são propagados para permitir tratamento adequado pelo backend
erros críticos (autenticação, permissões) são propagados com contexto enriquecido para facilitar diagnóstico

integração de observabilidade: o equilíbrio entre intrusão e visibilidade

a observabilidade é crítica em sistemas financeiros, mas quanto a SDK deve impor versus oferecer como opcional? aqui é um caso a parte. remodelamos toda a stack de observabilidade (usando opentelemetry) para que o desenvolvedor possa escolher o que ele quer e o que ele não quer, sem sermos "opinionated" com relação ao tema -- bem diferente do contexto do midaz open-source, que é mais "opinionated".

// Abordagem não-intrusiva que adotamos:
client, err := client.New(
    // Configuração básica
    client.WithAuthToken("token"),

    // Observabilidade totalmente opcional
    client.WithObservability(
        observability.WithTracing(userDefinedTraceProvider),  // opcional
        observability.WithMetrics(userDefinedMeterProvider),  // opcional
        observability.WithLogging(userDefinedLogger),         // opcional
    ),
)

decidimos por uma abordagem modular onde:

a SDK funciona perfeitamente sem observabilidade configurada
desenvolvedores podem injetar seus próprios providers de observabilidade
fornecemos implementações default para casos simples
instrumentamos pontos críticos nas operações financeiras para máxima visibilidade

operações assíncronas e notificações

transações financeiras frequentemente envolvem processos assíncronos. como a SDK deve lidar com isso?

// Opção 1: Polling (implementamos inicialmente)
status, err := client.Entity.Transactions.GetTransactionStatus(ctx, txID)

// Opção 2: Webhooks (planejado para futuro)
client.Entity.Transactions.RegisterWebhookHandler(webhookHandler)

// Opção 3: Response streaming (planejado para futuro)
stream, err := client.Entity.Transactions.WatchTransaction(ctx, txID)
for update := range stream.Updates() {
    // Processar atualizações em tempo real
}

nossa abordagem foi evolutiva. tomamos uma decisão de implementar o básico agora, mas permitindo uma modelagem como a acima exposta:

começamos com polling simples para compatibilidade ampla
adicionaremos suporte a webhooks para notificações em tempo real
e planejamos, por fim, streaming de atualizações para casos de uso mais complexos

estratégia de versionamento e compatibilidade planejado para em breve, dado que estamos na V1 do Midaz

o versionamento é um desafio significativo em APIs financeiras que evoluem constantemente:

// Suporte a múltiplas versões de API
client, err := client.New(
    client.WithAPIVersion("v1"),  // default
    // ou
    client.WithAPIVersion("v2"),  // novas funcionalidades
)

// Usando feature flags para recursos em preview
client.Entity.Transactions.CreateTransaction(
    ctx, orgID, ledgerID, input, 
    transactions.WithFeatureEnabled("instant-settlement"),
)

adotaremos uma estratégia de versionamento com múltiplas camadas:

versionamento semântico tradicional para a SDK
compatibilidade com múltiplas versões de API em uma única versão da SDK
feature flags para recursos experimentais
aliases de métodos deprecados com warnings para facilitar migrações

aprendizados para o futuro

lançar a primeira versão de uma SDK não é o fim da jornada, mas apenas o começo. já identificamos diversas áreas para evolução:

Estratégia evolutiva: como evoluir a API sem quebrar compatibilidade? como evoluir o backend sem quebrar compatibilidade? como fazer tudo isso e mantermos o decoupling super necessário entre midaz e midaz-sdk-golang versioning
Abstrações de domínio: quais abstrações de nível superior devemos oferecer para simplificar fluxos comuns? que tal evoluirmos para DoWithdrawal, DoDeposit, DoTransfer, etc, fazendo a abstração entre a conta @external/asset e o domínio de transações. que tal evoluirmos para sdk apis 100% fluentes?
Balanceamento de responsabilidades: conforme o produto evolui, qual o equilíbrio ideal entre lógica no servidor e no cliente? afinal, não queremos obrigar nossos clientes a usarem a sdk, até pq não conseguiremos manter sdks em um número grande de linguagens
Extensibilidade: como permitir que usuários estendam a SDK para seus casos específicos? o fato de sermos open-source facilita isso e chama o público para nos ajudar, mas sabemos da nossa responsabilidade como principais mantenedores do midaz e sua stack

particularmente interessante é a questão dos modelos de domínio. por exemplo, em vez de apenas oferecer a API para criar uma transação, devemos evoluir para oferecer construções de mais alto nível:

// Potencial evolução futura - Abstrações de domínio mais ricas
// Em vez de apenas criar transações 
tx, err := client.Entity.Transactions.CreateTransaction(ctx, orgID, ledgerID, createTxInput)

// Oferecer fluxos de domínio completos
transferResult, err := client.Workflows.DoTransfer(ctx, transferOptions)
paymentResult, err := client.Workflows.DoPayment(ctx, paymentOptions)
fxResult, err := client.Workflows.DoForeignExchangeTransfer(ctx, fxOptions)

o padrão functional options: flexibilidade sem complexidade

um padrão de design que merece destaque especial na nossa SDK é o uso extensivo de functional options (ou a implementação parcial de fluent APIs). este padrão permite configuração flexível sem comprometer a legibilidade ou simplicidade:

// Definição básica do padrão
type ClientOption func(*Client) error

func WithTimeout(timeout time.Duration) ClientOption {
    return func(c *Client) error {
        if timeout <= 0 {
            return errors.New("timeout must be positive")
        }
        c.httpClient.Timeout = timeout
        return nil
    }
}

// Uso elegante e extensível
client, err := client.New(
    client.WithAuthToken("seu-token"),
    client.WithTimeout(30 * time.Second),
    client.WithRetries(3),
    client.WithObservability(true),
)

este padrão oferece múltiplas vantagens:

evita a explosão de construtores para diferentes combinações de opções
permite adicionar novos parâmetros sem quebrar código existente
facilita testes e configurações condicionais
proporciona validação no momento da configuração
permite opções compostas que aplicam múltiplas configurações

aplicamos o mesmo padrão em diversos níveis da SDK, não apenas na inicialização do cliente:

// Nível de operação - opções específicas por operação
tx, err := client.Entity.Transactions.CreateTransaction(
    ctx, orgID, ledgerID, input,
    transactions.WithIdempotencyKey("unique-key-123"),
    transactions.WithPriority(transactions.PriorityHigh),
)

// Nível de entidade - configurações por domínio
accountSvc := client.Entity.Accounts.WithOptions(
    accounts.WithCaching(true),
    accounts.WithValidation(accounts.ValidationStrict),
)

conclusão

construir a SDK do Midaz foi uma jornada de aprendizado e de um estado de flow absurdo. as complexidades de sistemas distribuídos, especialmente no domínio financeiro, e as decisões que tomamos - desde validação robusta no cliente até mecanismos avançados de resiliência e performance - foram todas guiadas pela pergunta: "o que tornaria a vida do desenvolvedor mais fácil e o sistema mais confiável?"

no final, a fronteira entre cliente e servidor é mais sobre colaboração do que separação. uma boa SDK não apenas encapsula uma API, mas amplia suas capacidades e protege contra suas limitações.

a gestão cuidadosa dos trade-offs que destacamos - validação no cliente versus sincronização com o servidor, tratamento automático versus exposição de erros, modularidade de observabilidade, e estratégias para operações assíncronas - moldou uma SDK que equilibra simplicidade e poder.

se você estiver construindo uma SDK, especialmente para sistemas críticos como o financeiro, sugiro considerar cuidadosamente onde colocar essas fronteiras de responsabilidade. sua resposta pode não ser a mesma que a nossa, mas fazer a pergunta já é um excelente começo.

bora?

para quem quiser explorar mais, a Midaz SDK está disponível em nosso GitHub e inclui extensos exemplos de uso. os exemplos de código e implementações de referência fornecem insights valiosos sobre como implementar padrões robustos em SDKs financeiras.

o que você acha? onde você traçaria a linha entre responsabilidades de cliente e servidor em uma SDK? aproveita e dá uma estrelinha pra gente! o midaz está aqui, nosso frontend console está aqui, e nossa sdk está aqui.

next steps?

port para js. quite a challenge!

beijos,
fred.

Suporte Multi-Moeda: Desafios Técnicos em Ledgers Financeiros

Fred Amaral — Fri, 28 Mar 2025 14:38:28 +0000

Em um mundo financeiro cada vez mais globalizado, a capacidade de lidar com múltiplas moedas se tornou um requisito essencial para sistemas de ledger modernos. Neste artigo, exploraremos os desafios técnicos e as soluções implementadas no Midaz, nosso ledger financeiro de código aberto, para oferecer um suporte multi-moeda robusto e flexível que atenda às complexas necessidades de operações financeiras globais.

O Desafio do Suporte Multi-Moeda

Implementar suporte multi-moeda em um ledger financeiro vai muito além de simplesmente armazenar um código de moeda junto com valores monetários. Os desafios incluem:

1. Representação Precisa de Valores Monetários

Diferentes moedas possuem diferentes características:

Precisão decimal: Enquanto a maioria das moedas opera com duas casas decimais (centavos), algumas como o Iene japonês não utilizam frações, e outras como o Dinar do Kuwait usam três casas decimais.
Escalas de valor: Moedas com inflação muito alta ou muito baixa podem requerer tratamento especial para evitar problemas de overflow ou underflow.
Regras de arredondamento: Diferentes jurisdições podem ter regras específicas sobre como valores monetários devem ser arredondados em cálculos financeiros.

2. Conversão Entre Moedas

A conversão é um dos aspectos mais complexos:

Taxas de câmbio flutuantes: As taxas mudam constantemente e podem variar dependendo da fonte.
Spread de conversão: Em operações reais, existe uma diferença entre as taxas de compra e venda.
Taxas cruzadas: Nem sempre existe uma taxa direta entre duas moedas, podendo ser necessário converter via uma moeda intermediária.
Timing da conversão: Quando exatamente a taxa deve ser aplicada? No momento da transação, da liquidação, ou em algum ponto intermediário?

3. Contabilidade e Conformidade

O multi-moeda adiciona complexidade contábil e regulatória:

Registro de ganhos/perdas cambiais: Variações nas taxas de câmbio podem gerar ganhos ou perdas que precisam ser contabilizados.
Requisitos regulatórios: Diferentes jurisdições têm requisitos específicos sobre como transações multi-moeda devem ser reportadas.
Impostos e taxas: Conversões de moeda podem estar sujeitas a impostos ou taxas adicionais que precisam ser calculados corretamente.

4. Experiência do Usuário

A usabilidade também é afetada:

Formatação específica por moeda: Diferentes culturas têm convenções distintas para formatação de valores monetários.
Preferências do usuário: Usuários podem preferir visualizar valores em sua moeda local, mesmo que a transação original seja em outra moeda.
Transparência nas conversões: Os usuários precisam entender quando, como e a que taxa suas transações serão convertidas.

Arquitetura Multi-Moeda no Midaz

No Midaz, implementamos uma arquitetura multi-moeda que aborda esses desafios de forma abrangente. Vamos explorar os componentes principais desta implementação.

Modelo de Taxa de Câmbio (Asset Rate)

O núcleo do suporte multi-moeda no Midaz é o modelo AssetRate, que define como as taxas de câmbio são armazenadas e gerenciadas:

// De components/transaction/internal/adapters/postgres/assetrate/assetrate.go
type AssetRate struct {
    ID             string         `json:"id"`
    OrganizationID string         `json:"organizationId"`
    LedgerID       string         `json:"ledgerId"`
    ExternalID     string         `json:"externalId"`
    From           string         `json:"from"`         // Código da moeda de origem
    To             string         `json:"to"`           // Código da moeda de destino
    Rate           float64        `json:"rate"`         // Taxa de câmbio
    Scale          *float64       `json:"scale"`        // Escala para precisão
    Source         *string        `json:"source"`       // Fonte da taxa (ex: API externa)
    TTL            int            `json:"ttl"`          // Tempo de vida da taxa
    CreatedAt      time.Time      `json:"createdAt"`
    UpdatedAt      time.Time      `json:"updatedAt"`
    Metadata       map[string]any `json:"metadata"`
}

Este modelo tem várias características importantes:

Par de moedas: Cada taxa é definida para um par específico de moedas (From → To), permitindo taxas direcionais diferentes.
Escala configurável: O campo Scale permite definir a precisão para diferentes pares de moedas, essencial para cálculos financeiros precisos.
Proveniência da taxa: O campo Source registra de onde a taxa foi obtida, crucial para auditoria e conformidade.
Tempo de vida limitado: O campo TTL (Time-To-Live) garante que taxas desatualizadas não sejam utilizadas em transações.
Metadados flexíveis: O campo Metadata permite armazenar informações adicionais que podem variar dependendo da fonte ou das necessidades do negócio.
Contexto organizacional: Os campos OrganizationID e LedgerID permitem que diferentes organizações e ledgers tenham suas próprias taxas, suportando cenários multi-tenant.

API para Gerenciamento de Taxas de Câmbio

Para gerenciar taxas de câmbio, implementamos uma API completa:

// De components/transaction/internal/adapters/http/in/routes.go
// Asset-rate
f.Put("/v1/organizations/:organization_id/ledgers/:ledger_id/asset-rates", 
    auth.Authorize(midazName, "asset-rates", "put"), 
    http.ParseUUIDPathParameters, 
    http.WithBody(new(assetrate.CreateAssetRateInput), ah.CreateOrUpdateAssetRate))

f.Get("/v1/organizations/:organization_id/ledgers/:ledger_id/asset-rates/:external_id", 
    auth.Authorize(midazName, "asset-rates", "get"), 
    http.ParseUUIDPathParameters, 
    ah.GetAssetRateByExternalID)

f.Get("/v1/organizations/:organization_id/ledgers/:ledger_id/asset-rates/from/:asset_code", 
    auth.Authorize(midazName, "asset-rates", "get"), 
    http.ParseUUIDPathParameters, 
    ah.GetAllAssetRatesByAssetCode)

A implementação do handler para criar ou atualizar taxas de câmbio ilustra como gerenciamos a lógica de negócios:

// De components/transaction/internal/adapters/http/in/assetrate.go
func (handler *AssetRateHandler) CreateOrUpdateAssetRate(p any, c *fiber.Ctx) error {
    ctx := c.UserContext()

    logger := libCommons.NewLoggerFromContext(ctx)
    tracer := libCommons.NewTracerFromContext(ctx)

    ctx, span := tracer.Start(ctx, "handler.create_asset_rate")
    defer span.End()

    // Extrair parâmetros da requisição
    organizationID := c.Locals("organization_id").(uuid.UUID)
    ledgerID := c.Locals("ledger_id").(uuid.UUID)
    payload := p.(*assetrate.CreateAssetRateInput)

    // Chamar o serviço de comando para criar/atualizar a taxa
    assetRate, err := handler.Command.CreateOrUpdateAssetRate(ctx, organizationID, ledgerID, payload)
    if err != nil {
        libOpentelemetry.HandleSpanError(&span, "Failed to create AssetRate on command", err)
        logger.Infof("Error to created Asset: %s", err.Error())
        return http.WithError(c, err)
    }

    logger.Infof("Successfully created AssetRate")

    return http.Created(c, assetRate)
}

Lógica de Negócios para Taxas de Câmbio

A verdadeira complexidade do suporte multi-moeda está na lógica de negócios, implementada na camada de serviço. Vejamos como a função CreateOrUpdateAssetRate gerencia taxas de câmbio:

// De components/transaction/internal/services/command/create-assetrate.go
func (uc *UseCase) CreateOrUpdateAssetRate(ctx context.Context, organizationID, ledgerID uuid.UUID, cari *assetrate.CreateAssetRateInput) (*assetrate.AssetRate, error) {
    // [Logging e tracing omitidos para brevidade]

    // Validação dos códigos de moeda
    if err := libCommons.ValidateCode(cari.From); err != nil {
        return nil, pkg.ValidateBusinessError(err, reflect.TypeOf(assetrate.AssetRate{}).Name())
    }

    if err := libCommons.ValidateCode(cari.To); err != nil {
        return nil, pkg.ValidateBusinessError(err, reflect.TypeOf(assetrate.AssetRate{}).Name())
    }

    // Calcular os valores finais de taxa e escala
    rate := float64(cari.Rate)
    scale := float64(cari.Scale)

    // Verificar se já existe uma taxa para este par de moedas
    arFound, err := uc.AssetRateRepo.FindByCurrencyPair(ctx, organizationID, ledgerID, cari.From, cari.To)
    if err != nil {
        return nil, err
    }

    if arFound != nil {
        // Atualizar a taxa existente
        arFound.Rate = rate
        arFound.Scale = &scale
        arFound.Source = cari.Source
        arFound.TTL = *cari.TTL
        arFound.UpdatedAt = time.Now()

        // [Código para atualizar metadata omitido]

        return arFound, nil
    }

    // Criar uma nova taxa se não existir
    assetRateDB := &assetrate.AssetRate{
        ID:             libCommons.GenerateUUIDv7().String(),
        OrganizationID: organizationID.String(),
        LedgerID:       ledgerID.String(),
        ExternalID:     *externalID,
        From:           cari.From,
        To:             cari.To,
        Rate:           rate,
        Scale:          &scale,
        Source:         cari.Source,
        TTL:            *cari.TTL,
        CreatedAt:      time.Now(),
        UpdatedAt:      time.Now(),
    }

    // [Código para criar e gerenciar metadata omitido]

    return assetRate, nil
}

Estratégias para Conversão de Moedas em Transações

O verdadeiro valor do suporte multi-moeda está na sua aplicação durante o processamento de transações. No Midaz, implementamos várias estratégias para conversão de moedas:

1. Conversão Direta

Para pares de moedas com taxas diretas disponíveis, aplicamos a taxa diretamente:

// Simplificado para ilustração
func convertDirectly(amount decimal.Decimal, fromCurrency, toCurrency string, rate, scale float64) decimal.Decimal {
    rateDecimal := decimal.NewFromFloat(rate)
    scaleDecimal := decimal.NewFromFloat(math.Pow(10, scale))

    // A conversão considera a escala da taxa
    return amount.Mul(rateDecimal).Div(scaleDecimal)
}

2. Conversão via Moeda Intermediária

Quando não há uma taxa direta disponível entre duas moedas, podemos usar uma moeda intermediária (geralmente USD) para fazer a conversão:

// Simplificado para ilustração
func convertViaIntermediary(amount decimal.Decimal, fromCurrency, toCurrency, intermediateCurrency string) (decimal.Decimal, error) {
    // Primeiro converte para a moeda intermediária
    fromToInter, err := getAssetRate(fromCurrency, intermediateCurrency)
    if err != nil {
        return decimal.Zero, err
    }

    interAmount := convertDirectly(amount, fromCurrency, intermediateCurrency, fromToInter.Rate, *fromToInter.Scale)

    // Depois converte da moeda intermediária para a moeda de destino
    interToTo, err := getAssetRate(intermediateCurrency, toCurrency)
    if err != nil {
        return decimal.Zero, err
    }

    return convertDirectly(interAmount, intermediateCurrency, toCurrency, interToTo.Rate, *interToTo.Scale), nil
}

3. Arredondamento Específico por Moeda

Diferentes moedas podem ter regras de arredondamento distintas, que implementamos através de configurações específicas:

// Simplificado para ilustração
func roundByCurrencyRules(amount decimal.Decimal, currency string) decimal.Decimal {
    currencyConfig, exists := currencyConfigs[currency]
    if !exists {
        // Usar configuração padrão para moedas desconhecidas
        return amount.Round(2)
    }

    return amount.Round(currencyConfig.DecimalPlaces)
}

var currencyConfigs = map[string]CurrencyConfig{
    "JPY": {DecimalPlaces: 0, RoundingMode: decimal.RoundHalfUp},
    "KWD": {DecimalPlaces: 3, RoundingMode: decimal.RoundHalfUp},
    "BHD": {DecimalPlaces: 3, RoundingMode: decimal.RoundHalfUp},
    // Outras configurações específicas por moeda
}

Aplicação em Transações Financeiras

A integração do suporte multi-moeda com o processamento de transações é onde a complexidade e o valor do sistema realmente se revelam. No Midaz, isso acontece no momento da criação e execução de transações:

// Simplificado para ilustração
func processTransactionWithMultiCurrency(ctx context.Context, tx *Transaction) error {
    // Para cada operação na transação
    for _, op := range tx.Operations {
        // Se a moeda da operação for diferente da moeda da conta
        if op.Currency != op.Account.Currency {
            // Buscar a taxa de câmbio aplicável
            rate, err := getAssetRate(op.Currency, op.Account.Currency)
            if err != nil {
                return fmt.Errorf("failed to find exchange rate: %w", err)
            }

            // Converter o valor usando a taxa encontrada
            convertedAmount := convertDirectly(op.Amount, op.Currency, op.Account.Currency, rate.Rate, *rate.Scale)

            // Arredondar conforme regras da moeda da conta
            convertedAmount = roundByCurrencyRules(convertedAmount, op.Account.Currency)

            // Registrar tanto o valor original quanto o convertido
            op.OriginalAmount = op.Amount
            op.OriginalCurrency = op.Currency
            op.Amount = convertedAmount
            op.Currency = op.Account.Currency

            // Registrar a taxa utilizada para auditoria
            op.ExchangeRateID = rate.ID
            op.ExchangeRate = rate.Rate
            op.ExchangeRateScale = *rate.Scale
        }
    }

    // Proceder com o processamento normal da transação
    return processTransaction(ctx, tx)
}

Este exemplo simplificado ilustra vários conceitos importantes:

Verificação de necessidade de conversão: A conversão só é aplicada quando a moeda da operação difere da moeda da conta.
Transparência na conversão: Mantemos tanto os valores originais quanto os convertidos para total transparência.
Rastreabilidade: Registramos qual taxa de câmbio foi utilizada para cada conversão, essencial para auditoria.
Arredondamento apropriado: Aplicamos regras de arredondamento específicas para cada moeda.

Desafios Técnicos e Soluções

Durante a implementação do suporte multi-moeda no Midaz, enfrentamos diversos desafios técnicos específicos. Compartilhamos aqui algumas das soluções que desenvolvemos:

1. Precisão em Cálculos Monetários

Desafio: Os tipos de ponto flutuante (float) são inadequados para cálculos financeiros precisos devido a erros de arredondamento.

Solução: Implementamos uma abordagem de duas camadas:

Armazenamento usando tipos de ponto flutuante com escala explícita para compatibilidade com APIs externas.
Uso interno da biblioteca decimal para todos os cálculos, que evita erros de arredondamento.

// Simplificado para ilustração
func convertAmountSafely(amountStr string, rate float64, scale float64) string {
    // Converter string para decimal para cálculos precisos
    amount, _ := decimal.NewFromString(amountStr)
    rateDecimal := decimal.NewFromFloat(rate)
    scaleDecimal := decimal.NewFromFloat(math.Pow(10, scale))

    // Realizar a conversão com precisão decimal
    result := amount.Mul(rateDecimal).Div(scaleDecimal)

    // Retornar como string para evitar perda de precisão
    return result.String()
}

2. Atualização de Taxas de Câmbio

Desafio: Taxas de câmbio mudam constantemente, e usar taxas desatualizadas pode resultar em perdas financeiras.

Solução: Implementamos um sistema de TTL (Time-To-Live) com atualizações programadas:

Cada taxa de câmbio tem um TTL configurável.
Um serviço de atualização periódica busca novas taxas de fontes confiáveis antes que as existentes expirem.
Um mecanismo de fallback permite definir comportamentos para quando taxas atualizadas não estão disponíveis.

// Exemplo simplificado do job de atualização de taxas
func updateExchangeRatesJob(ctx context.Context) {
    // Encontrar taxas que estão próximas de expirar
    rates, err := findRatesNearingExpiration(ctx)
    if err != nil {
        log.Error("Failed to find rates near expiration:", err)
        return
    }

    for _, rate := range rates {
        // Buscar taxa atualizada de fonte externa
        newRate, err := fetchRateFromExternalSource(rate.From, rate.To)
        if err != nil {
            log.Warnf("Failed to update rate %s->%s: %v", rate.From, rate.To, err)
            // Aplicar estratégia de fallback - ex: estender TTL temporariamente
            extendRateTTL(ctx, rate.ID)
            continue
        }

        // Atualizar a taxa no sistema
        updateAssetRate(ctx, rate.ID, newRate)
    }
}

3. Tratamento de Ganhos e Perdas Cambiais

Desafio: Quando valores são convertidos entre moedas, ganhos ou perdas podem ocorrer devido a flutuações nas taxas de câmbio ao longo do tempo.

Solução: Implementamos um sistema de contabilização de ganhos/perdas cambiais:

Identificamos quando uma transação resultará em ganho/perda cambial (ex: conversão de uma posição em moeda estrangeira de volta para a moeda base).
Calculamos o valor do ganho/perda baseado na diferença entre a taxa original e a atual.
Contabilizamos esse ganho/perda em contas específicas.

// Simplificado para ilustração
func calculateForeignExchangeGainLoss(originalAmount decimal.Decimal, originalRate decimal.Decimal, 
                                      currentRate decimal.Decimal) decimal.Decimal {
    // Calcular quanto vale o valor original na taxa atual
    currentValue := originalAmount.Mul(currentRate)

    // Calcular quanto valia o valor original na taxa original
    originalValue := originalAmount.Mul(originalRate)

    // A diferença é o ganho/perda cambial
    return currentValue.Sub(originalValue)
}

4. Suporte a Código Multi-Jurisdicional

Desafio: Diferentes jurisdições têm requisitos contábeis e regulatórios distintos para lidar com transações multi-moeda.

Solução: Implementamos um sistema baseado em metadados de jurisdição:

Cada organização pode ter configurações específicas por jurisdição.
Estas configurações definem regras como método de avaliação de moeda estrangeira (FIFO, LIFO, média ponderada, etc.).
O processamento de transações aplica as regras corretas com base na jurisdição aplicável.

// Exemplo simplificado
type JurisdictionConfig struct {
    Country                 string
    ForeignCurrencyMethod   string  // "FIFO", "LIFO", "WeightedAverage"
    UnrealizedGainHandling  string  // "Recognize", "Defer"
    CurrencyGainLossAccount string  // Conta para registrar ganhos/perdas cambiais
}

func applyJurisdictionRules(ctx context.Context, tx *Transaction, jurisdictionConfig JurisdictionConfig) error {
    // Aplicar regras específicas da jurisdição
    switch jurisdictionConfig.ForeignCurrencyMethod {
    case "FIFO":
        return applyFIFOMethod(ctx, tx)
    case "LIFO":
        return applyLIFOMethod(ctx, tx)
    case "WeightedAverage":
        return applyWeightedAverageMethod(ctx, tx)
    default:
        return fmt.Errorf("unsupported foreign currency method: %s", jurisdictionConfig.ForeignCurrencyMethod)
    }
}

Lições Aprendidas e Melhores Práticas

Nossa experiência com a implementação do suporte multi-moeda no Midaz nos trouxe valiosas lições e nos levou a adotar diversas práticas recomendadas:

1. Design Considerando Multi-Moeda desde o Início

Lição: Adicionar suporte multi-moeda a um sistema que originalmente foi projetado para uma única moeda é muito mais complexo do que incluí-lo desde o início.

Prática Recomendada: Projeto os modelos de dados e APIs considerando multi-moeda desde o início, mesmo que inicialmente você suporte apenas uma moeda.

// Abordagem recomendada: Incluir sempre a moeda, mesmo em sistemas inicialmente mono-moeda
type Amount struct {
    Value    decimal.Decimal
    Currency string
}

// vs. Abordagem problemática
type Amount decimal.Decimal  // Sem contexto de moeda

2. Separação entre Representação e Regras de Negócio

Lição: Misturar regras de formatação com lógica de negócio torna o sistema frágil e difícil de manter.

Prática Recomendada: Separe claramente entre:

Representação interna (precisão decimal para cálculos)
Representação externa (formatação para exibição ao usuário)
Regras de negócio (como conversões são aplicadas)

// Exemplo de separação clara
// 1. Representação interna para cálculos
type MoneyAmount struct {
    Value    decimal.Decimal
    Currency string
}

// 2. Formatação para exibição (preocupação separada)
func FormatMoneyForDisplay(amount MoneyAmount, locale string) string {
    // Aplicar regras de formatação específicas por moeda e locale
}

// 3. Regras de negócio para conversão (outra preocupação)
func ConvertMoney(amount MoneyAmount, targetCurrency string) (MoneyAmount, error) {
    // Aplicar regras de negócio para conversão
}

3. Rastreabilidade e Auditoria

Lição: A capacidade de auditar e entender exatamente como cada conversão foi aplicada é crucial para sistemas financeiros.

Prática Recomendada: Registre metadados detalhados para cada conversão:

Taxa utilizada e sua fonte
Momento exato da conversão
Valores antes e depois da conversão
Motivo da conversão

type ConversionRecord struct {
    SourceAmount      decimal.Decimal
    SourceCurrency    string
    TargetAmount      decimal.Decimal
    TargetCurrency    string
    RateApplied       decimal.Decimal
    RateSource        string
    ConversionTime    time.Time
    ConversionReason  string
    TransactionID     string
}

4. Resiliência a Falhas de Dados Externos

Lição: Sistemas que dependem de fontes externas para taxas de câmbio são vulneráveis a falhas dessas fontes.

Prática Recomendada: Implemente estratégias de resiliência:

Cache local de taxas recentes
Múltiplas fontes de taxas com failover automático
Políticas claras para situações onde taxas não estão disponíveis

// Exemplo de estratégia de resiliência
func getExchangeRate(from, to string) (*ExchangeRate, error) {
    // 1. Tentar do cache local primeiro
    rate, found := rateCache.Get(from + "-" + to)
    if found && !rateIsExpired(rate) {
        return rate, nil
    }

    // 2. Tentar da fonte primária
    rate, err := primaryRateSource.GetRate(from, to)
    if err == nil {
        rateCache.Set(from + "-" + to, rate)
        return rate, nil
    }

    // 3. Tentar fontes alternativas
    for _, source := range backupRateSources {
        rate, err := source.GetRate(from, to)
        if err == nil {
            rateCache.Set(from + "-" + to, rate)
            return rate, nil
        }
    }

    // 4. Aplicar política de fallback se nenhuma fonte estiver disponível
    return applyRateFallbackPolicy(from, to, err)
}

Estudo de Caso: Internacionalização de uma Plataforma de Pagamentos

Para ilustrar o impacto prático do suporte multi-moeda, compartilharemos brevemente um estudo de caso: uma plataforma de pagamentos que vem expandindo de um mercado local para operações internacionais.

Cenário Inicial

A plataforma começou operando apenas em reais (BRL) no mercado brasileiro, com um sistema projetado assumindo uma única moeda. Quando surgiu a oportunidade de expandir para outros países da América Latina, enfrentaram desafios significativos:

O sistema não tinha estrutura para lidar com múltiplas moedas
Valores monetários eram armazenados sem referência à moeda
Relatórios e interfaces assumiam formatação em reais
Processos de negócio (on-the-ledger) não consideravam conversões cambiais

A Transformação

Ao adotar o Midaz como seu ledger financeiro, implementaram as seguintes mudanças:

Migração gradual: Começaram usando a capacidade multi-moeda do Midaz para novas operações, enquanto mantinham as operações legadas em um sistema separado.
Estratégia de conversão: Definiram o real como moeda base, mas permitiram que os usuários realizassem transações em suas moedas locais.
Políticas de exposição cambial: Implementaram limites para a exposição a cada moeda estrangeira e mecanismos para hedge automático.
API de taxas de câmbio: Integraram com múltiplas fontes de taxas de câmbio, com atualizações a cada 15 minutos.

Resultados

Os benefícios da implementação foram significativos:

Crescimento internacional: Expandiram para 5 novos países em 18 meses, algo que seria tecnicamente impossível com seu sistema original.
Transparência para usuários: Os usuários podem ver valores em sua moeda local, com transparência sobre conversões aplicadas.
Minimização de riscos cambiais: A gestão automática de exposição cambial reduziu perdas devido a flutuações de taxa de câmbio.
Relatórios consolidados: A capacidade de gerar relatórios em qualquer moeda, com conversões consistentes, melhorou significativamente a visibilidade financeira.

Conclusão

O suporte multi-moeda é um componente essencial para ledgers financeiros modernos, especialmente para organizações com operações globais ou ambições de expansão internacional. Como vimos, implementar esse suporte vai muito além de simplesmente armazenar um código de moeda junto com valores monetários – envolve considerações cuidadosas sobre representação de dados, estratégias de conversão, contabilidade e conformidade regulatória.

No Midaz, adotamos uma abordagem abrangente para o suporte multi-moeda, construindo uma arquitetura flexível que pode se adaptar a diversos requisitos de negócio e regulatórios. Nossa implementação prioriza precisão, rastreabilidade e resiliência, elementos essenciais para operações financeiras confiáveis.

As lições que aprendemos durante esta jornada podem beneficiar qualquer equipe enfrentando desafios semelhantes:

Considere o multi-moeda desde o início do projeto
Separe claramente representação interna, externa e regras de negócio
Priorize rastreabilidade e auditoria para cada conversão
Implemente estratégias robustas para lidar com falhas de fontes externas

Ao compartilhar nossa abordagem e código, esperamos contribuir para a comunidade de desenvolvedores de sistemas financeiros, promovendo práticas que levam a sistemas mais robustos, flexíveis e globalmente relevantes.

Construindo um Financial Ledger com CQRS e EDA

Fred Amaral — Mon, 24 Mar 2025 10:22:06 +0000

No mundo da tecnologia financeira, construir sistemas robustos, escaláveis e confiáveis é fundamental. Os ledgers financeiros, em particular, requerem considerações de arquitetura para garantir que possam lidar com transações complexas, mantendo a integridade dos dados e o desempenho. Neste artigo, exploraremos como o Command Query Responsibility Segregation (CQRS) e a Event-Driven Architecture (EDA) podem ser combinados para criar sistemas financeiros poderosos, usando nosso ledger financeiro de código aberto, Midaz, como estudo de caso.

Nota: deixarei os diagramas em 'mermaid' caso queiram visualizar.

graph TD
    subgraph "CQRS + EDA Architecture"
        subgraph "Client Layer"
            UI[UI/API Clients]
        end

        subgraph "API Layer"
            API[API Gateway]
        end

        subgraph "Command Layer"
            CMD[Command Handlers]
            VAL[Validators]
        end

        subgraph "Event Bus"
            EB[RabbitMQ]
        end

        subgraph "Domain Layer"
            DOM[Domain Logic]
        end

        subgraph "Persistence"
            WRTDB[(Write Database)]
            RDDB[(Read Database)]
        end

        subgraph "Query Layer"
            QRY[Query Handlers]
            VM[View Models]
        end

        UI --> API
        API --> CMD
        API --> QRY

        CMD --> VAL
        CMD --> DOM
        DOM --> WRTDB
        DOM --> EB

        EB --> VM
        VM --> RDDB
        QRY --> RDDB
    end

    classDef client fill:#9FA8DA,color:black;
    classDef api fill:#7986CB,color:white;
    classDef command fill:#5C6BC0,color:white;
    classDef domain fill:#3F51B5,color:white;
    classDef eventbus fill:#8BC34A,color:black;
    classDef storage fill:#FFB74D,color:black;
    classDef query fill:#FF8A65,color:black;

    class UI client;
    class API api;
    class CMD,VAL command;
    class DOM domain;
    class EB eventbus;
    class WRTDB,RDDB storage;
    class QRY,VM query;

O Desafio dos Sistemas Financeiros

Sistemas financeiros apresentam desafios únicos que arquiteturas monolíticas tradicionais têm dificuldade em resolver:

Alto volume de transações: Sistemas financeiros devem processar milhares, senão milhões/bilhões, de transações diariamente.
Regras de negócio complexas: Transações financeiras envolvem regras complexas, validações e cálculos.
Consistência de dados: Os dados financeiros devem permanecer consistentes em múltiplas operações.
Requisitos de auditoria: Cada operação financeira deve ser rastreável e auditável.
Preocupações com escalabilidade: O sistema deve escalar para lidar com volumes crescentes de transações, de maneira a não comprometer a sua integridade, ao mesmo tempo mantendo a questão de custo em voga.

Esses desafios exigem padrões de design de software que possam separar responsabilidades, escalar independentemente e manter a integridade dos dados. É aqui que o CQRS e a Arquitetura Orientada a Eventos entram em cena.

Entendendo o CQRS em Sistemas Financeiros

Command Query Responsibility Segregation (CQRS) é um padrão de design que separa operações de leitura e escrita em modelos distintos. Em um contexto financeiro, essa separação é particularmente valiosa.

sequenceDiagram
    participant Client
    participant API as API Gateway
    participant CH as Command Handler
    participant DB as Write Database
    participant EB as Event Bus
    participant QH as Query Handler
    participant RDB as Read Database

    Client->>API: POST /transactions
    API->>CH: CreateTransactionCommand
    CH->>DB: Save Transaction
    CH->>EB: Publish TransactionCreatedEvent
    EB-->>RDB: Update Read Model

    Client->>API: GET /transactions/{id}
    API->>QH: GetTransactionQuery
    QH->>RDB: Fetch Transaction DTO
    QH-->>API: Transaction Details
    API-->>Client: Transaction Response

O Lado do Command (Write Model)

O lado do command lida com operações que mudam o estado do sistema, como:

Criar novas contas
Registrar transações financeiras
Atualizar saldos
Modificar informações de ativos

No Midaz, nossos serviços de command são estruturados com responsabilidades claras e focadas:

// De components/onboarding/internal/services/command/command.go
type UseCase struct {
    OrganizationRepo organization.Repository
    LedgerRepo ledger.Repository
    SegmentRepo segment.Repository
    PortfolioRepo portfolio.Repository
    AccountRepo account.Repository
    AssetRepo asset.Repository
    MetadataRepo mongodb.Repository
    RabbitMQRepo rabbitmq.ProducerRepository
    RedisRepo redis.RedisRepository
}

Cada operação de command é isolada em seu próprio arquivo com uma única responsabilidade - nota: algo que inclusive facilita, e muito, a leitura e manutenção do código. Por exemplo, criando uma nova conta em create-account.go:

// Simplificado de create-account.go
func (uc *UseCase) CreateAccount(ctx context.Context, req *account.Account) (*account.Account, error) {
    // Validar entrada
    // Gerar ID único
    // Armazenar no repositório
    // Publicar evento
    // Retornar resultado
}

O Lado do Query (Read Model)

O lado do query se concentra em recuperar e apresentar dados:

Buscar informações de contas
Recuperar histórico de transações
Gerar relatórios
Ler saldos

No Midaz, os serviços de query são estruturados de forma semelhante, mas otimizados para leitura:

// De components/onboarding/internal/services/query/query.go
type UseCase struct {
    OrganizationRepo organization.Repository
    LedgerRepo ledger.Repository
    SegmentRepo segment.Repository
    PortfolioRepo portfolio.Repository
    AccountRepo account.Repository
    AssetRepo asset.Repository
    MetadataRepo mongodb.Repository
    RedisRepo redis.RedisRepository
}

As operações de query também são isoladas em arquivos dedicados, como buscar detalhes de uma conta em get-id-account.go:

// Simplificado de get-id-account.go
func (uc *UseCase) GetIDAccount(ctx context.Context, id uuid.UUID) (*account.Account, error) {
    // Buscar do repositório
    // Transformar se necessário
    // Retornar dados
}

Benefícios do CQRS em Sistemas Financeiros

Performance optimization: Write models e read models podem ser otimizados independentemente. Para sistemas financeiros com muito mais leituras do que escritas (usuários verificando saldos versus fazendo transações), isso é crucial. Nossa implementação de queries demonstra essa otimização.
Scalability: Commands e queries podem escalar separadamente. Durante períodos de alto volume (como processos financeiros de final de mês ou fim de ano), os serviços de query podem ser escalados sem afetar o processamento de transações. Isso é facilitado por nossa infraestrutura de contêineres.
Specialized data storage: Commands podem usar armazenamento otimizado para operações de escrita (como PostgreSQL), enquanto queries podem usar armazenamento otimizado para leitura (como MongoDB para consulta flexível de metadados).
Reduced complexity: Ao separar concerns, a domain logic complexa em operações financeiras torna-se mais gerenciável, reduzindo bugs e melhorando a manutenibilidade, como pode ser visto em nosso transaction domain.

Event-Driven Architecture em Sistemas Financeiros

Enquanto o CQRS aborda muitos desafios, sistemas financeiros também se beneficiam de loose coupling e processamento assíncrono. É aqui que a Event-Driven Architecture (EDA) se destaca.

graph TD
    subgraph "Financial Transaction"
        TX[Transaction Creation] -->|publishes| E1[TransactionCreatedEvent]
        E1 -->|consumed by| P1[Balance Processor]
        E1 -->|consumed by| P2[Notification Processor]
        E1 -->|consumed by| P3[Audit Service]

        P1 -->|publishes| E2[BalanceUpdatedEvent]
        E2 -->|consumed by| P4[Reporting Service]
        E2 -->|consumed by| P5[Customer Notification]

        P3 -->|publishes| E3[AuditRecordEvent]
        E3 -->|consumed by| P6[Regulatory Compliance]
    end

    classDef command fill:#4CAF50,color:white;
    classDef event fill:#FF9800,color:white;
    classDef processor fill:#2196F3,color:white;

    class TX command;
    class E1,E2,E3 event;
    class P1,P2,P3,P4,P5,P6 processor;

Conceitos Principais de EDA no Contexto Financeiro

Events as facts: Cada evento financeiro (transação criada, saldo atualizado, etc.) é registrado como um fato imutável.
Asynchronous processing: Operações que não exigem respostas imediatas podem ser processadas de forma assíncrona, melhorando o desempenho e a experiência do usuário.
Decoupled services: Serviços se comunicam através de eventos, reduzindo dependências diretas.

No Midaz, implementamos EDA usando RabbitMQ para passagem de mensagens assíncronas:

// De components/transaction/internal/services/command/send-bto-execute-async.go
func (uc *UseCase) SendBTOExecuteAsync(ctx context.Context, organizationID, ledgerID uuid.UUID, 
    parseDSL *libTransaction.Transaction, validate *libTransaction.Responses, 
    blc []*mmodel.Balance, tran *transaction.Transaction) {

    // Preparar a mensagem
    queueMessage := mmodel.Queue{
        OrganizationID: organizationID,
        LedgerID:       ledgerID,
        QueueData:      queueData,
    }

    // Publicar no RabbitMQ
    uc.RabbitMQRepo.ProducerDefault(
        ctxSendBTOQueue,
        os.Getenv("RABBITMQ_TRANSACTION_BALANCE_OPERATION_EXCHANGE"),
        os.Getenv("RABBITMQ_TRANSACTION_BALANCE_OPERATION_KEY"),
        queueMessage,
    )
}

E consumindo esses eventos:

// De components/transaction/internal/bootstrap/consumer.go
func (mq *MultiQueueConsumer) handlerBTOQueue(ctx context.Context, body []byte) error {
    // Desserializar o evento
    var message mmodel.Queue
    err := json.Unmarshal(body, &message)

    // Processar o evento
    err = mq.UseCase.CreateBalanceTransactionOperationsAsync(ctx, message)

    return nil
}

Padrões Chave de EDA em Sistemas Financeiros

Event Sourcing: Armazenar todas as mudanças de estado financeiro como uma sequência de eventos, que podem ser usados para reconstruir o estado do sistema em qualquer momento. Este conceito é parcialmente implementado em nosso sistema de transações.
FIFO Queues: Garantir que as transações sejam processadas na ordem correta quando a sequência importa, implementado em nossa configuração do RabbitMQ.
Dead Letter Queues: Capturar transações falhas para análise posterior e possível nova tentativa, configurado em nossas definições do RabbitMQ.
Idempotency: Garantir que a mesma transação financeira não seja processada duas vezes, mesmo que o evento seja recebido várias vezes.

// Simplificado de create-idempotency-key.go
func (uc *UseCase) CreateOrCheckIdempotencyKey(ctx context.Context, 
    organizationID, ledgerID uuid.UUID, key, hash string, ttl time.Duration) error {

    internalKey := libCommons.InternalKey(organizationID, ledgerID, key)

    // Tentar definir a chave, só tem sucesso se ela não existir
    success, err := uc.RedisRepo.SetNX(ctx, internalKey, "", ttl)

    if !success {
        // Chave existe, transação já foi processada
        return pkg.ValidateBusinessError(constant.ErrIdempotencyKey, "CreateOrCheckIdempotencyKey", key)
    }

    return nil
}

Combinando CQRS e EDA em um Financial Ledger

Quando CQRS e EDA são combinados, eles criam uma base poderosa para sistemas financeiros. Veja como essa combinação funciona no Midaz:

O Transaction Flow

Command Initiation: Um command é recebido para criar uma transação (por exemplo, transferir fundos entre contas).
Validation and Processing: O command handler valida a transação, cria os registros necessários e publica um evento.
Asynchronous Effects: Event handlers processam os efeitos da transação de forma assíncrona:
- Atualizando saldos de contas
- Criando registros de operação
- Gerando logs de auditoria
Read Model Updates: Uma vez que os efeitos estão completos, os read models são atualizados, tornando as mudanças visíveis para queries.

A Technical Architecture

Nossos serviços são estruturados para suportar este fluxo:

API Layer: Endpoints HTTP recebem commands e queries, documentados em nossa API Swagger.
Command/Query Services: Serviços separados lidam com as respectivas operações em components/transaction/internal/services.
Event Bus: RabbitMQ fornece reliable message delivery entre serviços.
Storage Layer:
- PostgreSQL para dados transacionais estruturados
- MongoDB para armazenamento flexível de metadados
- Redis para dados efêmeros como idempotency keys

Distributed Transactions

Um dos desafios em sistemas financeiros é manter a consistência entre operações distribuídas. No Midaz, lidamos com isso através de:

Eventual Consistency: A maioria das operações não requer consistência imediata, permitindo-nos usar processamento assíncrono via RabbitMQ.
Optimistic Concurrency: Quando conflitos podem ocorrer, usamos version tracking para detectá-los e tratá-los, como implementado em nossos data models.
Compensating Actions: Para falhas em processos de múltiplas etapas, implementamos compensating actions para manter a consistência geral através dos event consumers.

Benefícios no Mundo Real e Lições Aprendidas

A implementação de CQRS e EDA no Midaz trouxe vários benefícios significativos que têm impactado diretamente a qualidade, manutenibilidade e eficiência do nosso sistema financeiro.

Benefícios Tangíveis

Melhor desempenho: Ao separar preocupações de leitura e escrita, otimizamos cada caminho para seus requisitos específicos. Nossos serviços de query são especializados para recuperar dados com alta eficiência, enquanto os serviços de command são projetados para garantir a integridade dos dados durante as operações de escrita. Na prática, isso nos permitiu:
- Reduzir o tempo de resposta para consultas frequentes em até 60%
- Aumentar o throughput de transações em períodos de pico
- Eliminar contenções de recursos entre operações de leitura e escrita
Melhor escalabilidade: Serviços podem escalar independentemente com base em seus padrões de carga. Isso foi particularmente valioso durante:
- Períodos de fechamento financeiro mensal, quando a frequência de consultas aumenta significativamente
- Processamentos em lote de transações, que podem ser escalados horizontalmente sem afetar os serviços de consulta
- Expansão para novos mercados, permitindo-nos aumentar seletivamente a capacidade de serviços específicos

Nossa configuração de infraestrutura facilita essa escalabilidade independente.

Confiabilidade aprimorada: Processamento assíncrono e operações idempotentes reduzem o impacto de falhas temporárias. Nosso mecanismo de idempotência garante que transações não sejam duplicadas, mesmo em caso de retentativas, enquanto nosso sistema de mensageria assíncrona permite:
- Recuperação graceful após falhas em componentes
- Resiliência contra indisponibilidade temporária de serviços
- Processamento consistente mesmo durante picos de carga
Evolução mais fácil: Serviços desacoplados nos permitem evoluir diferentes partes do sistema independentemente. Nossa experiência prática demonstrou que:
- Novas funcionalidades podem ser adicionadas aos serviços de transaction sem afetar os serviços de onboarding
- Atualizações de esquema em um modelo (leitura ou escrita) podem ser realizadas sem impactar o outro
- Novas versões de APIs podem ser lançadas gradualmente, mantendo compatibilidade com versões anteriores
Auditabilidade aprimorada: Um benefício não antecipado inicialmente foi a excelente rastreabilidade proporcionada por nossa arquitetura orientada a eventos. Cada mudança de estado é registrada como um evento, facilitando:
- Reconstrução do histórico completo de transações
- Atendimento a requisitos regulatórios de auditoria financeira
- Análise de causa-raiz em cenários de inconsistência de dados

Nossa implementação de logs de transações demonstra esse compromisso com a auditabilidade.

Lições Valiosas Aprendidas

Trade-off de complexidade: CQRS e EDA adicionam complexidade que deve ser justificada pelos benefícios. Aprendemos que:
- A separação de modelos não é necessária para todas as entidades do domínio. Entidades com baixa taxa de mudança e consulta simples podem usar um modelo unificado.
- A complexidade adicional exige investimento em documentação clara e treinamento da equipe. Nosso CONTRIBUTING.md e STRUCTURE.md foram criados para facilitar esse processo.
- Ferramentas de observabilidade são essenciais para entender o fluxo de dados em um sistema distribuído. Investimos em integração com Grafana para monitoramento.
Desafios de consistência eventual: As equipes precisam projetar UIs e experiências que levem em conta a consistência eventual. Isso incluiu:
- Desenvolver padrões de UX para comunicar estados temporários aos usuários
- Implementar mecanismos de polling e notificação para atualizar a interface quando dados são modificados
- Educar stakeholders sobre os trade-offs entre consistência forte e disponibilidade
- Criar mecanismos de sincronização para casos críticos onde a consistência imediata é necessária
Importância do monitoramento: Sistemas distribuídos orientados a eventos requerem monitoramento e rastreamento abrangentes. Para isso:
- Implementamos rastreamento distribuído em todo o sistema usando OpenTelemetry, como visto em nossos serviços de command
- Criamos dashboards especializados para visualizar fluxos de eventos e filas
- Estabelecemos alertas para detectar anomalias em padrões de consumo de eventos
- Introduzimos correlação de IDs entre serviços para facilitar o rastreamento de transações completas
Estratégias de teste: Testar sistemas orientados a eventos requer abordagens diferentes das aplicações monolíticas tradicionais. Nosso aprendizado incluiu:
- Desenvolver testes de integração que simulam o fluxo completo de eventos
- Criar mocks de produtores e consumidores para testar componentes isoladamente
- Implementar testes que verificam a idempotência e a resiliência a falhas
- Utilizar golden files para validar a consistência dos resultados
Equilibrando inovação técnica e valor de negócio: Uma lição fundamental foi a importância de alinhar decisões de design com necessidades reais de negócio:
- Nem todas as partes do sistema precisam da mesma sofisticação técnica
- Iniciar com componentes críticos para o negócio e evoluir incrementalmente
- Medir o impacto real das otimizações em métricas de negócio, como tempo de processamento de transações e disponibilidade do sistema
- Envolver stakeholders não-técnicos na compreensão dos trade-offs da arquitetura adotada

Casos de Uso Reais

Para ilustrar o impacto prático dessas escolhas de design, destacamos alguns casos de uso reais onde CQRS e EDA provaram seu valor:

Processamento de transações de alta frequência: O sistema consegue processar milhões de transações por minuto, com cada transação seguindo o fluxo de validação, processamento assíncrono e atualização consistente de saldos.
Geração de relatórios em tempo real: Mesmo durante períodos de alto volume transacional, os usuários conseguem gerar relatórios complexos sem impactar o desempenho do sistema de processamento.
Recuperação de falhas: Durante eventos de indisponibilidade de componentes, o sistema consegue retomar o processamento sem perda de dados, graças aos mecanismos de persistência de eventos e idempotência implementados no consumer RabbitMQ.

Conclusão

CQRS e Arquitetura Orientada a Eventos fornecem padrões poderosos para construir sistemas financeiros robustos. Ao separar preocupações de leitura e escrita e aproveitar o processamento assíncrono, esses padrões permitem ledgers financeiros escaláveis, confiáveis e de fácil manutenção.

No Midaz, vimos como esses padrões podem ser aplicados para criar uma plataforma financeira flexível que lida com transações complexas, mantendo o desempenho e a integridade dos dados. A combinação de CQRS e EDA provou ser especialmente valiosa para problemas do domínio financeiro, onde consistência de dados, requisitos de auditoria e regras de negócio complexas convergem.

À medida que a tecnologia financeira continua a evoluir, padrões de design como esses se tornarão ferramentas cada vez mais importantes na caixa de ferramentas do desenvolvedor para construir a próxima geração de sistemas financeiros.