Relações: as setas

Uma relação é uma seta de uma caixa para outra, com um rótulo curto dizendo o que trafega. Ela descreve intenção — “reserva itens”, “publica o pedido” —, e não protocolo.

A forma mais simples

model/reservas/elements.yaml

relations:
  - from: colaborador
    to: reservas
    kind: sync
    label: Procura e reserva

Os campos de uma relação

Campo	Obrigatório	O que faz
from	sim	a caixa de origem
to	sim	a caixa de destino
kind	não	o tipo da seta, que decide traço, ponta e cor. Padrão: sync
label	não	poucas palavras sobre o que trafega. É o título do cartão que aparece ao passar o mouse
description	não	a forma longa, revelada ao passar o mouse
bidirectional	não	true põe ponta também na origem
route	não	straight, orthogonal ou bezier, sobrepondo o padrão do diagrama
tags	não	etiquetas livres
meta	não	pares chave/valor livres
id	não	um identificador próprio, para o caso raro de algo externo precisar nomear aquela seta

Sem id, o identificador é derivado como <origem>~<tipo>~<destino>. Duas setas iguais entre as mesmas caixas recebem um sufixo #2, #3 e assim por diante.

Os tipos de seta

kind	Aparência	Uso típico
sync	linha cheia, ponta fechada	uma chamada em que se espera resposta
async	tracejado longo, ponta aberta	uma mensagem em que não se espera resposta
event	pontilhado roxo, ponta aberta	a publicação de um evento
batch	tracejado bem espaçado	uma carga periódica
dep	tracejado fino cinza	uma dependência sem tráfego, como uma biblioteca
peer	pontas nos dois lados	uma conversa nos dois sentidos

Um tipo desconhecido não some do desenho: vira uma linha cheia com ponta fechada, e o cfour check avisa. Você pode criar tipos próprios em Aparência da modelagem.

Onde escrever uma relação

Numa lista relations:, em qualquer arquivo do projeto. É a forma que os exemplos usam. Um arquivo só de relações também vale.

Dentro do documento do próprio elemento. Num documento singular de elemento (kind: element), uma lista relations: aninhada tem o from implícito — ele é a caixa que declara:

model/reservas/api.yaml

kind: element
id: api
name: API de Reservas
shape: api
parent: reservas

relations:
  - to: banco
    kind: sync
    label: Le e grava

Escrever from: ali seria ignorado. A escolha entre as duas formas é de organização: setas junto da caixa que as origina ficam fáceis de achar; um arquivo de relações separado é melhor quando a seta atravessa projetos e nenhum dos dois lados deveria ser o dono dela.

Como uma referência é resolvida

Todo campo que cita outra caixa — from, to, parent, scope, subject, target, os seletores de um diagrama, os participantes de um fluxo — segue a mesma regra:

Como está escrito	Como resolve
com barra, reservas/api	absoluta: projeto e identificador
sem barra, api	tenta o projeto que declara; se não achar, tenta shared/

Uma referência sem barra não é global: api escrito dentro do projeto portaria procura portaria/api e depois shared/api, e falha se nenhum dos dois existir. Para atravessar projeto, qualifique.

Uma referência que não resolve é erro, não aviso: o cfour check reprova e diz o arquivo e o campo.

A seta é escrita uma vez, no nível mais fino

Esta é a segunda regra que muda a forma de trabalhar. Quando você desce um nível e descobre qual componente de fato conversa com o banco, a seta desce com ele — e você apaga a versão mais geral.

Antes, no nível de container:

relations:
  - from: api
    to: banco
    kind: sync
    label: Le e grava

Depois, quando os componentes da API existem:

relations:
  - from: repositorio-de-reservas
    to: banco
    kind: sync
    label: Le e grava

O diagrama de containers continua mostrando a mesma seta: como o repositório está dentro da API, o desenho projeta cada ponta na caixa mais próxima que ele está mostrando. Você não mantém a integração escrita em dois lugares.

Como confirmar isso

cfour diagram show containers --resolved lista as caixas e as setas que o desenho de fato produz, e diz por que cada uma entrou.

Erros comuns

Escrever a mesma integração em dois níveis. O resultado são duas setas paralelas no diagrama mais geral. Declare no nível mais fino que você conhece.

Uma seta de uma caixa para ela mesma. É ignorada, com aviso. Uma ação interna não é uma relação — se ela importa, ela é um passo de um fluxo.

Uma seta entre uma caixa e um filho dela. É aceita, mas quase sempre é ruído: a contenção já diz que um está dentro do outro.

Confiar num identificador sem barra para alcançar outro projeto. Ele só procura o projeto local e o shared.

Próximo passo

Com caixas e setas, dá para desenhar. Diagrama de contexto.