Diagrama de Arquitetura
Um diagrama é compreendido quando o que ele mostra se encaixa no que o leitor já sabe. Um desenvolvedor sênior o lê para o fluxo de alto nível e para as costuras. Um bloco é uma caixa-preta: seu padrão de design, pelo que é responsável, quem o possui, e seu interior oculto. O que um bloco oferece a outro através de uma costura é sua interface: operações com tipos de parâmetro e retorno, erros, os tipos de dados que a cruzam com seus campos, e um exemplo do que exatamente cruza e como se parece. O transporte (REST, OPC UA, uma inicialização de processo) é um atributo de uma interface e nunca a substitui.
Leia EXAMPLE.md antes de desenhar: uma mudança, completa, em ambas as formas.
Etapas
1. As palavras do leitor
Um novo termo não se ancora em nada. Antes de qualquer outra coisa, colete as palavras que o leitor já tem: de suas mensagens nesta conversa, dos documentos que escreveu (instruções do projeto, páginas de arquitetura, glossários, tabelas de nomenclatura), e de cada modelo com o qual o diagrama é comparado. Escreva a lista de palavras: a coisa, a palavra do leitor para ela, a palavra de cada outra parte que lerá o diagrama, o nome no código, e a palavra que o diagrama usa.
- Rotule cada bloco e interface com a palavra do leitor; o nome do código fica ao lado.
- Onde duas palavras colidirem, ou uma palavra for usada para a coisa errada, escolha uma, diga o porquê na lista de palavras, e nomeie a outra ao lado uma vez.
- Não cunhe nada. Uma interface sem um nome no código é chamada por suas duas extremidades,
Frontend -> Backend. - Comece pela imagem que o leitor já tem, seu próprio diagrama com seus níveis e nomes, e coloque o que é novo dentro dele.
Feito quando cada rótulo no diagrama vem da lista de palavras, e cada termo novo para o leitor está no glossário ao lado da palavra conhecida à qual pertence.
2. Perguntas
Escreva as perguntas do leitor, uma linha cada. Eles escolhem as visões.
| Pergunta | Visão |
|---|---|
| Quais são as partes, pelo que cada uma é responsável, quem a possui, quem chama quem? | visão de blocos de construção |
| Qual interface une duas partes, e o que exatamente a cruza? | a interface, seus tipos de dados e um exemplo em cada costura |
| O que acontece, em qual ordem, no cenário que importa? | visão de tempo de execução: uma sequência |
| Onde cada parte é executada? | host: em cada bloco; uma visão de implantação quando redes ou limites de confiança são a questão |
| O que uma mudança faz, ou como dois designs diferem? | cada estado na mesma forma, depois as diferenças |
Feito quando cada visão tem sua pergunta e a pergunta está acima dela como sua legenda.
3. Catálogo
Preencha quatro listas a partir das fontes antes de qualquer desenho.
- Blocos: a palavra do leitor e o nome no código, estereótipo, uma frase de responsabilidade, proprietário, host.
- Interfaces, uma por costura: provedor, consumidores, cada operação como uma assinatura
nome(parâmetro: Tipo) -> Tipo, erros, transporte. - Tipos de dados: cada tipo que uma assinatura nomeia, com seus campos, unidades e padrões.
- Exemplos, um por interface: uma mensagem como ela cruza, chamada e resposta em seu formato real: uma linha de comando com sua saída, um corpo JSON, uma linha de tabela. Tire-o de uma execução, uma gravação, um fixture ou os dados. Um exemplo montado a partir do código diz isso em sua primeira linha.
Cada entrada carrega sua origem: uma referência de código caminho:linha, ou uma tag (abaixo). Um estado desenhado por outra pessoa, um arquivo de modelo ou um esboço, é reproduzido como está e em suas próprias palavras; o que ele omite é marcado como [indefinido], e o que você adiciona vai para um estado próprio.
Feito quando cada bloco tem sua frase, cada costura uma interface cujas assinaturas são copiadas do código ou marcadas, cada tipo em uma assinatura seus campos, cada interface seu exemplo, e cada entrada uma referência ou uma tag.
4. Nível
Os blocos de um estado são pares: unidades que são implantadas, possuídas ou substituídas por conta própria, de cinco a nove delas. Arquivos, funções e as etapas dentro de um bloco são seu interior. Um zoom é um diagrama adicional um nível abaixo, desenhado para o bloco sobre o qual a pergunta é.
Feito quando nenhum bloco de um estado está dentro de outro, e cada zoom nomeia a pergunta que o justifica.
5. Forma
- Forma de chat, até 78 colunas: a visão de blocos de construção com o nome da interface e sua assinatura principal em cada aresta, depois o catálogo como tabelas e os exemplos como blocos de código. Para um estado ou uma pequena mudança.
- Forma de tela, uma página HTML estática de diagramas de texto tão largos quanto necessário: ao lado de cada aresta sua interface completa, o exemplo, e os tipos de dados com seus campos. Para vários estados, ou quando mais de três costuras são mostradas por completo. A página é construída por um script gerador que fica ao lado dela; a resposta do chat nomeia o arquivo, diz em algumas frases o que a comparação mostra e lista as decisões em aberto.
- Forma C4, o mesmo modelo desenhado com LikeC4 em uma página com uma guia por estado, caixas para clicar e ampliar. Os diagramas de texto são seu protótipo: estabeleça palavras, blocos, interfaces e exemplos lá primeiro, depois renderize. Para um resultado que outras pessoas abrirão. Leia LIKEC4.md.
6. Desenhe
Desenhe com os três arquivos nesta pasta, para que as caixas se alinhem e nenhuma linha seja mais larga que sua tela. O docstring de cada arquivo é seu manual, e executá-lo imprime uma demonstração.
| Arquivo | Fornece |
|---|---|
grid.py | Grid (caixas com compartimentos, linhas, setas), sequence (uma visão de tempo de execução), table |
canvas.py | glance (cada estado em uma linha), overview (estados lado a lado, uma linha por nível), panel (um estado: blocos, interfaces com exemplos, tipos de dados) |
page.py | html_page: a página ao redor dos diagramas, com as cores e os links entre ids |
likec4/ | para a forma C4: template.c4, build.sh, a página de guias index.html com tabs.js, e clicktest.py |
Uma página vai da imagem de dez segundos ao detalhe: de relance, a lista de palavras, o guia de leitura, a visão geral, um painel por estado, as diferenças por costura como uma tabela, as decisões em aberto, glossário, fontes.
7. Verifique
- Cada caixa é um bloco do catálogo, cada aresta uma interface, cada caixa de tipo um tipo de dado; uma entrada omitida de um diagrama é omitida de propósito.
- Cada referência de código se resolve: o arquivo existe e a linha mostra o nome.
- O mesmo bloco está no mesmo lugar em todos os estados. Um bloco que um estado não tem é uma caixa pontilhada lá.
- Capturas de tela da página inteira, lidas bloco por bloco: bordas se encontram, nada é cortado, as cores carregam seu significado.
- As fontes nomeiam o que foi lido, em qual commit, quais exemplos são reais, e o que não foi lido.
Estados
Um estado é o código como ele é, um alvo que alguém desenhou, ou uma proposta. Compare estados por posição: o mesmo bloco na mesma coluna de glance e na mesma linha de overview, para que as lacunas de dois estados mostrem onde eles se complementam.
Uma costura tem um id de uma letra para seu estado e um número, (I4). Uma interface ou tipo de dado definido em uma costura é referenciado por esse id em todos os outros lugares; seus campos são escritos uma vez.
As diferenças são uma tabela com uma linha por costura e uma coluna por estado. As decisões em aberto são uma tabela: a pergunta, as opções, quem decide.
Tags e estereótipos
| Tag | Significado |
|---|---|
[código] | existe no código; a referência está ao lado |
uma tag de fonte, ex. [c4] | declarado por um modelo fonte; nomeie a tag no guia de leitura |
[proposto] | proposto aqui, não existe em nenhum lugar ainda |
[novo] [alterado] [movido] | o que uma mudança faz, quando há apenas como-está e para-ser |
[indefinido] | o estado deixa em aberto |
[?1] | uma decisão em aberto, listada com seu número |
Estereótipos nomeiam o padrão de design que um bloco desempenha: <<ui>>, <<cliente>>, <<gateway>>, <<fachada>>, <<serviço>>, <<porta>>, <<adaptador>>, <<repositório>>, <<externo>>. Use um onde o código desempenha esse papel; um bloco sem estereótipo é melhor do que um com o errado. Uma porta é uma interface que o consumidor possui e o provedor implementa: <<porta>> está na interface, <<adaptador>> no bloco que a implementa. Os tipos próprios de um modelo fonte são citados como ele os escreve.
Dispositivos de explicação
Cada um destes ganha seu lugar ao responder algo que o leitor teria que perguntar de outra forma. Use-os com moderação.
- Guia de leitura: um pequeno diagrama que mostra como um painel é lido, e as tags.
- Referências de código: em cada interface e tipo de dado, para que o leitor possa consultá-las.
- Textos curtos: um parágrafo acima de um estado que diz a única coisa a ver nele; uma nota dentro de uma caixa de interface onde o leitor perguntaria por quê.
- Glossário: os termos que a lista de palavras não cobre, uma linha cada.
- Cor: apenas para as tags, os ids, e um ou dois nomes
chaveque permanecem os mesmos em todos os estados. A cor marca o que os estados compartilham e onde diferem; nada mais é colorido.
O texto em prosa está no idioma da conversa. Nomes do código e de modelos fonte são literais.