WebApiClient中枚举类型参数序列化的解决方案

在WebApiClient项目中，开发者经常会遇到枚举类型参数在URL序列化时出现的问题。默认情况下，当枚举类型作为API接口参数时，KeyValueSerializer会直接将枚举值转换为字符串形式（即枚举项的名称），而实际开发中我们可能需要将其序列化为对应的整数值。

问题背景

考虑以下API接口定义：

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

当调用此接口并传入type=normal时，期望URL中的参数应该是type=1（假设normal对应的枚举值为1），但实际结果却是type=normal。这是因为WebApiClient默认的序列化行为将枚举类型直接ToString()处理了。

解决方案

方案一：参数封装为类

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

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

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

这种方式利用了类的序列化机制，可以正确地将枚举值转换为对应的数字。

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

更灵活的解决方案是创建自定义特性，继承自PathQueryAttribute并重写序列化方法：

public class EnumPathQueryAttribute : 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([EnumPathQuery] TaskType type)

实现原理

WebApiClient默认的KeyValueSerializer在处理参数时，会检查参数的类型。对于枚举类型，由于它的TypeCode是Int32，所以会直接调用ToString()方法，导致输出的是枚举项名称而非数值。

通过自定义特性，我们可以拦截这个序列化过程，在遇到枚举类型时，先将其转换为底层数值类型（通常是int），然后再转为字符串。这样就能确保URL中的参数是数字形式而非名称形式。

最佳实践

1. 一致性原则：在整个项目中保持枚举参数的序列化方式一致，要么全部使用名称，要么全部使用数值。

2. 文档说明：在团队内部文档中明确枚举参数的序列化规则，避免不同开发者采用不同方式。

3. 性能考虑：自定义特性的序列化逻辑应保持高效，避免不必要的类型检查和转换。

4. 扩展性：可以考虑在自定义特性中添加一个属性，让开发者能够选择使用名称还是数值：

   public class EnumPathQueryAttribute : PathQueryAttribute
   {
       public bool UseNumericValue { get; set; } = true;
       
       // ...重写SerializeToKeyValues方法时根据此属性决定输出格式
   }
   

总结

WebApiClient提供了灵活的扩展机制来处理各种参数序列化场景。通过自定义特性，开发者可以轻松解决枚举类型参数序列化不符合预期的问题。这种方案不仅解决了当前问题，还展示了WebApiClient良好的扩展性设计，为处理其他特殊序列化需求提供了参考。