Técnicas

Estrutura de projeto

Camadas, forge.toml e como organizar código que cresce.

Começar#

bash

dataforge init meu-app
cd meu-app

text

meu-app/
  forge.toml                 manifesto
  src/main.df                o programa
  tests/principal_test.df    os testes

As quatro camadas#

Camada	Contém	Depende de
Modelo	records, enums, invariantes	nada
Regras	decisões de negócio	modelo
Apresentação	como virar texto	modelo, regras
Aplicação	orquestra o fluxo	todas

As setas apontam sempre para baixo. O modelo não sabe que existe apresentação; as regras não sabem se o resultado vira terminal, HTTP ou CSV.

Num projeto real#

text

src/
  modelo.df          record Produto, enum Situacao
  regras.df          situacao_de, precisa_repor
  apresentacao.df    formatar_produto, cabecalho
  main.df            junta tudo
tests/
  regras_test.df
forge.toml

E cada módulo declara sua interface:

dataforge

// regras.df
relay LIMITE_CRITICO, situacao_de, precisa_repor

Por que separar#

O critério prático é o que muda junto:

Trocar o limite de estoque crítico → mexe só em regras.df
Trocar o terminal por uma página web → mexe só em apresentacao.df
Acrescentar um campo ao produto → mexe em modelo.df e em quem usa o campo

Quando tudo está num arquivo, qualquer mudança arrisca qualquer coisa.

Regras puras são testáveis#

dataforge

action situacao_de(p: Produto) -> Situacao:
    given p.estoque is 0:
        yield Situacao.EmFalta
    orif p.estoque smaller LIMITE_CRITICO:
        yield Situacao.Critico
    yield Situacao.Normal

Essa ação não imprime, não lê arquivo, não consulta banco. O teste é uma linha e roda em microssegundos.

Converter na fronteira#

O banco guarda linhas; o programa trabalha com records:

dataforge

action buscar_todos():
    linhas := DB.query(conn, "SELECT id, nome, preco FROM produtos")
    yield linhas >> morph l: Produto(l["id"], l["nome"], l["preco"])

Essa conversão paga por si: dali em diante o código usa p.nome com verificação de tipo, em vez de l["nome"] com risco de digitar errado. E se a coluna mudar de nome, só esta linha muda.

O ciclo de trabalho#

bash

dataforge check src/          # nomes, tipos, aridade
dataforge lint src/           # estilo e higiene
dataforge fmt src/            # formatar
dataforge test tests/ -v      # testes
dataforge doc src/ --out=doc/API.md
dataforge run                 # executar