Cookbook do módulo

Cada página aqui é uma receita: uma coisa que você precisa fazer no módulo, com o código mínimo que já compila, a mudança de descritor que vem junto, como testar e o que costuma dar errado.

Todo bloco de código deste cookbook foi copiado de um módulo real — o módulo sample, que acompanha estas páginas. Ele é pequeno de propósito (itens de um tenant e a varredura assíncrona deles) e todo o código dele existe por causa de uma receita. Nada aqui é exemplo inventado: rode o módulo, rode os testes, e o comportamento é o que está escrito.

O que você precisa antes

• Java 26 e o Maven Wrapper do módulo (./mvnw) — o wrapper já está no repositório gerado.
• Um MySQL de desenvolvimento, para as receitas de banco e de migration.
• O módulo gerado pelo nnconsole module create <id> (ou um clone do módulo sample), com nnp/, nns/ e src/ na raiz.

Como o módulo é montado

Onde	O que é
nnp/release.yaml	A release: id, versão, o que ela publica. Muda a cada release, junto com o marcador.
nnp/api.yaml	As rotas: caminho, método, permissão, modo (sync/async), idempotência, limite de corpo.
nnp/iam.yaml	As permissões do produto e os papéis que as agrupam.
nnp/audit.yaml	As trilhas e os eventos de audit.
nnp/placement.yaml	Classe, recursos e réplicas (e o autoscaling por KEDA).
nns/service.yaml	O serviço: rede de saída, chamadores internos, slots de segredo, configuração, banco, identidade.
nns/internal/store/migrations/	As migrations (expand-only) e o MANIFEST.
nns/api/openapi.yaml	O contrato HTTP publicado, conferido contra o api.yaml.
nns/helm/chart/	O chart que o Module Manager renderiza.
java/	O serviço Spring Boot sobre o SDK.

O ciclo de trabalho

# 1. o serviço compila e os testes passam
./mvnw -q verify

# 2. os descritores estão coerentes entre si e com o código
./nnconsolew descriptors validate

# 3. a imagem (Paketo, JVM, non-root)
./mvnw spring-boot:build-image

# 4. o pacote instalável
./nnconsolew nnp build

O ./mvnw -q verify é o gate local: ele sobe os descritores embutidos (NnsModule), roda os testes de unidade, os de banco (com NNC_TEST_MYSQL_DSN definida) e as sondas de processo.

As receitas

Receita	Para quê
Endpoint	Expor uma rota pública e devolver JSON.
Ação assíncrona	Aceitar uma operação demorada e acompanhar o estado (202 + Action).
Papel	Declarar um papel e o que ele agrupa.
Claim	Ler o contexto verificado (quem chama, de que tenant, com que permissões).
Permissão	Declarar a permissão de uma rota e conferi-la no serviço.
Acesso a banco	Consultar e mutar o MySQL com Db/Tx, transação e paginação.
Migration	Mudar o schema sem quebrar a release que está no ar.
Segredo	Ler um slot de Secret que chega como arquivo.
Configuração	Declarar e ler configuração do service.yaml.
Evento de audit	Registrar a mudança de domínio na trilha certa, na mesma transação.
Tarefa periódica	Rodar trabalho de tempos em tempos, só na release ativa.
Integração com outro serviço	Chamar outro serviço com identidade de serviço pelo Service Registry.
Erros	Recusar com o Error Model (13 códigos, reason estável).
Testes	Unidade, HTTP com autorização e MySQL de verdade.
Build	Compilar, testar e empacotar o serviço.
Imagem	Gerar a imagem OCI com o Spring Boot.
NNP	Montar, conferir e assinar o pacote do módulo.
Publicação	Subir, implantar, atualizar e voltar atrás.

O módulo de exemplo

O módulo sample está em sample/ ao lado destas páginas:

sample/
  nnp/ release.yaml api.yaml iam.yaml audit.yaml placement.yaml
  nns/ service.yaml api/openapi.yaml helm/chart/ internal/store/migrations/
  java/ pom.xml mvnw src/main/java/... src/test/java/...

Para rodá-lo:

cd sample/java
export NNC_TEST_MYSQL_DSN='usuário:senha@tcp(127.0.0.1:3306)/'
./mvnw -q verify

Sem a NNC_TEST_MYSQL_DSN, os testes de banco são pulados (e dizem isso): nunca trocados por um banco em memória, porque o que se está provando é o comportamento do MySQL (collation, chave única, coluna JSON, contagem de linhas afetadas).