请求指导：将CloudFlare缓存清除请求的Files转为C#嵌套模型类

咱们先拆解一下你提供的Cloudflare API请求里的files数组结构：它是混合类型数组——既包含纯字符串URL，又包含带url和headers的复杂对象。在C#这种强类型语言里，我们需要用一些技巧来处理这种混合场景，下面是两种可行的方案：

方案1：使用object类型数组（快速实现） #

如果只是快速落地需求，不想写额外的自定义逻辑，可以直接用object[]来容纳两种类型的元素，依赖JSON序列化库（比如System.Text.Json或Newtonsoft.Json）自动处理类型转换：

// 根请求类，对应API的顶层结构
public class CachePurgeRequest
{
    // System.Text.Json用[JsonPropertyName]，Newtonsoft.Json用[JsonProperty]
    [JsonPropertyName("files")]
    public object[] Files { get; set; }
}

// 带Headers的文件对象类
public class PurgeFileWithHeaders
{
    [JsonPropertyName("url")]
    public string Url { get; set; }

    [JsonPropertyName("headers")]
    public PurgeHeaders Headers { get; set; }
}

// 对应文件的Headers结构
public class PurgeHeaders
{
    [JsonPropertyName("Origin")]
    public string Origin { get; set; }

    [JsonPropertyName("CF-IPCountry")]
    public string CfIpCountry { get; set; }

    [JsonPropertyName("CF-Device-Type")]
    public string CfDeviceType { get; set; }
}

使用示例 #

// 构建请求实例
var purgeRequest = new CachePurgeRequest
{
    Files = new object[]
    {
        "http://www.example.com/css/styles.css", // 直接传入纯URL字符串
        new PurgeFileWithHeaders
        {
            Url = "http://www.example.com/cat_picture.jpg",
            Headers = new PurgeHeaders
            {
                Origin = "cloudflare.com",
                CfIpCountry = "US",
                CfDeviceType = "desktop"
            }
        }
    }
};

// 序列化请求（以System.Text.Json为例）
var jsonPayload = JsonSerializer.Serialize(purgeRequest, new JsonSerializerOptions { WriteIndented = true });

这个方案优点是简单快捷，但缺点是Files数组是弱类型的，编译时无法校验元素类型，容易出现人为错误。

方案2：自定义JSON转换器（强类型推荐） #

如果想要强类型的安全性，避免类型错误，可以创建基类+自定义JSON转换器的组合，让编译器帮我们做类型检查：

步骤1：定义基类与子类 #

// 抽象基类，统一两种文件类型
public abstract class PurgeFileBase { }

// 纯URL的文件类
public class PurgeFileUrl : PurgeFileBase
{
    public string Url { get; set; }

    public PurgeFileUrl(string url) => Url = url;
}

// 带Headers的文件类（和方案1一致）
public class PurgeFileWithHeaders : PurgeFileBase
{
    [JsonPropertyName("url")]
    public string Url { get; set; }

    [JsonPropertyName("headers")]
    public PurgeHeaders Headers { get; set; }
}

// Headers类（和方案1一致）
public class PurgeHeaders
{
    [JsonPropertyName("Origin")]
    public string Origin { get; set; }

    [JsonPropertyName("CF-IPCountry")]
    public string CfIpCountry { get; set; }

    [JsonPropertyName("CF-Device-Type")]
    public string CfDeviceType { get; set; }
}

步骤2：编写自定义JSON转换器 #

以System.Text.Json为例，实现转换器来处理字符串和对象的双向转换：

public class PurgeFileConverter : JsonConverter<PurgeFileBase>
{
    public override PurgeFileBase Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
    {
        // 判断JSON token类型，决定反序列化的目标
        if (reader.TokenType == JsonTokenType.String)
        {
            return new PurgeFileUrl(reader.GetString());
        }
        else if (reader.TokenType == JsonTokenType.StartObject)
        {
            return JsonSerializer.Deserialize<PurgeFileWithHeaders>(ref reader, options);
        }

        throw new JsonException("无法解析PurgeFile类型");
    }

    public override void Write(Utf8JsonWriter writer, PurgeFileBase value, JsonSerializerOptions options)
    {
        // 根据实例类型，决定序列化的格式
        if (value is PurgeFileUrl urlFile)
        {
            writer.WriteStringValue(urlFile.Url);
        }
        else if (value is PurgeFileWithHeaders headerFile)
        {
            JsonSerializer.Serialize(writer, headerFile, options);
        }
        else
        {
            throw new JsonException("不支持的PurgeFile类型");
        }
    }
}

步骤3：更新根请求类并使用转换器 #

public class CachePurgeRequest
{
    [JsonPropertyName("files")]
    [JsonConverter(typeof(PurgeFileConverter))] // 指定自定义转换器
    public List<PurgeFileBase> Files { get; set; } = new List<PurgeFileBase>();
}

使用示例 #

var purgeRequest = new CachePurgeRequest
{
    Files = new List<PurgeFileBase>
    {
        new PurgeFileUrl("http://www.example.com/css/styles.css"),
        new PurgeFileWithHeaders
        {
            Url = "http://www.example.com/cat_picture.jpg",
            Headers = new PurgeHeaders
            {
                Origin = "cloudflare.com",
                CfIpCountry = "US",
                CfDeviceType = "desktop"
            }
        }
    }
};

// 序列化请求
var jsonPayload = JsonSerializer.Serialize(purgeRequest, new JsonSerializerOptions { WriteIndented = true });

这个方案是强类型的，编译时就能校验元素类型，更适合大型项目或者需要严格类型约束的场景。

注意事项 #

• 如果你使用的是Newtonsoft.Json（Json.NET），自定义转换器的写法会略有不同，但核心思路一致：判断JSON token类型来选择反序列化的目标类型。
• 发送请求时要确保设置正确的请求头：Content-Type: application/json，否则Cloudflare API可能无法正确解析 payload。

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