此文被笔者收录在系列文章 ​​​架构师必备（系列）​​ 中，这一章的注解是非官方的注解，属于一点扩展知识。自从java有了注解能力后，在有些时候可以考虑用注释来代替文档。

@GuardedBy和@ThreadSafe等Annotation用来展现如何将线程安全性的保证和同步策略进行文档化。下面会介绍一点经常用到的Annotation。

类Annotation

我们用到了3个类级Annotation来描述类的可预期的线程安全性保证：

• ✴@Immutable：不可变的，并包含了@ThreadSafe。
• ✴@NotThreadSafe：是可选的，如果类没有被标明是线程安全的，就无法肯定它是不是线程安全的，但是如果想标它不是线程安全的，就标为@ NotThreadSafe。
• ✴@ThreadSafe：线程安全的。

这些 Annotation相对是非侵入的，这对用户和维护者都是有益的，用户可以立即看出一个类是否是线程安全的，维护者也可以直接检查类是否遵守了线程安全性保证。 Annotation对于第三个利益即得者也是有用的：工具。静态的代码分析工具可以有能力对代码进行验证，看它是否遵守了由Annotation指定的契约，比如标明为@Immutable的类是否真正不可变的。

域Annotation和方法Annotation

上面的类级Annotation只是类的公共文档的一部分，类的线程安全性策略的其他方面，对于维护者来说是完全有必要的，不过并没有作为公共文档的一部分。使用加锁的类应该写入文档的信息包括：哪个状态变量被哪个锁保护着，以及哪个锁用来保护这些变量的信息。

使用@GuardedBy标识出每一个需要加锁的状态变量，这个锁确保它会有助于维护和代码审查，而且能够帮助自动化分析工具发现潜在的线程安全性错误。

@GuardedBy(lock)：线程只有在持有了一个特定的锁后，才能访问某个域或方法。lock参数代码一个锁，只有持有了该锁，才能访问被标的域或方法。lock的可能值如下：

• ✴@GuardedBy(“this”)：是指包含在对象中的内部锁(方法或域是这个对象的一个成员)。
• ✴@GuardedBy(“fieldName”)：是指与filedName引用的对象相关联的锁，它或者是一个隐式锁或一个显式锁。
• ✴@GuardedBy(“ClassName.fieldName”)：类似于@GuardedBy(“fieldName”)，不过所引用的锁对象是存储在另一个类中的静态域。
• ✴@GuardedBy(“methodName()”)：是指锁对象是methodName()方法的返回值
• ✴@GuardedBy(“ClassName.class”)：：是指className类的直接对象。