Marten框架中的命名兼容性改进：ProjectionName与SubscriptionName的过渡方案

背景与问题

在Marten这个基于PostgreSQL的.NET事件溯源和文档数据库框架中，随着版本演进，部分API命名需要进行合理化调整。开发团队发现原有的ProjectionName和SubscriptionName属性命名虽然直观，但在设计一致性上存在改进空间。

技术决策

Marten团队决定采用渐进式演进策略：

1. 引入新命名规范：将相关属性统一简化为Name和Version
2. 保持向后兼容：通过创建过渡性shim属性（包装器属性）确保现有代码不中断
3. 标记过时API：使用[Obsolete]特性提示开发者迁移到新API

实现细节

投影(Projection)相关改进

public abstract class ProjectionBase
{
    [Obsolete("请使用Name属性替代")]
    public string ProjectionName => Name;
    
    public string Name { get; protected set; }
    
    [Obsolete("请使用Version属性替代")] 
    public string ProjectionVersion => Version;
    
    public string Version { get; protected set; }
}

订阅(Subscription)相关改进

public abstract class SubscriptionBase
{
    [Obsolete("请使用Name属性替代")]
    public string SubscriptionName => Name;
    
    public string Name { get; protected set; }
    
    [Obsolete("请使用Version属性替代")]
    public string SubscriptionVersion => Version;
    
    public string Version { get; protected set; }
}

事件切片(IEventSlice)改进

同步对事件切片接口进行了类似优化：

public interface IEventSlice
{
    [Obsolete("请使用Snapshot属性替代")]
    object Aggregate => Snapshot;
    
    object Snapshot { get; }
}

开发者迁移指南

1. 立即行动项：

   • 编译器警告中提示的[Obsolete]属性应尽快处理
   • 将代码中的ProjectionName更新为Name
   • 将SubscriptionVersion更新为Version

2. 兼容性保证：

   • 旧属性仍会继续工作，但建议在新代码中使用统一命名
   • 过渡期结束后（通常2-3个主版本），旧属性可能会被移除

设计思考

这种演进方式体现了几个优秀实践：

1. 平滑过渡：避免破坏性变更给开发者带来困扰
2. 显式沟通：通过编译器警告明确指导迁移路径
3. 命名简化：统一的核心属性名使API更加整洁
4. 关注点分离：通过包装器属性保持单一职责原则

总结

Marten通过这种渐进式API演进策略，既改善了框架内部的一致性，又最大限度地降低了对现有用户的影响。这种模式值得在需要进行重大API变更的库开发中借鉴，它平衡了技术债务清理和用户体验保护的双重需求。开发者应当利用这个过渡期逐步更新代码，为未来的框架升级做好准备。