Introdução
Uma feature flag é uma configuração que ativa ou desativa uma funcionalidade sem alterar o código da aplicação. Imagine que você está preparando um novo banner de anúncio: você quer testá-lo no ambiente de prática, mantendo-o desativado na versão pública. O Workers KV armazena pequenos valores sob nomes chamados chaves. Um Worker pode ler uma chave como banner:new quando precisa decidir qual resposta enviar. Isso é útil para configurações que são lidas com frequência e alteradas ocasionalmente.
Antes de começar este curso, conclua Connect LabEx to Your Cloudflare Account. Esse laboratório explica o terminal da VM do LabEx, a autorização do dispositivo, a confirmação da conta e o account_id. Se você entrou diretamente neste curso, faça esse laboratório primeiro. Você também deve saber escrever um pequeno Worker em JavaScript e implantá-lo com o Wrangler, conforme ensinado no curso para iniciantes de Workers. Um Worker executa seu código de tratamento de requisições na Cloudflare sem exigir que você mantenha um servidor.
Aqui, você criará um namespace, um contêiner nomeado que mantém uma coleção de chaves separada das demais. Você o conectará a um Worker por meio de um binding, o nome configurado que seu código usa para acessar esse recurso. Você praticará operações locais e na nuvem, publicará um endpoint de banner somente leitura e excluirá os recursos temporários.
Use sua própria conta de aprendizado. Esta VM nova precisa de um login próprio com permissões para Workers e KV. O exercício usa um Worker, um namespace e alguns valores sintéticos dentro dos limites gratuitos do KV; não é necessário ter um domínio comprado nem fazer upgrade para um plano pago neste exercício pequeno. O uso existente da conta ainda conta para os limites. O endpoint público não contém informações privadas.
A configuração instala o Node.js 22.22.0 e o Wrangler 4.131.1 local do projeto em /home/labex/project/feature-flags. Ela fixa as versões das dependências diretas e executa npm install; você não precisa instalar as ferramentas novamente. Mantenha a VM aberta até que a exclusão dos recursos na nuvem e o logout sejam verificados.
Conectar um namespace dedicado para flags
Nesta etapa, você dará nomes próprios aos recursos deste laboratório e conectará um namespace da nuvem ao seu projeto. Manter um namespace separado evita que as chaves de prática se misturem com as de uma aplicação existente.
Entre no projeto preparado:
cd /home/labex/project/feature-flags
Gere um nome exclusivo uma única vez. openssl rand -hex 6 imprime um sufixo aleatório; $(...) insere esse sufixo no nome. A variável do shell mantém esse nome disponível para os comandos seguintes neste terminal.
WORKER_NAME="labex-flags-$(openssl rand -hex 6)"
printf '%s\n' "$WORKER_NAME"
Autorize esta VM. Além de ler a identidade da sua conta, Workers Scripts Write permite implantar e excluir recursos, e Workers KV Write permite gerenciar o namespace e as chaves deste laboratório.
npx wrangler login --device --browser=false --scopes account:read user:read workers_scripts:write workers_kv:write
Abra no navegador o link do dispositivo exibido, digite o código atual, revise as permissões solicitadas e a conta de aprendizado e autorize o Wrangler. O acesso em segundo plano também pode aparecer na página de consentimento. Volte ao terminal e aguarde a conclusão do login.
Expanda Developer Platform na página de consentimento e compare as permissões solicitadas com este exemplo. As duas permissões de gravação são necessárias para este laboratório; elas abrangem o gerenciamento de recursos, não apenas a leitura de uma flag.
npx wrangler whoami --json
Confirme loggedIn: true e o name da conta de aprendizado, mesmo que apenas uma conta esteja listada. Copie o id dessa conta. Salve-o na configuração abaixo, substituindo YOUR_ACCOUNT_ID antes de executar o comando. O here-document do cat grava em um arquivo tudo o que estiver entre as duas linhas JSON; > substitui o arquivo. O delimitador sem aspas permite que o shell insira $WORKER_NAME.
cat > wrangler.jsonc <<JSON
{
"name": "$WORKER_NAME",
"main": "src/index.js",
"compatibility_date": "2026-07-30",
"account_id": "YOUR_ACCOUNT_ID",
"workers_dev": true
}
JSON
Crie um namespace nessa conta. O título dele compartilha o nome exclusivo do Worker, para que você possa reconhecer os dois mais tarde. --update-config=false deixa a edição do binding visível para você, em vez de alterar o arquivo automaticamente.
npx wrangler kv namespace create "$WORKER_NAME-flags" --update-config=false
A saída inclui o ID do novo namespace. Copie esse ID e substitua YOUR_ACCOUNT_ID e YOUR_NAMESPACE_ID nesta configuração completa. O nome do binding FLAGS foi escolhido para o seu código; o ID identifica o recurso real na Cloudflare.
cat > wrangler.jsonc <<JSON
{
"name": "$WORKER_NAME",
"main": "src/index.js",
"compatibility_date": "2026-07-30",
"account_id": "YOUR_ACCOUNT_ID",
"workers_dev": true,
"kv_namespaces": [
{ "binding": "FLAGS", "id": "YOUR_NAMESPACE_ID" }
]
}
JSON
npx wrangler kv namespace list
Encontre o título do namespace deste laboratório e compare o ID dele com o ID no arquivo. Outros namespaces podem estar presentes; não altere esses namespaces. Essa configuração registra qual conta e qual recurso os comandos posteriores devem usar. Um binding é uma referência a um namespace, não uma cópia dos dados armazenados nele.
Manter as flags locais e remotas separadas
Nesta etapa, você armazenará valores diferentes sob a mesma chave e comprovará que as alterações locais não afetam os dados na nuvem. Local significa o armazenamento dentro desta VM do LabEx. Remoto significa o namespace na sua conta da Cloudflare. O Wrangler usa o binding para identificar o armazenamento; a opção explícita --local ou --remote seleciona onde a operação acontecerá.
Primeiro, mantenha a funcionalidade pública desativada:
npx wrangler kv key put banner:new disabled --binding FLAGS --remote
Ative a mesma funcionalidade no armazenamento local da VM:
npx wrangler kv key put banner:new enabled --binding FLAGS --local
Leia os dois valores. put grava uma chave e get recupera seu valor. Os dois-pontos em banner:new são uma convenção de nomenclatura que agrupa chaves relacionadas; eles não criam um diretório.
Use --text para decodificar o valor armazenado como UTF-8 e exibi-lo em uma linha própria.
npx wrangler kv key get banner:new --binding FLAGS --local --text
Espere enabled.
npx wrangler kv key get banner:new --binding FLAGS --remote --text
Espere disabled. Se você alterar acidentalmente o valor remoto, repita o comando put correspondente com disabled e leia a chave novamente. Não deduza o destino apenas pela pasta do projeto.
Agora pratique a remoção de uma flag aposentada. Estes comandos afetam somente o namespace remoto temporário associado a FLAGS.
npx wrangler kv key put banner:old retired --binding FLAGS --remote
npx wrangler kv key list --binding FLAGS --remote
A lista contém nomes como banner:new e banner:old, e não os valores armazenados. Use get quando precisar de um valor.
npx wrangler kv key delete banner:old --binding FLAGS --remote
npx wrangler kv key list --binding FLAGS --remote
npx wrangler kv key list --binding FLAGS --local
Agora, as duas listas devem conter apenas banner:new. Leia os dois valores novamente se precisar confirmar que eles continuam diferentes. Excluir uma chave remove uma entrada; excluir o namespace posteriormente removerá o contêiner inteiro.
O KV é eventualmente consistente: uma alteração pode levar algum tempo para ficar visível às leituras feitas em outros locais. Um Worker pode temporariamente visualizar um valor anterior, inclusive uma chave que antes não existia. Não substitua repetidamente um valor para forçar sua aparição. Essas flags de exibição inofensivas toleram esse atraso; elas seriam inadequadas para uma decisão imediata de revogação de acesso. Você explorará esse comportamento em um laboratório posterior. Consulte como o KV funciona para conhecer o modelo de armazenamento.
Ler uma flag de um Worker local
Nesta etapa, você fará o comportamento da aplicação depender da configuração armazenada. O Worker lê env.FLAGS, onde env contém os bindings de recursos configurados. get() é assíncrono, portanto await espera o valor antes que você decida o que retornar.
Escreva o handler. O delimitador JS entre aspas preserva o JavaScript exatamente, sem expansão de variáveis pelo shell.
cat > src/index.js <<'JS'
export default {
async fetch(request, env) {
if (new URL(request.url).pathname !== "/banner") {
return new Response("Not found", { status: 404 });
}
const value = await env.FLAGS.get("banner:new");
return Response.json({
feature: "new-banner",
enabled: value === "enabled"
});
}
};
JS
Uma chave ausente retorna null. Comparar especificamente com "enabled" faz com que uma chave ausente ou um valor inesperado mantenha este banner opcional desativado. Esse é um pequeno padrão seguro: a aplicação continua utilizável quando a configuração ainda não foi fornecida. Isso não oculta falhas de conexão, que são diferentes de uma chave ausente.
Inicie o desenvolvimento local. --local executa o Worker nesta VM usando bindings locais. > local.log 2>&1 envia a saída e os erros para o log; & permite que o terminal aceite mais comandos. $! é o ID do processo em segundo plano, salvo aqui para que você possa interromper esse processo mais tarde.
npx wrangler dev --local --ip 0.0.0.0 --port 8080 > local.log 2>&1 &
DEV_PID=$!
cat local.log
Aguarde a mensagem de que a porta 8080 está pronta. Se a inicialização ainda estiver em andamento, leia o log novamente antes de continuar.
curl -i http://127.0.0.1:8080/banner
curl -i mostra os cabeçalhos e o corpo da resposta. Espere HTTP 200, um tipo de conteúdo JSON e:
{"feature":"new-banner","enabled":true}
O valor true veio do armazenamento local do KV. Executar o servidor de desenvolvimento não copiou o valor remoto disabled para a VM. Mantenha o servidor em execução para a próxima comparação.
Implantar e comparar a resposta pública
Nesta etapa, você publicará o mesmo código e verá o Worker ler o namespace na nuvem. A implantação envia o Worker e a configuração dos bindings; ela não envia as entradas locais do KV.
npx wrangler deploy
Leia a saída da implantação. Confirme o nome do Worker, o binding FLAGS e o endereço público workers.dev. Salve o endereço real abaixo, substituindo o exemplo antes de executar o comando. Uma variável do shell evita que você precise digitar novamente uma URL longa.
WORKER_URL="https://YOUR_WORKER.YOUR_SUBDOMAIN.workers.dev"
curl -i "$WORKER_URL/banner"
Espere HTTP 200 e:
{"feature":"new-banner","enabled":false}
A configuração na nuvem é disabled, portanto a resposta pública é false. Se o novo hostname ainda não estiver acessível, aguarde um pouco e tente novamente. Se a resposta refletir um valor antigo, verifique a chave remota uma vez e aguarde a propagação da visibilidade do KV, em vez de regravá-la rapidamente. Um erro de rede não é um teste bem-sucedido.
curl -i http://127.0.0.1:8080/banner
A resposta local continua sendo true. Você tem um handler e dois armazenamentos de dados separados: o desenvolvimento local lê os dados da VM, enquanto o Worker implantado lê o namespace identificado pelo binding.
No Cloudflare Dashboard, selecione a mesma conta de aprendizado e abra Storage & databases → Workers KV. Encontre o namespace cujo nome corresponde ao deste laboratório e examine suas chaves. Confirme que somente banner:new permanece, com o valor remoto disabled. Em seguida, abra Workers & Pages, selecione o Worker deste laboratório e examine a visualização Bindings. Compare o binding FLAGS com o namespace que você acabou de inspecionar. Estes são pontos de verificação somente leitura: o terminal continua sendo o local onde você faz alterações.
O namespace abre em Metrics. Selecione KV Pairs para conferir as entradas reais; os contadores de uso podem ser atualizados depois das gravações. Se o novo Worker não aparecer em Workers & Pages, clique em Refresh. Em Bindings, role até a tabela para comparar o nome do binding com seu namespace.
O nome gerado, o ID do namespace e o subdomínio público serão diferentes dos exemplos. Ver um namespace no Dashboard confirma onde ele está; uma resposta HTTP bem-sucedida confirma que a aplicação consegue usá-lo.
Excluir os recursos temporários na nuvem
Nesta etapa, você removerá os dois recursos enquanto o Wrangler ainda estiver autorizado. Um namespace pode continuar existindo depois do Worker; portanto, excluir apenas a aplicação não limpa os dados.
Interrompa o processo de desenvolvimento local iniciado neste terminal:
kill "$DEV_PID"
Inspecione as referências de recursos salvas antes de excluir qualquer coisa:
cat wrangler.jsonc
Confirme o nome do Worker labex-flags-... e o ID do namespace FLAGS. Exclua o Worker selecionado por esta configuração:
npx wrangler delete
Se for solicitado, verifique se o nome exibido corresponde a este laboratório e confirme com y. Em seguida, exclua somente o namespace referenciado por FLAGS:
npx wrangler kv namespace delete --binding FLAGS
Revise o namespace em qualquer solicitação de confirmação antes de aceitar. Mantenha wrangler.jsonc intacto para que a verificação independente consiga identificar os recursos que devem estar ausentes.
npx wrangler kv namespace list
O namespace deste laboratório deve estar ausente; os namespaces não relacionados devem permanecer. Atualize as listas do Dashboard para confirmar que o Worker e o namespace do laboratório desapareceram. Uma requisição malsucedida ou um login expirado não comprova a exclusão. Execute a verificação desta etapa antes de fazer logout, para que ela possa inspecionar um inventário autorizado.
Encerrar a autorização da VM
Nesta etapa, você desconectará o Wrangler depois que a verificação da limpeza for aprovada. Fazer logout encerra a autorização do Wrangler salva nesta VM; isso não exclui recursos na nuvem nem encerra a sessão do Dashboard no navegador comum.
npx wrangler logout
npx wrangler whoami --json
Confirme que o resultado estruturado informa "loggedIn": false. Este comando não autenticado pode terminar com um status de saída diferente de zero, o que é esperado aqui. Se houver apenas um erro de conexão, sem um estado de autenticação explícito, tente novamente quando a conexão estiver funcionando.
Os arquivos locais restantes e o estado local do KV pertencem a esta VM temporária. Eles são separados dos recursos na nuvem que você já excluiu. Agora você pode concluir o laboratório.
Resumo
Você criou um namespace KV isolado, conectou-o por meio de um binding e usou comandos locais e remotos explícitos para gravar, ler, listar e excluir chaves. Seu Worker leu a mesma chave em armazenamentos separados: o banner local foi ativado, enquanto o banner público permaneceu desativado. Você também usou um padrão seguro para uma flag ausente e aprendeu por que as atualizações do KV não devem ser tratadas como uma chave global com efeito imediato.
Por fim, você verificou a resposta pública, removeu o Worker e o namespace enquanto estava autorizado e fez logout do Wrangler. Em seguida, você usará valores JSON estruturados para disponibilizar preferências de conta não confidenciais.
