إضافة بوت برقية للمشروع - "مشروع جافا من الألف إلى الياء"

تحياتي لكم أصدقائي الأعزاء. نعم، نعم، بالضبط الأصدقاء. لقد أصبحت بالفعل على دراية بهذه السلسلة من المقالات لدرجة أن الأشخاص الذين يكتبون بانتظام امتنانهم في التعليقات و/أو يظهرون أنهم قرأوا المادة وفهموها أصبحوا قريبين بالفعل. أنا وأنت نتحرك من اتجاهين نحو نفس الهدف. تريد أن تفهم، ولكن أريد أن أشرح. ولدينا نفس الهدف النهائي - طلب مكتوب مفهوم لك من البداية إلى النهاية. ربما تكون قد سمعت بالفعل عن الكثير مما سأصفه في هذه المقالة. لا أعتقد أنني سأخبركم بأي شيء جديد وغير عادي (ولكن في إطار المشروع من الضروري معرفة/تكرار ذلك). في الربيع كتبت لنفسي روبوتًا، لذلك سنعتمد على "أنماطه".

نكتب JRTB-2

سنفعل نفس ما فعلناه في المقالة المتعلقة بالمهمة JRTB-0 :

1. نقوم بتحديث الفرع الرئيسي في المشروع المحلي باستخدام تركيبة ctrl + t .
2. بناءً على الفرع الرئيسي نقوم بإنشاء:
3. إضافة بوت.
4. نقوم بإنشاء التزام جديد مع وصف لما تم إنجازه وندفعه إلى GitHub.
5. أنشئ طلب سحب للفرع الرئيسي وتحقق منه مرة أخرى. نحن في انتظار اكتمال البناء (إجراءات جيثب)، ودمجه في الفرع الرئيسي.
6. أغلق المهمة المقابلة.

ما هو بوت التليجرام

يمكننا نحن المطورين أن نتخيل العمل مع روبوت برقية مثل هذا: نستخدم عملائهم للعمل معهم. لدينا مكتبة جاهزة للعمل. هناك مجموعة من الإجراءات التي سيعرف بعدها بوت التليجرام أنه مرتبط ببرنامجنا. وبالفعل داخل البرنامج سوف نتعلم كيفية تلقي الرسائل والأوامر ومعالجتها بطريقة أو بأخرى. يوجد شيء مثل الأمر في روبوتات التليجرام : يبدأ بشرطة مائلة "/". وبعدها فورا نكتب الكلمة مع بعض وده هيعتبر أمر. على سبيل المثال، هناك أمران يجب على الجميع معرفتهما:

• /بدء - بدء العمل مع الروبوت؛
• / توقف - إنهاء العمل مع الروبوت.

وسنقوم بالباقي بأنفسنا. اسمحوا لي أن أقوم بالحجز على الفور: سنفعل بالضبط ما تعلمته وبالطريقة التي تعلمتها. وعند العمل مع الروبوت، أنا متأكد من أنه سيكون من الممكن القيام بعمل أفضل. وإذا أراد شخص ما القيام بذلك، سأكون سعيدًا فقط وسأدعم هذا المسعى بكل الطرق الممكنة. بالمناسبة، أول شيء سيكون رائعًا هو أن يشرح لي أحدهم كيفية برمجة وصف الأوامر من خلال الكود، وليس من خلال إعدادات الروبوت في البرقية. لم أتعلم هذا. لدينا العديد من المقالات على مواردنا التي تصف كيفية إنشاء روبوت أساسي: اليوم سنفعل شيئًا مشابهًا. إذا كان لديك أي أسئلة أخرى، أوصي بتصفح هذه المقالة.

قم بإنشاء روبوت باستخدام BotFather

