کتابخانه aiogram در پایتون — معرفی، اصول و نمونه‌های عملی

aiogram یکی از محبوب‌ترین کتابخانه‌های غیرهم‌زمان (asynchronous) برای ساخت ربات‌های تلگرام با پایتون است. این فریم‌ورک بر پایه asyncio طراحی شده و به‌خاطر سرعت، انعطاف‌پذیری و پشتیبانی از امکانات پیشرفته‌ی تلگرام (مثل FSM، فیلترها، middlewareها و inline queries) مورد استقبال توسعه‌دهندگان قرار گرفته است.

ویژگی‌های کلیدی aiogram

• غیربلاک‌کننده (async) — تمام عملیات شبکه به‌صورت async انجام می‌شود.
• پشتیبانی از FSM — ساخت فرم‌ها و جریان‌های گفتگو به‌سادگی با state machine.
• فیلترها و هندلرها — امکان تعریف قوانین پیشرفته برای پردازش پیام‌ها.
• قابلیت گسترش — middleware و پلاگین‌ها برای افزودن لایه‌های تخصصی.
• پشتیبانی از Polling و Webhook — مناسب توسعه محلی و استقرار در سرور.

نصب و شروع سریع

نصب aiogram ساده است:

pip install aiogram

سپس می‌توانید یک ربات ساده با polling بنویسید:

import asyncio
from aiogram import Bot, Dispatcher
from aiogram.filters import Command
from aiogram.types import Message
from aiogram.fsm.storage.memory import MemoryStorage

TOKEN = "YOUR_BOT_TOKEN"

bot = Bot(token=TOKEN)
storage = MemoryStorage()
dp = Dispatcher(storage=storage)

@dp.message(Command(commands=["start"]))
async def cmd_start(message: Message):
    await message.answer("سلام! با aiogram خوش آمدی.")

async def main():
    await dp.start_polling(bot)

if __name__ == "__main__":
    asyncio.run(main())

توضیح: این کد یک بات ساده با aiogram (نسخه 3.x) ایجاد می‌کند. ابتدا Bot و Dispatcher ساخته می‌شود و یک MemoryStorage برای حالت‌های موقتی (FSM) تعریف شده است. سپس یک هندلر برای دستور /start ثبت می‌شود و در نهایت با start_polling بات اجرا می‌گردد. استفاده از asyncio.run باعث اجرای حلقه رویداد می‌شود.

نمونه: فرم ثبت با FSM

برای جمع‌آوری چند مقدار از کاربر، FSM بسیار کاربردی است. مثال زیر روند ثبت نام ساده‌ای نشان می‌دهد:

from aiogram.fsm.context import FSMContext
from aiogram.fsm.state import StatesGroup, State
from aiogram.filters import StateFilter, Command
from aiogram.types import Message

class Form(StatesGroup):
    name = State()
    age = State()

@dp.message(Command(commands=["register"]))
async def cmd_register(message: Message, state: FSMContext):
    await state.set_state(Form.name)
    await message.answer("لطفاً نام خود را وارد کنید:")

@dp.message(StateFilter(Form.name))
async def process_name(message: Message, state: FSMContext):
    await state.update_data(name=message.text)
    await state.set_state(Form.age)
    await message.answer("لطفاً سن خود را وارد کنید:")

@dp.message(StateFilter(Form.age))
async def process_age(message: Message, state: FSMContext):
    data = await state.get_data()
    name = data.get("name")
    age = message.text
    await message.answer(f"ثبت شد: نام = {name}، سن = {age}")
    await state.clear()

توضیح: در این مثال یک StatesGroup به نام Form تعریف شده که دو State دارد. وقتی کاربر /register را بزند، حالت به Form.name منتقل می‌شود. در هر مرحله با استفاده از state.update_data داده‌ها ذخیره و با state.get_data بازیابی می‌شوند. در انتها با state.clear حالت پاک می‌شود.

کیبوردها، Inline و Callback

ایجاد کیبوردهای سفارشی و مدیریت callbackها بخش مهمی از تجربه کاربری ربات است:

from aiogram.types import InlineKeyboardMarkup, InlineKeyboardButton
from aiogram.filters import CallbackQuery

