👢 👂🏼 👩‍👩‍👧‍👧 Estamos desenvolvendo um bot Telegram para rastrear filmes no NodeJS e TypeScript 🔻 🉑 🥧

Aconteceu a você que você vem ao cinema e assiste a trailers antes do início do filme, enquanto alguns deles se apegam a você com muita força e você se compromete a assistir esse filme se não estiver no cinema, pelo menos mais tarde, quando estiver disponível para download ? Atrevo-me a sugerir que sim. Mas muitas vezes acaba com o fato de você ter esquecido com êxito e, na melhor das hipóteses, encontrar acidentalmente esse filme, percorrendo a lista de filmes já lançados.

Muitas vezes encontrei esse problema e decidi criá-lo com Eve - Telegram-bot, o que me ajuda a não esquecer os lançamentos de meus filmes favoritos. O que é, como funciona e como foi desenvolvido, você pode ler sob o corte!

Prefácio

Este artigo não é um guia detalhado sobre a criação de robôs do Telegram. E, embora no decorrer do artigo eu frequentemente me refira ao meu projeto, o objetivo deste material é uma história sobre desenvolvimento em geral, a saber, a escolha de tecnologias, pontos-chave e armadilhas que encontrei.

Porque

Então, como escrevi acima, muitas vezes esqueço de assistir aos filmes cujo trailer eu gostei. Estou pensando em uma solução para esse problema há muito tempo. A primeira coisa que me ocorreu foi a criação de um aplicativo nativo para smartphones, mas desde Eu nunca fiz isso antes, levaria muito tempo e não o fato de que o resultado final satisfaria minhas necessidades, bem como as necessidades de usuários em potencial.

A próxima idéia foi criar um PWA. É uma opção bastante interessante para se familiarizar com a tecnologia, mas decidi deixá-la para o futuro. Ao mesmo tempo, uso o Telegram há muito tempo e durante todo esse tempo acumulei um número suficiente de bots que periodicamente tornam minha vida um pouco mais fácil. Por fim, depois de ponderar todos os prós e contras, decidi que essa plataforma é perfeita para essa ideia.

Seleção de tecnologia

Se você acessa os bots do Github for Telegram, pode ver que a maioria deles está escrita em Python. Python é realmente uma ótima linguagem e ótima para essa ideia, mas eu queria implementar esse projeto especificamente no NodeJS + TypeScript. Aplicando os filtros apropriados, me deparei com duas ferramentas bastante populares: node-telegram-bot-api e Telegraf.js .

Antes dessa experiência no desenvolvimento de bots, eu não tinha; portanto, ao escolher uma dessas duas opções, não estava claro quais parâmetros deveriam ser considerados. Como resultado, depois de examinar a documentação e examinar os problemas de cada uma das bibliotecas, decidi pelo Telegraf.js. O fator decisivo foi a disponibilidade de middlewares, projetada da mesma maneira que na popular estrutura Express.js. O Telegraf.js também possui um histórico de atualizações mais frequente e documentação bem estruturada, o que sugere que os desenvolvedores estão se esforçando o suficiente para melhorar a ferramenta. Além disso, ele contém dicas para o TypeScript, que é definitivamente uma vantagem para a pilha selecionada.

Telegraf.js

Telegraf.js é a principal biblioteca na qual o projeto foi escrito. Ele usa várias abordagens interessantes que permitem criar bots complexos, mantendo a simplicidade do código. Abaixo estão os mecanismos mais interessantes:

Middlewares - sim, esses são os mesmos middlewares disponíveis no Express.js. Quando o usuário envia algo para o bot, a mensagem primeiro passa por todos os middlewares registrados e depois chega ao controlador. Os middlewares podem modificar o contexto e suspender a execução da solicitação, por exemplo, se um usuário comum tentar entrar na área para administradores. O Telegraf.js fornece alguns middlewares extremamente úteis prontos para uso, mas você também pode usá-los. Ou seja, os middlewares são considerados recursos matadores do Telegraf.js
Sessões - sessões que podem armazenar informações que não estão vinculadas ao controlador. Você pode fazer uma analogia com variáveis globais acessíveis em qualquer lugar do bot. Uma coisa muito conveniente, que é usada, por exemplo, para localização. É possível armazenar sessões em diferentes modos - banco de dados, redis, arquivos locais, etc.
Webooks - o bot pode funcionar de dois modos - pesquisas longas ou Webhooks . E embora eles trabalhem igualmente rápido, é melhor usar a segunda opção em um ambiente de produção. Assim, o bot não precisará bater no servidor Telegram; em vez disso, ele próprio receberá todas as atualizações.