لتوصيل الروبوت، عليك أولاً إنشائه. يتبع Telegram نهجًا يتمثل في إنشاء روبوت باسم فريد خاص به. وسيكون مصحوبًا أيضًا برمز مميز (سلسلة كبيرة تعمل مثل كلمة المرور). لقد قمت بالفعل بإنشاء روبوت لـ JavaRush - @javarush_community_bot . هذا الروبوت لا يزال فارغًا ولا يمكنه فعل أي شيء. الشيء الرئيسي هو أنه يجب أن يكون هناك _bot في نهاية الاسم . لإظهار كيفية القيام بذلك، سأقوم بإنشاء روبوت سنختبر عليه وظائفنا. وفيما يتعلق بالمشاريع الحقيقية، ستكون هذه بيئة اختبار. وستكون البيئة الرئيسية لدينا هي بيئة الإنتاج (منتج - إنتاج، أي البيئة الحقيقية التي سيتم تنفيذ المشروع عليها). بالطبع، سيكون من الممكن إضافة بيئة أخرى - بيئة الحماية: بيئة حماية مشتركة، أكثر قابلية للتغيير ويمكن الوصول إليها لجميع المشاركين في التطوير. لكن هذا لن يؤدي إلا إلى تعقيد الوضع في مرحلة إنشاء المشروع. في الوقت الحالي، لنقم بإنشاء روبوتين إضافيين للاختبار وبيئة وضع الحماية. الخطوة الأولى هي إنشاء (تسجيل) روبوت في Telegram نفسه. نحتاج إلى العثور على الروبوت: @BotFather وكتابة الأمر إليه: /newbot بعد ذلك، يُطلب منا إعطاء اسم لهذا الروبوت. نظرًا لأن هذا روبوت لاختبار المهام، فسيكون اسمه مناسبًا: [TEST] JavarushBot الآن حان الوقت لإعطاء اسم فريد يمكن العثور عليه دائمًا من خلاله - اسم المستخدم الخاص به: test_javarush_community كما قلت أعلاه، تحتاج إلى إضافة _bot لاحقة لاسم المستخدم، لذلك نكتب مرة أخرى: test_javarush_community_bot وهذا كل شيء! تم إنشاء البوت. الآن، باستخدام اسم المستخدم والرمز المميز، يمكن توصيله بمشروعنا. بالطبع، من أجل التشغيل السلس لخادم الاختبار، لن أعرض الرمز المميز (كلمة مرور للوصول إلى الروبوت) لهذا الروبوت للعرض العام.

نقوم بتوصيل الروبوت بالمشروع

لن نقوم بتضمين المكتبة كالمعتاد، ولكننا سنستفيد على الفور من الهيكل العظمي الخاص بنا - SpringBoot. لديه شيء مثل كاتب. من خلال تضمين المكتبة، يمكننا استخدامها للسماح لـ SpringBoot بمعرفة أننا نريد تكوين المشروع بشكل صحيح. إذا أردنا اتباع المسار المعتاد، الموضح في العديد من الأماكن، فسنحتاج إلى إنشاء تكوين في مكان ما يحتوي على شيء مثل هذا:

ApiContextInitializer.init();
TelegramBotsApi telegramBotsApi = new TelegramBotsApi();
try {
  telegramBotsApi.registerBot(Bot.getBot());
} catch (TelegramApiRequestException e) {
  e.printStackTrace();
}

هنا يتم إنشاء كائن يمكنك من خلاله إنشاء اتصال مع الروبوت. في حالتنا، فإن المبتدئ الذي نريد توصيله سيفعل كل شيء لنا في مكان ما "تحت الغطاء" (هذه أيضًا ترجمة للعبارة المستخدمة بشكل متكرر في مجال تكنولوجيا المعلومات - تحت الغطاء). هنا رابط لهذا المبدئ . يمكنك أن ترى على الفور من ملف README.md ما هو ولماذا وكيفية استخدامه. لتوصيله، تحتاج فقط إلى إضافة هذه التبعية إلى الذاكرة. هذا كل شيء :) هنا التبعية المطلوبة:

<dependency>
        <groupId>org.telegram</groupId>
        <artifactId>telegrambots-spring-boot-starter</artifactId>
        <version>5.0.1</version>
    </dependency>

