DEV Community: He4rt Developers

O que uma usina nuclear tem a ver com o seu processo de QA?

Alicia Marianne 🇧🇷 — Sun, 05 Apr 2026 12:02:52 +0000

A gente sabe que testar e validar um software antes de ir para produção é importante. Mas você já parou para pensar no peso real que isso carrega?

Recentemente, estava revendo a série Chernobyl, e ela me fez refletir sobre muita coisa — especialmente sobre a forma como encaro minha área, sendo QA, e sobre a responsabilidade que ela traz. Resolvi compartilhar isso com vocês.

Para quem não conhece, Chernobyl é uma minissérie dramática lançada em 2019 que retrata o desastre nuclear ocorrido na usina de mesmo nome, na então União Soviética, em 26 de abril de 1986. A história acompanha os eventos logo após a explosão do reator número 4 — o caos, as tentativas do governo soviético de esconder a gravidade do acidente e o enorme esforço de cientistas, bombeiros, militares e trabalhadores que arriscaram, e muitas vezes perderam, suas vidas para evitar uma catástrofe ainda maior. A série também segue o cientista Valery Legasov, que tenta descobrir a verdadeira causa do acidente e expor a verdade por trás da tragédia.

Mas o ponto aqui vai além da série.

O que mais me chamou atenção foi o quanto aquela tragédia conversa com algo que vivemos diariamente no desenvolvimento de software: a responsabilidade nas decisões.

O que aconteceu em Chernobyl?

Mesmo sabendo que existem elementos dramatizados, dá para aprender muita coisa com esse desastre. Não sou física nuclear, mas vou tentar resumir o que aconteceu — porque foi justamente essa parte que mais me fez refletir sobre responsabilidade e tomada de decisão.

Na madrugada do dia 26 de abril de 1986, os operadores da usina realizavam um teste de segurança no reator 4. O objetivo era validar se, em caso de queda de energia, as turbinas ainda conseguiriam gerar eletricidade por alguns segundos — tempo suficiente até que os geradores de emergência fossem acionados. No papel, o teste parecia simples.

O problema é que, para executá-lo, diversos sistemas de segurança foram desativados e a potência do reator foi reduzida para um nível muito abaixo do ideal. Foi aí que tudo começou a sair do controle.

O reator utilizado era do tipo RBMK, um modelo com uma falha crítica de projeto: em determinadas condições, quanto mais vapor era gerado dentro do sistema, maior ficava a potência do reator. Em vez de estabilizar, ele se tornava cada vez mais instável. Para piorar, o teste foi conduzido sob forte pressão da liderança, mesmo diante de sinais claros de que não era seguro continuar.

Ao longo da série, vemos os próprios operadores levantando preocupações — que foram ignoradas. Quando perceberam que a situação era crítica, acionaram o botão de desligamento de emergência. Em teoria, esse comando deveria encerrar a reação. Mas, por uma falha no design das barras de controle, o efeito inicial foi o oposto: a potência disparou. Em poucos segundos, temperatura e pressão subiram de forma descontrolada.

O resultado foram duas explosões que destruíram o topo do reator, expuseram o núcleo à atmosfera e liberaram uma enorme quantidade de material radioativo. O incêndio que se seguiu espalhou radiação por boa parte da Europa, transformando Chernobyl no maior desastre nuclear da história.

O que mais me impactou foi perceber que a tragédia não aconteceu por um único erro. Ela foi consequência de uma cadeia de decisões ruins: falhas técnicas ignoradas, riscos mal avaliados e pessoas que não foram ouvidas.

E o que isso tem a ver com software?

Depois de assistir à série, comecei a fazer um paralelo com a nossa área. Porque, no fim, quantas vezes um incidente em produção também não nasce da mesma forma?

Nem sempre o problema vem de um único bug. Muitas vezes, ele é o resultado de uma sequência de decisões tomadas sem o devido cuidado: um requisito mal definido, um risco não mapeado, uma validação superficial, uma entrega apressada — ou um alerta levantado pelo time que acabou sendo ignorado.

Foi aí que a série me fez enxergar algo que vai além do contexto dela: quando a pressa fala mais alto do que a análise, o custo quase sempre aparece depois.

O maior problema: risco tratado de forma rasa

Um dos maiores desafios que vejo hoje no desenvolvimento de software é justamente o planejamento e o levantamento de riscos feitos de maneira superficial.

Tenho certeza de que você vai concordar: não tem coisa pior do que refazer algo ou ficar apagando incêndios que poderiam ter sido discutidos antes.

Vivemos num mundo onde tempo é dinheiro. E é exatamente por isso que qualidade precisa estar presente desde o início — não como uma etapa final, mas como parte do processo.

Como QA, vou compartilhar duas coisas que considero essenciais.

Ouça sua equipe

Independentemente da sua posição no time, ouça as pessoas ao seu redor.

Ninguém conhece melhor o produto do que quem o construiu, testou e convive com ele diariamente. Antes de uma nova funcionalidade entrar ou de um teste ser executado, converse com o time.

Escute quem desenvolveu. Escute o produto. Escute suporte. Escute quem está mais próximo do usuário.

Muitas vezes, o risco já foi identificado por alguém. Ele só não foi ouvido.

Analise antes de agir

Entender o impacto de uma mudança não é só uma questão técnica — é também uma questão de negócio.

Por exemplo: você vai melhorar a query de uma API. Em teoria, isso pode não alterar nenhuma regra de negócio. Mas como isso afeta o usuário final? A performance realmente melhorou? Existe algum impacto colateral? Como vamos medir se essa mudança foi positiva ou negativa?

Nem toda melhoria técnica gera melhoria de produto. E esse olhar crítico é parte fundamental do papel de QA.

Conclusão

No fim, Chernobyl me fez refletir sobre algo que vai muito além de uma série: a responsabilidade por trás de cada decisão que tomamos no dia a dia.

A gente não está lidando com um reator nuclear. Mas ainda assim lida com impacto real — no usuário, no negócio e no próprio time. Um risco ignorado, um teste mal planejado ou uma decisão tomada sem ouvir a equipe podem não gerar uma catástrofe, mas certamente geram problemas que poderiam ter sido evitados com mais atenção, diálogo e análise.

Para mim, ser QA vai muito além de encontrar bugs.

É questionar antes que o problema aconteça. É analisar cenários com olhar crítico. É antecipar riscos. É provocar conversas importantes dentro do time. É ajudar a construir decisões mais seguras e conscientes.

No final, qualidade não é apenas sobre software funcionando.

É sobre responsabilidade, colaboração e cuidado com tudo aquilo que criamos.

De front-end para UX, e de volta ao código: o que significa ser Design Engineer em 2026

vitoriazzp — Fri, 03 Apr 2026 13:00:00 +0000

Sou UX/UI designer, mas antes disso fui front-end.

Atuei cerca de 5 anos trabalhando com HTML e CSS, transformando layouts em páginas, entendendo hierarquia de informação e estrutura de interface. Depois, tomei o caminho oposto: migrei para UX/UI e agora completo 5 anos atuando em produtos, passando por fintech, utilities e atuando como Product Designer.

Essa trajetória, de front para UX e agora voltando a se aproximar do código, é justamente o que me levou a me reconhecer em um termo que gosto bastante: Design Engineer.

Minha trajetória: 5 anos de front-end, 5 anos de UX

Quando era front-end, eu via a tela como um resultado de código: HTML estruturando a informação, CSS dando forma e layout, um pouco de JavaScript dando comportamento.

Quando migrei para UX, passei a olhar mais para o todo do produto: pesquisa, fluxos, contexto do usuário, design systems, governança, revisão de interfaces, conversa com times de produto e de negócios.
Hoje, percebo que essas duas visões não são opostas. Elas se completam.

O que é design engineer em 2026?

Se você pesquisar sobre "Design Engineer", vai encontrar muitas definições técnicas, mas na prática o que mais faz sentido para mim é:

A pessoa que entende UX, código e um pouco de backend ao mesmo tempo, e usa isso para desenhar interfaces que são pensadas desde o primeiro pixel até a última chamada de API.

Não é só "quem desenha + quem programa"
É quem pensa em experiência e implementação juntas:

Um botão que não só parece bem-desenhado, mas também considera estados de loading, erro, disabled.
Um fluxo de cadastro que não só é bonito, mas que já prevê o que o backend vai precisar para validar, salvar e devolver feedback.
Um produto que pensa em performance, acessibilidade e usabilidade em uma única conversa.

Como front-end e UX mudam sua forma de ver produto

Como eu via a tela como desenvolvedor front-end
HTML estruturando a informação. CSS dando forma. Um pouco de JavaScript dando comportamento. A tela era resultado direto do código.

O que mudou quando migrei para UX/UI
Passei a olhar para o produto como um todo: pesquisa, fluxos, contexto do usuário. O código virou uma consequência, não o ponto de partida.

O que muda agora é que percebo que não preciso mais ficar só de um lado

Por que estou voltando ao código agora

Com o avanço de ferramentas como IA integrada ao Figma, prototipagem cada vez mais próxima do código e experiências acumuladas como Product Designer, foi aí que o conceito de Design Engineer passou a fazer sentido de verdade pra mim.

JavaScript moderno, React e um pouco de backend
Comecei a estudar de forma mais focada para:

Atualizar meu JavaScript (ES2024, async/await, fetch, arrays/objetos)
Reativar React (componentes, hooks, estado compartilhado)
Entender backend leve (Node/Express, rotas simples, persistência básica)
Pensar em performance e otimização das interfaces que ajudo a construir

Como estou usando IA no processo de aprendizado

Hoje, uso o Claude AI não como substituto, mas como apoio para:

Quebrar problemas de código em etapas menores
Revisar fluxos de dados entre front e backend
Organizar pensamentos e lógica de features

Design Engineer não é um cargo. É uma forma de pensar

O que mais gosto de dizer é que, em 2026, Design Engineer não é só um título de empresa grande ou de time específico. Pode existir em qualquer lugar onde UX e código se encontram:

Em um produto próprio
Em um projeto freelancer
Em um repositório público
Em um fluxo de trabalho híbrido, mesmo sem ter um cargo oficial com esse nome

O que importa é a maneira de pensar: UX + código ao mesmo tempo. Protótipos e implementação como parte do mesmo processo. Interfaces que consideram o que o usuário sente e o que o backend precisa.

O que vem por aí: UX data-driven e componentes React

Esse movimento não é só "voltar" ao front-end. É re-aprender JavaScript, entender melhor React e backend, e levar essa visão de UX para dentro do código.
Em breve, quero escrever mais sobre:

Como transformo um fluxo de UX do Figma em componentes React
Como penso em performance e carregamento em UX para web
Como organizar estudos de UX + código em ciclos curtos e práticos

E numa parte que ainda não me sinto confortável, mas sei que é essencial: vou falar sobre como estou começando a me tornar uma UX mais data-driven, porque ser Design Engineer em 2026 também é aprender a ouvir o que os números dizem sobre o UX que eu desenho.

Você também está nesse meio-termo entre UX e código?

Se você chegou até aqui, é bem provável que também se sinta em algum meio-termo entre UX e código.

Que tal comentar:

Como você se vê hoje entre design e desenvolvimento?
Você já tentou voltar pro código depois de virar UX, ou está no caminho invertido?

Esse é o tipo de conversa que me ajuda a entender como o conceito de Design Engineer está se moldando, bem além de títulos de empresa.

Construí um gerador de playlists no Spotify com Claude

Leo Garcez — Tue, 24 Mar 2026 02:01:08 +0000

Eu queria digitar “noite chuvosa, meio melancólica” e receber uma playlist perfeita. Então eu construí isso.

TL;DR

Eu construí um gerador de playlists com IA usando Claude + Spotify API
Você descreve um humor → ele gera 50 músicas → salva direto no Spotify
O maior problema foi OAuth local com NextAuth (sim, foi um inferno)
Claude funciona bem, mas precisa de bastante controle pra não inventar músicas
Streaming com SSE melhorou muito a UX

Links:

Índice

A Ideia
A Stack
O Problema de Trabalhar com OAuth Localmente
Endpoints Deprecated do Spotify
Spotify em Produção
Fazendo o Claude Obedecer
Prompt Engineering Anti-Alucinação
Modo Related Artists
Construindo o Perfil Musical
Streaming com SSE
O Que Aprendi

A Ideia

Fazer um gerador de playlists que realmente entendesse vibes, não só tags de gênero. Algo tipo: você digita "tarde fria num apartamento vazio" e recebe uma playlist boa de verdade, já salva no seu Spotify.

O conceito:

Usuário descreve um humor
Claude retorna 50 músicas em JSON
App busca cada faixa no Spotify
Cria e salva a playlist na conta do usuário

Três APIs, um app.

A Stack

Next.js 14 (App Router)
NextAuth v5 beta
Anthropic Claude API (claude-sonnet-4-6)
Spotify Web API
Supabase (PostgreSQL)
TypeScript + Tailwind CSS + Framer Motion

Escolhi o Claude porque ele tá bem em alta agora e, na prática, é confiável, alucina menos do que eu esperava pra esse tipo de tarefa. Ele é um pouco menos criativo que o GPT nas recomendações, mas compensa sendo mais previsível no formato das respostas, o que importa bastante quando você tá parseando JSON.

O Problema de Trabalhar com OAuth Localmente

Isso me custou algumas horas e sessões de debug. Vou detalhar porque tem várias camadas de problema e você provavelmente vai bater na mesma parede se estiver usando NextAuth v5 com Spotify.

O Spotify não aceita `localhost`

O Spotify proíbe localhost como redirect URI pra URIs de loopback. A solução é usar 127.0.0.1. Cadastrei http://127.0.0.1:3000/api/auth/callback/spotify no dashboard e setei AUTH_URL=http://127.0.0.1:3000 no .env.local.

Não foi suficiente.

O `NextRequest` normaliza URLs pra `localhost`

O Next.js, independente do host que você passa pra next dev -H, normaliza req.url e req.nextUrl.href de volta pra localhost em desenvolvimento. Isso não é bug documentado — é comportamento interno do framework.

O NextAuth v5 tem um utilitário chamado reqWithEnvURL que tenta corrigir exatamente isso, mas falha silenciosamente:

// Dentro do next-auth — simplificado
function reqWithEnvURL(req: NextRequest): NextRequest {
  const url = process.env.AUTH_URL ?? req.url;
  return new NextRequest(url, req); // ← o construtor normaliza de volta pra localhost
}

Mesmo passando 127.0.0.1 explicitamente, o construtor do NextRequest sobrescreve. A "correção" não funciona.

Dois momentos onde o redirect URI importa

O OAuth tem dois momentos distintos onde o redirect URI aparece:

Requisição de autorização — a URL do Spotify onde o usuário loga. O redirect_uri aqui vem dos seus params de configuração, então você pode hardcodar 127.0.0.1 na config do provider. Isso funcionou.
Troca de token — quando o Spotify manda o código de volta, o @auth/core envia um POST pra trocar o código por tokens. O redirect_uri nessa requisição vem de provider.callbackUrl, que é derivado de params.url.origin — ou seja, da URL da requisição de callback. Se essa URL ainda diz localhost, a troca falha com invalid_grant: Invalid redirect URI.

O sintoma era desconcertante: a URL de autorização mostrava 127.0.0.1 corretamente, mas a troca de token continuava falhando. Fui atrás do código do @auth/core pra entender o que tava acontecendo.

A solução: `Auth()` direto com `Request` nativo

Objetos Request nativos do browser/Node não normalizam URLs. A correção é contornar os route handlers do NextAuth e chamar Auth() do @auth/core diretamente, passando um Request nativo com a URL já corrigida:

// src/app/api/auth/[...nextauth]/route.ts
import { Auth } from "@auth/core";
import { authConfig } from "../../../../../auth";
import { NextRequest } from "next/server";

function buildRequest(req: NextRequest): Request {
  const authOrigin = process.env.AUTH_URL ?? `http://${req.headers.get("host")}`;
  const fixedUrl = req.url.replace(/^https?:\/\/[^/]+/, authOrigin);

  const hasBody = req.method !== "GET" && req.method !== "HEAD";
  return new Request(fixedUrl, {
    method: req.method,
    headers: req.headers,
    body: hasBody ? req.body : undefined,
    // duplex necessário para streaming de body no Node.js
    ...(hasBody && ({ duplex: "half" } as object)),
  });
}

const handler = (req: NextRequest) =>
  Auth(buildRequest(req), authConfig as Parameters<typeof Auth>[1]);

export { handler as GET, handler as POST };

Versão do @auth/core: ao usar Auth() diretamente, instale a versão exata que o next-auth usa internamente:

npm ls @auth/core  # veja qual versão o next-auth requer
npm install @auth/core@0.41.0 --save-exact

Versões diferentes criam conflitos de tipo que explodem em runtime.

Configuração explícita no auth.ts: ao contornar os handlers do NextAuth, setEnvDefaults não roda mais. Configure basePath, secret e redirect_uri explicitamente:

// auth.ts
export const authConfig: NextAuthConfig = {
  trustHost: true,
  basePath: "/api/auth",
  secret: process.env.AUTH_SECRET,
  providers: [
    Spotify({
      clientId: process.env.AUTH_SPOTIFY_ID,
      clientSecret: process.env.AUTH_SPOTIFY_SECRET,
      authorization: {
        url: "https://accounts.spotify.com/authorize",
        params: {
          scope: SPOTIFY_SCOPES,
          show_dialog: true,
          redirect_uri: `${process.env.AUTH_URL}/api/auth/callback/spotify`,
        },
      },
    }),
  ],
  // ... callbacks e pages como antes
};

Bônus: problema de domínio do cookie PKCE