Importante: Um pré-requisito para Webhooks é o suporte ao servidor SSL / TLS. Verifique também se a porta na qual o Webhook está executando está aberta e acessível a partir do exterior.
Marcação - com esta turma, você pode ensinar o bot a responder na marcação de marcação / marcação. Isso é importante se, por exemplo, você estiver criando um jogo em HTML. No entanto, no meu projeto, usei apenas para texto em negrito / itálico.
O palco é um módulo extremamente interessante que me ajudou a manter meus nervos e algumas horas de desenvolvimento. Aqui vou contar com mais detalhes.
O bot pode ouvir as mensagens do usuário e, dependendo do tipo ou conteúdo da mensagem, redirecioná-lo para um ou outro controlador, que executará sua função e enviará uma resposta ao usuário. É assim:
```
bot.hears('hello', async ctx => { await ctx.reply('Hello!'); }); 
```
Funciona simplesmente: se você escrever um olá para o bot, ele simplesmente responderá Olá! Conhecendo esse aspecto do trabalho, vamos tentar imaginar como o bot pode trabalhar na pesquisa de filmes:
1. O usuário escreve que deseja ir à busca de filmes;
2. O usuário dirige o nome do filme
3. O bot retorna uma lista de filmes e solicita que o usuário salve o filme selecionado em sua biblioteca;
4. ...
Atenção, uma pergunta! Como um bot pode distinguir quando um usuário escreve para ele que ele quer começar a procurar um filme e quando ele escreve o nome do filme para pesquisar?

Sim, você pode usar qualquer texto enviado como o nome do filme, mas queremos tornar o bot com ~~blackjack e prostitutas uma~~ boa interface.

E aqui as cenas (etapas) entram em cena! Será mais fácil dizer pelo exemplo acima. Quando o usuário diz que quer ir à busca de filmes, iniciamos a cena. Dentro dessa cena, existem manipuladores de texto separados - bot.hears (...). Assim, todas as mensagens subsequentes se relacionam diretamente com a busca de filmes até que o usuário escreva uma mensagem para sair e sair da cena. Depois disso, os manipuladores dentro dessa cena são desativados até o usuário retornar lá novamente. A seguir, descreverei como usei as cenas para tornar a manipulação de eventos o mais simples possível.

Estrutura do projeto

Suspeita-se que o artigo se torne bastante volumoso e, portanto, para não esticá-lo ainda mais, omitirei alguns pontos. Por exemplo, para que o bot comece a funcionar, é necessário obter o token da API do Telegram Bot. Você pode ler sobre como fazer isso na documentação oficial do Telegram ou na documentação do Telegraf.js.

A estrutura de arquivos do projeto é a seguinte:

Estrutura do projeto

Funciona da seguinte maneira:

src / controllers - estas são as cenas sobre as quais foi escrito acima. Neste projeto, cada cena é um controlador separado que processa as solicitações correspondentes.
src / locales - traduções para diferentes idiomas. O Telegraf.js facilita a adição de localização ao bot usando middlewares.
src / models - modelos para MongoDB.
src / types - dicas para TypeScript. Infelizmente, nem todas as bibliotecas usadas no projeto têm tempos padrão.
src / util - várias funções auxiliares que são usadas em diferentes partes do projeto. Aqui você pode ver como funciona a disponibilidade do filme para download, gerenciamento de sessões, criação de teclados, manipuladores de erros e muito mais.
src / bot.ts - o arquivo principal onde é feita toda a preparação e lançamento do bot.
src / telegram.ts - nesse caso, criamos um objeto da classe Telegram da biblioteca Telegraf.js. Usando esse objeto, podemos enviar mensagens aos usuários primeiro, usando seu ID, e não esperar até que eles escrevam algo. Por exemplo, neste projeto, enviamos ao usuário uma mensagem informando que o filme que ele estava seguindo já pode ser baixado. Obviamente, esse objeto fornece muito mais recursos.
Tudo o resto são configurações para diferentes partes do projeto que não serão discutidas neste artigo.

Inicialização e Lançamento

Quando descobrimos a estrutura do projeto, vamos ver como o bot realmente começa. Novamente, para encurtar o artigo, não inserirei o código inteiro aqui, mas falarei apenas dos principais, na minha opinião, momentos. Você pode ver o código completo no repositório, cujo link está disponível no final do artigo.

Tudo começa com a conexão com o banco de dados, que armazena informações sobre os usuários e os filmes que eles rastreiam. Após uma conexão bem-sucedida, registramos todas as cenas usadas no projeto, definimos parâmetros para localização e adicionamos vários middlewares - sessões de processamento, localização, configuração de cenas e várias outras. Um deles, por exemplo, recebe todas as informações sobre o usuário de acordo com seu ID e as adiciona ao contexto usado nos controladores. Finalmente, depois de todos os preparativos básicos, lançamos o bot no modo de desenvolvimento (pesquisa longa) ou produção (Webhooks).

Importante: se você usar métodos diferentes para receber atualizações (pesquisa longa e Webhooks), ao iniciar o bot no modo de pesquisa longa, remova primeiro o Webhook de escuta usando a solicitação GET em api.telegram.org/botYOUR_TOKEN/deleteWebhook . Caso contrário, o bot pode não funcionar corretamente.

Lidar com entrada do usuário

Viva! O bot funciona, está conectado ao banco de dados e está pronto para receber mensagens dos usuários. Mas como fazer isso certo?