نضيفه إلى ذاكرتنا. نقوم بتثبيت الإصدار كما هو متوقع ونقوم بتحديث مشروع Maven. بناءً على الوصف، نحتاج فقط إلى إنشاء فئة جديدة، وورثها من TelegramLongPollingBot وإضافة هذه الفئة إلى سياق التطبيق الخاص بـ SpringBoot. سياق التطبيق هو المكان الذي يتم فيه تخزين الكائنات التي تم إنشاؤها لتشغيل المشروع. لإضافة فئة، تحتاج إلى استخدام أحد التعليقات التوضيحية: @Component، @Service، @Repository، @Controller. أو التعليق التوضيحي @Bean إذا تم إنشاؤه من خلال طريقة في فئة التكوين (أي، في فئة تم وضع علامة عليها بالتعليق التوضيحي للتكوين). أفهم أن كل هذا قد يبدو غير مفهوم. ولكن عندما تبدأ في فهم ذلك، سترى أنه لا يوجد شيء معقد هناك. لفهم Spring Boot بسرعة، أوصي بكتاب رائع - الإصدار الخامس من Spring In Action. إذا كانت هناك رغبة، فيمكنني كتابة سلسلة من المقالات بناءً على هذا الكتاب. دعونا نعود. في الحزمة التي تحتوي على JavarushTelegramBotApplication، قمنا بإنشاء حزمة الروبوتات ، والتي ستحتوي على روبوت Telegram الخاص بنا. سيكون اسمه JavaRushTelegramBot :

package com.github.javarushcommunity.jrtb.bot;

import org.telegram.telegrambots.bots.TelegramLongPollingBot;
import org.telegram.telegrambots.meta.api.objects.Update;

/**
* Telegrambot for Javarush Community from Javarush community.
*/
@Component
public class JavarushTelegramBot extends TelegramLongPollingBot {

   @Override
   public void onUpdateReceived(Update update) {

   }

   @Override
   public String getBotUsername() {
       return null;
   }

   @Override
   public String getBotToken() {
       return null;
   }
}

كان هذا الفصل مجردًا وكان لا بد من تنفيذ ثلاث طرق. دعونا نتحدث عنهم بمزيد من التفصيل:

• onUpdateReceived(تحديث التحديث) - هذه هي نقطة الدخول حيث ستصل الرسائل من المستخدمين. كل المنطق الجديد سيأتي من هنا؛
• getBotUsername() - هنا تحتاج إلى إضافة اسم المستخدم الخاص بالروبوت الخاص بنا والذي سنتصل به؛
• getBotToken() - وهذا، وفقًا لذلك، هو رمز الروبوت.

إنه في الأساس يشبه تسجيل الدخول وكلمة المرور لموقع ما. لن نكتب هذه القيمة بشكل صريح في الوقت الحالي. وهذا ما يسمى "الترميز الثابت" (أي ربط قيمة معينة - كالعادة، تتبع الورق من الكود الثابت الإنجليزي). لا يجب أن تفعل ذلك. سنذهب في الاتجاه الآخر - سنكتب هذه البيانات في فئة application.properties ونقرأها من هنا. لماذا هذا ضروري؟ وبعد ذلك، عند بدء تشغيل التطبيق، يمكننا ضبط هذه القيم خارجيًا. إنها مرنة، هذا صحيح. انتقل إلى الملف src/main/resources/application.properties. هناك سوف نأتي بأسماء هذه المتغيرات. تتم قراءة الملفات ذات الامتداد ‎.properties كبنية قيمة مفتاح مفصولة بـ "="، حيث يكون كل زوج سطرًا منفصلاً. لذلك توصلت إلى هذه المتغيرات:

• bot.اسم المستخدم ;
• bot.token .

هذا هو الشكل الذي سيبدو عليه: يحتوي SpringBoot على تعليق توضيحي رائع - @Value. إذا تم استخدامه بشكل صحيح، فإنه سيتم سحب القيم من ملف application.properties. نقوم بتحديث المشروع بهذا:

package com.github.javarushcommunity.jrtb.bot;

import org.springframework.beans.factory.annotation.Value;
import org.telegram.telegrambots.bots.TelegramLongPollingBot;
import org.telegram.telegrambots.meta.api.objects.Update;

