[Java] 올바른 Optional 사용으로 API 설계하기

API를 설계할 때, 사용자가 메서드 시그니처만 보고도 반환값이 선택형인지, 즉 값이 존재하지 않을 수 있음을 쉽게 인지할 수 있다면 훨씬 안전하고 명료한 API를 제공할 수 있을 것이다. 이 글에서는 Java 8부터 도입된 Optional 클래스를 활용해 API 설계의 명확성을 높이고, NullPointerException과 같은 오류를 예방하는 방법에 대해 알아보려 한다.

1. Optional의 기본 개념

public final class Optional<T>
extends Object

A container object which may or may not contain a non-null value. - 공식 문서 정의

Java 8 부터 도입된 Optional<T>는 null이 될 수 있는 값을 감싸는 래퍼(wrapper) 클래스다. 값이 존재할 수도, 존재하지 않을 수도 있는 컨테이너 객체로서, null 참조 대신 사용함으로써 NPE(NullPointerException)를 방지하고 코드의 가독성을 높여준다.

• 값이 존재하는 경우: 실제 객체를 Optional로 감싸 반환
• 값이 없을 경우: Optional.empty()와 같이 비어있는 Optional 인스턴스를 반환

예를 들어, Optional<Car>의 경우 차 객체가 존재하면 그 값을 감싸 반환하며, 그렇지 않은 경우 빈 Optional을 반환하여 null 대신 안전한 방식으로 “값 없음”을 표현한다.
이러한 접근 방식은 API 사용자에게 메서드 호출 시 null 체크의 필요성을 컴파일 타임에 인지하도록 도와줄 수 있다.

2. API 설계에 Optional 적용하기

잘 설계된 API는 메서드 시그니처만 보고도 해당 메서드가 반환하는 값이 반드시 존재하는지, 아니면 선택형인지 명확히 알 수 있어야 한다.
아래 두 가지 선언을 비교해보자.

• 필수 값 반환
  • public String getName();
  • 이 경우, 값이 반드시 존재해야 하며, 만약 내부적으로 null이 발생한다면 NullPointerException으로 이어질 수 있다.
• 선택형 값 반환
  • public Optional<String> getName();
  • Optional을 반환함으로써, API 사용자는 반환 값이 없을 가능성도 함께 고려할 수 있게 된다. 이를 통해 불필요한 null 체크를 줄이고, 함수형 프로그래밍 스타일의 다양한 메서드(map, filter, ifPresent 등)를 활용할 수 있다.

3. Optional의 생성 및 사용

Optional 클래스는 세 가지 정적 팩토리 메서드로 인스턴스를 생성한다.

• Optional.empty(): 빈 Optional 인스턴스를 반환
  • Optional<Car> emptyCar = Optional.empty();

• Optional.of: 반드시 null이 아닌 값을 전달해야 하며, 만약 null이 전달되면 즉시 NullPointerException이 발생한다.
  • Optional<Car> optCar = Optional.of(car); //car가 null일 경우 NullPointerException 발생!
  • 이는 초기 단계에서 오류를 노출시켜 문제를 조기에 해결하도록 도와준다.
• Optional.ofNullable: 값이 null일 가능성이 있을 때 사용하며, null이면 빈 Optional 객체(Optional.empty())를 반환한다.
  • Optional<Car> optCar = Optional.ofNullable(car);
  • 이 방식을 통해 null 체크를 보다 명시적이고 안전하게 처리할 수 있다.
• 추가적으로, 기존의 null 체크 패턴을 대체하기 위해 Optional의 map 메서드를 활용할 수 있다.
  • Optional<Insurance> optInsurance = Optional.ofNullable(insurance); // null일 수 있음(null 체크 필요)
    Optional<String> name = optInsurance.map(Insurance::getName); 
  • 이 방식은 insurance가 null이 아닌 경우에만 getName()을 호출하고, null인 경우 빈 Optional을 그대로 반환한다.

 

4. Optional을 활용한 API 설계의 장점

4.1. 명시적 의도 표현

메서드 시그니처에 Optional을 사용하면, 해당 값이 선택적임을 명시적으로 표현할 수 있다.

• API 사용자 인식: 반환 타입을 통해 사용자는 값이 없을 수 있음을 인지하고, 적절한 예외 처리나 대체 로직을 구현할 수 있게 된다.

4.2. 코드 가독성과 유지보수성 향상

Optional은 null 체크를 위한 불필요한 if 문을 줄여 코드의 가독성을 높여준다.

