Conceitos fundamentais

O que acontece quando sua aplicação sobe

Quando o host lê o seu YAML, cada step do pipeline é construído uma única vez: sua configuração é lida, qualquer expressão JSONata dentro dele é compilada, e referências a recursos declarados (uma entidade, um dataSource, um cache) são resolvidas. Se algo estiver errado — uma chave de step que não existe, uma expressão com sintaxe inválida, uma referência a uma entidade que não foi declarada — a aplicação não sobe. Você recebe um erro claro no startup, não uma exceção inesperada na primeira requisição de produção. É por isso que vale a pena testar sua aplicação localmente antes de implantar: qualquer erro estrutural do YAML aparece imediatamente.

Depois que a aplicação subiu com sucesso, cada requisição HTTP (ou cada mensagem consumida) roda o pipeline já construído, do primeiro step ao último, sobre o estado daquela execução específica. É esse pipeline construído — leve, sem reconstruir nada a cada chamada — que responde de fato.

Na prática, isso significa: erros de configuração custam um docker compose up que falha, não um incidente. Erros de dado (um payload inválido, uma regra de negócio violada) são responsabilidade do próprio pipeline em runtime, tratados com os steps que você já vê no YAML (validate, fail).

O estado do pipeline

Todo step lê e escreve num único documento com slots bem definidos, disponível para qualquer expressão JSONata do pipeline:

Slot Conteúdo
input A entrada da execução. Em api: body, query, headers, route, claims. Em consumer: body, headers, key, metadata
vars Variáveis criadas pelo pipeline (map, set)
steps.<id>.result O resultado de um step que declarou id
output O que vira a resposta HTTP ou a mensagem publicada
error Preenchido dentro de um bloco catch (veja Controle de fluxo)

Um exemplo: input.body.customerId lê um campo do corpo da requisição; steps.customer.result lê o resultado de um step anterior que declarou id: customer; vars.order lê algo que um map anterior gravou.

Anatomia do documento YAML

apiVersion: pipevine.dev/v1     # obrigatório — identifica a versão do vocabulário
kind: Application
metadata:
  name: orders                  # identificador da aplicação
  version: 1.0.0
  description: Serviço de pedidos
spec:
  type: api                     # api | consumer
  ...
  • apiVersion identifica a versão do vocabulário YAML em si (não a versão da sua aplicação). Veja Versionamento para a garantia de estabilidade por trás disso.
  • kind é sempre Application hoje.
  • metadata identifica a aplicação: name (obrigatório), version (obrigatório), description (opcional).
  • spec é onde tudo acontece: o type da aplicação (api ou consumer), as rotas ou consumidores, e os recursos compartilhados (fontes de dados, caches, brokers, integrações, esquemas de autenticação) referenciados por eles.

Todo campo documentado como expressão — em qualquer parte do documento — aceita JSONata avaliado sobre o estado do pipeline acima. Expressões são compiladas no startup: sintaxe inválida derruba o build, não a primeira requisição.

Convenções gerais

Referências e includes

Um documento grande pode ser dividido em arquivos menores com $ref:

routes:
  - $ref: ./routes/create-order.yaml

Substituição de variáveis

connectionString: "${config:ConnectionStrings:Orders}"
clientSecret:     "${secret:orders-idp-secret}"
logLevel:         "${env:LOG_LEVEL}"
  • ${env:...} lê uma variável de ambiente.
  • ${config:...} lê da configuração do host (appsettings.json, variáveis de ambiente mapeadas pelo binder padrão do .NET, etc.).
  • ${secret:...} é resolvido por um ISecretResolver plugável — veja ISecretResolver. Credenciais nunca aparecem em texto claro no YAML; todo campo que representa uma credencial (senha, chave de assinatura, segredo de cliente) exige essa forma, e a aplicação recusa subir se encontrar um valor literal onde uma referência a segredo é esperada.

JSONata: o papel dele

Dois usos bem separados, com responsabilidades diferentes:

  • JSON Schema valida a forma de um payload — campos obrigatórios, tipos, formatos. Ve Validação e mapeamento.
  • JSONata faz duas coisas: valida regras de negócio (relações entre campos, condições de domínio que um JSON Schema não expressa bem) e mapeia dados de uma forma para outra — transformando input.body num modelo de domínio, montando o payload de um evento, etc.

Toda expressão JSONata do seu YAML é compilada no startup, junto com o resto do pipeline — o mesmo raciocínio da seção anterior se aplica: um erro de sintaxe é um erro de build.

Para onde ir daqui

Edit this page