Lucene.NET 中的 SetOnce<T> 类重构：从 Java 风格到 .NET 风格的演变

在 Lucene.NET 项目中，SetOnce 类是一个典型的 Java 风格设计，它提供了 Get() 和 Set() 方法来操作内部值。随着项目向更符合 .NET 习惯的方向发展，这个类的设计也迎来了重构的机会。

原始设计分析

原始的 SetOnce 类采用了典型的 Java 方法命名风格：

• Get() 方法用于获取值
• Set() 方法用于设置值

这种设计虽然功能完整，但与 .NET 生态系统的习惯用法存在差异。在 .NET 中，类似的场景通常会使用属性（Property）来封装字段访问，特别是对于像 Nullable 这样的核心类型。

重构方案

重构的核心目标是将 Java 风格的方法转换为更符合 .NET 习惯的属性设计。具体方案包括：

1. 引入 Value 属性作为主要访问方式，替代原有的 Get() 和 Set() 方法
2. 将原有方法标记为过时（Obsolete），并计划在未来的 rc1 版本中移除
3. 使用 partial class 技术实现平滑过渡，便于后续完全移除过时方法

技术实现细节

重构后的 SetOnce 类将具有以下特点：

public partial class SetOnce<T>
{
    private T value;
    private bool isSet;
    
    public T Value
    {
        get
        {
            if (!isSet)
                throw new InvalidOperationException("Value is not set");
            return value;
        }
        set
        {
            if (isSet)
                throw new InvalidOperationException("Value is already set");
            this.value = value;
            isSet = true;
        }
    }
    
    [Obsolete("Use Value property instead")]
    public T Get() => Value;
    
    [Obsolete("Use Value property instead")]
    public void Set(T value) => Value = value;
}

类型系统考量

在 Java 中，所有自定义类型都是引用类型，因此 SetOnce 可以无差别地处理任何类型。但在 .NET 中，值类型和引用类型的行为差异需要考虑：

1. 对于值类型（如 int、struct 等），直接使用 SetOnce 会导致装箱/拆箱操作
2. 对于性能敏感的场景，可以考虑创建专门的 SetOnceInt32 等类型
3. 对于数值类型，可以使用 J2N.Numerics 中的引用类型包装器

向后兼容性处理

为了确保平滑过渡，重构采取了以下策略：

1. 保留原有方法，但标记为过时
2. 提供清晰的过时消息，指导用户迁移到新 API
3. 计划在未来版本中完全移除旧方法
4. 使用 partial class 设计，便于后续清理过时代码

最佳实践建议

基于此次重构，可以总结出以下 .NET API 设计经验：

1. 优先使用属性而非 Get/Set 方法对
2. 对于一次性设置的值，考虑使用更明确的命名（如 InitialValue）
3. 对于可能抛出异常的操作，提供明确的文档说明
4. 在跨平台移植代码时，注意语言习惯的差异

这次重构不仅提升了代码的 .NET 风格一致性，也为类似场景的 API 设计提供了参考范例。通过这种渐进式的改进，Lucene.NET 项目能够更好地融入 .NET 生态系统，同时保持对原有用户的友好过渡。