Eventos versus exportações: quando usar quais
FiveM fornece dois mecanismos principais para comunicação entre recursos: eventos e exportações. Os eventos são assíncronos e podem ser disparados e esquecidos por natureza, tornando-os ideais para notificações, registro e acionamento de efeitos colaterais em recursos. As exportações, por outro lado, são chamadas de função síncronas que retornam valores imediatamente, tornando-as perfeitas para recuperação de dados e funções utilitárias. Escolher o mecanismo certo para cada caso de uso é fundamental para escrever um código FiveM limpo e de fácil manutenção.
Eventos de servidor e cliente
Os eventos no FiveM fluem em direções específicas. TriggerServerEvent envia dados do cliente para o servidor, onde podem ser tratados com segurança. TriggerClientEvent envia dados do servidor para um ou todos os clientes usando um identificador de origem do player ou -1 para transmissão. Os eventos locais acionados com TriggerEvent permanecem no mesmo contexto de execução. Sempre registre eventos de rede com RegisterNetEvent antes de adicionar manipuladores e lembre-se de que qualquer evento registrado no cliente pode ser potencialmente acionado por trapaceiros usando injetores.
Protegendo seus eventos
Os manipuladores de eventos do lado do servidor sempre devem validar os dados recebidos. Verifique se o player de origem existe, verifique se os tipos de dados correspondem às expectativas e aplique limitação de taxa para evitar spam. Nunca passe informações confidenciais, como IDs de banco de dados, por meio de eventos de cliente sem verificação. Um padrão comum é usar retornos de chamada do lado do servidor em que o cliente solicita dados, o servidor valida a solicitação e busca as informações e, em seguida, aciona um evento de resposta de volta para esse cliente específico.
Trabalhando com exportações
As exportações permitem que um recurso exponha funções que outros recursos podem chamar diretamente. Você define exportações em seu fxmanifest.lua e as implementa em seus arquivos de script. Quando outro recurso chama exports['your-resource']:YourFunction(args), ele é executado de forma síncrona e retorna o resultado. Isso é particularmente útil para pontes de estrutura, bibliotecas de utilitários compartilhados e acesso a dados de scripts telefônicos, sistemas de inventário ou gerenciadores de trabalho sem acoplar recursos firmemente por meio de eventos.
Retornos de chamada e padrões assíncronos
Muitas estruturas FiveM implementam sistemas de retorno de chamada que combinam eventos com tratamento de respostas. QBCore usa QBCore.Functions.CreateCallback no servidor e QBCore.Functions.TriggerCallback no cliente. ESX tem um padrão semelhante com ESX.RegisterServerCallback. Esses retornos de chamada permitem que o cliente solicite dados do servidor e os receba em uma função de retorno de chamada, preenchendo a lacuna entre eventos assíncronos e código de sensação síncrona. Compreender esses padrões é essencial ao trabalhar com consultas de banco de dados ou verificações de inventário que exigem autoridade do servidor.
Práticas recomendadas para comunicação de recursos
Mantenha os nomes dos eventos com namespace para evitar colisões, usando um padrão como resourceName:eventAction. Documente suas exportações de forma clara para que outros desenvolvedores possam integrá-las ao seu recurso. Evite criar dependências circulares onde dois recursos são exportados um para o outro, pois isso pode causar problemas de ordem de carregamento. Ao projetar APIs para seus scripts, prefira exportações para acesso simples a dados e eventos para fluxos de trabalho complexos que envolvem várias etapas ou efeitos colaterais em diferentes partes do seu servidor.