As convenções de nomes de tópicos MQTT determinam se o seu sistema continua fácil de assinar, seguro e simples de depurar à medida que cresce de cinco para cinco mil dispositivos. Este guia traz 12 regras concretas com exemplos bons e ruins, um modelo reutilizável e um checklist que você pode aplicar antes de o primeiro dispositivo ser entregue.
Por Que os Nomes de Topics Merecem uma Convenção
Os topics MQTT são strings UTF-8 livres, separadas por /. O broker não impõe nenhuma estrutura, e os topics são criados na hora em que alguém publica. Essa liberdade é conveniente no primeiro dia e dolorosa no dia 300, quando os assinantes dependem de dezenas de grafias ligeiramente diferentes, os wildcards casam com os dados errados e ninguém se atreve a renomear nada porque consumidores desconhecidos podem quebrar.
Os nomes de topics são, na prática, a API pública do seu sistema. Todo assinante, dashboard, fluxo do Node-RED e regra de acesso depende deles. Definir uma convenção cedo é uma das melhorias de confiabilidade mais baratas que existem.
As 12 Convenções de Nomes de Tópicos MQTT
1. Não Comece com Barra
Uma / no início cria um primeiro nível vazio. /factory/line1 e factory/line1 são topics diferentes, e o nível vazio só acrescenta confusão.
- Ruim:
/factory/line1/temp - Bom:
factory/line1/temp
2. Use Apenas Minúsculas
Os topics diferenciam maiúsculas de minúsculas. Line1/Temp e line1/temp são topics diferentes, e misturar maiúsculas e minúsculas garante que alguém vai assinar o errado. Escolha minúsculas e mantenha.
3. Evite Espaços e Caracteres Especiais
Espaços, acentos (tentadores em nomes em português, como São Paulo ou pressão) e símbolos são permitidos, mas causam problemas de escape em shells, URLs, logs e arquivos de configuração. Use a-z, 0-9, - e _. Nunca use + ou # dentro de nomes; eles são caracteres curinga nas assinaturas.
- Ruim:
Plant A/Pump #3/Pressure (bar) - Bom:
plant-a/pump-3/pressure
4. Vá do Geral para o Específico
Ordene os níveis do escopo mais amplo para o mais restrito, para que os wildcards possam selecionar ramos inteiros. Um formato comum é:
<namespace>/<site>/<area>/<line-or-group>/<device>/<category>/<measurement>
Com essa ordem, acme/berlin/# seleciona um site e acme/+/+/+/+/telemetry/temperature seleciona todas as leituras de temperatura. A ordem inversa torna essas assinaturas impossíveis. Veja wildcards MQTT para entender como + e # funcionam.
5. Comece com um Namespace
Um primeiro nível com o nome da sua empresa, produto ou aplicação mantém o seu tráfego separado de outros sistemas que compartilham o mesmo broker e facilita bridges ou migrações no futuro. No servidor MQTT público (gratuito), usado para testes e protótipos, um prefixo único como connectmq/demo/<random-id>/ mantém os seus experimentos fora do caminho dos outros.
6. Coloque os IDs de Dispositivo Depois da Localização, Não Antes
Os identificadores pertencem ao nível que representa o dispositivo, depois dos níveis de agrupamento que descrevem onde ele está. Isso permite assinar uma localização sem conhecer cada ID de dispositivo e assinar um único dispositivo com um topic exato.
- Ruim:
esp32-a4cf12/berlin/hall2/temperature - Bom:
acme/berlin/hall2/esp32-a4cf12/telemetry/temperature
7. Separe as Categorias de Mensagem
Mantenha telemetria, estado, comandos e eventos em ramos diferentes. Assim, assinantes e regras de acesso podem mirar exatamente o que precisam.
| Categoria | Topic de exemplo | QoS / retain típicos |
|---|---|---|
| Telemetria | acme/berlin/hall2/pump-3/telemetry/pressure |
QoS 0, não retido |
| Estado | acme/berlin/hall2/pump-3/state/running |
QoS 1, retido |
| Status | acme/berlin/hall2/pump-3/status |
QoS 1, retido, definido pelo Last Will |
| Comandos | acme/berlin/hall2/pump-3/cmd/set-speed |
QoS 1, não retido |
| Eventos / alarmes | acme/berlin/hall2/pump-3/event/overpressure |
QoS 1, não retido |
8. Versione o Contrato do Payload
Quando os formatos de payload mudam, os consumidores quebram. Coloque uma versão em um lugar fácil de rotear, seja como nível do topic (acme/v2/...) ou como campo dentro de cada payload. Uma versão no topic permite que consumidores antigos e novos rodem lado a lado durante a migração.
9. Mantenha a Profundidade Razoável
Cada nível deve ter significado. Sete ou oito níveis bastam para a maioria dos sistemas, e alguns brokers impõem um limite; o servidor MQTT público da ConnectMQ permite até 8 níveis. Árvores profundas também custam banda, porque a string completa do topic é enviada com cada mensagem (os topic aliases do MQTT 5 ajudam, mas não corrigem um design ruim).
10. Não Coloque Dados ou Segredos no Topic
Valores, timestamps, tokens e dados pessoais pertencem ao payload. Um topic como acme/pump-3/pressure/4.2 cria um novo topic a cada leitura e quebra retained messages e assinaturas. Os nomes de topics também aparecem em logs e ferramentas de monitoramento, então nunca inclua credenciais ou informações pessoais.
11. Use Substantivos Estáveis no Singular
Escolha uma palavra por conceito e documente-a: temperature, e não temp em um lugar e Temperature_C em outro. As unidades pertencem ao payload ou à documentação, e não ao nome do topic, a menos que a mesma medida seja realmente publicada em várias unidades.
12. Reserve o $ para o Broker
Topics que começam com $ são reservados para uso interno do broker, como as estatísticas $SYS/..., e não são capturados por uma assinatura # simples. Não crie os seus próprios topics $. Saiba o que o seu broker publica ali em topics $SYS MQTT.
Árvores de Topics Boas e Ruins Lado a Lado
# Difícil de usar
/Factory1/Line 1/CNC#1/Temp
cnc1/factory1/temperature/71.3
Factory1/line1/CNC1/TEMP_C
# Fácil de usar
acme/factory1/machining/line1/cnc1/telemetry/spindle-temperature
acme/factory1/machining/line1/cnc1/state/mode
acme/factory1/machining/line1/cnc1/status
acme/factory1/machining/line1/cnc1/cmd/start
A segunda árvore segue a hierarquia no estilo ISA-95 de empresa, site, área, linha e célula, muito usada em um Unified Namespace. Se você trabalha em ambientes industriais, o guia de Sparkplug B e Unified Namespace explica como essas hierarquias são padronizadas. Para mais árvores prontas, confira nossos exemplos de hierarquia de topics MQTT.
Teste a Sua Convenção em um Broker Real
Publique algumas mensagens usando a estrutura proposta no servidor MQTT público (gratuito) e verifique se as assinaturas com wildcard selecionam exatamente o que você espera. Substitua n8x4 pela sua própria string aleatória; a área pública pode ser lida por qualquer pessoa, então não envie dados de produção. A demonstração omite o nível de área para que o topic completo fique dentro do limite de 8 níveis do servidor MQTT público.
P="connectmq/demo/n8x4/factory1/line1"
mosquitto_pub -h broker.connectmq.com -p 1883 -i naming-pub-n8x4 \
-t "$P/cnc1/telemetry/spindle-temperature" -m '{"v":71.3,"unit":"C"}'
mosquitto_pub -h broker.connectmq.com -p 1883 -i naming-pub-n8x4 \
-t "$P/cnc2/telemetry/spindle-temperature" -m '{"v":68.9,"unit":"C"}'
mosquitto_pub -h broker.connectmq.com -p 1883 -i naming-pub-n8x4 \
-r -q 1 -t "$P/cnc1/status" -m 'online'
# Toda a telemetria da line1, e nada mais
mosquitto_sub -h broker.connectmq.com -p 1883 -i naming-sub-n8x4 -v \
-t "connectmq/demo/n8x4/factory1/line1/+/telemetry/#"
Somente a mensagem status retida teria sido entregue imediatamente a um novo assinante; a telemetria acima foi publicada antes de o assinante se conectar e não era retida. Publique de novo com o assinante rodando para vê-la chegar.
Checklist da Convenção de Topics
- Um documento escrito lista cada nível, seu significado e os valores permitidos.
- Todos os topics estão em minúsculas, sem barra inicial, espaços ou caracteres curinga.
- Um namespace é o primeiro nível.
- Os níveis vão do geral para o específico, com o ID do dispositivo depois da sua localização.
- Telemetria, estado, status, comandos e eventos têm ramos separados.
- Existe uma estratégia de versionamento.
- Nenhum valor, timestamp ou segredo aparece nos topics.
- A profundidade fica dentro dos limites do broker.
- As assinaturas com wildcard de todos os consumidores conhecidos foram testadas.
- A árvore foi revisada em um navegador de topics com dados realistas.
Se você está bem no começo, o tutorial de MQTT aborda topics, assinaturas e QoS em conjunto.
Veja a Sua Árvore de Topics na ConnectMQ
A ConnectMQ oferece a cada broker um explorador de topics ao vivo, para que você veja a sua hierarquia crescer em tempo real e identifique grafias fora do padrão na hora. Ela também reconhece topics no estilo ISA-95 e Unified Namespace e mostra os dispositivos por nível ISA-95, o que recompensa uma convenção disciplinada. Como broker MQTT gerenciado, suporta MQTT 3.1.1 e 5.0 sobre TCP, TLS e WebSockets. Crie um broker Serverless gratuito, sem cartão de crédito, e teste a sua convenção de topics com dispositivos reais.
Perguntas frequentes
Os topics MQTT devem começar com barra?
Não. Uma barra inicial cria um primeiro nível de topic vazio, o que deixa os topics mais difíceis de ler e fáceis de digitar errado. Comece diretamente com o seu namespace, como acme/....
Os topics MQTT diferenciam maiúsculas de minúsculas?
Sim. Sensor/Temp e sensor/temp são topics completamente diferentes. Usar minúsculas em todos os lugares evita divergências acidentais.
Quantos níveis um topic MQTT deve ter?
Quantos tiverem significado, e não mais; a maioria dos sistemas precisa de quatro a oito. Verifique também os limites do broker: o servidor MQTT público da ConnectMQ permite até 8 níveis.
Onde o ID do dispositivo deve ficar em um topic MQTT?
Depois dos níveis que descrevem localização ou agrupamento e antes da categoria da mensagem e da medida. Essa ordem permite que os wildcards selecionem um site, uma linha ou um único dispositivo de forma limpa.
