如何表明API返回不可修改/不可变的集合

Question

除了记录它（显然它也应该被记录），使用特殊的返回类型（我担心将自己限制为ImmutableX）或让用户在运行时发现，是否有任何其他方式告诉API用户他们从所述API收到的集合是不可修改/不可变的？

是否有任何命名约定或标记注释通用信号相同？

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

Answer 1

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

Answer 2

1. 确实记录
2. 提供API以检查给定对象是否为imutable collection
3. 包装器中的返回集合将保存信息是其内部的集合是否可变 - 我最喜欢的解决方案
4. 如果可能的话，不要使用mullable和immutable集合，而是选择其中一个。结果总是不可变的，因为它们是结果 - 为什么要改变它。如果有这样的需要，将集合复制到新的，可变的并且修改它（例如用于链处理）是单行的问题。

Answer 3

好的和详细的解决方案是创建自己的UnmodifiableCollection包装类，并将其返回：

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

返回类型的名称足以对该集合的不可修改性进行详细说明。

Answer 4

在方法的返回类型上编写@Immutable注释是最好的方法。它有多种好处：

• 注释记录了用户的意思
• 工具可以验证客户端代码是否遵守注释（即客户端代码没有错误）
• 工具可以验证库代码是否符合注释（即库代码没有错误）

此外，验证可以在编译时进行，也可以在运行代码之前进行。

如果您想在编译时进行验证，可以使用IGJ Immutability Checker。它区分 @Immutable引用的抽象值永远不会改变，和 @ReadOnly提及无法进行哪些副作用。