Хотя Java не позволяет выражать null-безопасность в своей системе типов, Spring Framework теперь содержит следующие аннотации в пакете org.springframework.lang, чтобы вы могли объявлять null-безопасность API-интерфейсов и полей:

  • @Nullable: Аннотация, указывающая, что определенный параметр, возвращаемое значение или поле может быть null.

  • @NonNull: Аннотация, указывающая, что определенный параметр, возвращаемое значение или поле не может быть null (не нужна для параметров/возвращаемых значений и полей, где применяются аннотации @NonNullApi и @NonNullFields соответственно).

  • @NonNullApi: Аннотация на уровне пакета, которая объявляет значение, отличное от пустого (non-null), семантикой по умолчанию для параметров и возвращаемых значений.

  • @NonNullFields: Аннотация на уровне пакета, которая объявляет значение, отличное от пустого (non-null), семантикой по умолчанию для полей.

Java-университет

Spring Framework сам эффективно задействует эти аннотации, но они также могут быть использованы в любом Java-проекте на базе Spring для объявления null-безопасных API-интерфейсов и, по желанию, null-безопасных полей. Допустимость пустого (null) значения для аргументов универсального типа, аргументов переменной длинны (varargs) и элементов массива пока не поддерживаются, но должна быть добавлена в следующем выпуске. Актуальную информацию см. в SPR-15942. Ожидается, что объявления переменных, допускающих пустое значение, будут дорабатываться между выпусками Spring Framework, включая минорные. Допустимость пустого значения для типов, используемых внутри тела метода, выходит за область видимости этой функции.

Другие распространенные библиотеки, такие как Reactor и Spring Data, содержат null-безопасные API-интерфейсы, которые используют аналогичную организацию допустимости пустого значения, обеспечивая согласованный общий опыт работы для разработчиков приложений на Spring.

Примеры использования

В дополнение к предоставлению явного объявления допустимости пустого значения для API-интерфейса Spring Framework, эти аннотации могут быть использованы IDE (например, IDEA или Eclipse) для полезных предупреждений, связанных с null-безопасностью, что позволит избежать NullPointerException во время выполнения.

Они также используются для того, чтобы сделать API-интерфейс Spring null-безопасным в проектах Kotlin, поскольку Kotlin изначально поддерживает null-безопасность. Более подробную информацию можно найти в документации по поддержке Kotlin.

Мета-аннотации JSR-305

Аннотации Spring мета-аннотируются с помощью аннотаций из JSR 305 (не осуществляемый в данный момент, но широко распространенный JSR). Мета-аннотации из JSR-305 позволяют поставщикам инструментов, таких как IDEA или Kotlin, обеспечивать поддержку null-безопасности в общем виде без необходимости жестко кодировать поддержку аннотаций в Spring.

Нет необходимости и не рекомендуется добавлять зависимость JSR-305 в путь классов проекта, чтобы пользоваться преимуществами null-безопасного API-интерфейса Spring. Только для таких проектов, как библиотеки на базе Spring, которые используют аннотации null-безопасности в своей кодовой базе, следует добавить com.google.code.findbugs:jsr305:3.0.2 с конфигурацией compileOnly из Gradle или областью видимости provided из Maven, чтобы избежать получения предупреждений о компиляции.