WebApiClient中枚举类型参数序列化的处理技巧

在WebApiClient项目中，开发者经常会遇到枚举类型参数在HTTP请求中序列化的问题。默认情况下，当我们将枚举类型作为API接口参数时，系统会直接调用ToString()方法将枚举值转换为字符串形式，这可能导致与后端期望的数值格式不匹配。

问题场景分析

假设我们定义了以下API接口：

[HttpGet]
Task<TaskDto> GetAsync([PathQuery] TaskType type)

当TaskType是一个普通枚举时：

public enum TaskType
{
    Normal = 1,
    Special = 2
}

按照默认行为，调用GetAsync(TaskType.Normal)生成的URL会是"type=Normal"而不是期望的"type=1"。这是因为WebApiClient的KeyValueSerializer对于枚举类型的处理直接使用了ToString()方法。

解决方案

方法一：参数封装为类

一种简单的解决方案是将参数封装为类：

public class QueryParams
{
    public TaskType Type { get; set; }
}

[HttpGet]
Task<TaskDto> GetAsync([PathQuery] QueryParams query)

这种方式可以间接解决枚举序列化问题，但可能增加不必要的复杂度。

方法二：自定义特性（推荐）

更优雅的解决方案是创建自定义特性，继承PathQueryAttribute并重写序列化逻辑：

public class EnumAsNumberPathQueryAttribute : PathQueryAttribute
{
    public override IEnumerable<KeyValue> SerializeToKeyValues(ApiParameterContext context)
    {
        if (context.ParameterValue == null)
        {
            yield break;
        }

        var type = context.ParameterValue.GetType();
        if (type.IsEnum)
        {
            var numericValue = Convert.ChangeType(context.ParameterValue, Enum.GetUnderlyingType(type));
            yield return new KeyValue(context.ParameterName, numericValue.ToString());
        }
        else
        {
            foreach (var item in base.SerializeToKeyValues(context))
            {
                yield return item;
            }
        }
    }
}

使用方式：

[HttpGet]
Task<TaskDto> GetAsync([EnumAsNumberPathQuery] TaskType type)

实现原理

自定义特性通过以下步骤实现枚举值的正确序列化：

1. 检查参数是否为枚举类型
2. 如果是枚举，获取其基础类型(通常是int)并转换为数值
3. 将数值转换为字符串作为查询参数值
4. 非枚举类型则保持原有处理逻辑

扩展思考

对于更复杂的场景，可以考虑：

1. 支持字符串枚举和数值枚举的灵活切换
2. 添加全局配置选项控制枚举序列化行为
3. 支持自定义枚举值到字符串的映射关系

最佳实践建议

1. 前后端应明确约定枚举值的表示形式（数值或字符串）
2. 在团队内部统一枚举序列化策略
3. 对于公共API，优先使用数值形式，避免因枚举名称变更导致兼容性问题
4. 考虑在项目初期就实现自定义序列化逻辑，避免后期大规模修改

通过上述方法，开发者可以灵活控制WebApiClient中枚举类型的序列化行为，确保API调用符合预期。