Mesmo com tudo acima, pode acontecer mais uma falha: se o usuário acessa http://localhost:3000, o navegador seta o cookie PKCE pro domínio localhost. Quando o Spotify redireciona de volta pra http://127.0.0.1:3000/..., o navegador não envia o cookie — domínios diferentes — e o code_verifier some. A troca falha de novo.

A correção é garantir que localhost:3000 nunca apareça pro usuário, redirecionando via next.config.mjs:

async redirects() {
  return [
    {
      source: "/:path*",
      has: [{ type: "host", value: "localhost:3000" }],
      destination: "http://127.0.0.1:3000/:path*",
      permanent: false,
    },
    {
      source: "/",
      has: [{ type: "host", value: "localhost:3000" }],
      destination: "http://127.0.0.1:3000/",
      permanent: false,
    },
  ];
},

Com isso, todo o fluxo de auth fica em 127.0.0.1 e os cookies PKCE chegam onde precisam chegar.

Endpoints Deprecated do Spotify

Com o auth funcionando, bati num muro de 403s.

O Spotify deprecated alguns endpoints sem muito alarde:

Antigo (deprecated)	Novo
`POST /playlists/{id}/tracks`	`POST /playlists/{id}/items`
`GET /playlists/{id}/tracks`	`GET /playlists/{id}/items`
`GET /audio-features`, `GET /recommendations`	Deprecated, sem substituto

A migração /tracks → /items está documentada, mas é fácil de perder se você seguiu um tutorial de 2022. Audio features e recomendações sumindo foi mais chato — tive que construir contexto de energia de outra forma, mais sobre isso abaixo.

Spotify em Produção

Tem uma limitação que eu não vi muito discutida: no modo de desenvolvimento, o Spotify permite apenas 5 usuários autenticados E eles precisam ser adicionados manualmente via allowlist no dashboard.

Pra ir além disso, você precisa solicitar Extended Quota Mode. E o processo atual é bem pesado:

Entidade jurídica registrada (pessoa física não é aceita desde maio de 2025)
Serviço já lançado e ativo
Mínimo de 250.000 usuários ativos mensais
Viabilidade comercial

A análise pode levar até seis semanas, e sem garantia de aprovação.

Na prática, isso significa que se você tá construindo algo novo como indie dev, vai ficar travado em modo de desenvolvimento. Você consegue testar e mostrar pra até 4 pessoas além de você — e só. Vale saber disso antes de planejar algum lançamento público.

Fazendo o Claude Obedecer

O system prompt instrui o Claude a retornar apenas um array JSON, sem markdown, sem explicações. Essa parte é direta. O problema mais difícil é conseguir 50 faixas que realmente existam.

One-shot prompting

Incluir uma conversa de exemplo completa (usuário + assistente) antes do request real reduziu bastante os erros de formato, especialmente com artistas não-ingleses:

messages: [
  {
    role: "user",
    content: "Create a playlist for this mood/vibe: late night drive, nostalgic",
  },
  {
    role: "assistant",
    content: JSON.stringify([
      { title: "Drive", artist: "The Cars", reason: "Synth-pop clássico com energia perfeita de madrugada" },
      { title: "Running Up That Hill", artist: "Kate Bush", reason: "Art-pop etéreo, emocionalmente assombroso" },
      // ...
    ]),
  },
  { role: "user", content: actualUserMessage },
],

Extração de JSON como fallback

Mesmo com prompting cuidadoso, modelos eventualmente jogam texto de introdução. Sempre extraia o array:

const match = raw.match(/\[[\s\S]*\]/);
if (!match) throw new Error("Nenhum array JSON encontrado");
const suggestions = JSON.parse(match[0]);

Prompt Engineering Anti-Alucinação

Descobri que quanto mais músicas você pede, mais o modelo inventa títulos.

Pedindo 70 músicas, o Claude começa a criar faixas com nomes plausíveis que não existem. Com 50 e restrições explícitas, fica bem melhor.

O que adicionei ao system prompt:

EXISTÊNCIA NO SPOTIFY — CRÍTICO:
Cada música DEVE existir no Spotify. Antes de incluir uma faixa, pergunte:
"Tenho certeza que esta música existe no Spotify com este título e artista exatos?"
Se houver qualquer dúvida, escolha outra música que você tem certeza.

REGRAS DE FORMATO DO TÍTULO:
- Use apenas o título canônico limpo do lançamento
- SEM sufixos: sem "- Remastered", "- Live at...", "- Radio Edit"
- Use o nome do lançamento mais conhecido, não compilações

ARMADILHAS COMUNS DE ALUCINAÇÃO:
- Não invente títulos de músicas que parecem plausíveis mas podem não existir
- Não confunda dois artistas com nomes similares
- Não sugira deep cuts que você não tem certeza

Também removi a abordagem de duas etapas "gerar 70, refinar pra 50". Era cara em tempo e custo, e uma única geração de 50 com boas instruções performa melhor.

O system prompt atual completo

Esse é o prompt que tá rodando em produção hoje:

You are a world-class Spotify playlist curator.

GOAL:
Generate EXACTLY 50 high-quality songs for a playlist.

OUTPUT:
Return ONLY a raw JSON array. No markdown, no explanations.

Each item:
- "title": string — the canonical Spotify title, nothing else
- "artist": string — the primary artist exactly as listed on Spotify
- "reason": string — max 10 words

SPOTIFY EXISTENCE — CRITICAL:
Every song MUST exist on Spotify. Before including a track, ask yourself:
"Am I certain this song exists on Spotify under this exact title and artist?"
If there is any doubt, pick a different song you are certain about.

TITLE FORMAT RULES:
- Use the clean, canonical release title only
- NO suffixes: no "- Remastered", "- Live at...", "- Radio Edit", "- feat. X"
- NO parentheticals unless part of the official title
- Use the most well-known release name, not compilations or bonus versions

COMMON HALLUCINATION TRAPS TO AVOID:
- Do not invent song titles that sound plausible but may not exist
- Do not confuse two artists with similar names
- Do not suggest deep cuts you are uncertain about
- Do not suggest songs only released in specific regions unavailable globally

DISTRIBUTION:
- 50% recognizable hits (high confidence they exist)
- 40% lesser-known but confirmed tracks
- 10% deep cuts you are fully certain about

DIVERSITY:
- At least 2 genres
- At least 3 decades
- Non-English tracks welcome if you are certain they are on Spotify

CURATION:
- Cohesive flow, playlist-worthy, non-random
- No duplicates

Return ONLY the JSON array. Exactly 50 items.

Curiosidade: o prompt tá em inglês mesmo que o usuário escreva em português. O Claude entende o humor no idioma que vier e retorna os dados no formato esperado sem problema.

Melhor resolução de busca no Spotify

Mesmo com um bom prompt, algumas faixas voltam com títulos ou artistas levemente errados. Três ajustes no lado da busca:

1. Buscar 10 candidatos em vez de 1
Em vez de limit=1, buscar limit=10 e escolher o melhor match.

2. Filtro de popularidade
Pular resultados com popularity < 30 — evita gravar versões ao vivo obscuras quando a faixa correta não é encontrada:

const POPULARITY_FLOOR = 30;
const aboveFloor = candidates.filter(t => t.popularity >= POPULARITY_FLOOR);
const pool = aboveFloor.length > 0 ? aboveFloor : candidates;

3. Fuzzy matching + seleção por popularidade
Normalizar strings e verificar correspondência bidirecional de substring, depois escolher o match com maior popularidade:

function fuzzyMatch(candidate: SpotifyTrack, suggestion: ClaudeTrackSuggestion): boolean {
  const trackName = normalizeStr(candidate.name);
  const artistName = normalizeStr(candidate.artists[0]?.name ?? "");
  const sugTitle = normalizeStr(suggestion.title);
  const sugArtist = normalizeStr(suggestion.artist);
  const titleMatch = trackName.includes(sugTitle) || sugTitle.includes(trackName);
  const artistMatch = artistName.includes(sugArtist) || sugArtist.includes(artistName);
  return titleMatch && artistMatch;
}

Modo Related Artists

Playlists geradas por IA alucinam mais quando o humor é específico de artista — tipo "algo como Radiohead". Nesses casos, o grafo de artistas do próprio Spotify é mais confiável que o Claude.

Adicionei detecção automática: uma chamada rápida ao Claude Haiku (~0,5s) classifica o prompt antes da geração principal:

// Retorna { mode: "ai" | "related", artists: ["Radiohead", "Nick Cave"] }
const detected = await detectPlaylistMode(mood);

Se artistas são detectados, o app:

Os resolve no Spotify
Busca artistas relacionados (GET /artists/{id}/related-artists)
Pega top tracks de cada artista relacionado
Monta uma playlist com dados reais do Spotify, sem depender do Claude pra nada

Se não detectar artistas, cai pro fluxo normal com Claude.

if (detected.mode === "related" && detected.artists.length > 0) {
  const { suggestions, resolvedSeeds } = await buildRelatedArtistsPlaylist(
    detected.artists,
    accessToken,
    energy
  );
  if (suggestions.length > 0) {
    return NextResponse.json({ suggestions, mode: "related", seedArtists: resolvedSeeds });
  }
  // fallthrough para modo AI se não encontrou nada
}

Construindo o Perfil Musical

O app deixa usuários escolher uma playlist de referência ou seus top artistas do Spotify (último mês / 6 meses / histórico completo). Esse contexto é passado pro Claude como uma impressão digital musical.

Mandar nomes de faixas brutos confunde o modelo. Em vez disso, agregue num perfil:

// Contar frequência de artistas em todas as faixas da playlist
const artistFreq = new Map<string, { name: string; count: number }>();
for (const track of tracks) {
  const a = track.artists[0];
  const prev = artistFreq.get(a.id);
  artistFreq.set(a.id, { name: a.name, count: (prev?.count ?? 0) + 1 });
}

Pra playlists, também busco dados de gênero dos artistas principais via GET /artists/{id} (5 chamadas paralelas), já que os itens de playlist não retornam gêneros nativamente.

Mesmo sem seleção de referência explícita, o app passa os top artistas e gêneros baseline do usuário como contexto suave pra cada geração.

A instrução no prompt mudou de "não recomende esses artistas" pra algo mais útil:

→ Biase as recomendações em direção a este DNA musical: tempo, humor e estilo de produção similar.
→ Descubra artistas com som SIMILAR — não necessariamente os mesmos artistas.
→ NÃO repita faixas já listadas acima.

Streaming com SSE

O fluxo original: buscar todas as 50 faixas em paralelo, retornar tudo de uma vez, mostrar um spinner.

O problema é que o usuário ficava olhando "Salvando no Spotify..." por 5-10 segundos sem nenhum feedback. Server-Sent Events resolve isso — cada faixa é emitida conforme resolve:

// Na rota da API
const stream = new ReadableStream({
  async start(controller) {
    const send = (data: object) =>
      controller.enqueue(encoder.encode(`data: ${JSON.stringify(data)}\n\n`));

    await Promise.all(
      suggestions.map(async (suggestion) => {
        const track = await searchTrack(suggestion, accessToken);
        if (track) {
          foundTracks.push({ track, suggestion });
          send({ type: "track", track, suggestion }); // emitido imediatamente
        }
      })
    );

    // Criar playlist depois que todas as buscas terminam
    const playlist = await createPlaylist(...);
    send({ type: "done", playlist, found: foundTracks.length });
    controller.close();
  },
});

return new Response(stream, {
  headers: { "Content-Type": "text/event-stream", "Cache-Control": "no-cache" },
});

A busca paralela continua na velocidade máxima. Mas agora o cliente vê cada faixa aparecer com album art conforme resolve, com uma barra de progresso ao vivo — em vez de um spinner em branco por 10 segundos.

O Que Aprendi

Sobre prompt engineering:

Menos é mais (50 > 70)
Exemplos one-shot (par de mensagens usuário + assistente) são mais confiáveis que instruções de formato detalhadas.
Dizer o que não fazer funciona muito bem
Contexto de perfil funciona melhor como guia de DNA musical, não como lista de restrições.

Sobre a API do Spotify:

Sempre verifique se o endpoint ainda é atual. /tracks → /items, audio features sumiu, recomendações sumiram.
GET /artists/{id}/related-artists funciona bem pra descoberta e quase ninguém usa.
O score de popularidade nas faixas é um bom proxy pra "essa faixa existe como esperado."

Sobre streaming no Next.js:

ReadableStream + text/event-stream funciona limpo no App Router.
Promise.all + emit-on-resolve te dá paralelismo real com UI progressiva de graça.

Sobre Next.js + OAuth:

NextRequest normaliza URLs pra localhost em desenvolvimento, mesmo que você passe 127.0.0.1 explicitamente. Use Request nativo quando a URL importa.
O NextAuth v5 tem um utilitário reqWithEnvURL que tenta corrigir isso mas usa new NextRequest() internamente — que normaliza de novo. A correção do framework não funciona.
O OAuth tem dois momentos onde o redirect_uri é verificado: na requisição de autorização e na troca de token. Você precisa garantir que os dois mostrem 127.0.0.1.
provider.callbackUrl é derivado da URL da requisição de callback — não da sua config. Se a URL da requisição ainda diz localhost, a troca falha com invalid_grant.
Ao usar Auth() do @auth/core diretamente, pin a versão exata que o next-auth requer. Versões diferentes causam conflitos de tipo em runtime.
Cookies PKCE são scopados por domínio. Se o usuário começa em localhost e o callback chega em 127.0.0.1, o code_verifier some. Redirecione todo o tráfego de localhost pra 127.0.0.1 no next.config.mjs.
NextAuth v5 é poderoso mas a documentação beta é bem escassa. Ler o código-fonte do @auth/core foi necessário pra entender o que estava acontecendo.

Teste Você Mesmo

O app se chama Moodify. Está OpenSource no GitHub. Se você tá fazendo algo parecido, espero que ajude um pouco.

Como vocês melhorariam esse prompt? Se alguém já passou por algo parecido ou tiver ideias, comenta aí

Construído com Next.js, Claude API, Spotify Web API e Supabase. Deploy no Vercel.

Engenharia de Prompt: Por Que a Forma Como Você Pergunta Muda Tudo(Um guia introdutório)

Fran Borges — Mon, 23 Mar 2026 16:20:34 +0000

Neste artigo irei explicar alguns pontos importantes sobre Engenharia de prompt, e como saber esses pontos pode te ajudar muito no dia a dia lidando com IAs, no seus estudos, pesquisas, trabalho, vibeconding, whatever.

Prefácio
Antes de tudo, para lembrar, o que é uma LLM mesmo?
Fazendo Perguntas
- 1 - Evite a Ambiguidade
- 2 - Delimite o Escopo
- 3 - Forneça Contexto Relevante
Considerações Finais

Prefácio

A base do conhecimento é necessária em tudo que se quer aprender, com LLMs não é diferente. Analisando padrões, conversando com amigos, observei que a grande parte das pessoas que usam LLMs no dia a dia de trabalho, estudo, pessoas que trabalham com tecnologia e principalmente quem está começando na área tech, não tem ideia de como a LLM funciona e de como fazer as perguntas e tirar dúvidas de forma certa para um ChatGPT da vida.

Tendo isso em vista, e como venho estudando bastante sobre esse assunto, como forma de compartilhar o conhecimento, já dizia a poetisa brasileira Cora Coralina: "Feliz aquele que transfere o que sabe, e aprende o que ensina", farei uma série de artigos explicando sobre o tema, e esse é só o primeiro deles...

Antes de tudo, para lembrar, o que é uma LLM mesmo?

A LLM pode ser definida de algumas formas. Uma delas é: "São modelos de linguagem de máquina, que usam algoritmos de aprendizado profundo (Deep Learning) para processar e aprender a linguagem natural", essa é a sua definição estrutural. A definição que mais gosto é: "A LLM, na sua essência, é composta por dois arquivos: um contendo os pesos (parâmetros) com os conhecimentos aprendidos, e o outro com o código necessário para rodar os dados aprendidos.", como uma pessoa visual, consigo imaginar melhor como funciona.

Então, ChatGPT, Claude e muitos outros são exatamente isso, e atualmente têm a capacidade de executar várias atividades, como escrever código, traduzir texto, responder às mais variadas dúvidas e, dependendo da sua capacidade de escrever prompts mais robustos, pode até criar arquiteturas de produtos, te ajudar a resolver bugs complexos, te dar ideias, e até criar um SaaS revolucionário (risos).

O ponto é que a capacidade das LLMs de "compreender" e "criar" chegou a um ponto bem avançado, e você só chega na camada -17 de boas respostas fazendo as perguntas de forma certa!

Nota: Camada -17 se refere à camada onde se acha o minério de ouro no jogo Minecraft ;).

Fazendo Perguntas

Como fazer as perguntas certas? E por que saber isso importa? Vamos lá.

Saber fazer as perguntas certas para uma LLM é tão importante que existe uma área da tecnologia específica só para isso: a Engenharia de Prompts, definida como "a ciência empírica de planejar, criar e testar prompts para gerar melhores respostas em LLMs". Saber fazer as perguntas certas te coloca em outro nível, você consegue obter as melhores respostas, e isso te traz muitos ganhos, sendo o principal deles a produtividade.

Mas afinal, como perguntar de forma certa?

A LLM é poderosa, mas não adivinha sua intenção. Para obter os melhores resultados nas suas buscas, você precisa se concentrar na criação de prompts claros, na especificidade e ser rico em dar contexto. E tudo isso envolve:

1 - Evite a Ambiguidade

"Espaço de possibilidades"

Quando você escreve um prompt muito ambíguo, vago, o modelo enxerga vários caminhos estatisticamente válidos. É como se ele estivesse numa encruzilhada com 50 estradas e todas tivessem placas dizendo "Talvez por aqui", ele vai escolher uma, mas não necessariamente a que você precisa: a estrada com o percurso mais rápido e sem trânsito (a resposta correta de fato).

