Marten 项目中文档表名解析功能的设计与实现

背景介绍

Marten 是一个基于 PostgreSQL 的 .NET 文档数据库和事件存储库。在实际开发中，开发者经常需要直接使用 SQL 查询来操作文档数据，特别是在使用 Marten 新增的 session.AdvancedSqlQueryAsync() 方法时。然而，手动构造 SQL 查询时，准确获取文档和聚合对应的数据库表名一直是个挑战。

问题分析

Marten 在内部会自动为文档类型生成对应的数据库表，表名遵循特定规则（如 mt_doc_ 前缀）。但当开发者需要：

1. 自定义表名或模式名
2. 处理事件存储相关的特殊表
3. 确保 SQL 查询中的表名引用准确无误

时，缺乏一个统一的 API 来获取这些信息，容易导致硬编码和潜在的错误。

解决方案设计

Marten 团队提出了一个优雅的解决方案：通过 IDocumentSchemaResolver 接口提供表名解析功能。这个设计具有以下特点：

核心接口设计

public interface IDocumentSchemaResolver
{
    string DatabaseSchemaName { get; }
    string EventsSchemaName { get; }
    
    string For<TDocument>(bool qualified = true);
    string ForEvents(bool qualified = true);
    string ForStreams(bool qualified = true);
    string ForEventProgression(bool qualified = true);
}

功能亮点

1. 统一访问点：通过 IReadOnlyStoreOptions.Schema 属性暴露表名解析功能
2. 灵活的表名获取：
   • 支持文档类型和投影类型的表名查询
   • 支持事件存储相关特殊表的查询
   • 可选择是否包含模式名前缀
3. 强类型安全：使用泛型方法确保编译时类型检查

实际应用示例

// 获取表名解析器
var schema = session.DocumentStore.Options.Schema;

// 查询用户文档表名（带模式名）
var userTable = schema.For<User>();  // 返回 "public.mt_doc_user"

// 查询事件表名（不带模式名）
var eventsTable = schema.ForEvents(qualified: false);  // 返回 "mt_events"

// 在高级SQL查询中使用
var results = await session.AdvancedSqlQueryAsync<DocWithMeta, DocDetailsWithMeta, long>(
    $"""
    select row(a.id, a.data, a.mt_version),
           row(b.id, b.data, b.mt_version)
    from {schema.For<DocWithMeta>()} a
    join {schema.For<DocDetailsWithMeta>()} b on a.id = b.id
    where (a.data ->> 'Id')::int > 1
    """);

技术价值

1. 消除硬编码：不再需要在SQL字符串中硬编码表名
2. 支持自定义配置：自动适应开发者自定义的表名和模式名
3. 提高可维护性：表名变更只需修改配置，不影响查询代码
4. 增强类型安全：减少因表名拼写错误导致的运行时错误

实现建议

对于需要在Marten基础上进行开发的团队，可以：

1. 在数据访问层集中使用表名解析器
2. 为常用文档类型创建扩展方法简化调用
3. 在单元测试中验证关键查询的表名正确性

总结

Marten 的这一改进为开发者提供了更安全、更灵活的方式来构建SQL查询，特别是在复杂查询场景下。通过标准化的表名解析接口，既保持了Marten的易用性，又为高级用法提供了必要的支持，体现了框架设计的一致性和完整性。