在ASP.NET Core中实现OpenAPI的蛇形命名策略

在ASP.NET Core项目中，我们经常需要为API接口定义统一的命名规范。本文将详细介绍如何在ASP.NET Core 9.0中使用OpenAPI实现请求和响应的蛇形命名(snake case)策略。

蛇形命名策略简介

蛇形命名是一种常见的命名约定，它将多个单词用下划线连接，所有字母小写。例如："userName"会转换为"user_name"。这种命名方式在API设计中很受欢迎，特别是在与Python等语言交互时。

配置JSON序列化选项

在ASP.NET Core中，我们可以通过配置JsonSerializerOptions来实现蛇形命名：

builder.Services.ConfigureHttpJsonOptions(options =>
{
    options.SerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower;
});

这个配置会全局影响所有HTTP JSON响应的属性命名方式。JsonNamingPolicy.SnakeCaseLower是.NET内置的蛇形命名策略实现。

控制器级别的配置

如果需要更细粒度的控制，可以在控制器层面配置JSON选项：

builder.Services.AddControllers()
    .AddJsonOptions(options =>
    {
        options.JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower;
    });

统一配置方法

为了避免代码重复，可以创建一个统一的配置方法：

static void ConfigureJsonSerializer(JsonSerializerOptions options)
{
    options.PropertyNamingPolicy = JsonNamingPolicy.SnakeCaseLower;
    options.Converters.Add(new JsonStringEnumConverter());
    options.DefaultIgnoreCondition = JsonIgnoreCondition.WhenWritingNull;
    options.WriteIndented = false;
    options.ReferenceHandler = ReferenceHandler.IgnoreCycles;
}

然后在服务配置中调用这个方法：

builder.Services.AddControllers()
    .AddJsonOptions(options => ConfigureJsonSerializer(options.JsonSerializerOptions));

builder.Services.ConfigureHttpJsonOptions(options => ConfigureJsonSerializer(options.SerializerOptions));

查询参数处理

对于URL查询参数，需要单独处理：

builder.Services.AddControllers(options =>
{
    options.ValueProviderFactories.Add(new SnakeCaseQueryValueProviderFactory());
});

自定义命名策略

虽然.NET提供了内置的蛇形命名策略，但也可以实现自定义策略：

public class JsonSerializerSnakeCaseNamingPolicy : JsonNamingPolicy
{
    public override string ConvertName(string name)
    {
        // 自定义转换逻辑
        return name.ToSnakeCase();
    }
}

注意事项

1. 当前版本的Microsoft.AspNetCore.OpenApi不支持Newtonsoft.Json，如果需要使用Newtonsoft.Json，需要考虑其他方案。

2. 命名策略配置会影响整个应用程序的JSON序列化行为，确保这是你期望的效果。

3. 在API文档工具(如Swagger/Scalar)中，可能需要额外配置才能正确显示蛇形命名的参数。

通过以上配置，我们可以确保ASP.NET Core应用程序的API接口在请求和响应中都使用一致的蛇形命名策略，提高API的规范性和可读性。