Series: Axios Lesson 90

FormData — Multipart form data bilan ishlash

Axios'da FormData va multipart/form-data bilan ishlash: Content-Type boundary siri, fayllarni yuklash (File/Blob), onUploadProgress va transformRequest istisnolari.

90-dars

FormData — Multipart form data bilan ishlash

Frontend ilovalarida foydalanuvchi profil rasmini yuklash, hujjat (PDF, Excel) biriktirish yoki bir vaqtning o'zida matnli maydonlar va fayllarni yuborish talab etilganda odatiy application/json formatidan foydalanib bo'lmaydi.

Bunday vaziyatlarda brauzerning o'rnatilgan FormData obyektidan va multipart/form-data HTTP kodlash turidan foydalaniladi.


1. Axios va FormData munosabatidagi eng katta xato: Content-Type siri ⚠️

Dasturchilar fayl yuklashda yo'l qo'yadigan eng keng tarqalgan xato — bu sarlavhada Content-Type: multipart/form-data deb qo'lda yozishdir:

// ❌ QAT'IYAN TAVSIYA ETILMAYDIGAN XATO KOD:
await apiClient.post('/upload', formData, {
  headers: {
    'Content-Type': 'multipart/form-data', // 💥 XATOLIKKA OLIB KELADI!
  },
});

Nega buni qo'lda yozmaslik kerak?

multipart/form-data so'rovi yuborilayotganda brauzer har bir fayl yoki maydon orasini ajratib turuvchi maxsus tasodifiy boundary (chegara) satrini generatsiya qiladi:

Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW

Agar siz headers qismida Content-Typeni qo'lda belgilab qo'ysangiz:

  1. Brauzer yaratgan boundary=... qismi o'chib ketadi.
  2. Serverga shunchaki xom Content-Type: multipart/form-data boradi.
  3. Server ma'lumot qayerda boshlanib qayerda tugayotganini tushunmaydi va 400 Bad Request yoki 500 Internal Server Error xatosini qaytaradi.

[!CAUTION] To'g'ri yechim: Axios'ga FormData obyektini uzatsangiz, Axios va brauzer Content-Type sarlavhasini avtomatik ravishda, to'g'ri boundary bilan birga o'zi shakllantiradi. Siz shunchaki headersda Content-Typeni bo'sh qoldirishingiz kifoya!

flowchart TD
    A["FormData Obyekti\n(Matn + Fayllar)"] --> B["Axios API Chaqiruvi\napiClient.post('/upload', formData)"]
    B --> C["Brauzer Tarmoq Qatlami"]
    C -->|Avtomatik qo'shiladi| D["Content-Type: multipart/form-data;\nboundary=----WebKitFormBoundaryXYZ"]
    D --> E["Backend Server\n(Faylni muvaffaqiyatli qabul qiladi)"]

2. Amaliyot: TypeScript va Axios yordamida Fayl yuklash servisi

Keling, foydalanuvchi avatarini va uning ismini serverga yuboruvchi to'g'ri tiplashtirilgan servis yozamiz:

// src/services/fileService.ts
import { apiClient } from '../api/client';
import { AxiosProgressEvent } from 'axios';

export interface UploadProfilePayload {
  fullName: string;
  avatarFile: File; // HTML <input type="file" /> orqali tanlangan File obyekti
}

export interface UploadResponse {
  success: boolean;
  fileUrl: string;
  message: string;
}

export const FileService = {
  /**
   * Foydalanuvchi profil rasmini serverga yuklash
   */
  uploadAvatar: async (
    payload: UploadProfilePayload,
    onProgress?: (percent: number) => void
  ): Promise<UploadResponse> => {
    // 1. FormData obyektini yaratamiz
    const formData = new FormData();

    // 2. Matnli maydonlarni qo'shamiz
    formData.append('full_name', payload.fullName);

    // 3. Faylni qo'shamiz (kalit nomi backend kutayotgan parametr bilan bir xil bo'lishi kerak)
    formData.append('avatar', payload.avatarFile);

    // 4. So'rovni yuboramiz (Content-Type ni yozmaymiz!)
    const response = await apiClient.post<UploadResponse>(
      '/user/upload-avatar',
      formData,
      {
        // Fayl yuklanish jarayonini (Progress Bar) kuzatish
        onUploadProgress: (progressEvent: AxiosProgressEvent) => {
          if (progressEvent.total && onProgress) {
            const percentCompleted = Math.round(
              (progressEvent.loaded * 100) / progressEvent.total
            );
            onProgress(percentCompleted);
          }
        },
      }
    );

    return response.data;
  },
};

