把这个标题拆开看，其实是在说一件事：怎么用JetBrains IDE里的扩展注解，把“代码里看不见的约定”变成“IDE能帮你检查的规则”。很多人以为注解只是写给同事看的注释，但在IDEA里，注解更像是一套给静态分析引擎的信号灯——你亮哪个灯，IDE就帮你盯哪种问题。我在做高并发IM项目的时候，线上故障有一大半其实在写代码那一刻就能拦住：并发修改没加锁、硬编码的中文提示语、端口号传了个越界值。这些痛点的共性就是“约定只存在于文档里、大脑里，没有落到代码本身上”。而JetBrains扩展注解正好能把这三类约束变成IDE的自动检查，把问题拦截在编译之前、提交之前，甚至写出来的下一秒。这篇文章就围绕并发、国际化、值域约束这三个方向，结合我实际项目的踩坑经历，把整个思路、配置、扩展做法完整拆一遍。适合正在用IntelliJ IDEA做Java或Kotlin服务端开发的同学，尤其是高并发场景、国际化产品、基础组件或者SDK开发这些方向。
1. 内容整体设计与思路拆解
1.1 注解不是“给人看的注释”，而是给IDE看的“可执行契约”
我第一次认真研究IDEA的注解体系，是因为一个特别丢人的故障。当时线上IM服务的会话列表接口偶发返回503，排查到最后是ConcurrentHashMap的复合操作没加锁，两个线程同时做着“先检查再插入”，把会话状态搞坏了。那时候压测工具、监控平台都上了，但问题只能等线上暴露。后来我翻IDEA的自带检查列表，发现很多并发问题其实在键入代码的瞬间就能被标红——只要你把并发约定用注解告诉IDE。
这里有个重要的认知转变：注解和注释的最大区别，在于注释是写给“人”的，注解是写给“编译器、字节码工具、IDE分析引擎”的。比如你在字段上标一个@NotNull，IDEA的检查引擎就会在你对该字段做判空操作的时候给出提示；标了@GuardedBy("lock")，IDEA就会在你没持有锁的情况下访问该字段时报警。Java本身对大部分这类注解没有运行时强制力，但IDEA的静态分析引擎会把它们当作规则执行。所以，扩展注解的本质是“可执行的代码契约”：你定义规则，IDE负责执法。
很多项目里团队也写了详细的并发设计文档、接口规范，但文档和代码是会脱节的。今天修改一个字段忘了改文档，明天重构一个锁对象忘了更新注释，这种例行的“人肉同步”早晚会失效。用注解把约束直接嵌到代码里，约束就不会过期——改代码的时候，IDE会逼着你同步改注解，不然红波浪线马上教你做人。
1.2 为什么偏偏选“并发、国际化、值域约束”这三个场景
这三个方向不是拍脑袋选的，是我在一堆线上故障和code review记录里统计出来的高频问题。
先看并发。高并发项目的锁、线程安全标记、不可变对象设计，这些信息如果只靠命名和注释传递，新来的同事大概率会在某个字段上直接list.add()而没有加锁。IDEA自带的线程安全检查结合@GuardedBy、@ThreadSafe、@Immutable等注解，能把“这个字段受哪个锁保护”“这个类是不是线程安全”变成机器可读的约束。这类注解的价值不在于运行时强制，而在于给IDE一个判断依据，让它把可疑的并发访问直接标出来。特别是在IM、聊天、推送这类高并发场景，一个锁粒度判断错误就能让并发数上来之后CPU飙到满载还伴随大量阻塞。
其次是国际化。中国团队做国际化产品，最经典的问题有两种：一是字符串写死在代码里，等要出海了再全项目搜中文；二是资源文件的key拼错，IDEA里看着正常，一跑起来屏幕上直接显示messages.user.notfound这种原始键名。这两个问题靠人眼review几乎抓不干净，但用@Nls、@PropertyKey配合检查配置，IDE能在你写字符串的第一时间提醒“这里有硬编码文本”或者“这个key在资源文件里不存在”。
再看值域约束。服务端开发每天都在处理“端口号”“超时时间”“重试次数”“批大小”这类数值参数。参数范围往往写在接口文档里，但调用方经常不记得：端口传了个70000，超时传了-1，批大小传了100万。运行时校验当然能兜底，但能编译期拦下来何必拖到线上报错。@IntRange、@FloatRange、@Size这类注解配合IDE的“常量条件”检查，可以在写字面量时就直接提示越界，比单元测试早了一步。
1.3 常用扩展注解的总体鸟瞰
这三个场景对应的注解不算复杂，但容易混。我先给一张自己整理的速查表，后面每个方向再展开。
| 场景 | 注解 | 作用 | 检查时机 |
|---|---|---|---|
| 并发 | @GuardedBy("lockName") | 标注受指定锁保护的字段/方法 | 访问或调用时检查锁是否持有 |
| 并发 | @ThreadSafe | 标注类是线程安全的 | 辅助并发检查引擎做判断 |
| 并发 | @Immutable | 标注对象不可变 | 发现字段被修改时报错 |
| 国际化 | @Nls | 标注字符串必须是本地化文案 | 硬编码字符串时提示 |
| 国际化 | @NonNls | 标注字符串不需要本地化 | 用于豁免不必要的硬编码提示 |
| 国际化 | @PropertyKey | 标注参数必须是资源文件中的键 | 比较键名与属性文件内容 |
| 值域 | @IntRange(from, to) | 标注整型参数/字段的范围 | 检测越界常量 |
| 值域 | @FloatRange(from, to) | 标注浮点参数/字段的范围 | 检测越界常量 |
| 值域 | @Size(min, max) | 标注容器/数组/字符串尺寸范围 | 检测越界常量或非空检查 |
这些注解分布于JetBrains自己的annotations库、JSR 305的javax.annotation包、SpotBugs的edu.umd.cs.findbugs.annotations包里。我一般首选JetBrains自家那个，因为IDEA识别得最准、反馈最快，而且在多个IDE（IDEA、WebStorm、PyCharm、Android Studio）之间行为一致。
2. 并发场景：让IDE帮你盯住“这把锁到底护着谁”
2.1 高并发IM里的典型并发问题
先还原一个场景。我们当时做一个单聊+群聊的IM模块，用一个ChatSessionManager管理内存会话。核心数据结构是ConcurrentHashMap<String, Session>，本来以为并发安全稳了，结果压测一上，线上偶发出现Session already closed这类诡异错误。排查发现，问题出在“先检查后操作”的复合逻辑上：
public void sendMessage(String userId, Message message) { if (sessionManager.containsKey(userId)) { sessionManager.get(userId).send(message); } }两个线程同时看到containsKey为true，然后一个线程关闭了会话，另一个线程继续往已关闭的Session里发消息。ConcurrentHashMap只保证单个操作的原子性，保证不了复合操作的原子性。这种问题用JMeter压其实很难稳定复现，因为要靠时序巧合；但它又确实是高并发场景下的经典雷区。后来我的处理方式是：把锁、受保护字段、访问逻辑三者用@GuardedBy绑在一起。
public class ChatSessionManager { private final Object lock = new Object(); @GuardedBy("lock") private final Map<String, Session> sessions = new HashMap<>(); public void sendMessage(String userId, Message message) { synchronized (lock) { Session session = sessions.get(userId); if (session != null) { session.send(message); } } } }注意这里我特意把ConcurrentHashMap换回了普通HashMap，因为一旦用锁保护复合操作，ConcurrentHashMap的并发优势其实用不上，反而容易给人“这里安全了”的错觉。真正起作用的是：IDEA看到@GuardedBy("lock")，就会在你没用synchronized (lock)就访问sessions字段的地方画红波浪线，从机制层面防止未来有人绕过锁直接读写这个字段。
2.2 @GuardedBy 的检查机制与实操配置
要理解@GuardedBy怎么生效，得知道IDEA的“并发检查”默认开关在哪儿。路径是Settings/Preferences -> Editor -> Inspections -> Java -> Concurrency issues -> Thread safety issues。我实测下来，这个检查默认是开启的，但很多人没注意它的报错级别，默认可能只是黄色警告，被淹没在一堆提示里。建议把级别调成Warning甚至Error，让不持有锁就访问受保护字段的代码直接标红。
@GuardedBy的取值是字符串，不是Class引用，这是很多人用错的第一处。它的值必须和代码里锁对象的变量名严格一致。比如你用private final Object lock = new Object()，注解就得写@GuardedBy("lock")；如果你用private final ReentrantLock lock = new ReentrantLock()，注解写成@GuardedBy("lock")同样成立，但IDEA在检测的时候会判断你是否调用了lock.lock()而不是synchronized(lock)。这块IDE支持得挺好，但有个坑：lock()必须和unlock()配套放在同一个方法栈里，如果拆成两个方法获取锁和释放锁，IDEA可能识别不了“当前线程持锁”的状态，会误报。
private final ReentrantLock lock = new ReentrantLock(); @GuardedBy("lock") private List<String> pendingMessages = new ArrayList<>(); public void addMessage(String msg) { lock.lock(); try { pendingMessages.add(msg); } finally { lock.unlock(); } }2.3 不可变与线程安全标记：并发设计的第一道防线
在高并发IM里，消息对象、会话配置、用户资料这类数据经常跨线程传递。如果对象本身设计为不可变，很多并发问题直接消失。IDEA里@Immutable注解被标到类上后，你在这个类里给非final字段赋值、暴露内部可修改容器，IDE都会给提示。我分享一个经验：把热点数据类全部设计成不可变，并用@Immutable标注，这个习惯比加一百个锁都省心。
@Immutable public final class ChatMessage { private final long msgId; private final String fromUserId; private final String content; private final long timestamp; public ChatMessage(long msgId, String fromUserId, String content, long timestamp) { this.msgId = msgId; this.fromUserId = fromUserId; this.content = content; this.timestamp = timestamp; } }@ThreadSafe的用处则更多是“标记+辅助推断”。IDEA里如果类A的字段被多个线程读写，并且类A标注了@ThreadSafe，IDE可能会认为内部已经做了合适的同步，从而降低误报；反之，类上标@NotThreadSafe可以让IDE对新加入的共享可变字段给更积极的提示。这块不要把它当作运行时保护，它就是个“给IDE补上下文”的工具。
2.4 并发注解实践中的几个坑
第一，@GuardedBy不是Spring AOP那种动态代理，它没有任何运行时拦截能力，只是纯静态分析的辅助信息。不要指望它替代锁。
第二，同一个锁保护多个字段的时候，注解里的锁字符串必须完全一致，大小写都不能错。IDEA不会因为字符串匹配不上给你报错，它只会在背地里“不干活”。
第三，和Lombok配合的时候会有摩擦。Lombok生成的@Synchronized使用$lock作为锁对象名，但你的@GuardedBy如果写成@GuardedBy("$lock")，IDEA能识别，看起来比较怪；如果写成@GuardedBy("lock")，而Lombok自动生成的锁名是$lock，那检查就失效了。我建议要么手写synchronized块，要么在Lombok生成后检查一下lock字段名，避免两边对不上。
最后提醒一句：并发问题的真正来源往往是“设计时没有想清楚谁负责锁”。@GuardedBy不是代替你思考的工具，它只是帮你把思考结果固化下来。但一旦固化下来，后续维护者就对“这个字段的访问规则”一目了然，这个信息传递价值在团队协作里非常值钱。
3. 国际化场景：把硬编码文案和资源键错误扼杀在编辑器里
3.1 让IDE主动抓“硬编码字符串”
在IDEA里，想让IDE识别“这里应该写国际化文案而不是硬编码字符串”，靠的是@Nls注解。它的命名来自NetBeans的NLS（Native Language Support），语义就是“这个字符串必须是本地化资源里的文案”。当你给方法参数标了@Nls，却传了一个中文字符串字面量，IDEA会弹出提示“Hardcoded string should be localized”；传了英文也一样提示。官方比较激进的做法是：给所有“将要显示给用户”的字符串参数都加上@Nls，然后配合IDEA的检查项来拦截。
实际项目中我更喜欢用@NonNls做反向豁免。因为IDEA自带的“Hardcoded string”检查在有些场景特别啰嗦——比如日志消息、debug输出、HTTP header，这些不该国际化，但它也会提示。这时候给方法参数标@NonNls，旁边标红就消停了。
public void showToast(@Nls String message) { // UI显示用，必须传国际化文案 } public void logDebug(@NonNls String message) { // 日志输出用，不需要国际化 }这个设计有个好处：方法签名本身就传达了一个契约——凡是调用showToast的地方，你一眼就能看出需要传UI文案；凡是调用logDebug的地方，你也不必担心团队里有人硬塞一堆资源键进来。这个信息在跨端、跨团队协作时特别关键。
3.2 @PropertyKey：资源键名的编译期核对
硬编码字符串抓完之后，下一个痛点是资源文件的key拼写。传统做法是写messages.getString("user.login.success")，你根本不知道这个key在messages.properties里到底存在不存在，只能靠运行时抛MissingResourceException。JetBrains的@PropertyKey注解就是为这个场景设计的。
它使用起来很简单：在获取资源的方法参数上标@PropertyKey(resourceBundle = "messages")，然后IDE会检查传入的字符串常量是否真的在src/main/resources/messages.properties文件里存在key。如果key拼错、大小写不对、甚至resourceBundle名称没匹配上，IDE会直接标红。
public static String getMessage(@PropertyKey(resourceBundle = "messages") String key) { return ResourceBundle.getBundle("messages").getString(key); } // 调用方 String msg = getMessage("user.login.success"); // IDE能校验这个key存在 String wrong = getMessage("user.login.succes"); // IDE报红这里有个重要前提：@PropertyKey的检查是基于“字符串常量”的。如果你用动态拼接key，比如getMessage("user." + name)，IDE无法检查动态部分，只能放弃校验或者给出模糊警告。我的经验是：资源key尽量不用动态拼接，如果实在要拼，把公共前缀抽象成常量，IDEA对“常量+常量”的识别效果会好很多。
3.3 国际化检查的配套配置
想让这套检查真正跑起来，还需要在Inspection设置里关闭误报、调整级别。我习惯在Editor -> Inspections -> Java -> Internationalization下把几个关键检查项打开并调高严重级别：
Hardcoded strings：默认是警告，我调到Error，强制要求UI层不能出现裸字符串。Malformed resource bundle：检查属性文件编码、重复key，默认开着。StringEqualsIgnoringCase这类和国际化相关的模式检查，建议也开一下。
还要提醒一个地方：IDEA对properties文件的编码默认是ISO-8859-1，如果项目里用UTF-8写中文资源，会看到一堆\uXXXX转义或者乱码。建议在Settings -> Editor -> File Encodings里把*.properties的编码设为UTF-8，并在构建工具里配置native2ascii或直接使用UTF-8编码加载，不然@PropertyKey虽然能检查key，但资源文件本身显示乱码还是会让人崩溃。
我踩过一个比较隐蔽的坑：在Maven多模块项目里，资源文件不在当前模块的src/main/resources下，而在公共模块的jar包里。这种情况下IDEA的@PropertyKey偶尔会识别不到资源，显示“cannot resolve bundle name”。解决办法是确保公共模块作为依赖被IDEA正确索引，并且resourceBundle参数写的是messages而不是com.xxx.messages。如果还是不行，就在Project Structure -> Libraries检查一下依赖是否引入完整。
4. 值域约束：让IDE在字面量阶段拦住越界参数
4.1 三种常用值域注解的适用场景
值域约束的核心痛点很简单：“接口规定了范围，调用方记不住”。比如一个sendBatchMessage接口，batchSize合法范围是1到100，超过100必须分批；端口号范围是1024到65535；重试次数不能超过10次。这些约束如果只写在文档里，总有人会传个200、传个70000、传个15。值域注解的好处是：你在定义方法的参数上声明范围，IDE就能在调用方写常量字面量时直接检查。
@IntRange(from = 1024, to = 65535)用在端口参数上；@IntRange(from = 1, to = 100)用在批大小上；@FloatRange(from = 0.0, to = 1.0)用在概率、比例参数上；@Size(min = 1, max = 50)用在集合、数组、字符串长度上。这些都是JetBrains annotations库自带的，直接用就行。
我自己在IM网关层处理分页和批量推送时，是这么标的：
public List<Message> listMessages( @IntRange(from = 1, to = 10000) long userId, @IntRange(from = 1, to = 100) int pageSize, @IntRange(from = 0, to = 1000000) int offset) { // ... }加了注解之后，如果测试代码里写pageSize = 200，IDE会立刻在常量上画一道红。这个提示虽然不影响编译，但对代码审查和自测的帮助非常大，因为问题在写出来的瞬间就被发现了。
4.2 一个实际参数范围的计算与选择过程
很多人会问，from和to到底怎么定？这个其实和业务强相关，但有些通用原则。我以端口号为例说明一下：如果端口范围是0到65535，那@IntRange(from = 0, to = 65535)看起来合法，但你至少应该区分“保留端口”和“动态端口”。操作系统本身约定0到1023是特权端口，普通Java进程没权限监听；所以对外服务端口我一般直接定from = 1024。具体到IM服务，如果产品要求外部端口只能用8080到8082、8090，那from和to就写业务规定的范围，不用写全量范围——值域注解的“值域”本意就是业务允许的合法范围，而不是底层数据类型的物理范围。
再举一个批大小选择的例子。假设一个批量推送接口，单批最大100条，超过100条时调用方必须自己分片。有的同事会把to写成Integer.MAX_VALUE，认为“反正我心里的限制是无限大”，这是不对的。值域约束写得太宽就没有拦截意义，写得太紧又会误伤正常调用。我通常的做法是：先看数据库批量写的容量上限，比如单条SQL最多支持500条占位符，那就写from = 1, to = 500；再看业务容忍的响应时间，比如压测测出单批200条耗时50ms，那就把to设成200。经过这两个约束过滤，剩下的范围就是业务真正需要的合法区间。我的经验是“宁可初期范围定窄一点，后面按需放宽，也不要一开始就放开”，因为放宽容易，收紧成本高——收紧会让线上所有越界调用瞬间红屏，而放宽只是少了一层检查。
4.3 值域注解和Bean Validation的配合姿态
做服务端的人一定用过JSR 380（javax.validation.constraints.Min/@Max/@Size）。那为什么还要用JetBrains做编译期检查？两者不是一个层面的东西。运行时校验是“防线上”，编译期检查是“防开发”。我的项目里两者都留，但侧重不同：所有外部接口的入参DTO用@Min、@Max做运行时校验，保护系统不被打进来的脏数据搞坏；而内部方法、SDK方法、工具类方法的参数上用JetBrains注解做编译期检查，让团队内部调用方在IDEA里就能看到约束。
我尤其强调一句话：不要试图用编译期注解替代运行时校验。因为IDEA只对“常量字面量”和“可推断的final常量”给出精准提示，如果调用方从配置中心读到一个字符串再转int传进来，IDE可能感知不到范围，运行时就只能靠Bean Validation兜底。两条防线各有各的意义，缺一条都不稳。
4.4 和@Contract搭配：让IDE推断返回值范围
@Contract是JetBrains注解里的隐藏神器，它本身不直接做值域校验，但它可以给IDE提供关于返回值的逻辑关系。比如你写一个工具方法：
@Contract(pure = true) public static int normalizePort(int port) { return port < 1024 ? 8080 : port; }IDE就能根据这个契约推断出：normalizePort(随便什么值)的返回值一定大于等于8080？配合@IntRange一起用，就能对很多参数传递链路做更聪明的推断。但要注意，@Contract的表达式写错会造成IDE误判，比不写还糟。我最开始写@Contract("null -> null")的时候，IDE一直提示返回值可能为null，实际上方法是pure的，二者矛盾，排查了很久才发现是表达式语义理解错了。这块建议对着官方文档的语法表来写，不要靠猜。
5. 自定义扩展：让IDE按团队的私有规则检查
5.1 零代码方案：结构搜索与替换先顶上
不是所有团队都有精力写IDEA插件，但很多内部规则其实不需要写插件。IDEA自带的Structural Search（结构化搜索）可以按照代码结构模板做检查，我把一些团队的“硬性红线”做成了规则模板。举例：禁止在Message构造函数里直接传入null；禁止Thread.sleep写在for循环里；禁止直接用new Date()而不用System.currentTimeMillis()。这些都能用结构化搜索做成inspection模板。
结构化搜索的模板语法看起来像代码片段，但可以在里面用$变量$做占位。比如“禁止直接遍历ConcurrentHashMap期间调用put”可以写成一个模板。这块虽然不像注解那样细粒度，但胜在零依赖、开箱即用，很适合团队初期快速建立红线检查。缺点是维护成本会随着规则数量上升，规则多了还是得走插件路线。
5.2 写一个最小的Annotator插件
如果团队有几十条内部规则，或者你希望“注解+自定义逻辑”深度耦合，那就可以考虑写IDEA插件。其实写一个最小可用的Annotator并不复杂，核心是实现Annotator接口，在annotate()方法里根据PSI结构给元素添加提示。
我当时写过一个内部注解@ReviewRequired，用于标注“这个改动必须经过架构师评审”的敏感方法。实现在IDEA插件里就是这样：
public class ReviewRequiredAnnotator implements Annotator { @Override public void annotate(@NotNull PsiElement element, @NotNull AnnotationHolder holder) { if (element instanceof PsiMethod && element.hasAnnotation("com.example.ReviewRequired")) { holder.newWarningAnnotation(element, "此方法涉及资金操作，需架构评审") .withFix(new ShowReadMoreFix()) .create(); } } }这个插件的启用要在plugin.xml里声明：
<annotator language="JAVA" implementationClass="com.example.ReviewRequiredAnnotator"/>写完打包成jar，放到IDEA的插件目录或企业内部插件仓库就能用。说实话，开发的复杂度不高，难的是和现有代码库的量级匹配——如果团队有几十万行老代码，给老方法批量标注会引发大量提示，推行阻力会很大。我的建议是先从“新增代码必须标注”开始，存量代码慢慢补，不要一上来搞全量清零。
5.3 团队推广与分发的一些体会
自定义注解和插件做得再好，团队不认也是白搭。这里我分享几个实际经验。第一，把规则和“团队规范文档”绑定，每条注解都配上一条wiki链接，点击检查提示就能看到解释，这样开发者在IDE里看到的不是冷冰冰的一行报错，而是有上下文的指引。第二，推行初期把新检查设为“Warning”而非“Error”，给团队一到两个迭代的缓冲期，等大家习惯了再逐步升级。第三，在CI构建里加入Inspect Code命令行工具，让那些不用IDEA的同事也能在流水线上看到同样的检查结果。
技术细节上要特别注意：IDEA插件和IDE版本有兼容性要求，企业内部插件最好用IntelliJ Platform Plugin的SDK构建，并锁定最低版本号；不要只在最新版IDEA上打包，不然老版本用户安装了直接不加载。
6. 常见问题与排查技巧实录
6.1 注解装了却不生效？先查这几个地方
我几乎每到一个新项目都要排查一遍“为什么@NotNull没反应”“为什么@GuardedBy没标红”，这里把高频问题和排查路径整理成一张表，大家可以按图索骥。要记住两条主线：注解有没有被工程依赖引入、IDEA检查项有没有开启。
| 现象 | 可能原因 | 解决方式 |
|---|---|---|
| 注解不识别，类名标红 | 缺少JetBrains annotations依赖 | 在构建配置里加org.jetbrains:annotations依赖 |
| @GuardedBy能识别但不检查 | Thread safety检查项未开启或级别过低 | 检查Inspections -> Java -> Concurrency issues -> Thread safety issues |
| 硬编码字符串不提示 | Hardcoded strings检查被关闭 | 打开Inspections -> Java -> Internationalization -> Hardcoded strings |
| @PropertyKey提示resource bundle找不到 | 资源包名称写错或资源文件不在依赖模块 | 核对resourceBundle值，检查依赖索引 |
| @IntRange用数组参数时无效 | 注解放到了类型上而非元素类型上 | 检查参数注解位置：@IntRange List<Integer>标的是整个引用，应标到泛型或元素上 |
| 插件装了但检查不触发 | IDEA缓存未刷新 | File -> Invalidate Caches / Restart |
| 同一段代码在甲电脑报错乙电脑不报 | 两个环境Inspection配置不一致 | 导出/导入.idea/inspectionProfiles配置并提交到仓库 |
6.2 排查时最难发现的三个“假阴性”
除了配置问题，还有三类“假阴性”最坑人，我单独拿出来说。因为这三类都是IDE引擎的“认知盲区”，不是规则写错了。
第一类：通过反射或动态代理访问受保护字段，@GuardedBy完全无能为力。IDEA只看静态调用关系，你反射里field.get(obj)它无法判断有没有持锁。应对方法是对反射封装层做全局审计，或者直接禁止业务代码反射访问内部字段。
第二类：复合操作的锁通过方法调用间接获取，IDE推断不了。比如tryLock()在if条件里调用，锁对象在finally释放，IDEA有时候判定不了持锁状态。遇上这种最好显式把锁获取放在独立的lock()方法里，或者在代码注释里标注后关闭该项检查。
第三类：跨模块的注解类没有被统一管理。同一个@Nls在模块A生效、在模块B不生效，很可能是因为两个模块依赖的annotations版本不同。高版本JetBrains annotations把部分注解做了包迁移，建议全项目统一一个版本，由顶层BOM管理，避免到处复制。
6.3 把常用注解做成Live Template，减少重复劳动
这套东西推广过程中，我遇到一个很实际的阻力：让每个开发手写@GuardedBy("xxx")这种注解，大家嫌烦。后来我把常用注解做成了IDEA Live Template，输入缩写就能自动生成模板代码，效果好很多。举几个我常用的模板：
gsb：生成@GuardedBy("lock") private final Object lock = new Object();irange：生成@IntRange(from = 1, to = 100)，并把1和100留成编辑点nls：生成@Nls并自动导入dot：生成@Contract(pure = true)模板
配置路径在Settings -> Editor -> Live Templates，选择Java分组，添加Template，然后在Applicable contexts里勾选Java声明和参数位置。模板里的$END$表示生成后光标停留位置，$VAR1$是Tab跳转的编辑点。这个做法推广一周后，同事反馈“反正不费事，就顺手标了”，规则落地阻力瞬间小了很多。
6.4 扩展注解和代码审查制度的配合
最后说一点提升性的经验。JetBrains扩展注解的终极价值不是给IDE用的，而是给“代码审查”提供机器级的辅助。我们团队的PR检查清单里明确要求：所有涉及共享可变状态的类必须标注@GuardedBy或提供线程安全设计说明；所有新增的UI字符串必须标注@Nls；所有外部可调用接口的数值参数必须标注值域。人工review只看“注解有没有被正确标注”，而“标注之后代码是否真的遵守约束”交给IDE来盯。这样审查者不用再逐行数锁、逐条检查字符串，效率提升明显，而且降低了漏判。
我个人的体会是：JetBrains这套扩展注解体系是个典型的学习成本低、收益巨大的工程实践。它不会改变你的架构设计，也不替代压测和监控，但它把大量“文档里的约定”变成了“编辑器里的红绿蓝波线”，让规范活在代码旁边而不是活在Confluence里。你不需要一次性把所有代码都标注满，但每标注一处，就减少一处未来可能的人为失误。从IM网关到基础SDK，从单个方法到整个模块，这种“代码契约”的积累，会让项目的长期维护者受益无穷。最后再分享一个小技巧：遇到那种“所有人都默认知道但不能到处说明”的隐含规则，优先考虑用注解把它显式化，因为任何藏在脑子和文档里的约定，都有失效的一天。
