როგორ ხდება ფორმის მონაცემების და ფайლის ატვირთვის დამუშავება?

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` არის რეკომენდირებული ტიპი — ეს არის spooled ფაილი (დიდი ფაილები მიდის დისკზე, არა მთლიანად მეხსიერებაში), async მეთოდებით (`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
```

## რატომ აქვს მნიშვნელობა

ფორმის მონაცემების და ფაილის ატვირთვის დამუშავება ჩვეულებრივი, პრაქტიკული საჭიროება — შესვლის ფორმები, პროფილის სურათის ატვირთვები, დოკუმენტების წარდგენა და ფაილ-დამუშავების API-ები ყველა ის საჭიროებს, და ეს განსხვავებულად მუშაობს JSON სხეულებისგან, რომელსაც FastAPI ნაგულისხმევად იყენებს.

`Form()` გაგება ფორმის ველებისთვის და განსაკუთრებით **`UploadFile`** ატვირთვებისთვის (რეკომენდირებული მიდგომა, რადგან ეს spools დიდ ფაილებს დისკზე და არა ყველაფრის მეხსიერებაში ჩატვირთვას — მნიშვნელოვანი დიდი ფაილების დამუშავებისთვის RAM-ის ამოწურვის გარეშე) აუცილებელია ამ ფუნქციების წინააღმდეგ.

თანაბრად მნიშვნელოვანია **უსაფრთხოების ვალდებულება**, რომელიც მოდის ატვირთვებთან: რადგან ატვირთული ფაილები უნდობელი შეყვანაა, მათი ტიპის და ზომის ვალიდაცია, ფაილების სახელების დეზინფექცია და ზრუნვა როგორ შეინახოთ/მოგემსახuropთ ისინი აუცილებელია სიმ취vulnerability-ების თავიდან ასაცილებლად.

ცოდნა ფორმის ველების მიღების, ერთი და მრავალი ფაილის ატვირთვის დამუშავების, ფორმების და ფაილების კომბინირების და ატვირთვების უსაფრთხოდ ვალიდაციის შესახებ არის პრაქტიკული ცოდნა ნამდვილი მსოფლიოს API-ების აგებისთვის, რომლებიც იღებენ მომხმარებლის მიერ წარდგენილ კონტენტს.