表示 API returns 一个 unmodifiable/immutable 集合的方法

Question

除了记录它（显然它也应该被记录），使用特殊的 return 类型（我谨慎地限制自己使用 ImmutableX）或者让用户在运行时发现，是否有还有什么其他方法可以告诉 API 的用户他们从 API 收到的集合是 unmodifiable/immutable？

是否有任何命名约定或标记注释普遍表示同一事物？

编辑：不可修改和不可变并不意味着同一件事，但对于这个问题的目的，它们足够相似。这个问题基本上归结为让用户知道 returned 对象没有完全遵守其合同（即一些常见操作会抛出运行时异常）。

Answer 1

确实记录下来
提供 API 检查给定对象是否为不可变集合
Return 包装器中保存信息的集合是其中的集合是否可变 - 我最喜欢的解决方案
如果可能，不要使用可变和不可变集合，而是选择其中之一。结果总是不可变的，因为它们就是结果——为什么要改变它。如果有这样的需要，将集合复制到新的可变集合并修改它（例如用于链处理）是单行的问题

Answer 2

不是一般的命名约定，但您可能对使用此 @Immutable 注释感兴趣：http://aspects.jcabi.com/annotation-immutable.html 除了文档目的之外，该机制还将验证您的对象是否真的不可变（在实例化期间），如果不是则抛出运行时异常。

Answer 3

好的和冗长的解决方案是制作您自己的 UnmodifiableCollection 包装器 class，return 它：

public UnmodifiableCollection giveMeSomeUnmodifableCollection() {
    return new UnmodifiableCollection(new LinkedList());
}

return 类型的名称足以对集合的不可修改性做出冗长的声明。

Answer 4

在方法的 return 类型上写一个 @Immutable 注释是最好的方法。它有多重好处：

此外，验证可以发生在编译时，在您运行您的代码之前。

如果想在编译时进行校验，可以使用IGJ Immutability Checker。它区分 @Immutable 抽象值永不改变的引用，以及 @ReadOnly 不能对其执行副作用的引用。

Ways to signal that API returns an unmodifiable/immutable collection