@Nullable是 JetBrains 提供的一套用于 Java 静态分析的注解（annotations）之一，属于org.jetbrains.annotations包。它主要用于标注一个变量、参数、方法返回值等可能为 null，从而帮助 IDE（如 IntelliJ IDEA）或静态分析工具在编译期或开发过程中检测潜在的空指针异常（NullPointerException, NPE），提升代码健壮性和可读性。
基本介绍
所属依赖
Maven 坐标：
<dependency> <groupId>org.jetbrains</groupId> <artifactId>annotations</artifactId> <version>24.1.0</version> <!-- 推荐使用最新版 --> </dependency>Gradle：
implementation 'org.jetbrains:annotations:24.1.0'注意：该注解是运行时保留（RetentionPolicy.CLASS），不会影响运行时行为，仅用于静态分析。
@Nullable 的作用
基本用法
1.方法参数可空
public void processUser(@Nullable String userName) { if (userName != null) { System.out.println("Processing: " + userName); } }2.方法返回值可空
public @Nullable String findUserById(int id) { if (id > 0) { return userRepository.findById(id); } return null; // 明确标记可能返回 null }3.字段可空
public class User { private @Nullable String middleName; // getter/setter... }配套注解
@NotNull- 不可为空
public void saveUser(@NotNull String username, @Nullable String email) { // username 不能为 null，否则会有警告 // email 可以为 null }@Contract- 合约注解（更复杂的约束）
@Contract("null -> null; !null -> !null") public @Nullable String trim(@Nullable String str) { return str == null ? null : str.trim(); }实际应用示例
用户服务示例
public class UserService { /** * 查找用户 - 可能返回null */ public @Nullable User findUser(@NotNull String id, @Nullable String tenantId) { if (tenantId == null) { tenantId = "default"; } return userRepository.find(id, tenantId); } /** * 更新用户名 - 用户名不能为null */ public void updateUsername(@NotNull User user, @NotNull String newUsername) { user.setUsername(newUsername); userRepository.save(user); } }IDE 支持
IntelliJ IDEA 的智能提示
空值检查警告
User user = userService.findUser("123", null); user.getUsername(); // IDEA 会警告：可能NullPointerException智能自动修复
// IDEA 会建议： if (user != null) { System.out.println(user.getUsername()); }代码推断
@Nullable String name = getName(); int length = name.length(); // 直接警告：可能为null与其他框架的对比
| 注解来源 | 注解 | 特点 |
|---|---|---|
| JetBrains | @Nullable | IDE 支持好，轻量级 |
| JSR-305 | @Nullable | 标准提案，但已废弃 |
| Spring | @Nullable | 框架集成好 |
| Android | @Nullable | Android Studio 内置 |
与 @NotNull 对比
| 注解 | 含义 | 行为 |
|---|---|---|
@Nullable | 允许为 null | 调用处需做 null 检查 |
@NotNull | 不允许为 null | 若传入/返回 null，IDE 会警告，甚至在运行时抛出异常（如果启用了断言） |
IntelliJ IDEA 默认会对
@NotNull参数在运行时插入检查（可通过设置关闭）。
注意事项
@Nullable不会阻止你传入 null，它只是文档化和辅助检查。- 如果项目使用了其他空值注解体系（如 JSR-305 的
@Nullable、Spring 的@Nullable、Eclipse 的@Nullable等），建议统一使用一种，避免混淆。 - JetBrains 注解兼容 Android 开发，并且被广泛采用。
总结
@Nullable是一种契约式编程的体现，通过注解明确“这里可能为 null”，让开发者和工具都能据此做出更安全的决策。配合@NotNull使用，可以显著减少空指针异常，提升代码质量。
如果你使用的是 IntelliJ IDEA，强烈建议在项目中引入org.jetbrains.annotations并养成使用@Nullable/@NotNull的习惯。
