解决Java中的Sonar“Make Transient or Serializable”警告

1. 简介

在将 Java 原生序列化与 SonarQube 代码评估工具结合使用时，我们有时会遇到 “Serializable 类中的字段应该是 transient 或 Serializable” (规则键: java:S1948) 的警告。该规则是一道重要的护栏，可防止常见的运行时故障：NotSerializableException。

在本教程中，我们将探讨出现此警告的原因。此外，我们还将讨论 Java 序列化的底层机制以及解决该问题的最佳策略。

2. 理解序列化契约

要使 Java 对象可序列化，其类必须实现 java.io.Serializable 接口。这是一个标记接口，用于告知 JVM 该对象的状态将被转换为字节流，以便进行存储或网络传输。

因此，该契约的基本规则是递归的：如果一个类是可序列化的，那么它所有的非静态（non-static）和非瞬态（non-transient）成员字段也必须是可序列化的。 如果序列化机制遇到一个未实现 Serializable 且未标记为 transient 的字段，该过程将在运行时失败。Sonar 在静态分析期间会标记这些字段，帮助我们在代码运行前捕获此错误。

此外，请务必记住，序列化不仅仅针对顶级类，而是涉及整个对象图。

3. 重现 Sonar 警告

让我们看看触发 java:s1948 警告的典型场景。首先，将 SLF4J 依赖添加到我们的 pom.xml 中：

$ xml

<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-api</artifactId>
    <version>2.0.17</version>
</dependency>

现在，创建一个我们想要存储在分布式会话或缓存中的 User 类。该类包含对另一个未实现 Serializable 接口的类 Address 的引用。我们先从一个简单的实现开始：

$ java

public class User implements Serializable {
    private static final long serialVersionUID = 1L;
         
    private String username;
    private Address address; // Sonar 警告：将 "address" 设为 transient 或使其可序列化
    private final Logger logger = LoggerFactory.getLogger(User.class); // Sonar 警告
         
    public User(String username, Address address) {
        this.username = username;
        this.address = address;
    }
}

在此示例中，User 类正确实现了 Serializable。但是，如果 Address 类定义时没有实现该接口，Sonar 就会标记 address 字段。同样，由于 SLF4J Logger 未实现 Serializable，它也会触发警告。此外，如果我们尝试序列化 User 的实例，JVM 将在运行时抛出 NotSerializableException。 这正是 Sonar 试图帮助我们避免的情况。现在，让我们看看解决此警告的几种方法。

4. 使字段可序列化

最直接的修复方法是确保嵌套类也实现 Serializable 接口。 当该字段代表对象状态的核心部分且必须被保留时，这是首选方法。因此，如果我们拥有嵌套对象的源代码，只需更新类定义即可：

$ java

public class Address implements Serializable {
    private static final long serialVersionUID = 1L;
        
    private String street;
    private String city;
        
    public Address(String street, String city) {
        this.street = street;
        this.city = city;
    }
}

通过添加 implements Serializable 并提供 serialVersionUID，我们满足了契约要求。始终包含 serialVersionUID 是确保反序列化过程兼容性的最佳实践，尤其是当类结构随时间演变时。

5. 使用 static 修饰符

解决某些字段警告的另一种有效方法是将它们声明为 static。在 Java 中，静态字段不会被序列化，因为它们属于类本身，而不是特定的实例。 由于它们被 JVM 排除在序列化过程之外，SonarQube 不会对其进行标记。

这是记录器（loggers）和常量的标准解决方案：

$ java

public class User implements Serializable {
    private static final long serialVersionUID = 1L;
       
    private static final Logger logger = LoggerFactory.getLogger(User.class); // 无警告
    private String username;
    private Address address;
    // getters, setters ...
}

通过将记录器设为静态，警告消失了，我们也遵循了 Java 中记录器声明的通用模式。这种方法非常适合所有实例共享且不代表单个对象唯一状态的任何字段。

6. 利用 transient 关键字

如果某个字段是实例特定的，但不应该被序列化（例如对临时缓存的引用或不可序列化的第三方对象），我们应使用 transient 关键字。此修饰符告知 JVM 在序列化过程中跳过该字段：

$ java

public class User implements Serializable {
    private static final long serialVersionUID = 1L;
       
    private String username;
    private Address address;
    private transient List<String> temporaryCache; // 警告已解决
    // getters and setters ...
}

我们需要考虑到，当对象被反序列化时，所有 transient 字段都会被初始化为默认值：对象为 null，基本类型为 0。因此，如果对象在恢复后需要使用该 transient 字段，我们必须重新初始化它。一种实现方式是使用 readObject 方法：

$ java

private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException {
    in.defaultReadObject();
    this.temporaryCache = new ArrayList<>();
}

7. 处理框架依赖

在现代 Java 框架（如 Spring）中，当在 @SessionScoped bean 中注入 @Service 或 @Repository 时，经常会出现此警告。由于这些服务由容器管理且通常不可序列化，因此应将它们标记为 transient：

$ java

@SessionScoped
public class UserPreferences implements Serializable {
    @Autowired
    private transient PreferenceService service; // 通过标记 transient 修复
}

Spring 会处理依赖注入，因此当 bean 从会话中恢复时，它会重新注入该服务（前提是框架的代理机制支持）。 这使得我们的会话作用域 bean 保持可序列化，同时允许它们与无状态服务进行交互。

此外，我们可能会遇到使用未实现 Serializable 的第三方库类的情况。如果我们无法修改其源代码，主要有两种选择：

包装对象：创建一个仅包含必要原始数据的可序列化 DTO。
自定义序列化：对第三方对象使用 transient，并使用 writeObject 和 readObject 方法手动处理其状态。

例如，如果我们有一个不可序列化的 Metadata 对象，我们可以将其状态存储为可序列化的 Map，并在反序列化时重建它。这使得我们的领域模型保持可序列化，同时仍能利用强大的第三方工具。

8. 结论

在本教程中，我们介绍了如何处理 Sonar 的 “Make Transient or Serializable” 警告。尽管该警告有助于确保 Java 应用程序的运行时稳定性，但它有时会引起困惑。通过理解 Java 序列化的递归特性，我们可以根据字段在应用程序中的角色选择正确的修复方案。

如果字段是对象状态的核心部分，请实现 Serializable；对于记录器、常量和共享的类级别成员，请使用 static；如果字段是资源或临时数据，请标记为 transient；如果我们试图序列化不应持久化的无状态服务或第三方对象，则应重构设计。

分类导航

1. 简介

2. 理解序列化契约

3. 重现 Sonar 警告

4. 使字段可序列化

5. 使用 static 修饰符

6. 利用 transient 关键字

7. 处理框架依赖

8. 结论