基于.NET Core 7的Azure Cosmos DB NoSQL架构锁定需求问询

Azure Cosmos DB作为无Schema数据库，本身没有原生的“架构锁定”功能，但可以通过应用层约束和Cosmos DB侧验证结合的方式，实现类似效果，防止API变更意外修改现有文档的架构。以下是几种可行的方案：

1. 严格的实体模型与序列化配置 #

在.NET Core 7中，通过定义完全匹配现有架构的实体类，并配置CosmosClient的序列化规则，确保只有预期字段被写入数据库：

实现步骤： #

• 保持实体类严格对齐现有数据库的文档结构，不随意新增、修改或删除字段。
• 自定义Cosmos序列化器，启用严格的序列化/反序列化规则：
  • 序列化时仅包含实体类中定义的字段，避免写入额外属性
  • 反序列化时遇到未知字段直接抛出异常，及时发现结构不一致问题

// 严格匹配现有架构的实体类
public class Product
{
    [JsonPropertyName("id")]
    public string Id { get; set; }
    
    [JsonPropertyName("productName")]
    public string ProductName { get; set; }
    
    [JsonPropertyName("price")]
    public decimal Price { get; set; }
}

// 自定义严格序列化器
public class StrictCosmosSerializer : CosmosSerializer
{
    private readonly JsonSerializerOptions _strictOptions = new JsonSerializerOptions
    {
        PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
        // 仅序列化已赋值字段，避免写入null值到数据库
        DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull,
        // 反序列化时遇到未知字段直接抛出异常
        UnknownTypeHandling = JsonUnknownTypeHandling.Disallow
    };

    public override T FromStream<T>(Stream stream)
    {
        using (stream)
        {
            var result = JsonSerializer.Deserialize<T>(stream, _strictOptions);
            return result ?? throw new InvalidOperationException("文档反序列化失败");
        }
    }

    public override Stream ToStream<T>(T input)
    {
        var stream = new MemoryStream();
        JsonSerializer.Serialize(stream, input, _strictOptions);
        stream.Position = 0;
        return stream;
    }
}

// 配置CosmosClient使用自定义序列化器
var clientOptions = new CosmosClientOptions
{
    SerializerOptions = new CosmosSerializationOptions
    {
        Serializer = new StrictCosmosSerializer()
    }
};
var cosmosClient = new CosmosClient("your-connection-string", clientOptions);

当API代码中不小心修改了实体类（比如新增字段），序列化时不会将新字段写入数据库；如果数据库中出现不符合模型的文档，反序列化时会直接报错，及时暴露问题。

2. 使用Cosmos DB预触发器做写入前验证 #

在Cosmos DB容器上创建预触发器，在执行Create/Replace/Upsert操作前，强制验证文档架构是否符合现有规范，不符合则阻止写入：

实现步骤： #

1. 在Cosmos DB容器中创建名为validateSchema的预触发器（JavaScript）：

function validateSchema() {
    const context = getContext();
    const request = context.getRequest();
    const doc = request.getBody();

    // 定义现有架构的必填字段和类型约束
    const requiredFields = ["id", "productName", "price"];
    const fieldTypeMap = {
        "id": "string",
        "productName": "string",
        "price": "number"
    };

    // 检查必填字段是否存在
    for (const field of requiredFields) {
        if (!(field in doc)) {
            throw new Error(`缺失必填字段: ${field}`);
        }
    }

    // 检查字段类型是否正确
    for (const field in fieldTypeMap) {
        if (typeof doc[field] !== fieldTypeMap[field]) {
            throw new Error(`字段类型错误: ${field} 预期类型 ${fieldTypeMap[field]}, 实际类型 ${typeof doc[field]}`);
        }
    }

    // 可选：阻止写入额外字段
    const allowedFields = new Set(requiredFields);
    for (const field in doc) {
        if (!allowedFields.has(field)) {
            throw new Error(`不允许的额外字段: ${field}`);
        }
    }
}

2. 在.NET代码中调用CRUD操作时，指定使用该预触发器：

var upsertOptions = new ItemRequestOptions
{
    PreTriggers = new List<string> { "validateSchema" }
};
await container.UpsertItemAsync(product, requestOptions: upsertOptions);

这种方式直接在数据库侧拦截不符合架构的写入操作，即使API代码出现疏漏，也能有效保护现有数据的架构。

3. 架构合规性监控 #

定期运行Cosmos DB查询，检查容器内的文档是否符合现有架构，作为事后监控手段：

示例查询： #

SELECT COUNT(1) AS invalidDocCount
FROM c
WHERE 
    NOT IS_DEFINED(c.id) OR NOT IS_STRING(c.id)
    OR NOT IS_DEFINED(c.productName) OR NOT IS_STRING(c.productName)
    OR NOT IS_DEFINED(c.price) OR NOT IS_NUMBER(c.price)
    -- 检查是否存在额外字段（假设现有架构共3个字段）
    OR ARRAY_LENGTH(OBJECT_NAMES(c)) != 3

可以将这个查询封装成定时任务（比如用Azure Functions），一旦检测到不符合架构的文档，立即发送告警，及时处理异常情况。

4. 代码流程管控 #

除了技术手段，还要配合流程管控：

• 严格代码审查：任何对实体类的修改都需要经过审批，确保不会意外变更架构
• 单元测试：编写测试用例，验证序列化后的JSON结构与现有文档完全一致
• 集成测试：在测试环境模拟写入操作，验证新代码不会破坏现有架构

内容的提问来源于stack exchange，提问作者JHah