Interface Result<T>

Type Parameters:
T - value type - 值类型
All Known Implementing Classes:
Result.Failure, Result.Success
public sealed interface Result<T> permits Result.Success<T>, Result.Failure<T>
Result Monad - Represents the outcome of a computation that may succeed or fail Result Monad - 表示可能成功或失败的计算结果

A sealed type that contains either a Success value or a Failure with a Throwable cause. This provides a functional alternative to try-catch for error handling.

一个密封类型，包含 Success 值或带有 Throwable 原因的 Failure。 这为错误处理提供了 try-catch 的函数式替代方案。

Features | 主要功能:

  • Type-safe error handling without exceptions - 无需异常的类型安全错误处理
  • Monadic operations (map, flatMap) with automatic error catching - 自动捕获错误的 Monad 操作
  • Recovery operations - 恢复操作
  • Safe value extraction - 安全的值提取
  • Conversion to Optional and Stream - 转换为 Optional 和 Stream

Usage Examples | 使用示例:

// Wrapping a checked operation
Result<String> result = Result.of(() -> Files.readString(path));

// Chaining operations (errors caught automatically in map)
Result<Integer> length = result
    .map(String::trim)
    .map(String::length);

// Recovery
String value = result
    .recover(ex -> "default")
    .getOrElse("fallback");

// Pattern matching with switch (JDK 25)
switch (result) {
    case Result.Success(var v) -> process(v);
    case Result.Failure(var e) -> handleError(e);
}

Security | 安全性:

  • Thread-safe: Yes (immutable records) - 线程安全: 是 (不可变记录)
  • Failure.toString() hides stack traces for security - Failure.toString() 隐藏堆栈跟踪以保证安全
