使用批注确保方法返回的值不会被丢弃

String在Java中是不可变的。从广义上讲，以下片段是“错误的”。

String s = "hello world!";

s.toUpperCase(); // "wrong"!!

System.out.println(s); // still "hello world!"!!!

尽管这是“错误的”，但代码会编译并运行，这也许会让许多初学者感到困惑，他们必须被告知错误是什么，或者通过查阅文档来自己找出答案。

阅读文档是理解API的重要组成部分，但我想知道是否可以通过额外的编译时检查来补充这一点。特别是，我想知道Java的注释框架是否可以用来强制某些方法返回的值不被忽略。然后，API 设计人员/库作者将在其方法中使用此注释来记录不应忽略哪些返回值。

一旦API补充了这个注释（或者可能是另一种机制），那么每当用户编写如上所述的代码时，它就不会编译（或者在严厉警告的情况下编译）。

那么这可以做到吗，你会如何去做这样的事情呢？

附录：动机

很明显，在一般情况下，Java应该允许忽略方法的返回值。像List.add（总是），System.setProperty（以前的值）这样的方法的返回值在大多数情况下都可以安全地忽略。true

但是，也有许多方法的返回值不应被忽略。这样做几乎总是程序员的错误，或者不是API的正确用法。其中包括以下内容：

• 不可变类型（例如 、 等）上的方法，这些方法返回操作结果，而不是改变调用它的实例。StringBigInteger
• 其返回值是其行为的关键部分并且不应被忽略的方法，但人们有时会这样做（例如，InputStream.read（byte[]）返回读取的字节数，不应假定这是数组的整个长度）

目前，我们可以编写忽略这些返回值的代码，并让它们在没有警告的情况下编译和运行。静态分析检查器/错误查找器/样式执行器/等几乎可以肯定地将这些标记为可能的代码气味，但如果这可以由API本身强制执行，也许是通过注释，这似乎是合适的/理想的。

一个类几乎不可能确保它总是“正确”使用，但是它可以做一些事情来帮助指导客户端正确使用（参见：有效的Java 2nd Edition，项目58：对可恢复的条件使用已检查的异常，对编程错误使用运行时异常和项目62：记录每个方法引发的所有异常).有一个注释可以强制客户端不忽略某些方法的返回值，并且编译器在编译时以错误或警告的形式强制执行它，这似乎符合这个想法。

附录 2：代码段

以下是初步尝试，简明扼要地说明了我想要实现的目标：

@interface Undiscardable { }
//attachable to methods to indicate that its
//return value must not be discarded

public class UndiscardableTest {
     public static @Undiscardable int f() {
             return 42;
     }

     public static void main(String[] args) {
             f(); // what do I have to do so this generates
                  // compilation warning/error?

             System.out.println(f()); // this one would be fine!
     }
}

上面的代码编译并运行良好（如 ideone.com 所示）。我怎样才能让它不这样？如何分配我想要的语义？@Undiscardable