Exemplos:

Prompt ambíguo:

"Crie uma API."

O que a LLM "vê": Vários caminhos, API REST? GraphQL? Em qual linguagem? Para qual domínio? Com autenticação? Com banco? O modelo vai escolher o caminho mais estatisticamente comum nos dados de treino (provavelmente uma API REST genérica em Node.js com Express), que pode não ter nada a ver com o que você precisa.

Prompt sem ambiguidade:

"Crie um microsserviço em Node.js com Express e TypeScript para processar pagamentos via
Stripe. Endpoints: criar pagamento, confirmar webhook e consultar status. O payload tem:
orderId(UUID), amount(number), currency(enum: BRL, USD) e customerId(string).
Use zod para validação, Prisma com PostgreSQL para persistir as transações e winston
para logs. Retorne status codes apropriados como(201, 200, 400, 422, 500). Trate falhas de
rede com retry automático (máx. 3 tentativas)."

O que a LLM "vê": Um caminho quase único. Cada detalhe funciona como uma restrição que elimina ambiguidade: "Node.js com Express e TypeScript" define runtime, framework e linguagem de uma vez. "Pagamentos via Stripe" restringe o SDK e o domínio. "3 endpoints explícitos + payload com tipos" elimina adivinhações sobre rotas e schema. "Zod, Prisma, PostgreSQL, Winston" travam a stack, o modelo não vai sugerir alternativas. "Status codes específicos + retry com máximo de 3 tentativas" definem os status HTTP e a estratégia com limites claros. A distribuição de probabilidade fica concentrada e o modelo praticamente "só tem uma opção" a cada token gerado.

2 - Delimite o Escopo

"Janela de atenção"

LLMs têm um context window(Janela), uma quantidade de tokens (pedaço de palavra) que conseguem ser processados de uma vez. Isso inclui o seu prompt e a resposta gerada. Dentro dessa janela, existe um fenômeno importante: nem todos os tokens recebem a mesma "atenção" no processamento.

O mecanismo de self-attention (o coração da arquitetura Transformer, não é um cubo rsrsrs, e a arquitetura de rede neural, que seria o framework da LLM se a mesma fosse uma linguagem de programação), ela define a estrutura de tudo, calcula relações entre todos os tokens do prompt. Quanto mais tokens irrelevantes existem, mais o modelo precisa "dividir atenção" entre informações úteis e inúteis.

Exemplos:

Sem escopo:

"Me ensine Docker."

O que acontece internamente: O modelo precisa decidir entre centenas de subtópicos, instalação, conceitos básicos, Dockerfile, docker-compose, volumes, orquestração, a atenção se fragmenta e o resultado é um overview superficial de tudo.

Com escopo:

"Explique o conceito de multi-stage build no Docker para um dev backend pleno que já usa
Docker no dia a dia mas nunca otimizou o tamanho das imagens. Mostre um exemplo prático
com uma aplicação JavaScript, comparando o Dockerfile sem e com multi-stage build,
incluindo o tamanho final de cada imagem."

O que acontece internamente: O mecanismo de atenção se concentra em uma região muito específica, a interseção entre "Docker", "multi-stage build", "otimização de imagem" e "JavaScript". Os pesos de atenção ficam fortemente direcionados.

3 - Forneça Contexto Relevante

"Estado da aplicação"

Uma LLM é stateless por natureza, ela não tem memória entre requisições. Cada prompt é processado do zero, o único "estado" que ela tem é o que você coloca no prompt. Isso significa que todo contexto que você não fornece simplesmente não existe para o modelo.

Internamente, o contexto funciona como um sistema de pesos no mecanismo de atenção. Quando você adiciona informações, elas criam "âncoras" que influenciam a distribuição de probabilidades de todos os tokens subsequentes, é como se cada pedaço de contexto fosse um ímã que puxa a resposta para uma direção específica.

Exemplos:

Sem contexto:

"Revise meu código."

O que a LLM faz: Sem saber a linguagem, o framework, o nível do dev, o objetivo do código, o padrão do time ou o tipo de revisão esperada, ela vai fazer comentários genéricos: "adicione tratamento de erro", "use nomes mais descritivos", "considere adicionar testes".

Com contexto:

"Revise este endpoint Node.js com Express que lida com upload de arquivos para o S3.
O time usa ESLint + Prettier, então ignore estilo. O padrão do time é async/await com
try/catch e erros customizados. Endpoint em produção, recebe 200 uploads/min.
Foque em: memory leaks, tratamento de erros e uso correto do SDK do S3."

O que a LLM faz: Cada informação do prompt funciona como um filtro que elimina ruído e concentra a revisão: "Node.js com Express + upload para S3" ativa conhecimento específico sobre streams, buffers, multipart e AWS SDK. "ESLint + Prettier, ignore estilo" elimina os comentários possíveis que o linter já resolve. "async/await com erros customizados" faz o modelo pular sugestões que o time já aplica e focar em como estão sendo usadas. "Produção, 200 uploads/min" muda o peso de cada problema, um buffer não liberado que seria aceitável em dev vira um incidente crítico sob carga. "Foque em: memory leaks, erros, SDK S3" restringe a revisão a 3 eixos e ignora dezenas de outros tópicos.

Com base nisso, saber as limitações do modelo que você está usando, te ajuda também a entender até aonde você pode ir nas perguntas e inferências, então escolha a sua melhor IA, treine ela, faça as suas perguntas, teste, tente! ;)

É Lembre-se: a LLM não "pensa", ela calcula probabilidades!

Considerações Finais

É isto, tentei resumir cada ponto que achei interessante abordar e explicar nessa primeira etapa, mas há muito mais sobre engenharia de prompt de LLM para falar, como técnicas mais clássicas de engenharia de prompts(Zero-shot prompting, Role prompting), técnicas mais avançadas(Chain-of-Thought (CoT), Prompt Chaining), são muitas camadas que tentarei destrinchar nos próximos artigos, esse é apenas o primeiro que traz a minha volta para a escrita de artigos após alguns bons anos. Espero que você caro leitor tenha entendido e aprendido algo. Obrigado por ler até aqui. ;)

Onde me encontrar:

Meu LinkedIn
Meu GitHub

Do commit ao deploy: CI/CD de uma API na AWS usando GitHub Actions, ECS e Terraform

Fernando Andrade — Thu, 12 Mar 2026 00:07:27 +0000

Sumário

Introdução
Pré-requisitos
Visão Geral da Arquitetura
Configurando o IAM para o Terraform
Infraestrutura como Código com Terraform
- Recursos Provisionados
- IAM Role para Tarefas ECS
- Task Definition (Fargate)
- ECS Service
- OIDC: Autenticação Sem Credenciais Estáticas
Dockerfile Multi-Stage
Pipeline de CI
Protegendo a Branch Main
Configurando as Secrets no GitHub
Pipeline de CD
Acessando a Aplicação após o Deploy
Segurança: OIDC em Detalhe
Fluxo Completo: Do Commit ao Deploy
Considerações Finais

Introdução

Colocar uma aplicação em produção vai muito além de escrever código. Envolve compilar, testar, empacotar e entregar de forma confiável e repetível. Neste artigo, vou mostrar como construir uma pipeline completa — do commit ao deploy — usando GitHub Actions para CI/CD, Terraform para infraestrutura como código e AWS (ECR, ECS Fargate) como plataforma de execução.

O conceito apresentado aqui é agnóstico de linguagem — funciona para qualquer stack que rode em um container Docker (Node.js, Go, Java, Python, etc.). Para os exemplos práticos, vamos utilizar .NET como referência, mas os workflows, a infraestrutura Terraform e o fluxo de deploy são os mesmos independente da tecnologia escolhida.

O objetivo é demonstrar como essas ferramentas se conectam para formar um fluxo automatizado onde um simples merge na branch main resulta em uma nova versão rodando em produção, sem intervenção manual.

Pré-requisitos

Antes de começar, você precisa ter as seguintes ferramentas instaladas e configuradas:

Ferramenta	Descrição	Link de instalação
Docker	Para construir e executar containers	docs.docker.com/get-docker
Terraform	Para provisionar infraestrutura como código	developer.hashicorp.com/terraform/install
AWS CLI	Para interagir com os serviços da AWS via terminal	docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html
Git	Para versionamento de código	git-scm.com/downloads
Conta AWS	Com permissões para criar recursos (IAM, ECS, ECR)	aws.amazon.com/free
Conta GitHub	Para hospedar o repositório e rodar os workflows	github.com

Nota: Para o exemplo deste artigo, também é necessário o .NET SDK instalado localmente para desenvolvimento. Se você estiver usando outra stack, substitua pelo SDK correspondente (Node.js, Go, JDK, etc.). Outro ponto é que a escolha em utilizar o ECS ao invés de um EKS ou EC2 é devido sua simplicidade na curva de aprendizado, baixo gerenciamento e que para fins de aprendizado os recursos mínimos definidos para esse laboratório não gerem altos gastos para o aprendizado.

Visão Geral da Arquitetura

O fluxo completo funciona assim:

Developer → Feature Branch → Pull Request → Validação (CI)
                                                  ↓
                                            Merge na main
                                                  ↓
                                         Build & Push (CD)
                                                  ↓
                                        Deploy no ECS Fargate

Configurando o IAM para o Terraform

Antes de rodar qualquer terraform apply, é necessário que o Terraform tenha permissões para criar recursos na AWS. Para isso, precisamos de um usuário IAM (ou role) com as permissões adequadas e configurar suas credenciais localmente.

Criando um usuário IAM para o Terraform

No console da AWS (IAM > Users), crie um usuário dedicado para o Terraform:

Acesse IAM > Users > Create User
Nomeie o usuário (ex: terraform-deployer)
Anexe as policies necessárias para os recursos que serão criados:

AmazonECS_FullAccess
AmazonEC2ContainerRegistryFullAccess
AmazonVPCReadOnlyAccess
IAMFullAccess
CloudWatchLogsFullAccess
AmazonS3FullAccess

Nota de segurança: Em um ambiente produtivo, o ideal é criar uma policy customizada com o princípio do menor privilégio, concedendo apenas as permissões estritamente necessárias. Para fins de estudo, as managed policies acima simplificam o setup.

Após criar o usuário, gere um Access Key (IAM > Users > Security credentials > Create access key)
Selecione o caso de uso Command Line Interface (CLI)

Configurando as credenciais localmente

Com o AWS CLI instalado, configure as credenciais:

aws configure

Será solicitado:

AWS Access Key ID: AKIA...
AWS Secret Access Key: wJal...
Default region name: us-east-1
Default output format: json

Isso cria o arquivo ~/.aws/credentials que o Terraform utilizará automaticamente via o provider AWS. Com isso feito, o Terraform tem autorização para provisionar os recursos que definiremos a seguir.

Infraestrutura como Código com Terraform

Antes de qualquer pipeline rodar, a infraestrutura precisa existir. Com o Terraform, declaramos todos os recursos AWS em arquivos .tf e provisionamos com um único comando.

Recursos Provisionados

# Provider AWS
provider "aws" {
  region = "us-east-1"
}

# Repositório ECR para armazenar imagens Docker
resource "aws_ecr_repository" "app_repository" {
  name = "minha-app-repository"
}

# Cluster ECS
resource "aws_ecs_cluster" "app_cluster" {
  name = "minha-app-cluster"
}

IAM Role para Tarefas ECS

O ECS precisa de uma role para puxar imagens e enviar logs:

resource "aws_iam_role" "ecs_task_execution_role" {
  name = "ecs-task-execution-role"

  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Action    = "sts:AssumeRole"
      Effect    = "Allow"
      Principal = { Service = "ecs-tasks.amazonaws.com" }
    }]
  })
}

resource "aws_iam_role_policy_attachment" "ecs_policy" {
  role       = aws_iam_role.ecs_task_execution_role.name
  policy_arn = "arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy"
}

Task Definition (Fargate)

Aqui definimos como o container será executado:

resource "aws_ecs_task_definition" "app_task" {
  family                   = "minha-app-task"
  network_mode             = "awsvpc"
  requires_compatibilities = ["FARGATE"]
  cpu                      = "256"
  memory                   = "512"
  execution_role_arn       = aws_iam_role.ecs_task_execution_role.arn

  container_definitions = jsonencode([{
    name      = "app"
    image     = "${aws_ecr_repository.app_repository.repository_url}:latest"
    portMappings = [{
      containerPort = 8080
      hostPort      = 8080
    }]
    logConfiguration = {
      logDriver = "awslogs"
      options = {
        "awslogs-group"         = "/ecs/minha-app"
        "awslogs-region"        = "us-east-1"
        "awslogs-stream-prefix" = "ecs"
      }
    }
  }])
}

ECS Service

O service mantém o container rodando e gerencia o deploy:

resource "aws_ecs_service" "app_service" {
  name            = "minha-app-service"
  cluster         = aws_ecs_cluster.app_cluster.id
  task_definition = aws_ecs_task_definition.app_task.arn
  desired_count   = 1
  launch_type     = "FARGATE"

  network_configuration {
    subnets          = data.aws_subnets.default.ids
    security_groups  = [aws_security_group.app_sg.id]
    assign_public_ip = true
  }
}

OIDC: Autenticação Sem Credenciais Estáticas

Este é um dos pontos mais importantes da arquitetura. Em vez de armazenar AWS_ACCESS_KEY e AWS_SECRET_KEY como secrets no GitHub, usamos OIDC (OpenID Connect) para que o GitHub Actions troque um token temporário por credenciais AWS.

# Registra o GitHub como provedor OIDC na AWS
resource "aws_iam_openid_connect_provider" "github" {
  url             = "https://token.actions.githubusercontent.com"
  client_id_list  = ["sts.amazonaws.com"]
  thumbprint_list = ["ffffffffffffffffffffffffffffffffffffffff"]
}

# Role que o GitHub Actions vai assumir
resource "aws_iam_role" "github_actions_role" {
  name = "github-actions-role"

  assume_role_policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect = "Allow"
      Principal = {
        Federated = aws_iam_openid_connect_provider.github.arn
      }
      Action = "sts:AssumeRoleWithWebIdentity"
      Condition = {
        StringEquals = {
          "token.actions.githubusercontent.com:aud" = "sts.amazonaws.com"
        }
        StringLike = {
          "token.actions.githubusercontent.com:sub" = "repo:meu-usuario/meu-repo:ref:refs/heads/main"
        }
      }
    }]
  })
}

Por que isso importa? Credenciais estáticas são um risco de segurança. Com OIDC, as credenciais são temporárias e o acesso é restrito a uma branch específica de um repositório específico. Mesmo que alguém tenha acesso ao repositório, não consegue assumir a role a partir de outra branch.

Dockerfile Multi-Stage

Usamos um build multi-stage para separar o ambiente de compilação do ambiente de execução, resultando em uma imagem final menor e mais segura:

# Stage 1: Build
FROM mcr.microsoft.com/dotnet/sdk:10.0 AS build
WORKDIR /src
COPY ["MeuProjeto/MeuProjeto.csproj", "MeuProjeto/"]
RUN dotnet restore "MeuProjeto/MeuProjeto.csproj"
COPY . .
WORKDIR "/src/MeuProjeto"
RUN dotnet build -c Release -o /app/build

# Stage 2: Publish
FROM build AS publish
RUN dotnet publish -c Release -o /app/publish /p:UseAppHost=false

# Stage 3: Runtime
FROM mcr.microsoft.com/dotnet/aspnet:10.0 AS final
WORKDIR /app
EXPOSE 8080
COPY --from=publish /app/publish .
ENTRYPOINT ["dotnet", "MeuProjeto.dll"]

Benefícios do multi-stage:

A imagem final contém apenas o runtime, não o SDK completo
Reduz significativamente o tamanho da imagem
O código-fonte não fica presente na imagem de produção

Pipeline de CI

A primeira pipeline roda automaticamente quando um Pull Request é aberto contra a branch main. Seu objetivo é validar que o código compila e que os testes passam.

name: PR Validation

on:
  pull_request:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '10.0.x'

      - name: Restore
        run: dotnet restore MinhaSolution.sln

      - name: Build
        run: dotnet build MinhaSolution.sln --no-restore -c Release

  test:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup .NET
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: '10.0.x'

      - name: Run Tests with Coverage
        run: |
          dotnet test MinhaSolution.sln \
            --collect:"XPlat Code Coverage" \
            --results-directory ./coverage

O que acontece nesta pipeline:

Job build — Compila a solução para garantir que não há erros de compilação
Job test — Roda os testes unitários com cobertura de código usando Coverlet

Separar em dois jobs traz clareza: se o build falha, você sabe que é erro de compilação. Se o test falha, o código compila mas tem um bug.

Protegendo a Branch Main

Com a pipeline de CI configurada, é fundamental garantir que nenhum código chegue à main sem passar pela validação. Para isso, configuramos uma branch protection rule no GitHub.

Acesse Settings > Branches > Add branch protection rule no seu repositório e configure:

Branch name pattern: main
Marque Require a pull request before merging — impede push direto na main
Marque Require status checks to pass before merging — bloqueia o merge até que os checks passem
Em Status checks that are required, busque e adicione os jobs da pipeline de CI:
- build
- test

Nota: Na primeira vez que configurar, os status checks podem não aparecer na busca. Eles só ficam disponíveis após a pipeline rodar pelo menos uma vez no repositório. Abra um PR de teste para que os checks sejam registrados.

Configurando as Secrets no GitHub

Antes de configurar a pipeline de deploy, é necessário cadastrar as secrets no repositório do GitHub. A pipeline de CD depende delas para autenticar na AWS e saber para onde enviar a imagem Docker.

Acesse Settings > Secrets and variables > Actions > New repository secret no seu repositório e crie as seguintes secrets:

