为返回类型“Optional<T>”编写 Javadoc

Question

我目前正在为我工作场所使用的 SOAP 网络服务编写 Java-API。

Web 服务类是使用Axis2生成的，它们可以返回null. 因为我不想null在我的业务逻辑级别处理 -references，所以我使用Optional<>as 返回类型。

例如：

/**

 * Reads account-data to given accountId. 

 * 

 * @param accountId

 *          the primary key of table 'account'

 * @return  the account wrapped as an Optional<>, if an account with primary key 'accountId' exists; Optional.empty(), else

 */

public Optional<Account> readAccount(long accountId) throws RemoteException, ServiceFaultException {

        // prepare SOAP-Request

        ReadAccount request = new ReadAccount();

        request.setAccountId(accountId);

        // execute SOAP-Request

        ReadAccountResponse response = accountService.readAccount(request);

        // process Response

        Optional<Account> account = Optional.ofNullable(response.getAccount());

        return account;

    }

上面的方法执行一个网络服务操作来搜索数据库中的一些帐户记录。如果没有找到具有匹配参数的帐户accountId，则方法调用response.getAccount()可以返回null。

是否有更简洁的方法来编写 Javadoc @return？

特别是对于短语“wrapped as an Optional<>”？

Answer 1

为什么不说jdk是怎么做的呢？例如Stream::reduce：@return 一个描述归约结果的{@link Optional}在您的情况下，它将是：描述帐户的可选。

Answer 2

我建议将您的返回语句 javadoc 简化为以下内容：/**&nbsp;* Reads account-data to given accountId.&nbsp;&nbsp;*&nbsp;&nbsp;* @param accountId&nbsp;*&nbsp; &nbsp; &nbsp; &nbsp; &nbsp; the primary key of table 'account'&nbsp;* @return the account wrapped in an {@link Optional}&nbsp;*/public Optional<Account> readAccount(long accountId) throws RemoteException, ServiceFaultException {&nbsp; // function here}这样做的原因是因为它Optional.empty()是 API 的预期且不变的部分Optional；每个知道 anOptional是什么的开发人员都知道，如果帐户丢失，则期望一个空的 Optional；Optional如果帐户存在，他将理解他需要访问内部的实际信息。我们在这里提供一个@link，让没有听说过Optionals的开发者可以查阅它各自的javadoc，了解它是如何工作的；这本身不是强制性的，但如果有很多经验不足的开发人员参与您的项目，这可能会有所帮助。