FastEndpoints中JsonStringEnumConverter配置问题解析

问题背景

在使用FastEndpoints框架时，开发者可能会遇到枚举类型在JSON序列化时无法正确转换为字符串的问题。具体表现为：尽管已经配置了JsonStringEnumConverter，但API响应中枚举值仍然以数字形式输出，而不是预期的字符串形式。

问题现象

开发者配置了如下代码：

.UseFastEndpoints(c =>
{
    c.Serializer.Options.Converters.Add(new JsonStringEnumConverter());
    c.Endpoints.RoutePrefix = "api";
})

期望枚举类型AddressType在响应中显示为字符串形式（如"Type1"），但实际返回的是数字（如0）。

原因分析

1. 依赖冲突：项目中可能同时引用了多个JSON序列化相关的包，特别是同时存在Microsoft.AspNetCore.OpenApi和Swashbuckle.AspNetCore时，可能导致序列化行为不一致。

2. Converter配置时机：在某些情况下，全局配置的JsonStringEnumConverter可能没有正确应用到所有序列化场景。

3. Swagger集成问题：虽然SwaggerUI中显示正确的字符串形式，但实际API响应却返回数字，表明序列化配置可能没有完全传播到运行时环境。

解决方案

方案一：直接在枚举上添加特性

最可靠的解决方案是在枚举类型上直接添加[JsonConverter]特性：

[JsonConverter(typeof(JsonStringEnumConverter))]
public enum AddressType
{
    Type1,
    Type2,
    Type3
}

这种方法确保无论序列化配置如何，该枚举类型都会按照字符串形式序列化。

方案二：清理不必要的依赖

移除项目中与FastEndpoints不兼容或不必要的包引用：

<!-- 移除以下包 -->
<PackageReference Include="Microsoft.AspNetCore.OpenApi" Version="8.0.4"/>
<PackageReference Include="Swashbuckle.AspNetCore" Version="6.4.0"/>

FastEndpoints有自己的Swagger集成方案，不需要额外引入这些包。

方案三：验证Converter配置

确保使用的是正确的JsonStringEnumConverter：

// 确保使用的是System.Text.Json的Converter
using System.Text.Json.Serialization;
...
c.Serializer.Options.Converters.Add(new JsonStringEnumConverter());

最佳实践建议

1. 优先使用枚举特性：对于关键的枚举类型，直接在类型上添加[JsonConverter]特性是最可靠的做法。

2. 保持依赖简洁：只保留必要的依赖，避免引入可能冲突的包。

3. 测试实际响应：不要仅依赖SwaggerUI的显示，实际调用API验证响应格式。

4. 考虑全局一致性：如果项目中有大量枚举需要字符串序列化，可以在全局配置基础上，为关键枚举添加特性作为双重保障。

总结

FastEndpoints框架中枚举序列化问题通常源于配置未完全生效或依赖冲突。通过直接在枚举类型上添加JsonConverter特性是最可靠的解决方案，同时保持项目依赖的简洁性也能避免许多潜在问题。开发者应根据项目实际情况选择最适合的解决方案。