Secret	Valor	Exemplo
`AWS_ROLE`	O ARN completo da IAM Role criada para o GitHub Actions	`arn:aws:iam::123456789012:role/github-actions-role`
`ECR_REPOSITORY`	A URI completa do repositório ECR (não apenas o nome)	`123456789012.dkr.ecr.us-east-1.amazonaws.com/minha-app-repository`
`AWS_ACCOUNT_ID`	O ID numérico da sua conta AWS	`123456789012`

Atenção: Um erro comum é colocar apenas o nome do repositório ECR (ex: minha-app-repository) na secret ECR_REPOSITORY. O valor correto é a URI completa que inclui o domínio do ECR. Você pode obter essa URI no console da AWS em ECR > Repositories ou via CLI:

aws ecr describe-repositories --repository-names minha-app-repository \
  --query "repositories[0].repositoryUri" --output text

Da mesma forma, a secret AWS_ROLE deve conter o ARN (Amazon Resource Name) completo da role, não apenas o nome. Para consultar:

aws iam get-role --role-name github-actions-role \
  --query "Role.Arn" --output text

Com as secrets configuradas, a pipeline de deploy consegue autenticar via OIDC, fazer push da imagem para o ECR e disparar o deploy no ECS.

Pipeline de CD

Quando o PR é aprovado e mergeado na main, a pipeline de deploy entra em ação:

name: Build and Deploy

on:
  push:
    branches: [main]

permissions: #permissões necessárias para autenticação OIDC
  id-token: write
  contents: read 

env:
  AWS_REGION: us-east-1

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Configure AWS Credentials (OIDC)
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
          aws-region: ${{ env.AWS_REGION }}

      - name: Login to Amazon ECR
        uses: aws-actions/amazon-ecr-login@v2

      - name: Build Docker Image
        run: docker build -t minha-app .

      - name: Tag Image
        run: docker tag minha-app:latest ${{ secrets.ECR_REPOSITORY }}:latest

      - name: Push to ECR
        run: docker push ${{ secrets.ECR_REPOSITORY }}:latest

      - name: Deploy to ECS
        run: |
          aws ecs update-service \
            --cluster minha-app-cluster \
            --service minha-app-service \
            --force-new-deployment

O que acontece nesta pipeline:

Autenticação OIDC — O GitHub troca seu token JWT por credenciais AWS temporárias
Login no ECR — Autentica o Docker no registro da AWS
Build e Push — Constrói a imagem Docker e envia para o ECR
Deploy — Dispara um novo deployment no ECS, que puxa a imagem atualizada e substitui o container antigo

O --force-new-deployment garante que o ECS vai iniciar uma nova task mesmo que a tag da imagem (latest) não tenha mudado.

Acessando a Aplicação após o Deploy

Após a pipeline de CD concluir com sucesso, a aplicação estará rodando no ECS Fargate. Como configuramos assign_public_ip = true no Terraform, a task recebe um IP público que pode ser usado para acessar a API.

Obtendo o IP público pelo Console AWS

Acesse ECS > Clusters > minha-app-cluster
Clique na aba Tasks
Clique na task em execução (status RUNNING)
Na seção Network, copie o Public IP
Acesse no navegador: http://<PUBLIC_IP>:8080

Obtendo o IP público via CLI

# 1. Obtenha o ARN da task em execução
TASK_ARN=$(aws ecs list-tasks \
  --cluster minha-app-cluster \
  --service-name minha-app-service \
  --query "taskArns[0]" --output text)

# 2. Obtenha o ID da interface de rede (ENI)
ENI_ID=$(aws ecs describe-tasks \
  --cluster minha-app-cluster \
  --tasks $TASK_ARN \
  --query "tasks[0].attachments[0].details[?name=='networkInterfaceId'].value" \
  --output text)

# 3. Obtenha o IP público
aws ec2 describe-network-interfaces \
  --network-interface-ids $ENI_ID \
  --query "NetworkInterfaces[0].Association.PublicIp" \
  --output text

Importante: O IP público muda toda vez que uma nova task é criada (ou seja, a cada deploy). Para um ambiente produtivo, o ideal é utilizar um Application Load Balancer (ALB) ou um domínio com Route 53 apontando para o serviço ECS, garantindo um endereço fixo. Para fins de estudo, o IP público direto é suficiente.

Segurança: OIDC em Detalhe

Vale reforçar a importância do OIDC neste fluxo. O modelo tradicional funciona assim:

❌ Modelo Tradicional:
   GitHub Secrets → AWS_ACCESS_KEY_ID + AWS_SECRET_ACCESS_KEY
   - Credenciais estáticas que nunca expiram
   - Se vazadas, acesso total até serem rotacionadas manualmente

Com OIDC:

✅ Modelo OIDC:
   GitHub Actions → JWT Token → AWS STS → Credenciais Temporárias
   - Credenciais expiram automaticamente
   - Escopo restrito: apenas uma branch de um repositório específico
   - Sem segredos de longa duração armazenados

A configuração requer:

Registrar o GitHub como OIDC Provider na AWS (via Terraform)
Criar uma IAM Role com trust policy apontando para o repositório
No workflow, usar permissions: id-token: write e a action configure-aws-credentials com role-to-assume

Fluxo Completo: Do Commit ao Deploy

Resumindo o ciclo de vida de uma mudança:

1. git checkout -b feature/minha-feature
2. # Desenvolve e commita
3. git push origin feature/minha-feature
4. # Abre Pull Request → Dispara pr-validation.yml
   │
   ├── ✅ Build compila com sucesso
   └── ✅ Testes passam com cobertura
   │
5. # Code review + Aprovação
6. # Merge na main → Dispara build-and-deploy.yml
   │
   ├── 🔐 Autenticação via OIDC
   ├── 🐳 Build da imagem Docker (multi-stage)
   ├── 📦 Push para o ECR
   └── 🚀 Deploy no ECS Fargate
   │
7. # Nova versão rodando em produção

Considerações Finais

Este setup demonstra como é possível construir uma pipeline profissional de CI/CD com ferramentas modernas e boas práticas:

Infraestrutura como Código — Toda a infraestrutura é versionada e reproduzível
Autenticação Keyless — OIDC elimina o risco de credenciais estáticas
Serverless Containers — Fargate remove a necessidade de gerenciar servidores
Separação CI/CD — Validação em PRs e deploy apenas na main
Imagens otimizadas — Multi-stage build reduz a superfície de ataque

O custo de infraestrutura para um setup como esse é mínimo — com Fargate usando 0.25 vCPU e 512MB de memória, o custo fica na faixa de poucos dólares por mês para ambientes de estudo e projetos pequenos.

A barreira de entrada para CI/CD profissional diminuiu muito. Ferramentas como GitHub Actions e Terraform tornam acessível o que antes exigia equipes dedicadas de DevOps. O importante é começar simples, entender cada peça, e evoluir conforme a necessidade.

Este artigo foi escrito com base em um projeto prático de estudo. Todo o código-fonte está disponível publicamente neste repositório do GitHub.

Criei uma pipeline de planejamento no OpenCode e olha no que deu

Clinton Rocha — Mon, 09 Mar 2026 04:37:00 +0000

Você é como eu e vem buscando formas de otimizar o uso de ferramentas como o OpenCode? Talvez este conteúdo te ajude a ter novas ideias e até mesmo entender alguns fluxos dessa e de outras ferramentas.

Enquanto eu estudava a documentação do OpenCode, encontrei a aba de plugins feitos pela comunidade. Ali, encontrei três plugins que, na minha visão, se complementam bem. Na verdade, um deles eu já utilizava: o Plannotator.

A partir disso, comecei a estudar como funcionava os comandos, agentes e como eu poderia fazer um fluxo que fizesse sentido e principalmente que funcionasse, calma que já te explico oq cada um dos plugins fazem e qual a ideia final da integração.

Índice

Como eu estava usando o OpenCode
Objetivo da integração
Plannotator: Revisão Visual
Octto: Coleta estruturada de contexto
Subtask2: Orquestração de Pipeline
Comandos
Considerações
Referências

Como eu estava usando o OpenCode

Após começar a utilizar o OpenCode, notei o quão importante é o uso do módulo de planejamento e, principalmente, não apenas o planejamento em si, mas também as perguntas que são feitas durante esse processo. O resultado dessas duas novas abordagens (planejamento e perguntas) melhora bastante não só o código produzido, mas também a minha compreensão sobre a regra de negócio, além de comportamentos e fluxos do sistema.

Mesmo com todas essas descobertas que trouxeram otimizações para o processo, eu ainda sentia que dava para melhorar mais.

O fluxo de uso do OpenCode era basicamente o seguinte: eu enviava o prompt, a ferramenta vasculhava o código para obter contexto, depois vinham algumas perguntas e, em seguida, ela ia para a parte de build, ou seja, para colocar em prática o que tinha sido planejado.

Objetivo da integração

A ideia vai ser conseguir extrair o máximo de contexto com o Octto, usar o subtask2 para orquestrar os comandos e visualizar o plano final com Plannotator.

+---------------------------------------------------------------+
|                                                               |
|  IDEIA -> CONTEXTO -> PLANO -> REFINAMENTO -> REVISAO -> OK   |
|                                                               |
+---------------------------------------------------------------+

O resultado é um único comando que orquestra todo o processo:

/generate-plan "descrição do objetivo"

Plannotator: Revisão visual

O primeiro plugin chegou até mim por recomendação de uma amiga da comunidade (He4rtDevs), a Cherry, e o plugin era o Plannotator.

Esse plugin basicamente faz com que, ao final de um planejamento, seja aberta uma página no navegador contendo todo o plano gerado. Isso facilita muito a visualização em comparação com o terminal. Na interface do navegador, você consegue selecionar trechos do planejamento e dar feedback, que retorna para o processo de planejamento. Também é possível aprovar o plano e seguir diretamente para a etapa de build, ou seja, aplicar o que foi planejado.

Octto: Coleta estruturada de contexto

O Octto quando você envia o primeiro prompt, ele abre uma página no navegador com perguntas relacionadas ao que você pediu inicialmente. Essa página funciona como uma interface interativa de brainstorming. Conforme você responde às perguntas, o sistema utiliza essas respostas para gerar novas perguntas dentro da mesma sessão, aprofundando o entendimento do problema e ajudando a estruturar melhor o contexto antes de seguir para as próximas etapas, ao final ele gera um arquivo .md no diretório /docs/plans dentro do projeto.

A unica configuração que adicionei a ele, foi uma que faz com que a primeira pergunta seja um campo de texto livre onde o usuário consiga descrever o contexto com maior liberdade (colocar uma task completa, por exemplo).

Fluxo de Funcionamento

+----------------------+
|       ask_text       |  <-- Primeira ação obrigatória
+----------+-----------+
           |
           | Campo de texto no browser:
           | "Descreva com detalhes o que
           | você quer planejar..."
           v
+----------------------+
|   create_brainstorm  |  <-- Agente inicia sessão
+----------+-----------+      com contexto coletado
           |
           | Define branches de exploração
           v
+--------------------------------------------------------------+
|                    BRANCHES DE EXPLORAÇÃO                    |
|                                                              |
|  +----------------+  +-------------------+  +---------------+|
|  | Motivação &    |  | Requisitos &      |  | Riscos &      ||
|  | Objetivos      |  | Restrições        |  | Dependências  ||
|  +--------+-------+  +---------+---------+  +-------+-------+|
|           |                    |                    |        |
+-----------+--------------------+--------------------+--------+
            |
            v
+----------------------+
|      BROWSER UI      |
|                      |
|  [ Pergunta 1 ]      |
|  [ Pergunta 2 ]      |
|  [ Pergunta N ]      |
|                      |
|      [Responder]     |
+----------+-----------+
           |
           | Usuário responde
           v
+----------------------+
| await_brainstorm_    |
| complete             |  <-- Agente aguarda respostas
+----------+-----------+
           |
           | Sintetiza respostas
           v
+----------------------+
|      docs/plans/     |
| 2026-03-08-objetivo  |  <-- Arquivo gerado
|        .md           |
+----------------------+

Configuração via Fragments

O comportamento do Octto é customizado através de fragments, instruções adicionadas ao prompt dos agentes internos:

{
    "fragments": {
        "octto": [
            "Sempre pergunte a motivação e o 'porquê' das mudanças",
            "Gere nomes de arquivo no formato: YYYY-MM-DD-slug.md",
            "Salve os planos em docs/plans/"
        ],
        "probe": [
            "Priorize perguntas sobre motivações e restrições",
            "Inclua perguntas sobre requisitos não-funcionais"
        ],
        "bootstrapper": [
            "Crie branches focados em: requisitos, arquitetura, riscos"
        ]
    }
}

Função de cada agente interno:

bootstrapper: cria a estrutura inicial de branches
probe : gera perguntas de aprofundamento
octto: define o comportamento geral da coleta de contexto

Subtask2: Orquestração de pipeline

O Subtask2 permite encadear comandos de forma sequencial. Quando um comando termina, o próximo da cadeia é executado automaticamente.

Nesse meu contexto só vou usar a funcionalidade de return, mas esse plugin tem muitas outras funcionalidades interessantes como:

loop de subtarefas até que a condição do usuário seja atendida
paralela de subtarefas simultaneamente - PR pendente.
$TURN[n] passa turnos da sessão (mensagens do usuário/assistente).
{as:name} + $RESULT[name] captura e referência as saídas das subtarefas.

Sintaxe de Return Chain

---
subtask: true
return:
- /comando-1
- /comando-2
- /comando-3
---

Comandos

Com o subtask2, consigo adicionar comandos ao fluxo, e isso abre muitas possibilidades. Mas, por enquanto, estou com os pés no chão e vou fazer um fluxo simples com alguns novos comandos.

Eu criei esses comandos com o único intuito de usar na pipeline.

Comando Principal

O comando que vai dar inicio a todo o fluxo, vai ser o /generate-plan ao executar, ele da inicio a pipeline de planejamento.

Você é livre para escolher qualquer nome para o comando, para escolher o nome desse aqui eu só segui as vozes da minha cabeça.

Caso queira saber mais sobre como criar e configurar comandos no opencode, a doc é legalzinha.

/generate-plan refatorar sistema de autenticação
/generate-plan "adicionar suporte a múltiplos gateways de pagamento"

As aspas são opcionais: tudo após o comando é passado como $ARGUMENTS.

---
description: Pipeline completo de planejamento 
agent: octto
subtask: true
return:
- /refine-plan
- /review-plan
---

prompt aqui, e lembre de usar o $ARGUMENTS

Caso você queira ver como deixei o meu prompt usado no comando generate-plan é só ir no gist.

Todos os comandos podem ser usados individualmente/isolado no OpenCode, a unica diferença ao usar um comando com o subtask é que ele vai ser executado em um contexto diferente.

Refinamento Técnico

O /refine-plan tem como objetivo expandir um plano existente com detalhes arquiteturais.

/refine-plan # usa plano mais recente
/refine-plan docs/plans/meu-plano.md # plano específico

refine-plan:

---
description: Expande e refina tecnicamente um plano existente com arquitetura e diagramas
subtask: true
---

Mesma coisa que o anterior, aqui você consegue adicionar a instrução que você quiser.

No meu caso, o prompt que estou sando tá no gist 'refine-plan.md'.

Revisão Visual

Por último vem o comando /review-plan com o objetivo de mandar o plano para revisão interativa via Plannotator.

/review-plan # usa plano mais recente
/review-plan docs/plans/meu-plano.md # plano específico

Importante: Este comando não usa subtask: true. Ele roda na sessão primária para que a ferramenta submit_plan possa abrir a interface do Plannotator no browser corretamente. Comandos rodando como subtarefa não conseguem inicializar a UI do browser.

Fluxo Completo de Execução:

Considerações

O mais importante de tudo: funcionou? Sim. É uma bazuca? Sim, hahahaha. Esse projeto acabou saindo porque entrei em hiperfoco ao me fazer a pergunta “será que funciona?”. No fim, tive minha resposta.

Olhando para a usabilidade no dia a dia, acredito que os melhores momentos para utilizar algo assim são em novas features, refatoração de projeto e até mesmo para estruturar estudos, quem sabe. Só não use para algo como “quero trocar a cor de um botão”, aí você acaba complicando.

O ponto que mais curti foi o Octto, com as perguntas geradas de forma dinâmica. Aquilo ali, ao meu ver, auxilia na contextualização de uma baita maneira. Fora que é possível dar instruções para as branches dele, especificar qual tipo de input você quer ou não quer, entre outras coisas (vale ler a documentação).

Já o subtask2 abre portas para muita coisa. Como eu tinha dito antes, acabei indo pelo simples, mas alguém com a mente mais aberta provavelmente vai conseguir extrair o melhor da ferramenta.

Eu pretendo criar novos comandos, refinar mais os prompts e ver o que acontece. É isso, obrigado por ler até aqui e tente brincar com isso ai.

Como meu Tech Lead fala:

Faça codigo inútil e quebre alguma coisa.

Referências

API vs Event Streaming: O Que Muda Para Quem Testa?

Alicia Marianne 🇧🇷 — Thu, 12 Feb 2026 20:50:04 +0000

✨ Oi, gente!

Recentemente, tenho pensado bastante em como contribuir para a comunidade de QA e ajudar aqueles que estão começando ou que já estão há algum tempo na área. Também quero relatar mais sobre os desafios de ser uma brasileira morando em terras lusitanas 🇵🇹.

O que me levou a querer voltar — na verdade, começar — a escrever na minha língua materna?

Bom, se eu fosse dizer de bate-pronto: saudade. 💛

Sim, aqui em Portugal fala-se português também, porém, como boa mineira que sou, sinto falta do nosso jeitinho de falar e escrever as coisas. Acredito que falar sobre o que sei na minha língua materna me deixa mais próxima de casa.

