Um Guia para Iniciantes sobre Cloudflare Workers

Introdução

Se você está procurando construir aplicações web modernas sem gerenciar servidores, o Cloudflare Workers oferece uma solução atraente que vai muito além de simples funções serverless. Ao contrário de plataformas tradicionais, o Workers agora fornece tudo o que é necessário para aplicações full-stack: bancos de dados SQL através do D1, conexões com PostgreSQL ou MySQL existentes via Hyperdrive, hospedagem de assets estáticos e ampla compatibilidade com Node.js—tudo executando na edge, próximo aos seus usuários.

Este tutorial de Cloudflare Workers cobre os conceitos e ferramentas essenciais que você precisa para começar, desde entender a execução baseada em edge até construir aplicações completas com conectividade moderna de banco de dados e gerenciamento de assets.

O Que São Cloudflare Workers?

Execução Baseada em Edge Explicada

Cloudflare Workers são funções JavaScript, TypeScript, Python ou Rust que executam na rede global de data centers da Cloudflare. Em vez de executar em um único servidor, seu código roda na localização edge mais próxima de cada usuário, tipicamente dentro de 50 milissegundos de qualquer pessoa na Terra.

Este modelo baseado em edge significa que sua aplicação responde mais rapidamente porque as requisições não viajam para um servidor central. A plataforma lida automaticamente com escalabilidade—seja você tendo dez usuários ou dez milhões, o Workers ajusta sem configuração.

Conceitos Fundamentais: Bindings e Environment

Workers usam bindings para conectar seu código aos recursos. Estes não são variáveis de ambiente tradicionais, mas conexões diretas com serviços:

• KV namespaces para armazenamento chave-valor
• D1 databases para operações SQL
• R2 buckets para armazenamento de objetos
• Service bindings para outros Workers
• Hyperdrive connections para bancos de dados externos

Cada binding aparece como uma propriedade no objeto env passado para seu Worker:

export default {
  async fetch(request, env, ctx) {
    // Access D1 database
    const result = await env.DB.prepare('SELECT * FROM users').all()
    return Response.json(result)
  }
}

Opções Modernas de Banco de Dados com Cloudflare D1 Database

D1: SQL Pronto para Produção na Edge

O Cloudflare D1 database traz SQLite para a edge com replicação automática e backups. Ao contrário de bancos de dados serverless tradicionais, o D1 executa nas mesmas localizações que seus Workers, eliminando latência de rede para consultas ao banco de dados.

Criar um banco de dados D1 é simples:

npx wrangler d1 create my-database
npx wrangler d1 execute my-database --file=./schema.sql

Seu Worker acessa o D1 através de bindings, fazendo com que as consultas pareçam locais:

const user = await env.DB.prepare('SELECT * FROM users WHERE id = ?')
  .bind(userId)
  .first()

Conectividade Hyperdrive para Bancos de Dados Existentes

A conectividade Hyperdrive resolve um desafio comum: conectar Workers a bancos de dados PostgreSQL ou MySQL existentes, incluindo aqueles em redes privadas. O Hyperdrive mantém pools de conexão na edge da Cloudflare, reduzindo a sobrecarga de conexão em até 30x.

Configurar o Hyperdrive requer configuração mínima:

npx wrangler hyperdrive create my-postgres \
  --connection-string="postgresql://user:pass@host:5432/db"

Seu Worker então usa bibliotecas de banco de dados familiares com a conexão Hyperdrive:

import { Client } from 'pg'

export default {
  async fetch(request, env) {
    const client = new Client(env.HYPERDRIVE.connectionString)
    await client.connect()
    const result = await client.query('SELECT * FROM products')
    return Response.json(result.rows)
  }
}

Construindo Aplicações Full-Stack

Workers Static Assets e Roteamento

Workers static assets eliminam a necessidade de hospedagem separada. Seu HTML, CSS, JavaScript e imagens são implantados junto com seu código de API. A plataforma serve automaticamente arquivos estáticos com cabeçalhos de cache apropriados e compressão.

O tratamento de assets estáticos requer uma entrada assets no wrangler.toml apontando para seu diretório público.

Estrutura de projeto para um Worker full-stack:

my-app/
├── src/
│   └── index.js        # Worker code
├── public/
│   ├── index.html      # Static assets
│   ├── style.css
│   └── app.js
└── wrangler.toml       # Configuration

O roteamento lida com requisições estáticas e dinâmicas:

export default {
  async fetch(request, env, ctx) {
    const url = new URL(request.url)
    
    if (url.pathname.startsWith('/api/')) {
      // Handle API routes
      return handleAPI(request, env)
    }
    
    // Serve static assets
    return env.ASSETS.fetch(request)
  }
}

Benefícios da Camada de Compatibilidade Node.js

A camada de compatibilidade Node.js permite que milhares de pacotes npm funcionem no Workers. Ao contrário das versões iniciais que suportavam apenas APIs de padrão web, o Workers agora suporta built-ins do Node.js como Buffer, crypto, stream e path.

Habilite a compatibilidade Node.js no seu wrangler.toml:

compatibility_flags = ["nodejs_compat"]

Esta compatibilidade significa que código Node.js existente frequentemente funciona com mudanças mínimas, tornando a migração de servidores tradicionais direta.

Fluxo de Trabalho de Desenvolvimento Local

Configurando Seu Ambiente

Comece com o Wrangler, a ferramenta CLI da Cloudflare:

npm create cloudflare@latest my-app
cd my-app
npm run dev

O Wrangler fornece desenvolvimento com hot-reload e acesso a todos os bindings localmente. Seus bancos de dados D1, KV namespaces e até conexões Hyperdrive funcionam no modo de desenvolvimento.

Testes e Implantação

O servidor de desenvolvimento local imita o comportamento de produção:

# Test with local D1 database
npx wrangler d1 execute DB --local --file=./seed.sql

# Deploy to production
npm run deploy

Recursos Adicionais da Plataforma

Embora este tutorial se concentre em conceitos fundamentais, o Workers oferece capacidades adicionais que vale a pena explorar:

• Queues para processamento de jobs em background
• R2 event notifications para triggers de armazenamento de objetos
• Gradual Deployments para rollouts seguros
• Workers Analytics e logging estruturado para observabilidade

Estes recursos se integram perfeitamente conforme sua aplicação cresce.

Conclusão

O Cloudflare Workers evoluiu de simples funções edge para uma plataforma completa para aplicações web modernas. Com D1 para SQL serverless, Hyperdrive para conectividade com bancos de dados existentes, hospedagem integrada de assets estáticos e compatibilidade abrangente com Node.js, você pode construir aplicações full-stack que executam globalmente com configuração mínima.

Comece com um Worker simples, adicione um banco de dados D1 para persistência de dados e incorpore gradualmente recursos como Hyperdrive ou R2 conforme necessário. A plataforma lida com a complexidade da distribuição global, permitindo que você se concentre em construir sua aplicação.

Perguntas Frequentes

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.