PUT или PATCH — в чём разница, и почему после смены аватара пропало имя

Пользователь меняет аватарку. Ты отправляешь на сервер новый адрес картинки: { "avatar": "cat.png" }. Аватарка обновилась. А имя и email из профиля — пропали.

Сервер не сломан. Он сделал ровно то, что ты попросил. Ты отправил запрос методом PUT, а PUT значит «вот новая версия профиля целиком». В новой версии было только поле avatar. Значит, остальных полей больше нет.

Нужен был PATCH. Разберёмся, чем они отличаются и когда какой брать.

Коротко: что делает каждый

PUT — «замени целиком». Ты отправляешь полную версию объекта, и она встаёт на место старой. Чего нет в запросе — того нет и в результате. Как заменить старый комод новым: ящики старого с собой не переезжают.

PATCH — «поправь вот это». Ты отправляешь только то, что меняется. Остальное сервер не трогает. Как починить один ящик в том же комоде.

Оба метода — часть REST API, оба меняют существующие данные. Разница в том, что значит «пусто» в теле запроса.

Сравнение по пунктам

• Что отправляешь. PUT — объект целиком, все поля. PATCH — только изменённые поля.
• Чего нет в теле. PUT — поле стирается или сбрасывается в значение по умолчанию. PATCH — поле остаётся как было.
• Повтор того же запроса. PUT идемпотентен по стандарту: отправишь десять раз — результат как от одного. PATCH — не обязательно. Запрос «добавь тег в список», отправленный дважды, добавит два тега.
• Если объекта ещё нет. PUT по стандарту может его создать — сервер ответит 201 Created. PATCH обычно ответит 404. Подробнее о кодах — в разборе HTTP-статусов.
• Размер запроса. PUT тяжелее: шлёшь всё, даже то, что не менялось. PATCH — минимум.
• Риск затереть чужое. У PUT он выше. Два человека открыли один профиль. Первый сменил имя, второй — телефон. Оба отправили PUT целиком. Второй запрос молча вернёт старое имя. С PATCH каждый правит своё поле.

Скрытые ловушки

method: "patch" строчными — и сервер отвечает 405. По стандарту Fetch браузер сам переводит в верхний регистр только шесть методов: GET, POST, PUT, DELETE, HEAD и OPTIONS. PATCH в этот список не входит. Напишешь "patch" — так строчными и уйдёт, а большинство серверов такого метода не знают. Node.js даже выводит предупреждение об этом в консоль. Браузер промолчит. Пиши "PATCH" всегда.

null в PATCH может значить «удали». Есть популярный формат JSON Merge Patch. В нём { "phone": null } не записывает в поле пустоту, а удаляет поле. Хочешь именно пустое значение — уточни, как это устроено на твоём сервере.

Обычная HTML-форма не умеет ни PUT, ни PATCH. У <form method="..."> есть только GET и POST. Поэтому фреймворки прячут настоящий метод в скрытое поле _method, а форма уходит как POST.

Оба метода вызывают предзапрос CORS. Если фронтенд и API на разных доменах, браузер сначала спросит разрешения запросом OPTIONS. Сервер должен перечислить PUT и PATCH в Access-Control-Allow-Methods. Иначе получишь ошибку CORS, хотя GET и POST работали.

На деле всё решает сервер. Стандарт описывает, как методам положено себя вести. А код сервера пишет человек. В Rails, например, PUT и PATCH ведут в одно и то же действие обновления. А в PostgREST, на котором работает API Supabase, PATCH — это обычное обновление, а PUT — вставка-или-замена одной строки. И там нужно передать все её колонки. Всегда смотри документацию конкретного API.

Кому что подойдёт

Бери PATCH, если пользователь правит часть объекта. Сменить аватарку, переключить настройку, отметить задачу выполненной. Это девять случаев из десяти в обычном приложении.

Бери PUT, если клиент действительно знает объект целиком и хочет его заменить. Сохранить документ из редактора. Загрузить файл по известному адресу. Записать настройки, которые всегда хранятся одним блоком. Плюс PUT — повторять его безопасно. Если запрос оборвался, просто отправь ещё раз.

Если ИИ сгенерировал тебе API, проверь одно: что делает обработчик обновления с полями, которых нет в запросе. Если стирает, а ты шлёшь кусочки, меняй метод или логику. Иначе получишь пропавшие имена.

Можно ли сделать всё через POST?

Можно, и многие API так и живут. Но тогда клиенту не видно, безопасно ли повторять запрос. PUT и PATCH говорят об этом самим названием.

PATCH — это всегда частичное обновление?

По смыслу — да. Но формат тела разный: где-то это простой объект с полями, где-то список операций вроде «добавь», «удали», «замени». Какой формат ждёт сервер, написано в его документации.

Что вернуть из PUT или PATCH на сервере?

Чаще всего — обновлённый объект целиком с кодом 200. Так клиенту не нужно делать лишний GET, чтобы увидеть результат. Если тело не возвращаешь, ответь кодом 204.