Elasticsearch-NET客户端中RawJsonString参数编码问题解析

在Elasticsearch-NET客户端8.11.0版本中，开发人员发现了一个关于脚本参数处理的异常行为。当使用RawJsonString类型作为脚本参数时，该参数会被错误地编码为字符串而非原始JSON格式。

问题现象

开发人员在使用UpdateByQuery操作时，尝试通过InlineScript传递JSON格式的参数。按照设计预期，RawJsonString应该保持原始JSON格式直接嵌入到请求体中。然而实际生成的请求中，JSON内容被转义成了字符串形式，导致服务端无法正确解析。

示例代码中，开发人员期望生成如下结构的请求体：

{
    "script": {
        "params": {
            "msg": {
                "_access": ["ACC01"]
            }
        }
    }
}

但实际生成的却是：

{
    "script": {
        "params": {
            "msg": {
                "json": "{\"_access\": [\"ACC01\"]}"
            }
        }
    }
}

技术分析

这个问题源于RawJsonString类型未被正确标注使用RawJsonConverter。在Elasticsearch-NET客户端的序列化机制中，转换器负责决定如何将特定类型序列化为JSON格式。当缺少适当的转换器标注时，系统会默认使用字符串序列化方式。

影响范围

该问题主要影响以下场景：

1. 使用脚本操作（Script/InlineScript）时传递复杂JSON参数
2. 需要保持JSON原始结构不被转义的场景
3. 8.x版本的Elasticsearch-NET客户端

解决方案建议

对于遇到此问题的开发者，可以采取以下临时解决方案：

1. 手动序列化JSON字符串并直接赋值：

Params = new Dictionary<string, object>
{
    { "msg", JsonSerializer.Deserialize<JsonElement>(@"{""_access"":[""ACC01""]}") }
}

2. 等待官方修复版本发布后升级客户端

深入理解

Elasticsearch-NET客户端中的序列化机制采用了System.Text.Json作为底层框架。RawJsonString类型的本意是绕过常规的序列化流程，直接将预先生成的JSON内容写入输出流。这种设计在处理复杂嵌套结构或需要精确控制JSON输出的场景中尤为重要。

最佳实践

在使用脚本参数时，建议：

1. 对于简单类型参数，直接使用原生类型
2. 对于复杂JSON结构，考虑使用JsonDocument或JsonElement类型
3. 密切关注客户端的更新日志，及时获取问题修复信息

该问题的修复将确保Elasticsearch-NET客户端在处理原始JSON参数时能够保持预期的行为，为开发者提供更可靠的开发体验。