/**
* Telegram bot for Javarush Community from Javarush community.
*/
@Component
public class JavarushTelegramBot extends TelegramLongPollingBot {

   @Value("${bot.username}")
   private String username;

   @Value("${bot.token}")
   private String token;

   @Override
   public void onUpdateReceived(Update update) {

   }

   @Override
   public String getBotUsername() {
       return username;
   }

   @Override
   public String getBotToken() {
       return token;
   }
}

يمكن ملاحظة أننا مررنا قيمة المتغير إلى التعليق التوضيحي. وعندما يقوم SpringBoot بإنشاء كائن الروبوت الخاص بنا، سيتم أخذ القيم من الخصائص (مرة أخرى، ورقة البحث عن المفقودين من اللغة الإنجليزية - الخصائص). نحن على وشك الوصول. تحتاج إلى جعل الروبوت يجيب على شيء ما. لذلك، دعونا نقوم بتحديث طريقة onUpdateReceived . نحن بحاجة إلى استرداد الرسالة التي وصلت إلى الروبوت وتمريرها مرة أخرى. بهذه الطريقة سنعرف أن الروبوت يعمل. للقيام بذلك، سنكتب تقريبًا وبسرعة ما هو مطلوب:

@Override
public void onUpdateReceived(Update update) {
   if(update.hasMessage() && update.getMessage().hasText()) {
       String message = update.getMessage().getText().trim();
       String chatId = update.getMessage().getChatId().toString();

       SendMessage sm = new SendMessage();
       sm.setChatId(chatId);
       sm.setText(message);

       try {
           execute(sm);
       } catch (TelegramApiException e) {
           //todo add logging to the project.
           e.printStackTrace();
       }
   }
}

كل شيء هنا بسيط للغاية: نتحقق من وجود الرسالة بالفعل، لذلك نستخرج الرسالة نفسها ( الرسالة ) ومعرف الدردشة ( chatId ) الذي تجري فيه المراسلات. بعد ذلك، نقوم بإنشاء كائن لإرسال رسالة SendMessage ، ونمرر الرسالة نفسها ومعرف الدردشة إليها - أي ما يجب إرساله إلى الروبوت وأين. لدينا بالفعل ما يكفي من هذا. بعد ذلك، نقوم بتشغيل الطريقة الرئيسية في فئة JavarushTelegramBotApplication ونبحث عن الروبوت الخاص بنا في Telegram: من السجلات نرى أن الروبوت قد بدأ. لذا، حان الوقت للذهاب إلى Telegram والكتابة إلى الروبوت: نضغط على "ابدأ" ونتلقى إجابة على الفور: دعنا نكتب المزيد من الهراء للتحقق: وهذا كل شيء، في هذه المرحلة يمكننا القول أن مهمة JRTB-2 قد اكتملت. . لا يمكنك كتابة أي اختبارات هنا بعد، لذلك سنترك كل شيء كما هو. بعد ذلك، تحتاج إلى إنشاء التزام جديد: انتبه إلى اسم الالتزام: مرة أخرى ألفت انتباهك إلى هذا. يحتوي الالتزام أولاً على اسم المهمة، ثم وصفًا أكثر تفصيلاً لما تم إنجازه. انقر فوق Commit and Push... وقم بالتأكيد بالنقر فوق Push مرة أخرى : انتقل إلى مشروعنا . كما كان من قبل، رأى GitHub بالفعل الفرع الجديد ويعرض إنشاء طلب سحب للملف الرئيسي. نحن لا نقاوم وننشئه: كالعادة، اخترنا بالفعل تسمية ومشروعًا وأسندناه لي. وأخيرا، انقر فوق إنشاء طلب سحب. لننتظر قليلاً حتى تتم عملية الإنشاء - وهذا كل شيء، طلب السحب جاهز للدمج:

الإصدار