Outra razão que me fez querer começar a escrever em português foi voltar a ser mais ativa em comunidades de desenvolvimento (He4rt 💜). Tenho visto muitas mulheres entrando para a área, e algumas não são fluentes em inglês ou não confiam no que sabem para se arriscar em conteúdos em outros idiomas.

Com isso, eu pensei: por que não focar por um tempo em escrever em português? E cá estamos! ✍️

E, para que isso não seja apenas um comunicado, mas algo útil, já vou começar falando sobre serviços de mensageria (Event Streaming) e por que é importante que um QA (ou aspirante a QA) entenda pelo menos o básico sobre isso.

📡 Em termos técnicos

Event Streaming (Transmissão de Eventos) é a prática de capturar dados em tempo real a partir de fontes como bancos de dados, sensores, dispositivos móveis, serviços na nuvem e aplicações de software, na forma de fluxos de eventos; armazenar esses fluxos de forma duradoura para recuperação posterior; manipular, processar e reagir a esses eventos tanto em tempo real quanto retrospectivamente; e encaminhá-los para diferentes destinos, conforme necessário.

Lindo, né? 😅

Mas como podemos entender isso na prática?

🧠 Vamos imaginar o seu corpo

Sim, ele mesmo!

Você sente aquela dor no estômago 🍽️, que é um sinal de que está com fome. Esse sinal “fala” para o seu cérebro:

— Querido, estou precisando de nutrientes. Quando eles chegam?

Normalmente, você para o que está fazendo e vai comer algo. Mas perceba: seu estômago precisa esperar até o momento certo. Ainda assim, seu corpo continua funcionando normalmente. Ele não para.

No mundo do software, isso significa que, sempre que existir um sinal ou uma modificação, essa informação será interpretada sem que outras funcionalidades do sistema sejam interrompidas.

🛒 Exemplo prático: compras online

Você faz o seu pedido
Realiza o pagamento
O sistema de pagamento processa esse pagamento
Ele publica um evento informando que o pagamento foi aprovado
O sistema de notificação consome esse evento
E o cliente recebe a confirmação de que a compra será entregue 📦

Tudo isso pode acontecer sem que um sistema precise “esperar parado” pelo outro.

🔧 Algumas ferramentas de Event Streaming

Hoje, existem várias ferramentas no mercado que trabalham com esse modelo de comunicação baseada em eventos. Algumas das mais conhecidas são:

Apache Kafka 🐘 (uma das mais populares no mercado)
RabbitMQ 🐰
AWS Kinesis

Cada uma tem suas particularidades, mas todas trabalham com o conceito de produtores, consumidores e eventos trafegando por tópicos ou filas.

E aqui começa a parte interessante para nós, QAs. 👀

🔄 Event Streaming vs API

Você pode se perguntar:

“Alicia, mas qual a diferença disso para uma API? Eu consigo fazer o mesmo apenas chamando uma API.”

Conseguir, você consegue. Mas será que é a melhor opção? 🤔

Depende.

Normalmente, sistemas que utilizam apenas APIs (geralmente síncronas) funcionam assim: fazem uma requisição, esperam a resposta, e só depois continuam o processamento. Isso pode deixar o sistema mais acoplado e dependente.

Já em um sistema de Event Streaming (assíncrono), não é necessário esperar uma resposta para continuar o fluxo. O sistema segue funcionando enquanto os eventos são processados em paralelo.

E, principalmente, não queremos que o usuário fique esperando uma resposta para continuar usando o software ⏳.

🧪 E onde o QA e automação entram nisso?

Quando falamos de sistemas orientados a eventos, surgem novas perguntas de teste:

O evento foi realmente publicado?
O formato (schema) está correto?
O consumidor está processando corretamente?
O que acontece se o consumidor falhar?
Existe retry?

Percebe como o nível de complexidade aumenta?

Testar Event Streaming não é só validar payload. Envolve entender fluxo, consistência eventual, ordenação de mensagens, tolerância a falhas e comportamento assíncrono e partir dessa compreensão, é possível pensar em automações, do tipo:

Produzir eventos automatizados para testes
Validar consumo de mensagens
Testes de contrato (como com Schema Registry no Kafka)
Testes de integração ponta a ponta
Validação de mensagens em filas durante pipelines de CI/CD

✅ Conclusão

Entender mensageria e Event Streaming não é apenas “coisa de backend” — é conhecimento essencial para qualquer QA que queira testar sistemas modernos com mais profundidade. 💡

Quando compreendemos como os eventos trafegam, como os sistemas se comunicam de forma assíncrona e onde podem ocorrer falhas, ampliamos nossa capacidade de análise, criamos melhores cenários de teste e nos tornamos profissionais mais estratégicos.

Escrever sobre isso em português é, para mim, uma forma de compartilhar conhecimento, fortalecer a comunidade e também me sentir mais próxima de casa. 💛

E esse é só o começo. 🚀

Compartilhando seu conhecimento com o mundo! Como escrever artigos

Cherry Ramatis — Mon, 13 Nov 2023 21:31:19 +0000

Compartilhar conhecimento escrito é uma ótima forma de dominar um assunto específico, além de ser uma excelente maneira de melhorar a organização das ideias, comunicação e obviamente se autopromover na comunidade. Essa produção de artigos tanto técnicos quanto sociais são muito importantes tanto para quem escreve quanto para quem está lendo, lembre-se sempre: Você sabe mais hoje do que quem começou ontem. Pensando nisso vamos discutir um pouco mais sobre como organizar as próprias ideias na produção de um artigo técnico para a plataforma dev.to!

Método de Feynman e por que produzir conteúdo
Coletando ideias e se motivando para escrever
Entendendo a plataforma e achando a propria linguagem
Aprendendo markdown e dicas gerais para uma boa formatação
A estrutura básica de um artigo técnico
Como revisar e melhorar a escrita
Conclusão e agradecimentos

Método de Feynman e por que produzir conteúdo

Primeiramente precisamos discutir o porquê devemos compartilhar conteúdo, seja em formato textual (o foco desse artigo) ou em qualquer outro formato. Para iniciar essa discussão é importante entender o que é o método de Feynman e como ele pode nos ajudar a aprender 10 vezes mais com confiança e domínio do assunto.

O método de Feynman foi criado por um físico muito importante chamado Richard Feynman visando desenvolver uma abordagem nova ao aprendizado, essa nova proposta assume uma verdade central: "Se você não consegue explicar algo de maneira clara e simples, então você ainda não entendeu completamente".

Essa frase nos ajuda muito a pensar em como nosso aprendizado deve ser estruturado, pois a partir do momento que começamos a pensar em ensinar o que estamos estudando focamos muito mais em dominar as bases essenciais do assunto e se preparar para dúvidas que te forçam a olhar o problema, por outro lado, completamente diferente.

Ao se preparar para situações como essas, o resultado claro é uma excelente confiança e domínio sobre o assunto em questão que estava sendo estudado.

Eu particularmente amo esse método, o único problema dele é que quando saímos do ambiente acadêmico fica muito difícil de achar pessoas que se interessam pelo mesmo assunto que você esta estudando no momento, seja por não ter pessoas de TI no ciclo de amizade ou simplesmente por ter interesse em assuntos específicos.

Para esse problema temos uma solução muito incrível chamada "Learning in public"! Essa prática consiste em compartilhar seu aprendizado online em comunidades de tecnologia, seja produzindo vídeos, fazendo live streams ou no objetivo desse artigo: escrevendo!

Plataformas como o dev.to (que você usando para ler agora :D) visam tornar a ideia de "Learning in public" cada vez mais simples e próxima de quem está consumindo, pois agora é possível produzir artigos que vão chegar em pessoas com os mesmos interesses que os nossos que podem: aprender, tirar dúvidas ou mesmo sugerir mudanças e corrigir pensamentos. Incrível né?

Coletando ideias e se motivando para escrever

O processo de inspiração é provavelmente uma das fases mais chatinhas antes de produzir um artigo online, muitas vezes ficamos presos em um loop infinito de técnicas mirabolantes para ter ideias incríveis quando, na verdade, a solução acaba sendo muito simples: aceite suas ideias e consuma o máximo de conteúdos possível.

A forma mais prática de encontrar ideias e de construir sua própria linguagem é ler o que as outras pessoas já produzem sobre os temas que lhe interessam, quer se trate de uma linguagem de programação, de um tema específico em TI, etc; esse consumo de conteúdo vem de diversas fontes diferentes como artigos técnicos, vídeos no YouTube, tweets da bolha Tech, discussões no Github e muitos outros locais possíveis.

Bom, sei que falando assim parece simplificar algo que não é tão simples assim e eu concordo com você! Não é só ler ou assistir tudo o que existe na internet que vai nos tornar capazes de produzir os mesmos conteúdos, a habilidade mais importante que vai destacar essas pessoas é organizar as ideias que chegam no cérebro.

Mantendo um segundo cérebro

Nosso cérebro é uma excelente maquina de absorção de informação, praticamente uma esponja que guarda todas as informações ao nosso redor. O grande problema dessa maquina é que ela se tornou péssima em organização com o tempo, isso aconteceu principalmente para poupar energia já que não precisamos lembrar de tudo o tempo todo, mas sabendo disso o que podemos fazer para guardar as informações que queremos de forma organizada? Well well well jovem gafanhoto, precisamos parar de confiar no nosso cérebro é claro!

Manter um segundo cérebro é uma prática muito famosa entre escritores e pesquisadores, consiste em um local físico ou virtual onde você copia pequenos pedaços de conteúdo que consumiu junto de uma observação utilizando suas próprias palavras sobre o assunto. Esse amontoado de anotações vai compor o seu segundo cérebro e vai te empoderar com a habilidade de achar qualquer conteúdo rapidamente e referenciar seus autores sem nunca esquecer nada!

Para resumir a história, consuma o máximo de conteúdo possível, armazene-o em um segundo cérebro que pode ser armazenado e pesquisado e finalmente se desafie a escrever! Seja sobre um assunto que quer aprender, sobre algo específico que aprendeu recentemente ou até mesmo algo que domina há muitos anos.

Entendendo a plataforma e achando a propria linguagem

Entender a plataforma e o público que vamos atingir escrevendo nossos conteúdos é muito importante para podermos filtrar como vamos estruturar os artigos de forma geral certo? Na minha opinião, o dev.to é uma plataforma bem informal que valoriza muito conteúdos no formato de tutoriais com um estilo conversacional e direto ao ponto, com essa informação podemos deduzir algumas formas de estruturar nossos artigos para que possamos ilustrar nossa ideia em um modelo conhecido pelos leitores.

Isso significa que tudo o que você vai produzir são tutoriais diretos e informais? De forma alguma! Só significa que você pode moldar o seu conteúdo para conter essa linguagem mais informal, conversacional e direta mesmo que o tema tratado seja super complexo, isso inclusive vira um desafio muito interessante de simplificar o complexo.

A habilidade de simplificar o complexo vai te acompanhar para o resto da sua vida profissional, é importantíssimo a criação de analogias e exemplos para que facilite o entendimento e a identificação com os problemas apresentados e as soluções propostas.

Aprendendo markdown e dicas gerais para uma boa formatação

A forma para produzirmos nossos artigos no dev.to é utilizando uma linguagem de marcação (exatamente, igual o HTML) chamada Markdown, apesar dela ser super simples é importante termos um domínio bem solido do que é possível fazer quando falamos sobre organizar e deixar nosso texto bonitinho, semelhante como vamos produzir uma estrutura complexa no Microsoft Word devemos ser capazes de produzir o mesmo com código Markdown.

É sempre importante ressaltar a importância de um material educacional bem estruturado (afinal você está lendo esse artigo justamente para isso certo?) e quando o assunto é excelência e qualidade não consigo recomendar o suficiente o projeto 4noobs que junta em um único repositório diversos cursos grátis e no formato de texto sobre diversos assuntos em TI, para o tema desse artigo recomendo o uso do markdown4noobs no aprendizado da linguagem de marcação Markdown.

O básico sobre manipulação de texto e blocos de código

Markdown nos permite marcar partes do nosso texto com estruturas super básicas e necessárias como negrito, itálico, highlight, níveis de título, etc. Abaixo vamos ver rapidamente como realizar cada uma das ações com a sintaxe correta.

# Primeiro titulo equivalente a um h1
## Segundo titulo equivalente a um h2
### Terceiro titulo equivalente a um h3
#### Quarto titulo equivalente a um h4

`Texto em highlight`
**Texto em negrito**
*Texto em itálico*

Esses artifícios da linguagem markdown nos permitem controlar a narrativa a nosso favor e deixar a leitura mais simples de seguir, utilizando bold no meio do texto para chamar a atenção, deixar explicito um termo técnico usando highlight ou até mesmo utilizando imagens ilustrativas que introduzem o ponto do parágrafo enquanto mantém o clima geral do texto muito mais gostoso de ler.

Outra coisa importante de se mencionar é o bloco especifico que usei acima, ele é extremamente útil quando vamos escrever artigos técnicos, tanto, pois ele permite um destaque maior a um bloco de texto quanto ele permite habilitar syntax highlighting caso esteja escrevendo um bloco de código, ele é utilizado da seguinte maneira:

Disclaimer: Como markdown não permite um bloco dentro de um bloco optei por mostrar com um screenshot:

Após os símbolos de backtick, podemos incluir o nome da linguagem (no meu caso ruby) para que o dev.to possa habilitar o syntax highlighting especifico para essa linguagem de programação.

Tabela de conteúdo

Caso o seu artigo esteja ultrapassando a margem das duas mil palavras ou esteja com pelo menos 4 títulos principais, eu recomendo fortemente que deixe definido um Table of contents, ou Tabela de conteúdo. Essa tabela de conteúdo serve para guiar a leitura durante os pontos principais que serão lidados durante o artigo, para a criação de um existem uns macetes que vou demonstrar abaixo:

Na plataforma dev.to, use listas não ordenadas ao invés de listas numeradas

Listas em Markdown são bem simples de serem usadas e elas possuem dois tipos principais: não ordenadas e numeradas.

- Uma lista
- Não
- Ordenada

1. Uma lista
2. Numerada
3. Aqui

O problema de usar as listas numeradas no dev.to é que elas ficam desalinhadas como podemos ver no exemplo abaixo, portanto não recomendo o uso delas de maneira geral, sempre tento utilizar as listas não ordenadas e se for necessário aplicar alguma ordem utilizar um número após o símbolo da lista não ordenada manualmente.

Como organizar os links para um título

Assumindo que você já descobriu como estruturar um link no Markdown (já que você leu o markdown4noobs né?) vamos aprender os macetes simples para indicar um link em um título e como estruturar nossa tabela de conteúdo.

Uma tabela de conteúdo de exemplo pode ser vista abaixo:

## Table of contents

