如何限制Cosmos DB部分文档更新时添加新属性（允许数组操作）

目前Azure Cosmos DB .NET v3 SDK本身没有原生开关直接限制Patch操作添加新属性，但可以通过以下几种方案实现你的需求：

1. 容器级Schema验证（推荐原生方案） #

利用Cosmos DB的Schema验证策略，在容器层面定义文档的合法结构，直接拦截添加新属性的请求。通过设置additionalProperties: false来禁止新增未定义的属性，同时允许对已有数组执行追加操作。

代码示例：创建带Schema验证的容器 #

// 定义JSON Schema，指定允许的属性和结构
var schema = @"
{
    ""type"": ""object"",
    ""properties"": {
        ""id"": { ""type"": ""string"" },
        ""name"": { ""type"": ""string"" },
        ""tags"": { ""type"": ""array"", ""items"": { ""type"": ""string"" } }
    },
    ""required"": [""id"", ""name""],
    ""additionalProperties"": false
}";

var validationPolicy = new SchemaValidationPolicy
{
    Schema = schema,
    ValidationLevel = SchemaValidationLevel.Strict, // 严格校验
    ValidationFailureAction = SchemaValidationFailureAction.Reject // 拒绝不符合Schema的请求
};

var containerProps = new ContainerProperties("Products", "/id")
{
    SchemaValidationPolicy = validationPolicy
};

// 创建或更新容器
await database.CreateContainerIfNotExistsAsync(containerProps);

当用户尝试添加/color这类未定义属性时，Cosmos DB会直接返回400错误，无需额外代码处理。

2. API层自定义Patch操作拦截 #

在ASP.NET的API接收Patch请求后，先对传入的PatchOperation集合做校验，过滤掉非法操作：

• 允许对现有数组的追加操作（路径以/-结尾，比如/tags/-）
• 允许对现有属性的replace/remove操作
• 拒绝所有添加新属性的add操作

代码示例：校验Patch操作 #

// 假设你的实体类是Product
var allowedPropertyPaths = typeof(Product)
    .GetProperties()
    .Select(p => $"/{p.Name}")
    .ToList();

var validOperations = new List<PatchOperation>();

foreach (var op in incomingPatchOperations)
{
    switch (op.OperationType)
    {
        case PatchOperationType.Add:
            // 数组追加操作（如/tags/-）
            if (op.Path.EndsWith("/-"))
            {
                var basePath = op.Path.Substring(0, op.Path.Length - 2);
                if (allowedPropertyPaths.Contains(basePath))
                {
                    validOperations.Add(op);
                }
                else
                {
                    throw new BadHttpRequestException("仅允许对现有数组执行追加操作");
                }
            }
            // 对现有属性的add操作（等价于replace）
            else if (allowedPropertyPaths.Contains(op.Path))
            {
                validOperations.Add(op);
            }
            else
            {
                throw new BadHttpRequestException("禁止添加新属性");
            }
            break;
        case PatchOperationType.Replace:
        case PatchOperationType.Remove:
            if (allowedPropertyPaths.Contains(op.Path))
            {
                validOperations.Add(op);
            }
            else
            {
                throw new BadHttpRequestException("仅允许操作现有属性");
            }
            break;
        default:
            throw new BadHttpRequestException("不支持的Patch操作类型");
    }
}

// 执行合法的Patch操作
await container.PatchItemAsync<Product>(docId, new PartitionKey(docId), validOperations);

3. 存储过程封装Patch逻辑 #

将Patch操作的校验和执行逻辑放到Cosmos DB的存储过程中，所有Patch请求必须通过存储过程触发，在数据库端完成合法性校验。

存储过程示例（JavaScript） #

function validateAndPatch(id, patchOps) {
    const collection = getContext().getCollection();
    const response = getContext().getResponse();

    // 获取目标文档
    collection.readDocument(collection.getSelfLink() + "/docs/" + id, (err, doc) => {
        if (err) throw err;

        const validOps = [];
        const docProps = Object.keys(doc);

        for (const op of patchOps) {
            if (op.op === "add") {
                // 数组追加操作
                if (op.path.endsWith("/-")) {
                    const propName = op.path.slice(1, -2);
                    if (docProps.includes(propName) && Array.isArray(doc[propName])) {
                        validOps.push(op);
                    } else {
                        throw new Error("仅允许对现有数组追加元素");
                    }
                } else {
                    // 现有属性的add操作
                    const propName = op.path.slice(1);
                    if (docProps.includes(propName)) {
                        validOps.push(op);
                    } else {
                        throw new Error("禁止添加新属性");
                    }
                }
            } else if (op.op === "replace" || op.op === "remove") {
                const propName = op.path.slice(1);
                if (docProps.includes(propName)) {
                    validOps.push(op);
                } else {
                    throw new Error("仅允许操作现有属性");
                }
            }
        }

        // 执行合法操作并更新文档
        const updatedDoc = {...doc};
        for (const op of validOps) {
            if (op.op === "add" && op.path.endsWith("/-")) {
                const propName = op.path.slice(1, -2);
                updatedDoc[propName].push(op.value);
            } else if (op.op === "replace") {
                const propName = op.path.slice(1);
                updatedDoc[propName] = op.value;
            } else if (op.op === "remove") {
                const propName = op.path.slice(1);
                delete updatedDoc[propName];
            }
        }

        collection.replaceDocument(doc._self, updatedDoc, (err, result) => {
            if (err) throw err;
            response.setBody(result);
        });
    });
}

方案对比 #

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