Как сервер понимает, что нужно отдать файл на скачивание, а не просто вернуть сущность (например, при скачивании PDF)?

Когда сервер возвращает файл, браузер по умолчанию ориентируется на заголовок Content-Type. Если это application/pdf, современные браузеры обычно открывают PDF во встроенном просмотрщике, а не скачивают. Чтобы заставить браузер именно скачать файл, сервер добавляет заголовок Content-Disposition со значением attachment.

Как это работает

Заголовок Content-Disposition имеет два основных значения:

• inline — отобразить содержимое прямо в браузере (значение по умолчанию для многих типов).
• attachment — предложить пользователю сохранить файл, обычно с указанным именем.

Дополнительно можно указать имя файла через параметр filename или filename* (для UTF-8 имён).

Пример на Node.js (Express)

app.get('/download', (req, res) => {
  const filePath = './files/report.pdf';
  res.setHeader('Content-Type', 'application/pdf');
  res.setHeader(
    'Content-Disposition',
    'attachment; filename="report.pdf"'
  );
  res.sendFile(filePath);
});

Пример на Python (FastAPI)

from fastapi import FastAPI
from fastapi.responses import FileResponse

app = FastAPI()

@app.get('/download')
def download():
    return FileResponse(
        'report.pdf',
        media_type='application/pdf',
        filename='report.pdf'
    )

В обоих примерах ключевой момент — заголовок Content-Disposition: attachment. Без него браузер, скорее всего, откроет PDF во вкладке. С ним — покажет диалог сохранения.

Также важно правильно указывать Content-Type: он помогает браузеру понять тип данных и корректно обработать файл после скачивания. Для неизвестных типов используют application/octet-stream, что почти всегда приводит к скачиванию.

Итог: чтобы сервер отдавал файл на скачивание, нужно установить заголовок Content-Disposition: attachment (с именем файла) и корректный Content-Type. Это стандартный способ управления поведением браузера при получении файлов.