- [What is metaprogramming anyway?](#what-is-metaprogramming-anyway)
- [In ruby everything is an object, what does that mean?](#in-ruby-everything-is-an-object-what-does-that-mean)
- [But what about rails? How this framework applies that concept for maximum developer experience](#but-what-about-rails-how-this-framework-applies-that-concept-for-maximum-developer-experience)
- [How to define methods dynamically](#how-to-define-methods-dynamically)
- [Using hooks to detect moments on the instantiation of the class](#using-hooks-to-detect-moments-on-the-instantiation-of-the-class)
- [Conclusion](#conclusion)

Como você pode ver, a ideia geral para definir a segunda parte do link é incluir uma hashtag # junto ao título em um formato especifico seguindo as regras:

Trocar todos os espaços em branco por hifens -
Deixar todo o título em minúsculo

E é isso! Títulos com acentos podem continuar igual sem nenhum problema, o Markdown compreende como texto padrão igual mostrado abaixo:

- [Um título com muitos acentos e çedilha](#um-título-com-muitos-acentos-e-çedilha)

A estrutura básica de um artigo técnico

Agora que temos uma noção interessante de como podemos marcar nosso texto para ficar legível e agradável de ler, vamos entender um pouco a estrutura de um artigo. É importante ressaltar que um modelo não vai servir para todo tipo de texto possível, a ideia é prover uma ideia geral que deve ser adaptada e mudada conforme o contexto.

Primeiro é muito importante definir o parágrafo inicial para chamar o leitor para o problema ou a situação que você vai dissecar ao longo do artigo, é importante fazer isso, pois esse primeiro paragrafo vai ser usado pelo dev.to para comunicações de marketing por e-mail ou por redes sociais. Um exemplo de parágrafo inicial pode ser achado nesse mesmo artigo que você esta lendo ou em alguns outros que deixo abaixo:

A ideia é sempre utilizar perguntas e pausas no texto para podermos alcançar uma comunicação direta e bem conversacional, sempre tentando apresentar a situação da maneira mais geral possível para que quem esteja lendo fique com bastante curiosidade e vontade de ler.

Após o primeiro parágrafo de apresentação, é muito importante definir a Tabela de conteúdo para guiar o usuário ao longo dos títulos principais do seu artigo, sobre isso inclusive eu particularmente não recomendo listar os subtítulos junto dos títulos por conta de deixar a tabela de conteúdo muito grande e pouco útil para quem estiver lendo, obviamente que se você considerar seus subtítulos muito importantes de serem listados é completamente valido incluir.

Passando para o corpo geral do artigo, entramos em uma área muito subjetiva, pois depende muito do assunto que está sendo abordado para entender a estrutura dos seus títulos e parágrafos. Vou assumir um artigo no modelo de tutorial simples para ser possível partir de algum lugar.

Recomendo sempre ter três títulos satélites que vão nortear o seu artigo e dar inspiração para aumentar o conteúdo com mais detalhes. Esses títulos satélites são os seguintes:

Introdução a tecnologia ou problema: Esse parágrafo vai servir para podermos detalhar o que foi falado no começo do artigo, respondendo às perguntas que criamos para atiçar a curiosidade e aprofundando mais no tema que vai ser discutido com os tópicos específicos.
Prós e contras: Nesse momento vamos deixar claro os prós e contras da solução que vai ser apresentada no artigo, seja ela uma arquitetura, um padrão de código, uma linguagem, framework, etc. A existência desse paragrafo pode ser bem situacional dependendo do seu tema, mas costuma ser bem útil caso esteja apresentando uma solução em forma de tutorial!
Conclusão: Esse ponto é mais uma opinião do que uma regra geral, mas eu acho muito importante ter um parágrafo onde vai ser indicado o final do processo de leitura, assim podemos deixar argumentos finais, agradecimentos, contato e qualquer outra mensagem interessante.

Ao redor desses três principais títulos, podemos desenvolver nosso artigo com uma escrita ilustrativa e que apresente exemplos práticos ou analogias, facilitando a visualização tanto do problema quanto da solução pelo leitor. É importante ressaltar também o cuidado ao aprofundar muito nas analogias, elas são extremamente uteis, mas podem ser um tiro no pé quando você abusa e nunca volta para o mundo real com uma solução e explicação clara.

Uma dica geral ao redor da estrutura do artigo é manter o sentimento geral da leitura leve, portanto é super aconselhável utilizar imagens (seja um meme para descontrair ou um gráfico para ilustrar melhor o ponto apresentado), como a plataforma do dev.to comporta artigos técnicos mais informais, abusar dessa linguagem mais próxima é uma estratégia muito certeira.

Como revisar e melhorar a escrita

Bom, agora que temos uma boa ideia de como estruturar nosso artigo, como mantê-lo bonito utilizando Markdown e como ponderar nossa linguagem para a plataforma especifica, o que falta? Bom, agora o que falta é entender que não somos perfeitos e erramos, portanto, precisamos de uma boa estratégia para revisar o artigo que acabamos de produzir com nossas técnicas aprendidas.

Para auxiliar na escrita, eu recomendo fortemente utilizar um editor que oferece visualização do Markdown em tempo real como VSCode ou o queridinho da comunidade Obsidian. Inclusive esse artigo foi escrito utilizando o Obsidian!

No que se entende por revisão temos algumas ferramentas bem interessantes que nos auxiliam em diversos aspectos da escrita:

LanguageTool: Essa ferramenta é meu xodózinho e ela cuida de toda correção de ortografia, a parte legal é que nessa ferramenta você pode ter dicas de contexto que vão melhorar a frase e também correção de termos específicos de programação como nomes de linguagens visto que o banco de dados deles é super atualizado.
Deepl: Entrando no mundo das inteligências artificiais, o Deepl utiliza deep learning para oferecer uma interface incrível de tradução, mas não só isso! Com ele podemos ter uma segunda opinião para refrasear nosso parágrafo de forma muito simples, você só precisa traduzir o texto para inglês e traduzir o texto em inglês para português de novo; normalmente no Google Translate isso destruiria o contexto, mas essa ferramenta mantém o contexto e melhora as expressões para que você possua uma segundo percepção de um mesmo paragrafo.
ChatGPT ou Bard: Bom, aqui eu confesso que não tenho muito domínio e não uso tanto, mas essas interfaces de chat com IA ajudam muito a ter visões diferentes para refrasear um parágrafo já existente ou até mesmo começar a escrever algum. Importante: Preciso ressaltar para usar essas ferramentas apenas para ter ideias ou ajudar a refrasear textos que você já escreveu, por favor não produza artigos inteiros utilizando inteligência artificial
Comunidade: Na comunidade He4rt Developers tentamos providenciar o máximo de auxílio para a escrita de artigos técnicos na plataforma dev.to. Fazemos isso providenciando um fórum onde você pode postar seu artigo ainda em progresso e ganhar feedback da comunidade até a publicação, após a publicação a gente ainda faz um trabalho de divulgação para pessoas ativas! Disclaimer: Obviamente estou citando a He4rt, pois temos um projeto voltado para isso, mas a lição geral é compartilhar seus progressos com a comunidade de maneira geral.

Conclusão e agradecimentos

Esse é o último artigo que estou postando seguindo o desafio 100 dias de código, foi um desafio muito intenso e com muito aprendizado onde eu descobri uma nova paixão: escrever e compartilhar conhecimento! Não tenho nem palavras para agradecer a comunidade da He4rt por ter me apoiado 100% nessa jornada imensa. Espero que esse artigo seja útil para quem esteja lendo e que inspire qualquer um a compartilhar conhecimento online para podermos criar uma internet mais segura e rica em informação.

Gostaria também de deixar um agradecimento especial aos revisores desse artigo:

May the force be with you! 🍒

Compondo música com Java! É hora do Jmusic

Bruno Rezende Novais — Tue, 24 Oct 2023 11:56:13 +0000

É isso mesmo que você leu, se você sempre quis compor uma música ou imaginou como fazer isso com código saiba que é possível fazer isso e está a poucas linhas de distância. Hoje vou discutir um pouco e mostrar como é possível codar música usando Java.

Índice

O que é Música Computacional?
JMusic
Show me The Music
Quais as vantagens de se compor usando código?

O que é Música Computacional?

Primeiro é necessário darmos um passo atrás e falarmos sobre música computacional, para quem não conhece, de forma geral música computacional pode ser definida como música que envolve computação em qualquer estágio de seu ciclo de vida (Collins, 2009). Se aprofundarmos um pouco mais nessa definição, podemos pensar esse ramo como o estudo do uso da tecnologia computacional na música em quaisquer de seus estágios, seja na teoria ou prática.

Hoje com o avanço das inteligências artificiais a composição de música por máquinas já não é algo tão distante e geralmente não percebemos, mas já há o uso desse ramo de estudo em nosso dia a dia. Seja no Spotify que você abre, nos módulos de equalização de som que há no seu sistema operacional ou até mesmo no estúdio quando o engenheiro de som está usando compressores digitais ou efeitos de reverbs criados virtualmente. A música computacional é uma realidade.

Se ela é algo ético ou não, podemos discutir isso em outro artigo, mas hoje vamos passar a aprender um pouco mais sobre.

JMusic

Saiba que há uma infinidade de bibliotecas criadas para manipular e gerar som em diversas linguagens de programação, mas nesse artigo irei focar e mostrar que é possível criar música com Java. Para isso, vou introduzir a biblioteca JMusic, um projeto criado por Andrew Sorensen e Andrew R. Brown. Trata-se de uma lib completa e focada em composição que agrega desde exportadores de arquivo MIDI até mesmo instrumentos virtuais para você criar suas composições. Vale citar aqui também o livro escrito por Andrew R. Brown que foca exatamente na composição usando Java, vale leitura!

A documentação do JMusic está disponível aqui.

Show Me The Music

Vamos dar uma olhada no código e analisá-lo tal como um maestro.

Caso não esteja familiarizado com alguns termos musicais vou deixar um glossário no fim do artigo para ficar mais fácil :)


import jm.constants.ProgramChanges;
import jm.music.data.Note;
import jm.music.data.Part;
import jm.music.data.Phrase;
import jm.music.data.Score;
import jm.util.Read;
import jm.util.Write;

import static jm.constants.Durations.SEMIBREVE;
import static jm.constants.Pitches.C4;

public class Application {

    public static void main(String[] args) {

        Score score = new Score("JMDemo1 - Chromatic Scale");
        Part prt = new Part("Piano", ProgramChanges.PIANO, 0);
        Phrase phr = new Phrase("Chromatic Scale", 0.0);

        for(int i =0; i < 12; i++) {
            Note n  = new Note(C4+i,SEMIBREVE);
            phr.add(n);
        }

        prt.add(phr);

        score.add(prt);

        SimpleSineInst simpleSineInst = new SimpleSineInst(10000);

        Write.au(score, "WaveformExample.au",simpleSineInst);

        float[] audio = Read.audio("WaveformExample.au");

        Write.audio(audio,"waveform.wav");

    }
}

3.1 Definindo a partitura


      Score score = new Score("JMDemo1 - Chromatic Scale");
      Part prt = new Part("Piano", ProgramChanges.PIANO, 0);
      Phrase phr = new Phrase("Chromatic Scale", 0.0);

Primeiro instanciamos uma classe chamada Score (partitura) e precisaremos definir algumas partes dela como qual será o instrumento a seguir e qual canal do arquivo MIDI utilizaremos. Pense que o arquivo MIDI (Musical Instrument Digital Interface) é um arquivo que tem várias linhas ou canais.

A partir daí, já na linha seguinte criamos uma frase, que é onde conterá nossas notas e ritmos. Nesse caso, vamos fazer um exemplo mais simples e criar uma escala cromática começando a partir do minuto 0:0.


 for(int i =0; i < 12; i++) {
            Note n  = new Note(C4+i,SEMIBREVE);
            phr.add(n);
        }

Já no laço for, inserimos dentro da nossa frase as notas, a nota por sua vez tem também a sua altura. (usaremos a nota Dó – C na cifra americana) Adotaremos o Dó e como ritmo usaremos a semibreve que é uma unidade de tempo para a música. Assim, incrementalmente passaremos de nota em nota até completarmos o laço.


 prt.add(phr);

 score.add(prt);

Podemos pensar então que um Score (ou partitura) contém partes e as partes contém as frases que por sua vez contém as notas. Dessa forma vamos adicionando-as até que a frase fique completa.

3.2. Sintetizando nossa partitura

SimpleSineInst simpleSineInst = new SimpleSineInst(10000);

Write.au(score, "WaveformExample.au",simpleSineInst);

Poderíamos já tocar nossa composição, porém vamos exportá-la primeiro. Para isso, vamos ter que usar um sintetizador para produzir os sons da nossa partitura, assim criaremos uma instância de SimpleSineInst (um sintetizador simples) e passaremos ele para o módulo de escrita, exportando-o inicialmente em um arquivo do tipo au.

3.3 Exportando em outros formatos


float[] audio = Read.audio("WaveformExample.au");

Write.audio(audio,"waveform.wav");

Tendo agora nosso arquivo.aufica fácil, basta que leiamos ele e em seguida pode-se escrevê-lo como arquivo de áudio na extensão .wav por exemplo que é mais comum. Agora temos nossa composição exportada!

Ouça aqui o resultado final! Mas antes, recomendo que abaixe o volume de seu fone de ouvido para evitar problemas.

Quais as vantagens de se compor usando código?

Bom, a primeira de todas é que compomos uma música e criamos um sample(amostra) usando apenas código. Sim, não tivemos que comprar um teclado, uma guitarra ou uma interface de áudio para podermos capturar o som, bastou apenas algumas linhas do bom e velho Java. Com isso a primeira vantagem é custo, o custo para criar música assim é bem reduzido.

Ainda assim, podemos dar uma extrapolada e ir para “fora da caixa”. Podemos pensar no uso disso em diversos lugares, como por exemplo: games. Pode-se gerar proceduralmente música, pode-se fazer com que a partir de uma determinada decisão do jogador um som seja gerado ou ele mesmo gere uma partitura e no final você toque-a usando o JMusic por baixo dos panos, pode-se ler uma imagem por exemplo e convertê-la em uma sequência numérica para poder criar música a partir disso, música a partir de uma imagem!

Em termos de acessibilidade, podemos agora dar o poder para queles que não conseguem tocar por suas limitações físicas para dentro do mundo virtual, onde conseguirão produzir música usando os recursos de assistência dos computadores.

Aqui, o que limita é apenas a sua criatividade e a sua habilidade no código.

Bibliografia

COLLINS,N. Introduction to Computer Music. West Sussex, Reino Unido. 2009. p 2

Glossário

Partitura: Paritura pode ser definida como uma representação escrita de uma música onde está definido o ritmo, o tempo e as frases da música.

Frase: Também conhecida como frase musical, pode ser definido como um trecho de música coerente e autonomo em relação a um ritmo definido pela partitura.

Semibreve: Semibreve é uma das figuras rítmicas usadas na música sendo ela uma das de maior duração.

Escala cromática: A escala cromática é uma das escalas na música, escalas nada mais são que uma sequência ordenada de notas. Você pode saber mais sobre essa escala neste link.

Formato de arquivo Au: arquivos .au são tipo um tipo voltado para áudio, menos usual porém focado em conter informações os dados de áudio divido em três grandes blocos de dados.

Formato de arquivo WAV: arquivos .wav são um tipo mais comum de arquivos de áudio, geralmente usados já para músicas completas com uma maior qualidade sonora, geralmente são arquivos mais pesados em termos de espaço (megabytes)

Conhecendo o ecossistema Crystal: ferramentas e projetos

guto — Mon, 16 Oct 2023 23:26:52 +0000

Bem, se você abriu esse artigo, então, tenho certeza que está interessado em entender um pouco mais sobre o ecossistema de Crystal. Antes de mais nada, vamos primeiramente introduzir o que é Crystal e onde se aplica.

Índice

O que é Crystal?
Ruby e Crystal
Integração nativa com LibC
Ferramentas
1. Language Server Protocol (LSP)
2. Read-Eval-Print Loop (REPL)
3. Code style linter
4. Debugger
5. Gerenciador de dependências
6. Livro
7. Documentação
8. Patterns
Frameworks
1. Kemal
2. Amber
3. Lucky
4. Marten
Projetos com Crystal
Finalização

O que é Crystal?

Crystal é uma linguagem de programação de código aberto, com sintaxe inspirada no Ruby, que visa a produtividade e o desempenho. Ele tem uma sintaxe elegante e uma tipagem estática, mas sem a necessidade de declarar tipos de variáveis. O Crystal é compilado para código nativo, e não para bytecode, e usa LLVM para gerar o código binário.

A aplicabilidade de Crystal é vasta, podendo ser visto de diferentes formas, mas, consigo afirmar que a ênfase de aplicabilidade ocorre para aplicações web, na qual consegue se destacar em pontos específicos exatamente por ser uma linguagem de programação compilada.

O principal motivo para o surgimento de Crystal foi para resolver alguns problemas bem específicos que Ruby possuia, porém, seriam solucionados deixando de lado a dinamicidade que Ruby proporcionava para abrir espaço para uma linguagem de programação totalmente nova, com a possibilidade de inferência de tipos, sendo compilada. Assim, em 2011 surge o projeto de uma nova linguagem de programação, criada por Ary Borenszweig, Juan Wajnerman e Brian Cardiff, contando hoje com mais de 450 colaboradores do mundo todo, tendo seu código fonte disponibilizado no repositório oficial do GitHub.

Ruby e Crystal

Como citado anteriormente, Ruby por sua vez possui uma sintaxe muito elegante, na qual Crystal se inspirou em sua maior parte exatamente pelo contexto de desenvolvimento da época, desejando uma linguagem de programação elegante na sintaxe como Ruby, veloz como C, podendo ainda realizar otimizações nativas com interoperabilidade utilizando a LibC e o melhor: sem escrever uma linha de código em C. Parece mágica não é? Bem, é apenas Crystal!

Uma analogia para entender melhor a compatibilidade de ambas as linguagens de programação que gosto de fazer é: imagine que você hoje é dono de uma empresa que possui N desenvolvedores Ruby, que consequentemente são a maioria dentro da empresa. Em um belo dia você em uma conversa com seus arquitetos de software decidem que uma linguagem compilada é necessária em apenas alguns serviços que estão funcionando hoje. Ao invés de simplesmente reescrever todo o código em alguma outra linguagem compilada, você pode reaproveitar toda a base de código para utilizar e compilar em Crystal, assim, a curva de aprendizado para seus desenvolvedores Ruby será praticamente nula, afinal, apenas alguns pontos específicos requerem maior cuidado ao se trabalhar com Crystal, como por exemplo a verificação de tipos, que pode ser um pouco estranho no início, mas, garanto que com o passar do tempo será mais prática a manutenção de seu código.

Entenda que Crystal não veio para substituir o Ruby, mas, para que ambos possam ser utilizados em conjunto, visando um melhor aproveitamento de código, melhor eficiência e melhor ambiente de desenvolvimento. O exemplo que deixarei abaixo demonstra a diferença de dois códigos que fazem a mesma coisa, porém, Crystal possui uma peculiaridade específica que vou retratar logo abaixo.

def soma(a, b)
  a + b
end

print "Digite o primeiro número inteiro: "
a = gets.chomp.to_i
print "Digite o segundo número inteiro: "
b = gets.chomp.to_i

puts "A soma dos números é #{soma(a, b)}"

O código acima é bem simples: pedimos para o usuário informar dois números, a e b respectivamente, na qual chomp remove o enter (\n ou \r) e o to_i converte o valor para inteiro. Agora, em Crystal precisamos apenas adicionar uma validação bem simples:

def soma(a, b)
  a + b
end

print "Digite o primeiro número inteiro: "
a = gets
print "Digite o segundo número inteiro: "
b = gets

# É necessário validar se o valor é nil!
if a.nil? || b.nil?
  puts "Você deve digitar dois números inteiros."
  exit
end

puts "A soma dos números é #{soma(a.chomp.to_i, b.chomp.to_i)}"

A validação é necessária para não enviarmos um valor nulo para o método chomp, afinal, ele está esperando receber uma String e sem a validação estaremos enviando um String | Nil, não validando com o tipo esperado. Nesse momento você deve estar pensando: mas, os tipos enviados foram validados em tempo de compilação? Isto é, a inferência dos tipos foi feita sem eu precisar falar nada? Bem, a resposta é sim, o compilador automaticamente adivinhou de quais tipos se tratavam.

Certo, agora você deve perguntar: nossa mas eu também consigo inferir os tipos manualmente? Como por exemplo na função soma, informando os tipos dos parâmetros que espero receber, além do tipo do retorno? A resposta é sim, e neste caso ficaria algo como o exemplo abaixo:

def soma(a : Int32, b : Int32) : Int32
  a + b
end

Interessante, certo?

O principal ponto é dar nas mãos do desenvolvedor a possibilidade de nivelar exatamente o que um método deve ter e/ou deve retornar.

Integração nativa com LibC

Se você quer utilizar ferramentas da LibC, mas, sem a necessidade de escrever código em C, então Crystal pode te ajudar com isso. Com bindings nativas você pode utilizar bibliotecas externas, incluindo a LibC, para utilizar ferramentas que seriam possíveis apenas escrevendo código nativo em C.

Para entender um pouco melhor sobre o funcionamento, recomendo seguir a documentação oficial, porém, deixarei um exemplo abaixo,

lib C
  # Em C: double cos(double x)
  fun cos(value : Float64) : Float64
end

O exemplo acima demonstra o uso da função cos

Ferramentas

Como todo desenvolvedor, nada melhor do que saber como preparar seu ambiente de desenvolvimento com Crystal, não é mesmo? Bem, vamos então navegar por algumas tecnologias que vão te ajudar nessa jornada.

Language Server Protocol (LSP)

Como todo bom desenvolvedor, sabemos que um LSP pode nos auxiliar muito durante o desenvolvimento de software, por isso, o LSP que estarei recomendando para uso com Crystal é o Crystalline, na qual você poderá configurar de forma simples na maioria dos editores de código que esteja utilizando.

Basicamente o Crystalline vai disponibilizar um executável simples, sendo totalmente escrito em Crystal. Você pode seguir os passos deixados no próprio repositório para configurar seu ambiente, porém, gostaria de dizer que um dos guias de configuração que contribuí foi para o Emacs, utilizando o emacs-lsp.

Minhas recomendações para editores de código são bem pessoais, porém, recomendaria alguns como Visual Studio Code, Sublime Text, Vim e Emacs.

Read-Eval-Print Loop (REPL)

Desenvolver ao lado de um REPL é uma experiência simplesmente magnífica e recomendo sempre que possível, por isso, Crystal não fica de fora no mundo de REPLs e possui o icr como REPL oficial, vindo hoje já embutido no próprio Crystal, podendo ser acessado com o comando crystal i!

Basicamente a funcionalidade principal do REPL é ser seu companheiro durante o desenvolvimento, possibilitando a execução de trechos do código de forma isolada sem muitos problemas.

Code style linter

Mais importante do que escrever código para si mesmo é escrever código para outras pessoas, por isso, sempre que possível é recomendado escrever códigos de acordo com as convenções de cada linguagem de programação. Dessa forma, Crystal possui uma convenção de estilo de código incrível, logo, nada mais justo do que uma ferramenta que te ajude no processo de escrita.

Assim surge o projeto Ameba, sendo um linter para validar seu código e verificar se está adequado de acordo com as convenções apresentadas oficialmente.

Debugger

Nada melhor do que poder rodar seu código passo por passo para validar problemas e rotinas, não é? Pois bem, o projeto debug surge com objetivo de ser um debugger completo para seu desenvolvimento, sendo escrito completamente em Crystal.

Gerenciador de dependências

Dependências podem ser definidas como um conjunto de pacotes/bibliotecas que são necessárias para a execução de determinada aplicação. Gerenciar dependências de forma elegante é algo que Crystal não decepciona utilizando o projeto Shards.

Basicamente existe um arquivo chamado shard.yml, utilizado para definir de maneira simples pontos como nome do projeto, autores, dependências, versão atual e licença em que determinado projeto é distribuído.

Livro

Um livro sobre a linguagem é necessário, não apenas para ser utilizado como referência, mas, para ser utilizado no processo de aprendizado do leitor.

Assim surge o projeto crystal-book, sendo um livro completo com referências da documentação oficial.

Documentação

A documentação oficial é necessária para qualquer tecnologia, assim, Crystal possui dois tipos de documentações que podem ser encontradas, sendo elas:

A segunda referência geralmente é utilizada para um detalhamento maior dos métodos e funcionalidades nativas que Crystal proporciona.

Patterns

A definição de patterns e padrões de código é necessária, por isso, existe um repositório com exemplos didáticos de implementações com Crystal utilizando os patterns GOF (Gang of Four), chamado crystal-patterns.

Frameworks

Atualmente, Crystal conta com diversos frameworks para diversos propósitos, porém, irei citar os mais conhecidos para desenvolvimento de aplicações web no geral.

Kemal

Sendo um dos frameworks mais conhecidos, Kemal se destaca por ser inspirado no estilo de outro framework já existente para Ruby, o Sinatra, sendo utilizado para ser uma solução simples, com tratamento de rotas elegante, possibilitando um middleware que pode ser ampliado.

Sua implementação ocorre de forma simples, sendo bem minimalista, assim, uma comparação deixada no site oficial do Kemal compara a quantidade de requisições por segundo de uma aplicação com Kemal comparada com uma aplicação Ruby com Sinatra: enquanto o Sinatra conseguiu chegar em 5268 requisições por segundo, Kemal conseguiu atingir invejadas 122697 requisições por segundo (magnífico, não é?).

Amber

Com uma proposta um pouco diferente do Kemal, porém, levando tanto o Kemal quanto Rails e Phoenix como inspiração, temos o Amber, um framework para aplicações robustas, possuindo templates de renderização HTML prontos, possibilitando um desenvolvimento mais produtivo.

O framework conta com a possibilidade de uso de três ORMs distintos, sendo eles Jennifer, Granite e Crecto.

Lucky

Sendo um framework inspirado principalmente no Rails, o Lucky é um framework que está no coração de grande parte dos desenvolvedores que alguma vez já trabalharam com Crystal, trazendo infinitas possibilidades, sendo extremamente rápido e produtivo!

O repositório oficial está disponível no GitHub, tendo consigo também um artigo interessante falando sobre o uso do Lucky na perspectiva de um desenvolvedor que já trabalhou alguma vez com Rails. O nome do artigo é Ruby on Rails to Lucky on Crystal: Blazing fast, fewer bugs, and even more fun e recomendo a leitura.

Marten

Um framework novo, porém com propostas interessantes, trazendo conceitos novos para o mundo de desenvolvimento com Crystal, ampliando a simplicidade e produtividade dentro do seu código. Este é o Marten, tendo seu repositório oficial publicado no GitHub já está tomando espaço e crescendo cada vez mais como um dos frameworks para Crystal que tende a melhorar ainda mais.

Já ganhou um espaço especial no meu coração e tenho certeza que você vai adorar utilizar o Marten em seu cotidiano como desenvolvedor.

Projetos com Crystal

Bem, como foi possível observar, a aplicabilidade de Crystal é bem vasta e existem diversas ferramentas para te auxiliar durante todo o processo, mas, quais projetos reais já existem e levam como base o uso de Crystal? Bem, vamos passar citando alguns maneiros se você talvez esteja pensando em começar a contribuir...

Awesome Crystal: conjunto de repositórios, bibliotecas e ferramentas para uso no desenvolvimento com Crystal, trazendo tudo de melhor que o ecossistema pode te proporcionar
Invidious: um projeto que tem crescido muito e traz consigo o objetivo de ser uma alternativa para o front-end do YouTube, reduzindo a quantidade de JavaScript a ser renderizado, sendo distribuído sob licença AGPL 3.0
Slang: uma linguagem de template inspirada no Slim para construção de páginas web sem a necessidade de escrever HTML puro
Immutable: uma implementação completa de uma coleção de estruturas de dados imutáveis, thread-safe e persistente, possibilitando uma melhor segurança no processamento e acesso de memória
Hetzner k3s: um CLI completo para gerenciamento de cluster Kubernetes na Hetzner Cloud utilizando a distribuição k3s
Hackacrow: um CLI completo para validação de entradas e saídas de comandos, sendo útil principalmente para validações de respostas em hackathons
Crystal ZSH: um plugin completo para utilizar junto do oh-my-zsh, permitindo uma integração magnífica com seu terminal durante o desenvolvimento com Crystal
Editor Plugins: sendo uma área específica de outro repositório (awesome-crystal nesse caso) conta com plugins interessantes para diferentes editores de código, por isso, recomendo conhecer

Existem diversos outros projetos com Crystal, porém, acredito que vale a pena conferir o primeiro repositório citado anteriormente para conhecer outros projetos que utilizam Crystal.

Finalização

O intuito desse artigo foi apresentar um pouco mais sobre a proposta que Crystal traz no mundo de desenvolvimento de software, citando ferramentas e projetos que podem fazer parte do seu cotidiano de desenvolvimento.

Se você quer aprender um pouco mais sobre Crystal com um conteúdo totalmente gratuito, em português, escrito com muito amor e carinho, recomendo a leitura do crystal4noobs, um conteúdo parte do projeto 4noobs da He4rt Devs, trazendo conteúdo de qualidade para todos de forma gratuita.

Agradeço imensamente se você chegou até aqui e espero que tenha gostado da leitura. Não se esqueça de deixar sua estrelinha os repositórios apresentados. Espero que esse artigo possa crystalizar ainda mais sua rotina de desenvolvimento. Meu muito obrigado e até a próxima!

Da comunidade para a comunidade 💜💛

Criando Exceptions para impressionar no Teste Técnico

Daniel Reis — Tue, 10 Oct 2023 01:03:22 +0000

Exceptions sempre vai ser um assunto constante quando o tópico for Orientação à Objetos e hoje vamos descobrir como criá-las como um artesão de software!

Tabela de Conteúdo

1. Prólogo
2. O que gostariamos de EVITAR
3. Refatoração 1: Criando Exceptions
4. Design Patterns: Factory Pattern
5. Refatoração 2: Refinando as Exceptions
6. Conclusão

1. Prólogo

Quando eu comecei a estudar programação, um dos assuntos que sempre me assustava eram "erros" ou qualquer coisa que se relaciona à isso, porém após começar a estudar com mais frequencia, eu entendi que os erros e/ou Exceptions são muito mais amigas do que inimigas. Mas é claro que pra isso, você precisa entender como utilizar de um jeito interessante pro seu projeto.

No meu caso, acabava usando o trecho throw new Exception() pra literalmente qualquer coisa e me perdia facilmente na codebase, por conta de uma Exception genérica espalhada no meio de tantas outras. No início não tinha problema, eu ainda não trabalhava com time que tinha observabilidade, então tá tudo certo.

Passado o tempo, entrei em mais empresas FODAS e me deparei com excelentes implementações de Exceptions, principalmente o Factory Pattern. Esse método me deixou maravilhado em como as coisas podem ser simples e elegantes, mesmo quando se trata de erros.

E hoje vou mostrar pra vocês como criar um certo gosto em escrever exceções elegantes pra não encher seu código com 2km de mensagem de erro dentro da regra de negócio.

2. O que gostariamos de EVITAR

Vamos começar dando um pouco de contexto para esse tutorial: imagine que você tá desenvolvendo um sistema de RPG e nele você precisa criar um inventário simples pro seu personagem.

src
├── Item
│   └── Item.php
└── Player
    ├── Inventory.php
    └── Player.php

Dentro desse contexto, imagine que você está tentando equipar um item no seu personagem. Porém, é lógico que nós vamos colocar algumas regras de validação com suas devidas Exceptions.

namespace DanielHe4rt\Player;

use DanielHe4rt\Item\Item;

class Player {

    public function __construct(
        public string $username,
        public int $level,
        protected Inventory $inventory,
    ) {

    }

    public function equipItem(Item $item): void
    {

        if ($this->inventory->hasItem($item)) {
            throw new \Exception(
                'Você não possui o item "' . $item->name . '". '
            );
        }

        if ($item->minLevel > $this->level) {
            throw new \Exception(
                'Você não pode equipar o item ' . $item->name . 'pois o nível minimo é ' . $item->minLevel 
            );
        }

        $this->setupItem($item);
    }


    private function setupItem(Item $item): void 
    {
        // faça coisas iradas
    }
}

Vimos que existem duas regras de validação que jogam exceções diferentes pro nosso cliente. E pasmem: isso funciona (num cenário que o código tá completinho) e cumpre o papel de validação... MASSSSS, depois que eu aprendi que em testes de emprego o que é visto é a QUALIDADE DA ENTREGA e não a agilidade que foi criado, meu mundo deu uma leve mudada para entender como transformar coisas que parecem "estranhas e feias" em coisas "simples e elegantes".

Nesse caso, eu gostaria muito de evitar duas coisas:

Exceptions genéricas;
Exceptions que tomam conta de locais para regra de negócio.

Não entenda errado, as exceptions vão continuar onde elas estão, porém vamos melhorar a legibilidade do código.

3. Refatoração 1 : Criando Exceptions

src
├── Item
│   └── Item.php
└── Player
    ├── Exceptions
    │   ├── PlayerException.php
    │   └── PlayerInventoryException.php
    ├── Inventory.php
    └── Player.php

Beleza, agora passamos para parte que criamos nossa primeira Exception "customizada", onde só estendemos a Exception base para uma nova classe. Não é nada de outro mundo, mas já melhora nossa legibilidade e entendimento do código em alguns vários pontos.

namespace DanielHe4rt\Player; 

class PlayerException extends \Exception
{}

class PlayerInventoryException extends \Exception
{}

E faremos uma refatoração simples na nossa função equipItem(), reposicionando as exceptions padrões pela nova exception que criamos.


namespace DanielHe4rt\Player;

use DanielHe4rt\Item\Item;
use DanielHe4rt\Player\PlayerException;
use DanielHe4rt\Player\PlayerInventoryException;

class Player {

    public function __construct(
        public string $username,
        public int $level,
        protected Inventory $inventory,
    ) {

    }

    public function equipItem(Item $item): void
    {
        if (!$this->inventory->hasItem($item)) {
            throw new PlayerInventoryException(
                'Você não possui o item "' . $item->name . '". '
            );
        }

        if ($item->minLevel > $this->level) {
            throw new PlayerException(
                'Você não pode equipar o item ' . $item->name . 'pois o nível minimo é ' . $item->minLevel 
            );
        }

        $this->setupItem($item);
    }


    private function setupItem(Item $item): void 
    {
        // faça coisas iradas
    }
}

Com as novas Exceptions, agora sabemos exatamente do que se trata e principalmente onde buscar na nossa codebase quando essa Exception estourar. É literalmente um CTRL + ALT + F e pesquisar o nome "PlayerInventoryException". Facilita sua vida, a vida do DevOps que vai meter isso num NewRelic/DataDog da vida e assim seguimos.

Porém algo ainda me incomoda muito... Por quê essas mensagens gigantes estão no meio da regra de negócio? Misturar pt-br com en desse jeito é triste d+ pra mim desculpa amigos!! Vamos aprender um jeito de por isso debaixo dos panos, porém antes precisamos passar num tópico de Design Pattern chamado Factory!

4. Design Patterns: Factory Pattern

Se você já ouviu falar de Design Patterns, provavelmente já entende um pouco sobre o que isso resolve. Mas caso não, eu te explico!

"Design Patterns são soluções genéricas para problemas genéricos." - Alguém por ai

Nessa ideia de problemas genéricos, uma galera se reuniu e começou a criar alguns principios de Design de Software pra você resolver problemas do dia a dia com uma certa agilidade. Os Design Patterns são divididos em três tipos:

Padrões Comportamentais;
Padrões Criacionais;
Padrões Estruturais.

e você pode ler mais sobre eles no site https:/refactoring.guru e eu recomendo MUITO pra qualquer pessoa desenvolvedora explorar essa documentação e se auto desenvolver. Ok, mas vamos focar nele, o tal do Criacional de Fábrica (ou Factory Method).

A ideia desse padrão é você criar objetos sem ter que instaciar mil coisas em classes diferentes, você literalmente fabricar alguma instância de algo e só receber numa chamada simples de alguma função. No mundo da programação existem centenas de milhões de chamadas como Models::make(), Exception::create(), ApiQualquer::factory() pra você não ter que acessar o método construtor de uma respectiva classe.

Dando o exemplo de um Client de API, onde deixamos o construtor modular pra caso precisemos trocar a chave e segredo PORÉM ainda damos a possibilidade de uma chamada rápida fabricando o objeto final:


class GithubClient {

    public function __construct(string $clientId, string $clientSecret) 
    {
        $this->client = new Client([
            'clientId' => $clientId,
            'clientSecret' => $clientSecret,
        ]);
    }

    public static function make(): self
    {
        return new self(
            env('github.client_id'),
            env('github.client_secret'),
        );
    }

    public function getUserByUsername(string $username = 'danielhe4rt'): array 
    {
        // faça uma chamada pro github..
    }
}

// Chamando sem fabricar o objeto

$client = (new GithubClient('client-id-foda', 'client-secret-foda'))
    ->getUserByUsername('danielhe4rt');

// Chamando usando o Factory 

$client = GithubClient::make()
    ->getUserByUsername('danielhe4rt');

Nós fizemos uma chamada estática fabricando todos os parâmetros de um jeito sucinto. Esse "make/factory" ou o que você quiser chamar, pode ser um método bem extenso dependendo do que você for injetar mas isso não chega a ser problema.

Mas de qualquer forma, vimos que a legibilidade usando o Factory Pattern foi melhorada, claro que você pode colocar melhores nomes pras funções mas na base é isso. Agora voltemos para nossas exceptions!

5. Refatoração 2: Refinando as Exceptions

Show, aprendemos um pouquinho sobre o factory, agora vamos aplicar.

Criaremos um método de factory para nossa exception que faça sentido com o contexto do que tá acontecendo. Pois é, nada de usar "make" ou "create" nesses momentos. Exception precisam contar minimamente uma história pro usuário ou pro desenvolvedor do quê tá acontecendo e vamos focar nisso.

Depois de uma leve refatoração na nossa PlayerInventoryException, temos o resultado de:

class PlayerInventoryException extends \Exception 
{
    public static function itemNotFound(string $itemName): self
    {
        $message = sprintf('Você não possui o item "%s".', $itemName);
        return new self(
            message: $message,
            code: 403 // Forbidden
        );
    }
}

E após chamarmos essa factory em nosso código, podemos perceber uma melhora de leitura e mantenibilidade já que isolamos as informações da Exception dentro da mesma.

public function equipItem(Item $item): void
{

    if (!$this->inventory->hasItem($item)) {
        throw PlayerInventoryException::itemNotFound($item->name);
    }

    if ($item->minLevel > $this->level) {
        throw new PlayerException(
            'Você não pode equipar o item ' . $item->name . 'pois o nível minimo é ' . $item->minLevel 
        );
    }

    $this->setupItem($item);
}

Agora refatorando a próxima, temos a mesma ideia de trocar a PlayerException.

class PlayerException extends \Exception 
{
    public static function lowLevelForThisEquipment(string $itemName, int $itemLevel): self
    {

        $message = sprintf(
            'Você não pode equipar o item %s pois o nível minimo é %s.',
            $itemName,
            $itemLevel
        );

        return new self(
            message: $message,
            code: 403 // Forbidden
        );
    }
}

e agora nossa equipItem() tá ó, uma maravilha!

public function equipItem(Item $item): void
{
    if (!$this->inventory->hasItem($item)) {
        throw PlayerInventoryException::itemNotFound($item->name);
    }

    if ($item->minLevel > $this->level) {
        throw PlayerException::lowLevelForThisEquipment($item->name, $item->minLevel);
    }

    $this->setupItem($item);
}

Tá uma maravilha? Tá. Mas ainda tem algo me incomodando... Por quê passar os tipos primitivos sendo que essas exceptions estão se "comunicando" com classes?

Ficaria bem mais limpo se passarmos a referência do objeto inteiro pra Exception e lá dentro ela resolve o que precisa usar. Afinal, vai que precisamos de mais algo num futuro e não custa nada já deixar bonitinho, né?

namespace DanielHe4rt\Player;

use DanielHe4rt\Item\Item;

class PlayerException extends \Exception 
{
    public static function lowLevelForThisEquipment(Item $item): self
    {

        $message = sprintf(
            'Você não pode equipar o item %s pois o nível minimo é %s.',
            $item->name,
            $item->minLevel
        );

        return new self(
            message: $message,
            code: 403 // Forbidden
        );
    }
}

class PlayerInventoryException extends \Exception 
{
    public static function itemNotFound(Item $item): self
    {

        $message = sprintf('Você não possui o item "%s".', $item);

        return new self(
            message: $message,
            code: 403 // Forbidden
        );
    }
}

E o resultado final do nosso método fica só o charme, tendo exceptions encapsuladas e ainda vai te gerar ótimos feedbacks na sua entrevista de emprego.

namespace DanielHe4rt\Player;

use DanielHe4rt\Item\Item;
use DanielHe4rt\Player\PlayerException;
use DanielHe4rt\Player\PlayerInventoryException;

class Player {

    public function __construct(
        public string $username,
        public int $level,
        protected Inventory $inventory,
    ) {

    }

    public function equipItem(Item $item): void
    {
        if (!$this->inventory->hasItem($item)) {
            throw PlayerInventoryException::itemNotFound($item);
        }

        if ($item->minLevel > $this->level) {
            throw PlayerException::lowLevelForThisEquipment($item);
        }

        $this->setupItem($item);
    }


    private function setupItem(Item $item): void 
    {
        // faça coisas iradas
    }
}

6. Conclusão

Exceptions são de longe uma das coisas mais "chatas" de se lidar. Afinal ninguém quer erro estourando na tela do cliente, mas no geral elas só precisam ter uma boa escrita e adicionar um pouquinho de charme com chamadas estáticas e PLAU tu ganha um elogio e ponto positivo na entrevista de emprego.

Espero que vocês tenham curtido o conteúdo e não esqueça de me seguir nas redes sociais!

Referência: Formatting Exception Messages

Breaking Terraform files into composable layers

Lucas F. da Costa — Thu, 14 Sep 2023 23:20:10 +0000

Terraform allows you to spin up cloud infrastructure using a single command. Let's say you're trying to run Elasticsearch and Kibana within a Kubernetes cluster, for example.

For that, you could write a few .tf files and run terraform apply to provision a Kubernetes cluster and deploy a few pods to it.

Now, assume you want other instances of the Elastic stack that you can use for demos. In that case, you'll have to set up brand new Terraform workspaces and run terraform apply multiple times.

The problem with this approach is that it will cause you to replicate your entire infrastructure every time. Consequently, you'll have multiple Kubernetes clusters. Each cluster takes at least 15 minutes to spin up and costs $72 a month on AWS.

A much better alternative would be to reuse a single Kubernetes cluster and spin up multiple environments on top of it. Thus, you'd pay for a single cluster, and you don't have to wait for a brand new cluster every time you spawn a new environment.

That's why Layerform exists. Layerform allows engineers to break their Terraform files into composable layers. That way, teams can have a shared base layer for their Kubernetes cluster and multiple top layers with Elasticsearch, Kibana, and even other serverless components they need, like Lambdas, SQS queues, or load balancers.

In this post, I'll explain how layers work, how to break your Terraform files into composable layers and demonstrate a few use cases that layers enable. Those use cases include creating production-like development environments and setting up pull request preview links for any type of application.

As a note, Terraform workspaces are quite laborious to use. The official documentation even contains a warning about using them.
Important: Workspaces are not appropriate for system decomposition or deployments requiring separate credentials and access controls.

How layers work

In Layerform, Terraform files are divided into layers. Each layer definition specifies the files that belong to it and a list of dependencies.

Let's say you're trying to run Elasticsearch and Kibana within an EKS instance (AWS-managed k8s).

For that, you'd have two layers, one for eks, and another for the elastic_stack.

{
    "layers": [
        {
            "name": "eks",
            "files": ["layers/eks.tf", "layers/eks/**"]
        },
        {
            "name": "elastic_stack",
            "files": ["layers/elastic_stack.tf", "layers/elastic_stack/**"],
            "dependencies": ["eks"]
        }
    ]
}

In the eks layer definition, you specify which files belong to that layer. Given that eks does not depend on any other infrastructure, it won't list any other layers as dependencies. On the other hand, the elastic_stack layer's files depend on eks. Consequently, it will include eks as a dependency.

After defining layers this way, you can spin up an EKS cluster independently by running layerform spawn eks default.

Then, each engineer can create their own instances of the elastic_stack and reuse the same cluster. For that, they'd all run layerform spawn elastic_stack <name>, and each of these layers would look for an underlying eks layer with ID default.

➜ layerform list instances
INSTANCE NAME                LAYER NAME    DEPENDENCIES
default                      eks
first                        elastic_stack  eks=default
second                       elastic_stack  eks=default

If someone needs a new cluster, they can recreate the whole stack by passing the --base flag, as in layerform spawn elastic_stack third --base eks=another_eks.

➜ layerform list instances
INSTANCE NAME                LAYER NAME    DEPENDENCIES
default                      eks
another_eks                  eks
first                        elastic_stack  eks=default
second                       elastic_stack  eks=default
third                        elastic_stack  eks=another_eks

When done with their layers, engineers can kill their layer instances without damaging someone else's work.

In a way, Layerform's layers are similar to container layers. Some people refer to them as "Kustomize for Terraform."

Using layers to create development environments

For most teams, "staging" is a bottleneck. Usually, companies have many engineers, but there's only a single "staging" environment for everyone to use. Consequently, developers wanting to test changes in a production-like environment must queue.

Additionally, when systems are large or depend on serverless components, engineers cannot reliably run all their software on their machines. Therefore, they all point to the same staging environment and step on each others' toes.

Layers help teams solve this problem by enabling each engineer to spin up their own environment and share core pieces of infrastructure, as shown earlier.

Layerform also provides developers valuable features to develop applications locally while pointing them to their own "staging" environment's back-end.

Assume you cannot run Elasticsearch locally because the JVM needs too much memory, for example. In that case, you could use layerform output to get the address of your remote Elasticsearch instance.

➜ layerform output elastic_stack first

{
  "cluster_name": {
    "sensitive": false,
    "type": "string",
    "value": "demo-eks-post-example"
  },
  "elasticsearch_url": {
    "sensitive": false,
    "type": "string",
    "value": "https://elasticsearch-post-example.environment.ergomake.link"
  }
}

You could use that URL in your Kibana configuration file (config.yml). That way, you could point your local Kibana to the remote Elasticsearch as you develop.

elasticsearch.hosts:
    ["https://elasticsearch-post-example.environment.ergomake.link"]

In case you had multiple outputs you need to interpolate in your configuration file, as many applications have, you could even write a template file and tell Layerform to interpolate it for you.

Take the following template file for Kibana's config.yml, for example.

elasticsearch.hosts: ["{{elasticsearch_url.value}}"]

To render that file and replace {{ elasticsearch_url.value }} with the actual values for your particular layer, you could use the --template flag to output the rendered file to stdout.

➜ layerform output elastic_stack first --template config/kibana-template.yml

elasticsearch.hosts: ['http://elastic-stack-xehl-es.environment.ergomake.link']

Engineers could then pipe the rendered file to an actual config.yml and use it without knowing anything about layers or manually entering values.

➜ layerform output elastic_stack first --template config/kibana-template.yml > config.yml

After that, yarn start would cause Kibana to read config.yml and point to the remote Elasticsearch.

A note on collaborating with layers

Similarly to Terraform, Layerform may use a remote back-end to store states and layer definitions.

Once an engineer creates a layer instance, Layerform syncs it with a remote state file in S3. Then, when someone else uses layerform list instances, Layerform will fetch states from the remote back-end and list an up-to-date list of instances.

Assume engineer A spun up layer first. If engineer B wants to collaborate with engineer A, they will be able to see first in the list of layers because the list is stored remotely.

# Ran by engineer B
➜ layerform list instances

INSTANCE NAME                LAYER NAME     DEPENDENCIES
default                      eks
first                        elastic_stack  eks=default

Then, engineer B can also get the URL of the Elasticsearch instance in layer first by running layerform output.

We're still working on proper locking and collaboration mechanisms to keep states free of race conditions. We welcome pull requests for that in case you're interested in contributing.

Using layers to create pull request previews

Whenever engineers make changes and open a pull request, Vercel spins up their Next.js application and adds a preview link to the PR.

Most developers, designers, and product managers love Vercel's previews. The problem is that these previews do not work for teams with more complex set-ups. For example, you can't get full-stack previews if you have a serverless application or need a Kubernetes cluster.

Today, most teams end up building these preview environments in-house, using a bunch of ad-hoc scripts.

Layerform helps teams solve this problem by allowing them to create a separate preview layer. Then, engineers can call the Layerform CLI from their CI and spin up only the infrastructure they need.

Since Layerform uses Terraform files, it can spin up all types of infrastructure for these previews, including Kubernetes resources, Lambdas, SQS instances, and S3 buckets.

In the case of the Elastic stack, for example, engineers could create a GitHub action to layerform spawn only the Elastic stack layer on top of a shared preview cluster, making previews much less expensive.

name: Preview

on:
    pull_request:

jobs:
    preview:
        runs-on: ubuntu-latest

        steps:
            # + Checkout code, install deps, etc...
            - name: Install Layerform
              run: go install github.com/ergomake/layerform@main

            # Configure remote state — we'll improve this
            - name: Create Layerform config file
              run: |
                  mkdir -p ~/.layerform
                  echo "currentContext: demo" > ~/.layerform/config
                  echo "contexts:" >> ~/.layerform/config
                  echo "  demo:" >> ~/.layerform/config
                  echo "    type: s3" >> ~/.layerform/config
                  echo "    bucket: layerform-post-demo" >> ~/.layerform/config
                  echo "    region: us-west-1" >> ~/.layerform/config

            # Actually spawn the preview layer
            - id: layerform
              name: Spawn Elasticstack using Layerform
              run: |
                  layerform spawn elastic_stack ${{ github.event.pull_request.head.ref }}
              env:
                  AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
                  AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

The workflow above will use the pull request's branch name as the layer instance's name.

Just like any other layer instance, it will appear when running layerform list, so you can connect to it from your terminal too, if you want.

Finally, once the spawn is done, you can write some code to call layerform output and add a comment with a preview link to the pull request.

# ...

# Get Kibana's URL from layerform output using jq
- id: layerform
  name: Spawn Elasticstack using Layerform
  run: |
      layerform spawn elastic_stack ${{ github.event.pull_request.head.ref }}
      kibana=$(layerform output elastic_stack ${{ github.event.pull_request.head.ref }} | jq -r .kibana_url.value)
      echo "kibana=$kibana" >> "$GITHUB_OUTPUT"
  env:
      AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
      AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}

# Add a comment to the pull request
- uses: actions/github-script@v6
  with:
      script: |
          github.rest.issues.createComment({
            issue_number: context.issue.number,
            owner: context.repo.owner,
            repo: context.repo.repo,
            body: '${{ steps.layerform.outputs.kibana }}'
          })

After that change, you'll see a preview link pointing to actual production-like infrastructure in every PR you open.

To destroy these layer instances, you should create a second workflow that's triggered when someone closes or merges a PR. That workflow should call layerform kill and pass it the layer's name, which, in this case, is the same as the branch's.

name: Destroy previews when PRs are closed

on:
    pull_request:
        types: [closed]

jobs:
    kill_preview:
        runs-on: ubuntu-latest
        steps:
            # + Checkout code, install deps, etc...
            - name: Install Layerform
              run: go install github.com/ergomake/layerform@main

            - name: Kill preview
              run: layerform kill elastic_stack ${{ github.event.pull_request.head.ref }}

Extra implementation notes

In these examples, I assume that users have deployed an nginx-ingress-controller to their cluster through the eks layer. This controller is responsible for creating an nlb and exposing Elasticsearch and Kibana to the internet through their ingresses.

In any case, many developers would probably want to keep their development environments within a VPN, which is also possible because Layerform provisions all the infrastructure in your cloud using plain Terraform files.

When it comes to deploying the actual pods to your cluster, you can use whatever you want. When I tested the examples myself, I specified raw Kubernetes resources through the kubernetes provider. Still, you could use Helm charts with the Helm provider. The only requirement for using layers is that your infra is in a Terraform file, not ad-hoc scripts.

Finally, another interesting detail is that engineers must provide layer definitions to the remote back-end with layerform configure before anyone can spawn instances.

If you've found this idea intriguing, please consider giving us a star on GitHub.

DEV Community: He4rt Developers

O que uma usina nuclear tem a ver com o seu processo de QA?

O que aconteceu em Chernobyl?

E o que isso tem a ver com software?

O maior problema: risco tratado de forma rasa

Ouça sua equipe

Analise antes de agir

Conclusão

De front-end para UX, e de volta ao código: o que significa ser Design Engineer em 2026

Minha trajetória: 5 anos de front-end, 5 anos de UX

O que é design engineer em 2026?

Como front-end e UX mudam sua forma de ver produto

Por que estou voltando ao código agora

Como estou usando IA no processo de aprendizado

Design Engineer não é um cargo. É uma forma de pensar

O que vem por aí: UX data-driven e componentes React

Você também está nesse meio-termo entre UX e código?

Construí um gerador de playlists no Spotify com Claude

TL;DR

Índice

A Ideia

A Stack

O Problema de Trabalhar com OAuth Localmente

O Spotify não aceita localhost

O NextRequest normaliza URLs pra localhost

Dois momentos onde o redirect URI importa

A solução: Auth() direto com Request nativo

Bônus: problema de domínio do cookie PKCE

Endpoints Deprecated do Spotify

Spotify em Produção

Fazendo o Claude Obedecer

One-shot prompting

Extração de JSON como fallback

Prompt Engineering Anti-Alucinação

O system prompt atual completo

Melhor resolução de busca no Spotify

Modo Related Artists

Construindo o Perfil Musical

Streaming com SSE

O Que Aprendi

Teste Você Mesmo

Engenharia de Prompt: Por Que a Forma Como Você Pergunta Muda Tudo(Um guia introdutório)

Prefácio

Antes de tudo, para lembrar, o que é uma LLM mesmo?

Fazendo Perguntas

Mas afinal, como perguntar de forma certa?

1 - Evite a Ambiguidade

2 - Delimite o Escopo

3 - Forneça Contexto Relevante

Considerações Finais

Do commit ao deploy: CI/CD de uma API na AWS usando GitHub Actions, ECS e Terraform

Sumário

Introdução

Pré-requisitos

Visão Geral da Arquitetura

Configurando o IAM para o Terraform

Criando um usuário IAM para o Terraform

Configurando as credenciais localmente

Infraestrutura como Código com Terraform

Recursos Provisionados

IAM Role para Tarefas ECS

Task Definition (Fargate)

ECS Service

OIDC: Autenticação Sem Credenciais Estáticas

Dockerfile Multi-Stage

Pipeline de CI

O que acontece nesta pipeline:

Protegendo a Branch Main

Configurando as Secrets no GitHub

Pipeline de CD

O que acontece nesta pipeline:

Acessando a Aplicação após o Deploy

Obtendo o IP público pelo Console AWS

Obtendo o IP público via CLI

Segurança: OIDC em Detalhe

Fluxo Completo: Do Commit ao Deploy

Considerações Finais

Criei uma pipeline de planejamento no OpenCode e olha no que deu

Índice

Como eu estava usando o OpenCode

O Spotify não aceita `localhost`

O `NextRequest` normaliza URLs pra `localhost`

A solução: `Auth()` direto com `Request` nativo