Java - 메서드 인수에서 NotNull 주석 사용

참조형 메서드 인수에 @NotNull을 붙여 호출자가 값을 제공해야 한다는 계약을 문서화할 수 있습니다. 이 애너테이션은 계약을 나타내지만, 그 자체로 null을 거부하거나 검증을 수행하지는 않습니다. 이 예제에서는 선언 방법과 별도의 강제 적용이 무엇을 의미하는지 설명합니다.

@NotNull 주석 개요

@NotNull은 값이 null이 아니어야 한다는 의미를 나타내기 위해 Java 라이브러리에서 제공하는 애너테이션입니다. 소스 코드와 문서에서 API 계약을 더 쉽게 확인할 수 있게 하며, 해당 애너테이션을 이해하는 도구도 활용할 수 있습니다. 정확한 패키지와 동작은 애너테이션을 제공하는 라이브러리에 따라 다르므로, 모든 @NotNull이 같은 방식으로 구현되어 있다고 가정하지 말고 프로젝트에서 지원하는 애너테이션을 사용하세요.

애너테이션을 선언해도 Java의 타입 시스템은 바뀌지 않으며, 변수가 null을 가질 수 없게 되는 것도 아닙니다. 메서드가 null이 아닌 값을 반환한다고 보장하거나, null을 전달하면 예외가 발생한다고 보장하지도 않습니다. 런타임에서 적용하려면 애너테이션이 붙은 값을 검사하거나 검증하도록 별도의 메커니즘을 구성해야 합니다. 그 메커니즘과 동작 방식은 이 선언만 다루는 예제의 범위에 포함되지 않습니다.

주요 이점은 메서드 작성자와 호출자 사이의 의도를 더 명확하게 전달하는 것입니다. 코드에서 확인할 수 있는 null 아님 계약은 독자가 의도된 입력을 이해하는 데 도움이 되며, 호환되는 정적 분석 도구나 프레임워크 도구에서도 활용될 수 있습니다. 유용한 문서 역할을 하지만, 애플리케이션에서 실제로 강제해야 하는 입력 검사를 대신하지는 않습니다.

메서드 인수에서 @NotNull 주석 사용

String과 같은 참조형 매개변수 바로 앞에 애너테이션을 붙입니다. 다음은 선언만 보여 주는 예시이므로, 프로젝트에서 사용하는 라이브러리와 import를 선택하세요.

public void createUser(@NotNull String username) { ... }

여기서 username은 메서드 인수이며, @NotNull은 호출자가 null이 아닌 문자열을 전달해야 한다는 의미를 나타냅니다. String은 참조형이므로 별도의 검사나 구성된 메커니즘이 거부하지 않는 한 Java에서 null을 받을 수 있습니다. int와 같은 기본형에는 null을 전달할 수 없으므로 이 계약을 설명하는 예로 적합하지 않습니다.

프로젝트에서 강제가 필요하다면 선택한 애너테이션을 지원하는 메커니즘을 구성하고 실행해야 합니다. 애너테이션을 import하거나 매개변수에 적는 것만으로는 검증이 수행되지 않습니다. 위 선언에는 의존성, 제공자, 호출 경로 또는 런타임 결과가 연결되어 있지 않습니다. 이런 선택은 프로젝트마다 다르며 여기서는 다루지 않습니다.

이 계약을 통해 의도를 검토하고 유지 관리하기 쉽게 전달하세요. 호출자는 실제 사용자 이름을 전달해야 하며, 애플리케이션에 필요하다면 메서드 자체에서도 입력을 검사할 수 있습니다. 같은 단순 이름을 가진 애너테이션도 서로 다른 라이브러리에서 제공되어 도구 지원이 다를 수 있으므로, 코드베이스 전체에서 애너테이션의 패키지를 일관되게 유지하세요.