Primeiro de tudo, será conveniente que os usuários usem o teclado Telegram embutido. De fato, quando você clica nos botões deste teclado, as mensagens são enviadas com o conteúdo desses botões. Em seguida, simplesmente adicionamos manipuladores para este texto e executamos determinadas ações.

O arquivo bot.ts contém esses manipuladores. Como o bot suporta dois idiomas, os botões também podem conter texto diferente - em russo e inglês. O Telegraf-i18n possui uma função de correspondência que permite clicar no mesmo botão em diferentes idiomas.

A maioria dos manipuladores no bot.ts executa uma única função - eles iniciam o usuário na cena correspondente. Então, temos várias seções - procure filmes, minha coleção, cenários e contatos. Cada seção possui sua própria cena e seu próprio botão. Quando clicado, o usuário passa para a cena correspondente.

Importante: certifique-se de adicionar um manipulador que liberte o usuário da cena; caso contrário, eles correm o risco de ficar lá para sempre! Também será útil fazer um comando geral (/ saveme é usado no bot), que será adicionado a cada cena e ao arquivo principal. Este comando servirá como uma saída de qualquer cena, além de redefinir as configurações do usuário.

E agora, o usuário quer ir à busca de filmes. Ao clicar no botão apropriado, movemos para o cenário de pesquisa. Por conveniência, cada cena possui sua própria pasta com arquivos, cada um dos quais desempenha uma função específica.

Dentro da cena, você pode usar seus middlewares, que estão no arquivo middlewares.ts. Por exemplo, usando o middleware na cena de pesquisa, podemos simplesmente encaminhar todas as informações sobre o filme para os métodos apropriados, em vez de executar a mesma função sempre que dentro deles.

O telegrama também possui um teclado embutido. Talvez você tenha encontrado mensagens com votos, nas quais existem vários botões translúcidos, e quando você clica em um deles, o número de votos muda. Esses botões são o teclado embutido

É assim que se vê Eve

Cada botão contém informações, quando você clica no botão, elas são transmitidas ao manipulador correspondente. O tamanho da informação transmitida não deve exceder 64 bytes! Para ensinar o bot a ouvir cliques no botão, precisamos registrá-los usando bot.action (/ trigger /, callback). O primeiro parâmetro contém todos os dados que foram vinculados ao botão. Decidi usar algo como Actions from Redux, onde um objeto do formulário {a: actionName, p: payload} é anexado a cada botão. Ao registrar ouvintes, podemos usar um RegExp simples, por exemplo: bot.action (/ actionName /, callBack). Todos os manipuladores do teclado embutido estão nos arquivos actions.ts.

Além disso, em algumas cenas, existem arquivos helpers.ts, que contêm pequenas funções executadas lá para descarregar os arquivos restantes. Na maioria das vezes, existem geradores de teclado para várias ações do usuário.

Localização

Como esse é um tópico importante, acho que vale a pena mencionar separadamente. Como eu disse anteriormente, o Telegraf.js contém um número bastante grande de middlewares, um dos quais é o telegraf-i18n . O repositório contém instruções detalhadas e eu não tive nenhum problema especial com isso, mas, no entanto, adicionarei algumas palavras sobre como isso funciona neste projeto.

Há uma pasta de localidades onde os arquivos para localização estão localizados, que são um objeto JSON no formato {"key": "translation"}. Além disso, sempre que precisamos usar idiomas diferentes, usamos o método desta biblioteca, onde transferimos a tradução necessária por chave e, na saída, obtemos a tradução correspondente. Uma sessão pode ser usada para armazenar informações sobre o idioma selecionado pelo usuário. Também vale a pena mencionar sobre os botões novamente. Há uma função de correspondência na mesma biblioteca; portanto, se o texto no botão mudar dependendo do idioma, essa função ajudará você a desligar o ouvinte correto.

Importante: se você usar a localização e escrever um bot no TypeScript, não se esqueça de adicionar a pasta de tradução ao tsconfig.json, caso contrário, o código não será compilado. Por exemplo:

 "include": ["src/locales/*.json"]

Conclusão

Obrigado por ler até o fim! Neste artigo, tentei descrever o processo de criação de um bot do Telegram como um todo, o mais detalhado possível, sem um forte apego ao meu projeto. Espero que, depois de ler este artigo, além de estudar o código fonte do Eve, você possa criar facilmente um bot que possa ajudá-lo.

Como prometido, você pode olhar o código fonte no GitHub e experimentar o Eve em ação aqui . Serei imensamente grato por qualquer crítica e sugestão de melhoria.

Também gostaria de observar a seção na documentação do Telegraf.js com projetos interessantes de código aberto que você pode ver e se inspirar na arquitetura e nas soluções. Eu, por sua vez, quero mencionar um deles - The Guard Bot . Um bot realmente grande e bem feito, de onde peguei emprestadas algumas das soluções para o meu desenvolvimento.

E no momento em que contei tudo o que queria, terei prazer em responder suas perguntas, sugestões e comentários!

Estamos desenvolvendo um bot Telegram para rastrear filmes no NodeJS e TypeScript