کتابخانه uvicorn در پایتون — معرفی و راهنمای کاربردی

Uvicorn یک سرور ASGI سبک، سریع و مبتنی بر رویداد برای اجرای برنامه‌های وب آسنکرون در پایتون است. این پروژه برای اجرای فریم‌ورک‌های مدرن مانند FastAPI و Starlette طراحی شده و از asyncio یا uvloop برای کارایی بالا استفاده می‌کند. در این مقاله به مفاهیم پایه، نحوه نصب و اجرا، تنظیمات مهم و نکات بهینه‌سازی می‌پردازیم.

چرا از Uvicorn استفاده کنیم؟

• پشتیبانی از ASGI: مناسب برای برنامه‌های آسنکرون و WebSocket.
• کارایی بالا: با استفاده از uvloop و httptools سرعت بالاتری نسبت به سرورهای مبتنی بر asyncio پایه دارد.
• سادگی در توسعه: گزینه –reload برای توسعه سریع و مشاهده تغییرات بدون ری‌استارت دستی.
• قابلیت اجرا در محیط تولید: با استفاده از چند worker یا ترکیب با Gunicorn قابل توسعه برای تولید است.

نصب و اجرای اولیه

pip install "uvicorn[standard]"

این دستور بستهٔ استاندارد uvicorn را شامل وابستگی‌های پرکاربرد (مثل uvloop و httptools) نصب می‌کند تا بهترین عملکرد ممکن حاصل شود.

# اجرای یک فایل ساده: فرض کنید فایل app.py شامل متغیر app باشد
uvicorn app:app --host 0.0.0.0 --port 8000 --reload

در این مثال uvicorn به دنبال شیء app در ماژول app.py می‌گردد و سرور را روی پورت 8000 اجرا می‌کند. گزینه –reload برای محیط توسعه است و هنگام تغییر کد سرور را مجدداً بارگذاری می‌کند.

نمونه برنامه سریع با FastAPI

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def read_root():
    return {"message": "Hello, Uvicorn!"}

این کد نمونه یک API بسیار ساده با FastAPI می‌سازد که توسط Uvicorn قابل اجرا است. ساختار async در endpoint نشان‌دهندهٔ استفاده از قابلیت‌های آسنکرون است.

اجرای برنامه با گزینه‌های مهم

uvicorn app:app --host 0.0.0.0 --port 8000 --workers 4 --log-level info --proxy-headers

توضیح گزینه‌ها:

• –workers 4: تعداد پروسس‌های worker (برای استفاده از چند هسته CPU).
• –log-level info: تعیین سطح لاگ.
• –proxy-headers: هنگامی که جلوی سرور پروکسی معکوس مثل Nginx قرار دارد، هدرهای پروکسی را می‌پذیرد.

نمونهٔ استفادهٔ تولیدی با Gunicorn

gunicorn -k uvicorn.workers.UvicornWorker app:app -w 4 -b 0.0.0.0:8000

Gunicorn مدیریت پروسس‌ها و مانیتورینگ را ساده‌تر می‌کند و با استفاده از کارگرهای Uvicorn می‌توان از مزایای هر دو بهره برد. این ترکیب در محیط‌های تولیدی متداول است.

ویژگی‌های فنی و نکات پیشرفته

• uvloop و httptools: نصب uvicorn[standard] به طور پیش‌فرض uvloop (یک حلقه رویداد سریع) و httptools (پارسینگ سریع HTTP) را نصب می‌کند که موجب افزایش کارایی می‌شوند.
• پشتیبانی از WebSocket: Uvicorn می‌تواند WebSocketهای ASGI را مدیریت کند که برای اپلیکیشن‌های real-time ضروری است.
• HTTP/2 و HTTP/1.1: به‌طور کلی Uvicorn برای HTTP/1.1 بهینه شده؛ گزینه‌های HTTP/2 ممکن است نیازمند پیکربندی اضافی و وابستگی‌های جانبی باشند و در برخی موارد experimental هستند.
• رویدادهای lifespan: ASGI اجازهٔ تعریف رویدادهای startup و shutdown را می‌دهد که برای آماده‌سازی منابع و پاک‌سازی مفید است.

بهینه‌سازی و نکات تولید

• همیشه در تولید از workerهای متعدد استفاده کنید تا از چند هسته CPU بهره ببرید.
• از load balancer (مثل Nginx) برای مدیریت TLS، فشرده‌سازی و تایم‌اوت‌ها استفاده کنید و از گزینه –proxy-headers برای درستی IP مشتری بهره ببرید.
• محدودیت‌های Keep-Alive، timeout و حداکثر اندازهٔ هدرها را بر اساس نیاز تنظیم کنید تا محافظت در برابر حملات DoS ساده فراهم شود.
• در صورتی که عملکرد شبکه حیاتی است، از uvloop و httptools استفاده کنید (uvicorn[standard]).

مقایسهٔ کوتاه با سایر سرورها

مثال پیکربندی SSL و تنظیمات امنیتی

uvicorn app:app --host 0.0.0.0 --port 443 --ssl-keyfile /path/to/key.pem --ssl-certfile /path/to/cert.pem

در این حالت Uvicorn سرویس را مستقیم با TLS اجرا می‌کند اما توصیهٔ معمول در تولید این است که TLS را در لایهٔ معکوس (مثل Nginx یا Load Balancer) مدیریت کنید تا انعطاف‌پذیری و امکانات بیشتری داشته باشید.

خطاهای رایج و اشکال‌زدایی

• خطاهای مربوط به import: مطمئن شوید نام ماژول و اسم شیء app درست وارد شده باشد (مثلاً app:app یا package.module:app).
• عدم نصب uvloop/httptools: اگر عملکرد پایین است، نصب بستهٔ standard توصیه می‌شود.
• مشکلات مربوط به پروکسی: در صورت وجود Nginx از –proxy-headers استفاده کرده و هدرهای مربوطه را بپذیرید.

جمع‌بندی

Uvicorn یک انتخاب عالی برای اجرای برنامه‌های آسنکرون در پایتون است؛ سبک، سریع و با ادغام ساده در استک‌های مدرن مانند FastAPI. با تنظیم صحیح workerها، استفاده از uvloop و معماری مناسب پشت یک پروکسی معکوس، می‌توان به عملکرد و پایداری بسیار خوبی در محیط‌های تولید دست یافت.

اگر نیاز به نمونه پیکربندی خاص یا بررسی خطاهای اجرا دارید، می‌توان مثال‌های دقیق‌تری از فایل‌های سرویس systemd یا پیکربندی Nginx ارائه کرد.

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

ارسال