• 함수형 스타일: map, flatMap, filter 등의 메서드를 사용해 더욱 선언적인 코드 작성이 가능해진다.
• 에러 발생 시점: Optional.of를 사용하면 null 전달 시점에 오류가 발생하여, 문제의 원인을 빠르게 파악할 수 있다.

 

5. Optional 사용 시 고려해야 할 사항

5.1. 과도한 남용 방지

Optional은 반환 타입에서의 사용이 권장되며, 필드나 컬렉션 요소로 사용하는 것은 피하는 것이 좋다. (필드로 사용했을때  발생 가능한 문제점은 아래에 추가로 정리하였다.)

• 메모리 오버헤드: Optional 객체는 래퍼(wrapper) 클래스이므로 불필요하게 남용할 경우 메모리 오버헤드가 발생할 수 있다.

5.2. get() 메서드 사용 주의

Optional의 get() 메서드를 사용하면, 값이 없을 경우 NoSuchElementException이 발생한다.

• 대안: orElse, orElseThrow, ifPresent 등의 메서드를 활용해 보다 안전하게 값을 다룰 수 있다.

5.2. Value-Based Class 특성 유의

 Value-Based Class는 다음과 같은 특성을 갖는다.

• 식별성 없음(No identity): 인스턴스가 고유한 식별성을 갖지 않음
• 불변성(Immutability): 생성 후 상태가 변경되지 않음
• 값 중심(Value-oriented): 참조가 아닌 값으로 취급됨

Optional은 value-based class이기 때문에 다음과 같은 작업은 피해야 한다.

This is a value-based class; use of identity-sensitive operations (including reference equality (==), identity hash code, or synchronization) on instances of Optional may have unpredictable results and should be avoided. -  공식 문서 참고

• 동일성 검사 (==) 사용 금지 (identity-sensitive 연산 시 예측 불가능한 결과가 발생할 수 있다.)
• 즉, 메모리 주소가 아닌 내부 상태(값)을 기반으로 연산한다는 점에 유의해야 한다.
• Optional의 equals()는 내부 값의 equals()를 비교하여 기대하는 결과를 얻을 수 있다. (equals()/hashCode() 정의 필요)

Optional<String> opt1 = Optional.of("value");
Optional<String> opt2 = Optional.of("value");

// 문제가 될 수 있는 코드
boolean result = (opt1 == opt2); // 예측 불가능한 결과

// 대신 .equals() 사용
boolean safeResult = opt1.equals(opt2); // 올바른 비교 방법

• JVM은 value-based class의 최적화를 위해 같은 값을 가진 인스턴스를 내부적으로 캐시하여 동일한 참조로 처리할 수 있다. 하지만 이는 보장된 동작이 아니므로 == 연산자 사용은 지양해야 한다. (JVM은 value-based class에 대해 인스턴스 풀링, 인라이닝, 스칼라 대체 등 다양한 최적화를 수행할 수 있는데 JVM 구현/버전에 따라 식별성 기반 연산의 결과가 예측 불가능해질 수 있다고 한다.)
• identityHashCode()를 사용하거나 Optional 인스턴스를 동기화의 대상으로 삼는 것 역시 내부 구현에 따라 예측할 수 없는 결과를 초래할 수 있으므로 피해야 한다.
• 즉, Optional 비교시 equals()나 hashCode() 메서드를 사용해야 하며, 동기화 블록의 모니터 객체로 사용하지 않는 것이 권장된다.
• Optional 인스턴스 자체는 새로 생성되지만, 내부 값의 참조는 원본 객체를 그대로 유지한다. (아래 예시 참고)

StringBuilder sb1 = new StringBuilder("A");
StringBuilder sb2 = sb1;  // 동일 객체 참조

Optional<StringBuilder> opt1 = Optional.of(sb1);
Optional<StringBuilder> opt2 = Optional.of(sb2);

System.out.println(opt1.get() == opt2.get());  // true
sb1.append("B");  // 가변 객체 수정
System.out.println(opt1.get());  // "AB" 출력 (동일 객체 상태 변경)
System.out.println(opt2.get());  // "AB"
System.out.println(opt1.get() == opt2.get()); //true

5.3. API 문서화

Optional을 사용한 메서드의 경우, API 문서에 값이 없는 상황에 대한 처리를 명확하게 기술해 두는 것이 권장된다.

 

정리

Optional 클래스의 사용은 API 설계에 있어 null 안전성과 명시적 의도를 표현하는 효과적인 방법이다.

