Protocolo de comunicação e integração

As aplicações desenvolvidas com Devprime utilizam uma arquitetura orientada a eventos (event-driven architecture - EDA) para comunicação assíncrona e utilizam um protocolo padrão, garantindo comunicação e integração fluida entre os microsserviços. Essa abordagem assegura rastreabilidade e melhora a observabilidade por meio de logs e rastreamento distribuído.

Esta documentação define o modelo de payload para publicação de eventos em sistemas de streaming como RabbitMQ e Kafka, e detalha as adaptações necessárias para aplicações legadas, destacando os campos obrigatórios e opcionais. Para aplicações externas, é essencial que o payload siga o mesmo formato e inclua as informações especificadas, garantindo compatibilidade e monitoramento eficiente. Embora a integração nativa seja opcional, recomenda-se para maximizar os benefícios da Devprime em todo o ecossistema de aplicações.

Estrutura do Payload padrão do Evento

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

{
  "Headers": {},
  "Id": "<Guid>", 
  "CorrelationId": "<Guid>",
  "TraceId": "<Guid>",
  "AppId": "<Guid fixo identificando app legado>",
  "AppName": "Myapp",
  "Version": 1,
  "Name": "OrderCreated",
  "CreationDate": "2022-06-07T11:26:21.7636769-03:00", 
  "Payload": {
    //Include your custom payload (json)
  }
}

Descrição dos Campos

Campo Tipo Descrição Obrigatoriedade
Headers object Contém headers adicionais, pode ser usado para transportar metadados específicos. Opcional
Id string (GUID) Identificador Guid único do evento gerado pela aplicação legada ao criar um novo evento. Obrigatório
CorrelationId string (GUID) Identificador Guid usado para correlacionar eventos e deve ser gerado pela aplicação legada. Obrigatório
TraceId string (GUID) Identificador Guid de rastreamento, útil para tracing distribuído. Obrigatório
AppId string (GUID) Identificador Guid fixo da aplicação legada que gera o evento. Obrigatório
AppName string Nome da aplicação que está publicando o evento. Exemplo: “Integrador 1.0”. Obrigatório
Version integer Versão do evento. Normalmente incrementado em caso de mudanças no formato do payload. Obrigatório
Name string Nome do evento. Exemplo: “OrderCreated”. Obrigatório
CreateDate string (DateTime) Data e hora da criação do evento, no formato ISO 8601. Obrigatório
Payload object (JSON) JSON contendo os dados do evento. Obrigatório

Exemplos de Uso

Payload Completo (Recomendado)

Este exemplo inclui todos os campos necessários para uma rastreabilidade completa e integração adequada com o sistema de observabilidade:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

{
  "Headers": {},
  "Id": "6598cd76-7e9f-4f1f-a140-01ed92f3b60d",
  "CorrelationId": "26a91e94-7f31-4401-8352-3d6d7ad0f5fb",
  "TraceId": "26a91e94-7f31-4401-8352-3d6d7ad0f5fb",
  "AppId": "e6ae2fd2-99ca-4287-bcaa-fb8c83b92edc",
  "AppName": "MyApp",
  "TenantID": "",
  "TenantUserID": "",
  "Version": 1,
  "Name": "OrderCreated",
  "CreationDate": "2024-09-11T12:04:47.5302497-03:00",
  "Payload": {
    "OrderId": "9375cde2-1770-4186-8ffb-ee6e81aa5d91",
    "CustomerName": "Name",
    "CustomerTaxId": "string",
    "Total": 0
  }
}

Payload Reduzido (Opcional)

Este exemplo omite alguns campos para uma implementação mais simples para casos em que a rastreabilidade não é necessária:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

{
  "AppId": "fef824a5-0eea-4b49-b08e-0bad25dbd55d",
  "AppName": "MyApp",
  "Version": 1,
  "Name": "OrderCreated",
  "CreationDate": "2022-06-07T11:26:21.7636769-03:00",
  "Payload": {
    "OrderId": "9375cde2-1770-4186-8ffb-ee6e81aa5d91",
    "CustomerName": "Name",
    "CustomerTaxId": "string",
    "Total": 0
  }
}

Considerações Finais

Ao implementar o padrão de payload descrito acima permitirá que aplicações legadas e externas interajam de forma eficaz com a plataforma Devprime, garantindo que eventos sejam monitorados e rastreados adequadamente durante todo o processo de homologação e produção. É altamente recomendável que os desenvolvedores sigam as orientações para garantir a compatibilidade e a eficiência da integração.

Para saber mais:

Última modificação September 12, 2024 (e8cc11e9)