Frontend Academy · Aula

API WebSocket: abrir, mensagem, fechar e erro

Criar uma ligação WebSocket, enviar e receber mensagens no manipulador do evento de mensagem e tratar erros de ligação e encerramentos limpos.

API WebSocket: abrir, mensagem, fechar e erro é uma aula grátis de Frontend Academy no CoddyKit. Esta é a aula 1 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de Frontend Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de Frontend Academy inclui 4 aulas no total.

Por que usar WebSockets?

HTTP segue o modelo de solicitação e resposta. Em aplicações em tempo real (chats, jogos multijogador e atualizações ao vivo), é necessária uma comunicação bidirecional persistente. WebSockets fornecem uma única conexão TCP que permanece aberta e permite que ambos os lados enviem mensagens a qualquer momento.

Criando um WebSocket

Crie um WebSocket com uma URL ws:// ou wss://. O navegador gerencia o handshake de atualização.

const ws = new WebSocket('wss://api.example.com/realtime');

// Always use wss:// (secure) in production

Os quatro eventos

WebSocket tem quatro tipos de evento: open (conectado), message (dados recebidos), close (conexão encerrada) e error (problema).

ws.addEventListener('open', () => {
  console.log('Connected');
  ws.send(JSON.stringify({ type: 'subscribe', channel: 'updates' }));
});

ws.addEventListener('message', (event) => {
  const data = JSON.parse(event.data);
  console.log('Received:', data);
});

ws.addEventListener('close', (event) => {
  console.log('Closed:', event.code, event.reason);
});

ws.addEventListener('error', (event) => {
  console.error('Error:', event);
});

Enviando mensagens

Utilize ws.send(). Ele aceita strings, ArrayBuffers, Blobs ou ArrayBufferView. Para dados estruturados, execute JSON.stringify primeiro.

ws.send('hello');
ws.send(JSON.stringify({ type: 'chat', text: 'Hi' }));

// Binary:
const buffer = new ArrayBuffer(8);
ws.send(buffer);

Recebendo mensagens

Inspecione event.data: o tipo corresponde ao que o servidor enviou. Use JSON.parse para cargas úteis em forma de objeto.

ws.addEventListener('message', (event) => {
  // typeof event.data: string | ArrayBuffer | Blob
  if (typeof event.data === 'string') {
    const msg = JSON.parse(event.data);
    handleMessage(msg);
  }
});

Estado da conexão (readyState)

Verifique ws.readyState: CONNECTING=0, OPEN=1, CLOSING=2 e CLOSED=3. Não envie nada antes de OPEN.

if (ws.readyState === WebSocket.OPEN) {
  ws.send(message);
} else {
  console.warn('Not connected yet');
}

Encerrando corretamente

Chame ws.close(code, reason). Códigos de encerramento padrão: 1000 (normal), 1001 (desconexão), 1008 (violação de política) e 1011 (erro do servidor).

ws.close(1000, 'User logged out');

Estratégia de reconexão

WebSockets são desconectados quando a rede muda, o servidor é reiniciado e em outras situações. Implemente a reconexão com espera exponencial.

let reconnectDelay = 1000;

function connect() {
  const ws = new WebSocket('wss://api/realtime');
  ws.addEventListener('open', () => { reconnectDelay = 1000; });
  ws.addEventListener('close', () => {
    setTimeout(connect, reconnectDelay);
    reconnectDelay = Math.min(reconnectDelay * 2, 30000);
  });
  return ws;
}

Sinais de atividade / manutenção da conexão

WebSockets ociosos são encerrados por proxies e balanceadores de carga após aproximadamente 60 s. Envie um ping a cada 25 a 30 segundos para manter a conexão ativa.

let pingInterval;
ws.addEventListener('open', () => {
  pingInterval = setInterval(() => {
    if (ws.readyState === WebSocket.OPEN) {
      ws.send(JSON.stringify({ type: 'ping' }));
    }
  }, 25000);
});
ws.addEventListener('close', () => clearInterval(pingInterval));

Autenticação

WebSockets não oferecem suporte a cabeçalhos personalizados. Opções: 1) autentique por meio de um token na string de consulta (?token=jwt) da URL WS; 2) envie uma mensagem de autenticação após open; 3) use um cookie (funciona automaticamente na mesma origem).

// Query string:
const ws = new WebSocket(`wss://api/realtime?token=${jwt}`);

// Auth message:
ws.addEventListener('open', () => {
  ws.send(JSON.stringify({ type: 'auth', token: jwt }));
});

Hook do React para WebSockets

Encapsule o ciclo de vida de WS em um hook personalizado para evitar vazamentos de conexões.

function useWebSocket(url) {
  const [messages, setMessages] = useState([]);
  const wsRef = useRef(null);

  useEffect(() => {
    const ws = new WebSocket(url);
    wsRef.current = ws;
    ws.addEventListener('message', (e) => {
      setMessages(m => [...m, JSON.parse(e.data)]);
    });
    return () => ws.close();
  }, [url]);

  return { messages, send: (msg) => wsRef.current?.send(JSON.stringify(msg)) };
}

WebSocket vs HTTP/2 vs SSE

WebSocket: duplex completo, ambos os lados enviam dados. Envio pelo servidor do HTTP/2: obsoleto. Server-Sent Events: somente do servidor para o cliente, mais simples e com reconexão automática. Escolha WS quando o cliente também precisar enviar dados (como em um chat); use SSE para notificações unidirecionais.

Verificação rápida

Qual é o código de encerramento padrão de WebSocket para um encerramento normal e intencional (por exemplo, quando o usuário sai da conta)?

Recapitulação: API de WebSocket

new WebSocket('wss://...') abre a conexão. Quatro eventos: open, message, close e error. send() aceita string, ArrayBuffer ou Blob; use JSON.stringify para objetos. Verifique readyState antes de enviar. Use close(1000) para um encerramento correto. Reconecte usando espera exponencial. Envie um sinal de atividade a cada 25 s para manter a conexão ativa. Autentique pela string de consulta ou por uma mensagem de autenticação. Para o React, envolva tudo em um hook.

Perguntas Frequentes

A aula “API WebSocket: abrir, mensagem, fechar e erro” é grátis?

Sim — o texto completo de “API WebSocket: abrir, mensagem, fechar e erro” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de Frontend Academy, atualize para CoddyKit PRO. O curso de Frontend Academy inclui 4 aulas no total.

O que vou aprender em “API WebSocket: abrir, mensagem, fechar e erro”?

Criar uma ligação WebSocket, enviar e receber mensagens no manipulador do evento de mensagem e tratar erros de ligação e encerramentos limpos. Você pratica Frontend Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.

Preciso ter experiência prévia para começar Frontend Academy?

Nenhuma experiência prévia é necessária. Frontend Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 1 de 4.

Quanto tempo leva a aula “API WebSocket: abrir, mensagem, fechar e erro”?

A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.

Posso escrever e executar código nesta aula de Frontend Academy?

Sim. Cada aula de Frontend Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.

Todas as aulas deste curso

API WebSocket: abrir, mensagem, fechar e erro
Integração do cliente Socket.io
Eventos enviados pelo servidor para transmissão unidirecional
Padrões de interface em tempo real

← Voltar para Frontend Academy