3. onUploadProgress — Yuklanish Jarayonini Kuzatish

Katta hajmli fayllarni yuklayotganda foydalanuvchiga progress-bar (foiz ko'rsatkichi) ko'rsatish ajoyib foydalanuvchi tajribasini (UX) ta'minlaydi.

Axios buning uchun o'rnatilgan onUploadProgress xossasiga ega:

// React komponenti ichida ishlatish misoli:
const handleUpload = async (file: File) => {
  try {
    const result = await FileService.uploadAvatar(
      { fullName: 'Anvar Narzullayev', avatarFile: file },
      (percent) => {
        console.log(`Yuklandi: ${percent}%`);
        setUploadProgress(percent); // UI dagi progress bar holatini yangilash
      }
    );
    alert('Fayl muvaffaqiyatli yuklandi: ' + result.fileUrl);
  } catch (error) {
    console.error('Yuklashda xatolik:', error);
  }
};

4. transformRequest bilan Ehtiyot Bo'lish (FormData Istisnosi)

88-darsda biz transformRequest orqali barcha yuborilayotgan obyekt kalitlarini avtomatik ravishda snake_case qilishni ko'rib chiqqan edik.

[!WARNING] Agar so'rov tanasi (data) FormData bo'lsa, uni oddiy JavaScript obyekti kabi JSON.stringify yoki rekursiv kalit o'zgartirish funksiyalariga uzatib bo'lmaydi!

Shuning uchun apiClient konfiguratsiyasida har doim FormData tekshiruvini qo'shish shart:

// src/api/client.ts
apiClient.defaults.transformRequest = [
  (data, headers) => {
    // ⚠️ AGAR DATA FORMDATA BO'LSA, UNGA TEGINMAYMIZ!
    if (data instanceof FormData) {
      return data;
    }

    // Oddiy JSON obyektlar uchun transformatsiya
    return transformKeysToSnakeCase(data);
  },
  ...(axios.defaults.transformRequest as any),
];

5. Bir nechta fayllar (Multiple Files) bilan ishlash

Agar foydalanuvchi birdaniga bir nechta fayllarni (masalan, fotogalereya) yuklayotgan bo'lsa, FormDataga quyidagicha qo'shiladi:

const formData = new FormData();

// Bir xil kalit nomi bilan bir nechta faylni biriktirish (backend massiv sifatida qabul qiladi)
files.forEach((file) => {
  formData.append('images[]', file);
});

// Yoki alohida nom bilan:
// files.forEach((file, index) => formData.append(`file_${index}`, file));

6. JSON vs FormData Taqqoslovi

Mezon application/json multipart/form-data (FormData)
Ma'lumot turi Matn, son, massiv, oddiy obyektlar Binary fayllar (rasm, video, pdf) + matn
Hajm samaradorligi Matn uchun juda ixcham Binar fayllar uchun optimal
Content-Type Avtomatik application/json Avtomatik boundary bilan birga
Qo'lda header yozish Shart emas Qat'iyan yozilmaydi (boundary buzilmasligi uchun)
Progress kuzatish Kichik hajmda sezilmaydi onUploadProgress orqali foizini kuzatish mumkin

Xulosa

Axios orqali fayllar va multipart ma'lumotlarni yuborishda eng asosiy qoida — Content-Type: multipart/form-data sarlavhasini qo'lda yozmaslikdir.

Brauzerning FormData APIsi, onUploadProgress monitoringi va to'g'ri TypeScript tiplashtirishidan foydalanish orqali fayl yuklash amaliyotini professional va barqaror amalga oshirish mumkin.