Padrões de Desenvolvimento tinystruct

Padrões de arquitetura e implementação para construir módulos com o framework Java tinystruct – um framework leve e de alta performance que trata CLI e HTTP como cidadãos iguais, não exigindo um método main() e configuração mínima.

Princípio Central

CLI e HTTP são cidadãos iguais. Cada método anotado com @Action deve, idealmente, ser executável tanto de um terminal quanto de um navegador web sem modificação. Essa capacidade "dual-mode" é a filosofia de design central do tinystruct.

Ferramenta Primária de Desenvolvimento: bin/dispatcher

bin/dispatcher é a ferramenta padrão e de maior prioridade para desenvolver, executar, testar e depurar uma aplicação tinystruct – use-a antes de uma configuração de execução de IDE, um main() escrito manualmente, curl ou um navegador. Como cada @Action é dual-mode por design, bin/dispatcher permite que você exercite roteamento, vinculação de argumentos e lógica de negócios diretamente do terminal, com o ciclo de feedback mais rápido possível e sem a necessidade de servidor/navegador.

# Run any @Action directly - the fastest way to verify a new action works
# (the class must be imported; see --import or default.import.applications in application.properties)
bin/dispatcher greet/James --import com.example.MyService
bin/dispatcher echo --words "Praise the Lord"

# Start the HTTP server when you need the web-facing counterpart
bin/dispatcher start --import org.tinystruct.system.HttpServer

# Import additional Application/MCP classes for the current run
# (one --import per class; a comma-separated list fails with ClassNotFoundException)
bin/dispatcher start --import org.tinystruct.system.HttpServer --import com.example.MyService

# Discover what's available
bin/dispatcher --help
bin/dispatcher --version

Adote este fluxo de trabalho por padrão: implemente o @Action, execute-o imediatamente via bin/dispatcher <action> para confirmar que ele se comporta corretamente no modo CLI e só inicie o servidor HTTP (também via bin/dispatcher start ...) quando precisar verificar o caminho voltado para a web (por exemplo, mode = Mode.HTTP_POST, sessões, uploads de arquivos). Nunca codifique um main(String[] args) como ponto de entrada de uma aplicação – bin/dispatcher (ou bin/dispatcher.cmd no Windows) é o único ponto de entrada para cada módulo.

Gerando bin/dispatcher e bin/dispatcher.cmd

Todo projeto tinystruct precisa de seu launcher em bin/. O framework o gera – nunca o escreva à mão, e nunca o copie de outro projeto ou substitua um main(). ApplicationManager.init() escreve o launcher para o sistema operacional atual em bin/ sob o diretório de trabalho sempre que ele estiver faltando, a partir de templates dentro do jar do tinystruct, com a versão desse jar preenchida. Quebras de linha e o bit executável já estão corretos.

1. Encontre a versão do tinystruct contra a qual o projeto está sendo compilado: a propriedade <tinystruct.version> ou a dependência org.tinystruct:tinystruct em pom.xml. O jar deve ser alcançável, em ~/.m2/repository/org/tinystruct/tinystruct/<version>/ (execute mvn dependency:resolve se não estiver) ou no lib/ do projeto.

2. A partir da raiz do projeto, execute o framework uma vez:

java -cp ~/.m2/repository/org/tinystruct/tinystruct/<version>/tinystruct-<version>.jar \
     org.tinystruct.system.Dispatcher --version

Substitua <version> pela versão encontrada na etapa 1. No Windows, use %USERPROFILE%\.m2\repository\org\tinystruct\tinystruct\<version>\tinystruct-<version>.jar e a mesma classe. Isso cria apenas o script para o SO em que você o executou, e apenas se ele ainda não existir:

3. Verifique. A partir da raiz do projeto, execute bin/dispatcher --version (Windows: bin\dispatcher.cmd --version). Ele imprime Dispatcher (cli) (built on tinystruct-<version>), e o VERSION dentro do script é igual à versão do jar. Em seguida, bin/dispatcher --help lista os comandos e todas as ações importadas. Mostre ao usuário o arquivo que você criou.

4. Obtenha ambos os scripts executando a etapa 2 em cada SO, ou deixe um colega de equipe ou CI no outro SO executá-lo e commitar o resultado. Commite ambos, para que um checkout em qualquer SO funcione. Não tente simular o outro SO com -Dos.name=…: no Windows, ele falha (UnsupportedOperationException de setPosixFilePermissions) e deixa um bin/dispatcher vazio. .gitattributes recomendado, para que um checkout não corrompa as quebras de linha:

…