لقد فاتني بطريقة ما النقطة التي نحتاجها للقيام بالإصدار. للقيام بذلك، سنقوم بإجراء بعض التغييرات الإضافية في فرعنا. نعود إلى IDEA وننظر إلى إصدار المشروع في الذاكرة: الإصدار هو 0.0.1-SNAPSHOT . هذه هي النسخة واجب. وسنبدأ بتحديث نسخة المشروع مع كل مشكلة جديدة يتم حلها. حتى نصل إلى MVP، سيأتي الإصدار باللاحقة -SNAPSHOT. ماذا سيكون مخطط الإصدار؟ XYZ-SNAPSHOT حيث:

• X - تحديث الإصدار الرئيسي، غالبًا ما يحتوي على مشاكل في التوافق مع الإصدار السابق؛
• Y - ليست تغييرات كبيرة جدًا، متوافقة تمامًا مع الإصدار السابق؛
• Z عبارة عن عداد للعيوب التي وجدناها وأصلحناها.

وبناءً على ذلك، سيكون لدينا الإصدار الأول - 0.1.0-SNAPSHOT - أي أننا لم نحصل بعد على تحديثات كبيرة، فقط القليل من كل شيء، ولم نصل بعد إلى MVP، لذلك هناك لاحقة -SNAPSHOT . دعونا نغير هذا في الذاكرة: انتقل إلى ملف RELEASE_NOTES، حيث سنصف التغييرات التي تطرأ على المشروع مع كل إصدار جديد: إدخالنا الأول. الآن، مع كل تحديث لاحق للإصدار، سنصف هنا ما حدث بالضبط. نلتزم بهذه الحالة ونكتب وصفًا: JRTB-2: إصدار المشروع المحدث وإضافته إلى RELEASE_NOTES، كل شيء هو نفسه تمامًا كما كان من قبل. نحن في انتظار مرور الإنشاء ويمكننا دمج تغييراتنا. هنا فقط سيكون الأمر مختلفًا بعض الشيء. أريد التأكد من أن كل مهمة في الفرع الرئيسي هي التزام منفصل، لذا فإن مجرد دفع طلب سحب الدمج لن ينجح بالنسبة لنا. يحتوي Git على خيار git Squash، الذي يجمع كل الالتزامات في واحدة ويدمجها. نختار هذا الخيار: انقر فوق Squash and Merge، ويُعرض علينا تعديل الرسالة التي ستكون في النهاية: مريحة للغاية والأهم من ذلك ما هو مطلوب. بالمناسبة، لم أر مثل هذه الميزة على bitbucket =/ تأكيد الدمج. الشيء الوحيد المتبقي هو تغيير حالة المهمة إلى "تم" في لوحتنا، وكتابة تعليق يحتوي على رابط لطلب السحب وإغلاقه: تبدو لوحتنا الآن كما يلي:

خاتمة

قمنا اليوم بإنشاء روبوت برقية خطوة بخطوة وقمنا بتنفيذه في مشروع SpringBoot الخاص بنا. الروبوت يعمل ويعطي الإجابات. لقد تمكنا على الفور من الوصول إلى بيانات الروبوت من خلال الخصائص. المزيد في المستقبل: سنقوم بعمل كبير - تنفيذ JRTB-3 - إضافة نمط الأمر لمشروعنا. أوه ، شيء آخر ... أخبرتك أنني لن أنشر الرمز حتى لا يتم استخدامه. لكن بما أنني كنت أكتب المقال قرب منتصف الليل وبعد العمل، فقد اتضح أنني قد نشرت رمزًا صالحًا في المستودع، وأخبرني GitGuardian عن ذلك في رسالة: شكرًا لهم على هذا! ماذا تفعل الآن؟ لن يكون من الممكن حذفه من البوابة، لأنه حتى لو قمت بتحميل التزام جديد بدون هذا الرمز المميز، فإنه سيظل في القديم. لكنني لا أريد حذف الالتزام والتراجع عنه. لذلك ذهبت وقمت بإلغاء تنشيط الرمز المميز من BotFather المذكور بالفعل. والآن أصبح الرمز موجودًا، لكنه لم يعد صالحًا. اشترك في حسابي على GitHub لترى كل الكود الخاص به قبل نشر المقال. شكرا لكم جميعا على القراءة، نراكم قريبا.

توجد قائمة بجميع المواد الموجودة في السلسلة في بداية هذه المقالة.