Краткий ответ

Map.put возвращает предыдущее значение, но null означает сразу два возможных состояния: ключ отсутствовал либо ключ существовал и был связан с null. Поэтому по одному результату put нельзя надёжно определить, была ли заменена запись; для этого отдельно проверяют наличие ключа через containsKey.

Исторический контекст

Контракт Map разделяет понятия ключа и значения и допускает реализации с поддержкой null. Это позволяло моделировать отсутствие значения непосредственно через null, но создало неоднозначность для методов, возвращающих значение как признак состояния.

Поэтому API карт обычно предоставляет отдельные операции проверки наличия ключа. Такой подход сохраняет совместимость с картами, где null является допустимым значением, не заставляя put возвращать дополнительный объект-статус.

Постановка проблемы

Предположим, код трактует результат put как признак того, что прежняя запись существовала. Если результат равен null, нельзя сделать однозначный вывод: запись могла отсутствовать или содержать null.

Ошибка особенно опасна в кэшах, обработчиках обновления и коде аудита. Программа может ошибочно посчитать замену новой вставкой либо, наоборот, пропустить факт изменения существующей записи.

Подробное решение

Согласно контракту Map.put, метод возвращает значение, ранее связанное с ключом, либо null, если отображения для ключа не было. Если карта допускает null-значения, этот результат неоднозначен.

Надёжная проверка состоит из двух независимых операций: сначала определяется наличие ключа через containsKey, затем при необходимости анализируется результат put. В многопоточном коде раздельные вызовы не образуют атомарную проверку: между ними другой поток может изменить карту, поэтому нужна соответствующая атомарная операция конкурентной реализации или внешняя синхронизация.

Если прикладная логика не различает «ключ отсутствует» и «ключ присутствует со значением null», можно использовать только результат put. Но если эти состояния имеют разный смысл, необходимо явно учитывать контракт Map.

Map<String, String> map = new HashMap<>();
map.put("a", null);

String previous = map.put("a", "новое значение");
boolean existed = map.containsKey("a");

System.out.println(previous == null); // true
System.out.println(existed);          // true

Здесь previous == null не означает, что ключ отсутствовал: он существовал, но прежнее значение было null.

Ситуация из практики

В обработчике обновления профиля нужно записать новое значение и отправить событие «поле изменено» только для уже существующего поля. Простая проверка результата put ошибочно классифицирует запись со старым значением null как новую.

Вариант с предварительным containsKey корректен для обычной однопоточной HashMap, но добавляет отдельный поиск и не является атомарным в многопоточном сценарии. Вариант с запретом null на уровне доменной модели устраняет неоднозначность, но может быть несовместим с требованиями данных.

Практическое решение — явно запретить null, если он не несёт самостоятельного смысла. Если null допустим, код должен различать наличие ключа и его значение; для конкурентного доступа эту логику следует выполнять под нужной синхронизацией или заменить на подходящую атомарную операцию. В результате события формируются корректно, включая переход значения из null в ненулевое.

Что кандидаты часто упускают

Одинакова ли эта неоднозначность для Map.get и Map.put?

Да, если карта допускает null. get возвращает null и при отсутствии ключа, и при наличии ключа со значением null, поэтому для различения также нужен containsKey. У put неоднозначность относится не к новому, а к предыдущему значению.

Можно ли устранить проблему, проверив put до containsKey?

Нет. После put информация о прежнем состоянии уже доступна только в неоднозначной форме: null не раскрывает, существовала ли запись. Проверка containsKey после операции покажет уже новое состояние, а не гарантированно прежнее; кроме того, в многопоточном коде результат может быть изменён другим потоком.

Почему нельзя всегда заменить проверку на сравнение результата put с новым значением?

Возвращается прежнее значение, а не признак успешной вставки и не новое значение. Сравнение с новым значением не определяет отсутствие ключа, особенно если значения равны по equals, а при null снова возникает неоднозначность. Для определения прежнего наличия ключа нужен отдельный контрактный механизм, например containsKey, либо операция, специально предназначенная для атомарного условного обновления.