• 명확성 제공: 메서드 시그니처만으로도 반환값의 선택적 특성을 파악할 수 있게 하여, API 사용자가 발생 가능한 문제를 미리 인지하고 대응할 수 있도록 한다.
• 함수형 프로그래밍 지원: 다양한 함수형 연산을 활용함으로써 코드의 가독성과 유지보수성을 높이며, 개발자가 보다 선언적인 방식으로 로직을 구현할 수 있다.

---

6. Optional을 사용을 지양해야 되는 경우

6.1. 클래스 필드로 사용 지양

Optional은 Serializable 인터페이스를 구현하지 않기 때문에 직렬화가 필요한 클래스의 필드로 사용하면 문제가 발생할 수 있다.

(Serializable을 구현하지 않았으며 final 클래스이기 때문에 서브클래싱을 통한 직렬화 구현도 불가)

도메인 모델 설계시 Optional을 사용하지 말라는 의견이 많았지만,

"모던 자바 인 액션"의 저자는 직렬화가 필요한 필드에서는 Optional 대신 원시 타입 또는 nullable 타입을 사용하고, Optional로 값을 반환받을 수 있는 메서드를 추가하는 방식으로라도 Optional을 도메인 모델에 사용하는 것을 긍정적으로 생각하는 것 같다. (아래 참고) 

 

// 안티 패턴: 필드로 Optional 사용
public class User {
    private String name;
    private Optional<Address> address; // 직렬화 문제 발생 가능
}

// 올바른 설계
public class User {
    private String name;
    private Address address; // address는 null일 수 있음

    public Optional<Address> getAddress() {
        return Optional.ofNullable(address);
    }
}

 

기본 Jackson 설정으로 Optional 필드를 직렬화하면 java 8에서는 {"present":true}, java 15에서는 {"empty":false,"present":true}과 같이 예상과 다른 결과가 나오고, 역직렬화 시에는 MismatchedInputException, InvalidDefinitionException 등의 예외가 발생했다고한다.

 

Optional을 필드로 사용하며 이러한 직렬화 문제는 Jackson-datatype-jdk8 의존성 추가를 통해 Optional 값을 일반 객체로 처리하는 기능을 제공한다고 한다.

Jackson이 비어 있는 객체를 null로, 값이 있는 객체는 해당 값을 포함하는 필드로 처리한다는 것을 의미한다. (jackson-modules-java8 프로젝트 링크 참고) https://github.com/FasterXML/jackson-modules-java8

 

 

그러나 JSON에서 null을 Optional.empty()로 변환하지 않고 Optional 자체를 null로 초기화하기 때문에 여전히 null 처리 논리 충돌하는 문제가 존재한다.

문제 발생 가능 시나리오

{"something": null} → something 필드가 null (Optional.empty() 아님)

// 예상: Optional.empty()

// 실제: Test.something = null → NPE 발생 가능

조사 결과 Jdk8Module + NON_ABSENT + 기본값 초기화의 방법으로 일반적인 null 방지가 가능하지만 JSON에서 명시적으로 null 전송 시 커스텀 역직렬화가 필요해 보인다.

https://stackoverflow.com/questions/75844408/how-to-make-jackson-deserialize-explicit-null-to-optional-empty-but-not-to-seri

 

 이러한 여러 문제 발생 가능성을 숙지했다면 도메인 설계시에는 필요한 경우 제한적으로 사용할 수 있겠지만, 개인적으로는 아직 알지 못하는 여러 문제가 내제되어 있는 것 같아 아예 Optional을 사용하지 않는 것이 좋다고 생각한다.

 

6.2. 생성자나 메서드의 매개변수로 사용 지양

Optional을 매개변수로 사용하면 코드가 불필요하게 복잡해질 수 있다.

// 안티 패턴: 매개변수로 Optional 사용
User user = new User("john@gmail.com", "1234", Optional.empty());

// 권장
User user = new User("john@gmail.com", "1234", null);
// 다른 대안: 빌더 패턴이나 오버로드된 생성자 사용
User user = new User.Builder()
    .email("john@gmail.com")
    .password("1234")
    .build();

 

6.3. 컬렉션에 대한 Optional 사용 지양

빈 컬렉션을 반환하는 것이 일반적으로 권장된다.

// 안티 패턴
public Optional<List<User>> getUsers() { ... }

// 빈 리스트 반환
public List<User> getUsers() {
    return users != null ? users : Collections.emptyList();
}

 

7. orElse vs orElseGet 의 올바른 사용

orElse는 항상 평가되지만, orElseGet은 Optional이 비어있을 때만 평가된다.

// 항상 createDefaultUser()가 호출됨
User user = userOpt.orElse(createDefaultUser());