Since:
JDK 25, opencode-base-core V1.0.3
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static final record 
    Result.Failure<T>
    Failure - Represents a failed computation result Failure - 表示失败的计算结果
    static final record 
    Result.Success<T>
    Success - Represents a successful computation result Success - 表示成功的计算结果

  • Method Summary

    Modifier and Type
    Method
    Description
    static <T> Result<T>
    failure(Throwable cause)
    Create a failed Result with the given cause 创建包含给定原因的失败 Result
    <U> Result<U>
    flatMap(Function<? super T, Result<U>> mapper)
    Transform the success value to another Result.
    T
    getOrElse(T defaultValue)
    Get the success value, or return default if Failure 获取成功值，如果是 Failure 返回默认值
    T
    getOrElseGet(Supplier<? extends T> supplier)
    Get the success value, or compute default from Supplier if Failure 获取成功值，如果是 Failure 从 Supplier 计算默认值
    <X extends Throwable>
    T
    getOrElseThrow(Function<? super Throwable, ? extends X> exceptionMapper)
    Get the success value, or throw an exception mapped from the cause 获取成功值，或抛出从原因映射的异常
    boolean
    isFailure()
    Check if this is a Failure 检查是否为失败
    boolean
    isSuccess()
    Check if this is a Success 检查是否为成功
    <U> Result<U>
    map(Function<? super T, ? extends U> mapper)
    Transform the success value.
    static <T> Result<T>
    of(CheckedSupplier<T> supplier)
    Create a Result by executing a CheckedSupplier, catching any exception as Failure 通过执行 CheckedSupplier 创建 Result，捕获任何异常为 Failure
    Result<T>
    peek(Consumer<? super T> action)
    Execute action on Success value 对成功值执行操作
    Result<T>
    peekFailure(Consumer<? super Throwable> action)
    Execute action on Failure cause 对失败原因执行操作
    Result<T>
    recover(Function<? super Throwable, ? extends T> recoverer)
    Recover from a Failure by applying a function to the cause 通过对原因应用函数来从 Failure 恢复
    Result<T>
    recoverWith(Function<? super Throwable, Result<T>> recoverer)
    Recover from a Failure by applying a function that returns a Result 通过应用返回 Result 的函数来从 Failure 恢复
    Stream<T>
    stream()
    Convert to Stream.
    static <T> Result<T>
    success(T value)
    Create a successful Result with the given value 创建包含给定值的成功 Result
    static Result<Void>
    successVoid()
    Create a successful Result<Void> with null value, for side-effect-only operations 创建值为 null 的成功 Result<Void>，用于仅副作用操作
    Optional<T>
    toOptional()
    Convert to Optional.

  • Method Details

    • of

      static <T> Result<T> of(CheckedSupplier<T> supplier)
      Create a Result by executing a CheckedSupplier, catching any exception as Failure 通过执行 CheckedSupplier 创建 Result，捕获任何异常为 Failure
      Type Parameters:
      T - value type - 值类型
      Parameters:
      supplier - the checked supplier to execute - 要执行的受检供应商
      Returns:
      Success with the value, or Failure with the caught exception

    • success

      static <T> Result<T> success(T value)
      Create a successful Result with the given value 创建包含给定值的成功 Result
      Type Parameters:
      T - value type - 值类型
      Parameters:
      value - the success value (may be null for Result<Void>) - 成功值（对于 Result<Void> 可以为 null）
      Returns:
      Success result

    • failure

      static <T> Result<T> failure(Throwable cause)
      Create a failed Result with the given cause 创建包含给定原因的失败 Result
      Type Parameters:
      T - value type - 值类型
      Parameters:
      cause - the failure cause (must not be null) - 失败原因（不能为 null）
      Returns:
      Failure result
      Throws:
      NullPointerException - if cause is null

    • successVoid

      static Result<Void> successVoid()
      Create a successful Result<Void> with null value, for side-effect-only operations 创建值为 null 的成功 Result<Void>，用于仅副作用操作
      Returns:
      Success result with null value

    • isSuccess

      boolean isSuccess()
      Check if this is a Success 检查是否为成功
      Returns:
      true if Success - 如果成功返回 true

    • isFailure

      boolean isFailure()
      Check if this is a Failure 检查是否为失败
      Returns:
      true if Failure - 如果失败返回 true

    • map

      <U> Result<U> map(Function<? super T, ? extends U> mapper)
      Transform the success value. If the mapper throws, returns Failure with the caught exception. 转换成功值。如果映射函数抛出异常，返回包含捕获异常的 Failure。
      Type Parameters:
      U - result type - 结果类型
      Parameters:
      mapper - transformation function - 转换函数
      Returns:
      transformed Result

    • flatMap

      <U> Result<U> flatMap(Function<? super T, Result<U>> mapper)
      Transform the success value to another Result. If the mapper throws, returns Failure. 将成功值转换为另一个 Result。如果映射函数抛出异常，返回 Failure。
      Type Parameters:
      U - result type - 结果类型
      Parameters:
      mapper - transformation function returning Result - 返回 Result 的转换函数
      Returns:
      resulting Result

    • recover

      Result<T> recover(Function<? super Throwable, ? extends T> recoverer)
      Recover from a Failure by applying a function to the cause 通过对原因应用函数来从 Failure 恢复
      Parameters:
      recoverer - recovery function that takes the cause and returns a value - 接受原因并返回值的恢复函数
      Returns:
      Success with recovered value, or original Success

    • recoverWith

      Result<T> recoverWith(Function<? super Throwable, Result<T>> recoverer)
      Recover from a Failure by applying a function that returns a Result 通过应用返回 Result 的函数来从 Failure 恢复
      Parameters:
      recoverer - recovery function that takes the cause and returns a Result - 接受原因并返回 Result 的恢复函数
      Returns:
      recovered Result, or original Success

    • peek

      Result<T> peek(Consumer<? super T> action)
      Execute action on Success value 对成功值执行操作
      Parameters:
      action - action to execute on success value - 对成功值执行的操作
      Returns:
      this Result for chaining

    • peekFailure

      Result<T> peekFailure(Consumer<? super Throwable> action)
      Execute action on Failure cause 对失败原因执行操作
      Parameters:
      action - action to execute on failure cause - 对失败原因执行的操作
      Returns:
      this Result for chaining

    • getOrElse

      T getOrElse(T defaultValue)
      Get the success value, or return default if Failure 获取成功值，如果是 Failure 返回默认值
      Parameters:
      defaultValue - default value - 默认值
      Returns:
      success value or default

    • getOrElseGet

      T getOrElseGet(Supplier<? extends T> supplier)
      Get the success value, or compute default from Supplier if Failure 获取成功值，如果是 Failure 从 Supplier 计算默认值
      Parameters:
      supplier - default value supplier - 默认值供应商
      Returns:
      success value or computed default

    • getOrElseThrow

      <X extends Throwable> T getOrElseThrow(Function<? super Throwable, ? extends X> exceptionMapper) throws X
      Get the success value, or throw an exception mapped from the cause 获取成功值，或抛出从原因映射的异常
      Type Parameters:
      X - exception type - 异常类型
      Parameters:
      exceptionMapper - function to map cause to throwable - 将原因映射为异常的函数
      Returns:
      success value
      Throws:
      X - if this is a Failure

    • toOptional

      Optional<T> toOptional()
      Convert to Optional. Success becomes Optional.of(value), Failure becomes Optional.empty(). 转换为 Optional。Success 变为 Optional.of(value)，Failure 变为 Optional.empty()。
      Returns:
      Optional containing the success value, or empty if Failure

    • stream

      Stream<T> stream()
      Convert to Stream. Success becomes a single-element Stream, Failure becomes an empty Stream. 转换为 Stream。Success 变为单元素 Stream，Failure 变为空 Stream。
      Returns:
      Stream containing the success value, or empty if Failure