كيف تتعامل مع بيانات النماذج وتحميل الملفات؟

Question

Accepted Answer

يتعامل FastAPI مع **بيانات نموذج HTML** (`Form`) و**تحميل الملفات** (`File`/`UploadFile`) — وهي مختلفة عن أجسام JSON، لأنها تستخدم أنواع محتوى مختلفة (`multipart/form-data`). يتم التصريح عن كليهما بأنواع معاملات خاصة.

## حقول النموذج

```python
from fastapi import Form

@app.post("/login")
def login(username: str = Form(), password: str = Form()):   # form fields, not JSON
    # data comes as application/x-www-form-urlencoded or multipart/form-data
    return {"username": username}
```

استخدم `Form()` لاستقبال حقول نموذج HTML (على سبيل المثال نموذج تسجيل الدخول). ملاحظة: يمكن للمسار أن يستخدم إما جسم JSON **أو** بيانات نموذج، وليس كليهما، لأنهما أنواع محتوى مختلفة. (يتطلب تثبيت `python-multipart`.)

## تحميل الملفات

```python
from fastapi import File, UploadFile

@app.post("/upload")
async def upload(file: UploadFile):                  # a single file
    contents = await file.read()                      # read the file's bytes
    file.filename                                      # original name
    file.content_type                                  # MIME type
    # save it:
    with open(f"uploads/{file.filename}", "wb") as f:
        f.write(contents)
    return {"filename": file.filename, "size": len(contents)}
```

`UploadFile` هو النوع الموصى به — إنه ملف مجمع (الملفات الكبيرة تذهب إلى القرص، وليس كلها في الذاكرة)، مع طرق غير متزامنة (`read`، `write`، `seek`) وبيانات وصفية. استخدمه بدلاً من `bytes` الخام لأي شيء ما عدا الملفات الصغيرة جداً.

## ملفات متعددة ونموذج + ملف معاً

```python
@app.post("/upload-many")
async def upload_many(files: list[UploadFile]):       # multiple files
    return [f.filename for f in files]

@app.post("/profile")
async def profile(name: str = Form(), avatar: UploadFile = File()):
    # combine form fields AND a file upload in one multipart request
    ...
```

## التحقق من الملفات المرفوعة (الأمان!)

```python
if file.content_type not in ["image/jpeg", "image/png"]:   # check type
    raise HTTPException(400, "Invalid file type")
# also: limit file SIZE, sanitize filenames, scan content — uploads are untrusted input
```

## لماذا يهم

التعامل مع بيانات النماذج وتحميل الملفات هو احتياج عملي شائع — نماذج تسجيل الدخول، وتحميل صور الملف الشخصي، وتقديم المستندات، وواجهات برمجية لمعالجة الملفات كلها تتطلبها، وتعمل بشكل مختلف عن أجسام JSON التي يستخدمها FastAPI بشكل افتراضي.

فهم `Form()` لحقول النموذج والأهم من ذلك **`UploadFile`** للملفات المرفوعة (الطريقة الموصى بها، لأنها تجمع الملفات الكبيرة على القرص بدلاً من تحميل كل شيء في الذاكرة — وهو مهم للتعامل مع الملفات الكبيرة دون استنزاف RAM) ضروري لهذه الميزات.

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

معرفة كيفية استقبال حقول النموذج، والتعامل مع تحميلات ملفات فردية ومتعددة، ودمج النماذج مع الملفات، والتحقق من المرفوعات بأمان هي معرفة عملية لبناء واجهات برمجية حقيقية تقبل محتوى مُرسل من المستخدم.