// Optional이 비어있을 때만 createDefaultUser()가 호출됨
User user = userOpt.orElseGet(() -> createDefaultUser());

 

7.1. orElse 사용 시나리오- 즉시 평가

User user = userOpt.orElse(createDefaultUser());

 

• step 1: createDefaultUser()가 먼저 호출되어 기본 사용자 객체를 생성
• step 2: 생성된 기본 사용자 객체가 인자로 전달
• step 3: userOpt가 값을 가지고 있다면, 그 값이 반환되지만 이미 createDefaultUser()가 호출되어 비용이 발생
• step 4: 만약 userOpt가 비어있다면, 인자로 전달된 기본 사용자 객체가 반환

즉, 항상 createDefaultUser()가 실행되므로, 실제로 기본값이 필요 없더라도 불필요한 연산과 부수 효과가 발생할 수 있음을 인지하자.

 

 

orElse 사용이 적절한 케이스

간단하고 비용이 낮은 경우
만약 기본값이 이미 준비되어 있거나, 생성 비용이 극히 낮고 부수 효과가 전혀 없다면 orElse를 사용하는 것이 코드가 간결해지는 장점이 있다. 예를 들어, 상수 값이나 미리 계산된 값이라면 굳이 지연 평가를 위해 orElseGet을 쓸 필요가 없다.

 

+ 기본값 생성 비용이 낮다고 판단할 수 있는 경우

• 단순 객체 생성
  예를 들어, 단순 생성자를 호출하여 새로운 객체를 만드는 경우(예: new User("default", "default@example.com"))처럼 연산이 매우 가볍고 메모리 할당 비용이 미미한 경우 사용을 고려해볼 수 있다.
• 계산이나 외부 연산이 없는 경우
  기본값을 생성할 때 네트워크 요청, 파일 입출력, 데이터베이스 접근, 복잡한 계산 등의 무거운 연산이 전혀 포함되어 있지 않다면, 이 경우는 기본값 생성 비용이 낮다고 볼 수 있다.
• 부수 효과가 없는 순수 메서드
  기본값을 만드는 메서드가 순수 메서드라면, 즉 입력이 같으면 항상 같은 결과를 반환하고 외부 상태나 부수 효과(로그, 상태 변경 등)를 발생시키지 않는다면 비용 부담이 낮다고 판단할 수 있다.

7.2. orElseGet 사용 시나리오 - 지연 평가

User user = userOpt.orElseGet(() -> createDefaultUser());

 

• step 1: 먼저 userOpt 내부의 값이 있는지 확인
• step 2: 만약 userOpt가 값을 가지고 있다면, 그 값이 바로 반환되고 람다 함수는 호출되지 않음
• step 3: 만약 userOpt가 비어있다면, 람다 함수 내의 createDefaultUser()가 호출되어 기본 사용자 객체를 생성한 후 반환

 

따라서 orElseGet 사용 시, Optional이 비어있을 때만 createDefaultUser()가 실행되어 불필요한 연산과 부수 효과를 피할 수 있다.

 

orElse Get 사용이 적절한 케이스

비용과 부수 효과가 높은 경우

기본값을 생성하는 과정이 복잡하거나 외부 자원을 사용하는 경우, 혹은 부수 효과가 발생할 수 있는 상황에서는 orElseGet을 사용해야한다. orElseGet은 Optional이 비어있을 때만 Supplier의 코드를 실행하므로 불필요한 오버헤드 방지와 메서드 호출로 인한 의도치 않는 결과를 방지할 수 있다. 

위의 예시의 createDefaultUser()가 만약 기본 데이터를 불러오기 위해 데이터베이스 접근이나 외부 API 호출을 포함한다면, userOpt에 값이 존재할 때 해당 메서드가 호출되지 않도록 하는 것이 성능 면에서 유리할 것이다.

 

 

참고 자료 :

모던 자바 인 액션

https://docs.oracle.com/javase/8/docs/api///?java/util/Optional.html

Java Platform SE 8

 

https://dzone.com/articles/java-8-optional-usage-and-best-practices

Java 8 Optional Usage and Best Practices

https://nipafx.dev/java-value-based-classes/

Value-Based Classes // nipafx

https://www.baeldung.com/java-optional-or-else-vs-or-else-get

https://github.com/FasterXML/jackson-modules-java8

GitHub - FasterXML/jackson-modules-java8: Set of support modules for Java 8 datatypes (Optionals, date/time) and features (param

https://www.codekru.com/java/java-optional-with-jackson