kb = InlineKeyboardMarkup(inline_keyboard=[
    [InlineKeyboardButton(text="فشار بده", callback_data="press")]
])

@dp.message(Command(commands=["menu"]))
async def cmd_menu(message: Message):
    await message.answer("منو:", reply_markup=kb)

@dp.callback_query(CallbackQuery(filters=lambda c: c.data == "press"))
async def cb_press(callback_query):
    await callback_query.message.answer("دکمه فشرده شد!")
    await callback_query.answer()

توضیح: این کد یک کیبورد اینلاین با یک دکمه ایجاد می‌کند. با فشردن دکمه، callback query ارسال و هندل می‌شود. متد callback_query.answer باعث حذف ساعت لودینگ در کلاینت تلگرام می‌شود.

Webhook vs Polling — کدام بهتر است؟

• Polling: برای توسعه محلی و ربات‌های کوچک مناسب است. پیاده‌سازی ساده و سریع دارد.
• Webhook: برای ربات‌های پر ترافیک و محیط‌های تولیدی مناسب‌تر است. نیاز به HTTPS و سرور دارد ولی مصرف منابع کمتر و تأخیر پایین‌تری دارد.

برای استفاده از webhook معمولاً از یک فریم‌ورک وب (مانند aiohttp یا FastAPI) و Reverse Proxy (Nginx) یا سرویس‌هایی مانند Cloudflare استفاده می‌شود.

نکات عملکردی و بهترین شیوه‌ها

• از کدهای بلوکه‌کننده (مثلاً درخواست‌های همزمان به دیتابیس بلوکه‌کننده) اجتناب کنید؛ به‌جای آن از کتابخانه‌های async یا اجرا در ThreadPool استفاده کنید.
• برای حالت‌ها و داده‌های مشترک بین چند instance از ذخیره‌سازهایی مثل Redis استفاده کنید (aiogram از Redis storage پشتیبانی دارد).
• Middlewareها را برای logging، rate limiting و احراز هویت استفاده کنید.
• خطاها را به‌صورت متمرکز هندل کنید و پاسخ دوستانه به کاربر ارسال کنید.

مقایسه‌ای اجمالی بین aiogram v2 و v3

اشتباهات متداول و راه‌حل‌ها

• فراموش کردن استفاده از storage مناسب در حالت چندپردازشی — از Redis یا PostgreSQL-based storage استفاده کنید.
• اجرای توابع بلوکه‌کننده داخل هندلرها — همیشه از async یا اجرا در executor استفاده کنید.
• عدم مدیریت خطاهای شبکه — از retry و timeout استفاده کنید.

نمونه middleware ساده برای لاگ

from aiogram import BaseMiddleware
from aiogram.types import Message

class SimpleLogger(BaseMiddleware):
    async def __call__(self, handler, event, data):
        if isinstance(event, Message):
            print(f"Incoming message from {event.from_user.id}: {event.text}")
        return await handler(event, data)

dp.update.middleware(SimpleLogger())

توضیح: این middleware تمام پیام‌های ورودی را لاگ می‌کند. سپس برای ادامه پردازش، handler اصلی صدا زده می‌شود. Middlewareها برای افزودن لایه‌های cross-cutting مثل لاگ، نرخ‌دهی و اعتبارسنجی مناسب‌اند.

جمع‌بندی و نکات نهایی

aiogram ابزاری قدرتمند برای توسعه ربات‌های تلگرام است که با استفاده از طراحی async قابلیت ساخت ربات‌های واکنش‌پذیر، سریع و مقیاس‌پذیر را فراهم می‌کند. با درک عمیق‌تر از FSM، middleware، و ذخیره‌سازی مقیاس‌پذیر (مثل Redis)، می‌توانید ربات‌هایی حرفه‌ای و قابل اطمینان تولید کنید. برای شروع از polling استفاده کنید و پس از آماده‌شدن برای تولید، به webhook و استفاده از سرورهای HTTPS و ذخیره‌سازی مرکزی مهاجرت کنید.

منابع پیشنهادی: مستندات رسمی aiogram، مثال‌های GitHub و مقالات مرتبط با asyncio و طراحی سیستم‌های توزیع‌شده.

لطفاً از کمبود ها و مشکلات این محتوا برای ما بنویسید

ارسال