كيف تدير الإعدادات باستخدام Pydantic؟

Question

Accepted Answer

تدير تطبيقات FastAPI الإعدادات من خلال **`pydantic-settings`** (`BaseSettings`) — فئة تقرأ الإعدادات من **متغيرات البيئة** (وملفات `.env`) مع **التحقق من الصحة وتحويل النوع**، مما يبقي الأسرار خارج الكود ويضمن صحة الإعدادات عند بدء التشغيل.

## تحديد الإعدادات

```python
from pydantic_settings import BaseSettings

class Settings(BaseSettings):
    app_name: str = "My API"
    database_url: str                       # required — must be provided
    secret_key: str                          # required (a secret)
    debug: bool = False
    max_connections: int = 10

class Config:
        env_file = ".env"                    # also read from a .env file

settings = Settings()                        # reads & VALIDATES env vars at startup
```

تقرأ `BaseSettings` تلقائياً كل حقل من متغير البيئة المطابق (مثل `DATABASE_URL`)، وتحول الأنواع (`"true"` → `bool`، `"10"` → `int`)، و**تتحقق من الصحة** — فالقيمة المفقودة المطلوبة أو النوع الخاطئ يفشل فوراً عند بدء التشغيل برسالة خطأ واضحة (فشل سريع).

## استخدام الإعدادات (عبر حقن التبعيات)

```python
from functools import lru_cache
from fastapi import Depends

@lru_cache                              # create the Settings once (cached)
def get_settings():
    return Settings()

@app.get("/info")
def info(settings: Settings = Depends(get_settings)):
    return {"app": settings.app_name, "debug": settings.debug}
```

يجعل حقن الإعدادات عبر تبعية مخزنة مؤقتاً أنها **قابلة للاختبار** (تجاوز في الاختبارات) ويضمن نسخة واحدة فقط.

## ملف .env والأسرار

```bash
# .env — local config, GITIGNORED (never commit secrets)
DATABASE_URL=postgresql://localhost/mydb
SECRET_KEY=dev-secret
DEBUG=true
```

```text
✓ Keep secrets in env vars / .env (gitignored); commit a .env.example documenting keys
✓ In production, inject config via the platform's environment / secret manager
✓ Validation at startup catches misconfiguration immediately (not deep in a request)
```

## لماذا يهم

إدارة الإعدادات الصحيحة ضرورية **تشغيلياً** (التطبيقات تحتاج إعدادات مختلفة عبر البيئات المختلفة) و**متطلب أمان** (الأسرار مثل عناوين URL قواعد البيانات والمفاتيح يجب ألا تكون مشفرة في التحكم بالإصدار — خرق شائع وخطير).

توفر `BaseSettings` من Pydantic الحل الاصطلاحي FastAPI، وفهمها مهم كمعرفة يومية.

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

مع حقن التبعيات (جعل الإعدادات قابلة للاختبار وفردية) وممارسة ملفات `.env` المتجاهلة من git للتطوير المحلي، يعطيك هذا إعدادات آمنة ومتحققة ومناسبة للبيئة.

معرفة كيفية تحديد الإعدادات واستخدامها عبر حقن التبعيات والتعامل مع الأسرار بأمان أساسية لبناء تطبيقات FastAPI جاهزة للإنتاج.