MessagePack no Node.js é uma alternativa binária ao JSON para transportar e armazenar dados com menos bytes, mantendo uma estrutura familiar baseada em mapas, listas, strings, números, booleanos e valores nulos. Em aplicações com alto volume de mensagens, WebSockets, filas, caches ou comunicação entre serviços, essa redução pode diminuir largura de banda, uso de memória e tempo de serialização.
O formato não é uma solução automática para qualquer API. JSON continua excelente para depuração, interoperabilidade e integrações públicas. MessagePack faz mais sentido quando produtor e consumidor são controlados pela mesma equipe, quando o contrato está bem definido e quando métricas mostram que tamanho ou custo de serialização realmente importam.
Neste guia, você aprenderá a instalar uma biblioteca, codificar e decodificar objetos, trabalhar com Buffer, datas, BigInt, extensões, streams, validação, limites de segurança, versionamento e testes.
O que é MessagePack?
MessagePack é um formato de serialização binária que representa estruturas semelhantes ao JSON, mas usa marcadores compactos para tipos e comprimentos. A documentação oficial do MessagePack descreve o formato e suas famílias de tipos.
Um objeto como {"ok":true,"count":3} é convertido em bytes. O consumidor precisa decodificar esses bytes antes de acessar os campos.
Quando usar
- mensagens frequentes em WebSockets;
- eventos em filas e brokers;
- valores compactos em cache;
- protocolos internos entre serviços;
- telemetria com grande volume;
- persistência temporária de objetos.
Para APIs abertas, payloads inspecionados manualmente ou integrações simples, JSON costuma ser mais prático.
Instalação
Uma opção conhecida é @msgpack/msgpack:
npm install @msgpack/msgpackConsulte também o repositório oficial da implementação JavaScript para verificar recursos e compatibilidade.
Codificando um objeto
import { encode } from '@msgpack/msgpack';
const event = {
type: 'order.created',
orderId: 'ord-42',
totalCents: 15990,
createdAt: new Date().toISOString()
};
const bytes = encode(event);
const buffer = Buffer.from(bytes);
console.log(buffer.length);encode retorna Uint8Array. No Node.js, Buffer.from facilita o uso com sockets, arquivos, Redis e clientes de mensageria.
Decodificando
import { decode } from '@msgpack/msgpack';
const value = decode(buffer);
console.log(value);Dados externos devem ser tratados como desconhecidos. Decodificar não substitui validação de esquema.
Valide depois de decodificar
import { z } from 'zod';
const EventSchema = z.object({
type: z.literal('order.created'),
orderId: z.string().min(1),
totalCents: z.number().int().nonnegative(),
createdAt: z.string().datetime()
});
const parsed = EventSchema.parse(decode(buffer));Para um guia de validação, consulte Zod no TypeScript. Outra alternativa baseada em JSON Schema é Ajv no Node.js.
Integração com TypeScript
type OrderCreated = {
type: 'order.created';
orderId: string;
totalCents: number;
createdAt: string;
};
const decoded = decode(buffer) as unknown;
const event = EventSchema.parse(decoded) satisfies OrderCreated;Uma asserção direta, como decode(buffer) as OrderCreated, não valida nada em runtime. Use schema ou guard quando os bytes vierem de rede, cache ou disco.
MessagePack e Buffer
Node.js usa Buffer em várias APIs. O conteúdo binário pode ser enviado diretamente:
socket.write(Buffer.from(encode(event)));Para compreender melhor bytes e buffers, leia Buffer no Node.js.
WebSockets
WebSockets aceitam frames binários. O servidor pode enviar:
client.send(Buffer.from(encode(event)), { binary: true });O cliente precisa conhecer o formato. Defina uma negociação simples, como subprotocolo ou versão no envelope. Veja também WebSocket com Node.js.
Envelope de mensagem
const envelope = {
version: 1,
type: 'order.created',
messageId: crypto.randomUUID(),
occurredAt: Date.now(),
payload: {
orderId: 'ord-42',
totalCents: 15990
}
};O envelope facilita roteamento, idempotência, observabilidade e migração. Não confie apenas no formato binário para definir contrato.
Datas
Uma abordagem portátil é serializar datas como string ISO ou timestamp numérico. Strings ISO são legíveis; timestamps são menores. Documente unidade e timezone.
const data = {
createdAt: Date.now()
};Evite interpretar segundos como milissegundos. Nomear o campo como createdAtMs pode eliminar ambiguidade.
BigInt e inteiros de 64 bits
JavaScript não representa com segurança todos os inteiros de 64 bits usando Number. Dependendo da biblioteca e configuração, BigInt pode ter suporte específico. Para interoperabilidade ampla, IDs grandes podem ser strings:
{ sequence: '9223372036854775807' }Teste o comportamento entre todas as linguagens consumidoras.
Tipos binários
MessagePack representa bytes diretamente, evitando Base64:
const payload = {
checksum: crypto.randomBytes(32),
thumbnail: imageBuffer
};Mesmo assim, imponha limites. Um campo binário sem limite pode esgotar memória.
Extensões
O formato possui extension types para valores definidos pela aplicação, como UUID, Decimal, Date ou classes específicas. Extensões exigem coordenação entre produtores e consumidores.
Use um código de extensão estável e documente o layout dos bytes. Nunca altere o significado de um código já distribuído.
Exemplo conceitual de extensão
const extensionCodec = new ExtensionCodec();
extensionCodec.register({
type: 1,
encode(value) {
if (value instanceof UUIDValue) {
return value.toBytes();
}
return null;
},
decode(data) {
return UUIDValue.fromBytes(data);
}
});Antes de criar extensão, avalie se uma string é suficiente. Tipos customizados aumentam acoplamento.
Streams e mensagens concatenadas
Uma conexão TCP pode entregar mensagens fragmentadas ou concatenadas. Não presuma que cada evento data contém um pacote completo.
Use framing: prefixe cada mensagem com tamanho, use um decoder de múltiplos objetos ou um protocolo que já delimite frames.
// formato conceitual: [4 bytes de tamanho][payload]
const header = Buffer.allocUnsafe(4);
header.writeUInt32BE(payload.length, 0);
const frame = Buffer.concat([header, payload]);Defina tamanho máximo antes de alocar o corpo.
Uso em Redis
await redis.set(
`order:${order.id}`,
Buffer.from(encode(order)),
{ EX: 300 }
);Ao ler, recupere como Buffer conforme o cliente usado. Para conceitos de cache e expiração, consulte Redis com Node.js.
Uso em filas
Em Kafka, NATS ou RabbitMQ, publique bytes e inclua metadados de content type e versão quando o broker permitir. Para ambientes com muitos consumidores e evolução rígida, formatos com schemas formais, como Protobuf ou Avro, podem ser mais apropriados.
Leia Protobuf no Node.js e Avro no Node.js para comparar.
Comparação com JSON
- MessagePack: compacto, binário e menos legível.
- JSON: simples, universal e fácil de inspecionar.
- Protobuf: schema explícito e geração de código.
- Avro: resolução entre writer e reader schema.
Faça benchmark com dados reais. Objetos pequenos podem não justificar complexidade adicional.
Benchmark responsável
import { performance } from 'node:perf_hooks';
const iterations = 100_000;
const started = performance.now();
for (let i = 0; i < iterations; i++) {
encode(event);
}
console.log(performance.now() - started);Aqueça o processo, repita amostras, compare decode e encode, meça tamanho, CPU e alocações. Não conclua com um único teste local.
Segurança
- limite tamanho antes de decodificar;
- valide o objeto resultante;
- limite profundidade e coleções quando possível;
- não aceite extensões desconhecidas;
- evite decodificar payloads ilimitados em memória;
- não registre dados sensíveis;
- mantenha a biblioteca atualizada.
Formato binário não torna conteúdo confiável nem criptografado. Use TLS em trânsito e criptografia adequada quando necessário.
Proteção contra payloads grandes
const MAX_MESSAGE_BYTES = 1024 * 1024;
if (buffer.length > MAX_MESSAGE_BYTES) {
throw new Error('Mensagem excede o limite');
}
const decoded = decode(buffer);Em HTTP, limite também o body no framework ou proxy.
Versionamento
Adicionar campos costuma ser simples quando consumidores ignoram dados desconhecidos. Remover, renomear ou alterar tipo pode quebrar aplicações.
{
version: 2,
type: 'customer.updated',
payload: { ... }
}Prefira mudanças aditivas. Quando a semântica mudar, crie nova versão ou novo tipo de evento.
Compatibilidade entre linguagens
Crie fixtures binárias produzidas em uma linguagem e decodificadas em outra. Cubra strings Unicode, números extremos, binários, mapas, arrays, nulos e extensões.
Testes de round trip
import assert from 'node:assert/strict';
const encoded = encode(event);
const decoded = decode(encoded);
assert.deepEqual(decoded, event);Round trip não basta para provar compatibilidade. Teste fixtures antigas com código novo.
Observabilidade
Registre tipo, versão, tamanho, duração e resultado da decodificação. Não registre o payload completo por padrão.
- bytes por mensagem;
- tempo de encode e decode;
- falhas de validação;
- versões desconhecidas;
- mensagens rejeitadas por tamanho.
Erros comuns
- usar
as Tiposem validar; - não limitar tamanho;
- enviar MessagePack sem indicar content type;
- misturar timestamps em segundos e milissegundos;
- usar extensões sem documentação;
- depender de ordem de chaves;
- supor que TCP preserva mensagens;
- adotar o formato sem benchmark.
Content type
Em HTTP, um tipo comum é application/msgpack, conforme convenção do ecossistema. Cliente e servidor devem concordar explicitamente.
res.setHeader('Content-Type', 'application/msgpack');
res.end(Buffer.from(encode(responseBody)));Estratégia de adoção
- escolha um fluxo interno de alto volume;
- meça JSON como baseline;
- implemente limites e validação;
- adicione content type e versão;
- crie fixtures de compatibilidade;
- implante gradualmente;
- acompanhe CPU, latência e tamanho.
Conclusão
MessagePack no Node.js pode reduzir payloads e oferecer serialização rápida para comunicação interna, WebSockets, cache e mensageria. A integração é simples: encode produz bytes, decode reconstrói valores e Buffer conecta o formato às APIs do Node.js.
O resultado só é robusto quando há validação, limites, framing, versionamento e testes entre consumidores. Use benchmarks reais para decidir entre MessagePack, JSON, Protobuf e Avro, considerando não apenas desempenho, mas também depuração, evolução e interoperabilidade.
