FastEndpoints Get方法查询参数Swagger生成异常及代码示例求助

核心问题原因 #

FastEndpoints 默认会将请求对象解析为请求体，但 GET 请求的查询参数需要明确指定绑定源为Query，否则 Swagger 会错误地将其识别为请求体，同时运行时也会因为 GET 请求不允许携带请求体而报错。另外，"Value cannot be null. (Parameter 'key')" 错误通常是因为请求对象的属性未正确标记查询参数绑定，导致框架无法找到对应的参数键。

解决步骤 #

1. 明确标记查询参数绑定：使用 [QueryParam] 属性标记请求对象中的查询参数字段，或者在端点配置中指定绑定源为 BindingSource.Query。
2. 确保 GET 请求不使用请求体：FastEndpoints 中 GET 端点的请求对象必须绑定到 Query，不能默认用 Body。

示例代码1：无请求对象的 GET 端点（直接使用查询参数） #

这种场景适合参数较少的情况，直接在端点方法中声明查询参数，框架会自动识别并生成正确的 Swagger 文档。

using FastEndpoints;

public class GetUserEndpoint : EndpointWithoutRequest<object>
{
    public override void Configure()
    {
        Get("/api/users");
        AllowAnonymous();
        Summary(s =>
        {
            s.Summary = "根据ID和用户名获取用户";
            s.Description = "通过查询参数传递用户ID和用户名进行查询";
            s.QueryParam<int>("userId").Description = "用户ID";
            s.QueryParam<string>("userName").Description = "用户名（可选）";
        });
    }

    public override async Task HandleAsync(CancellationToken ct)
    {
        // 从查询参数获取值
        var userId = Query<int>("userId");
        var userName = Query<string?>("userName");

        // 业务逻辑示例
        var user = new { Id = userId, Name = userName ?? "默认用户" };
        await SendAsync(user, cancellation: ct);
    }
}

示例代码2：使用请求对象的 GET 端点 #

当查询参数较多时，推荐使用请求对象，此时必须给每个属性标记 [QueryParam]，确保框架将其识别为查询参数而非请求体。

第一步：定义请求对象 #

using FastEndpoints;

public class GetUserRequest
{
    [QueryParam] // 关键：标记为查询参数
    public int UserId { get; set; }

    [QueryParam]
    public string? UserName { get; set; }

    [QueryParam(Required = false)] // 可选参数可以显式标记
    public int? Age { get; set; }
}

第二步：实现端点 #

using FastEndpoints;

public class GetUserWithRequestEndpoint : Endpoint<GetUserRequest, object>
{
    public override void Configure()
    {
        Get("/api/users/with-request");
        AllowAnonymous();
        Summary(s =>
        {
            s.Summary = "使用请求对象获取用户";
            s.Description = "通过绑定到查询参数的请求对象传递查询条件";
        });
        // 可选：强制指定绑定源（如果自动识别失效时用）
        // BindFrom(BindingSource.Query);
    }

    public override async Task HandleAsync(GetUserRequest req, CancellationToken ct)
    {
        // 直接使用请求对象的属性
        var user = new 
        { 
            Id = req.UserId, 
            Name = req.UserName ?? "默认用户",
            Age = req.Age ?? 0
        };
        await SendAsync(user, cancellation: ct);
    }
}

解决"Value cannot be null. (Parameter 'key')"错误 #

这个错误通常出现在以下场景：

• 请求对象的属性未标记 [QueryParam]，框架尝试从 Body 绑定但 GET 请求没有 Body，导致找不到参数键。
• 端点方法中使用 Query<T>("key") 时，传入的 key 字符串为 null 或空。

修复方式：

1. 确保请求对象的每个查询参数属性都添加 [QueryParam] 属性。
2. 使用 Query<T>() 方法时，传入的参数名必须与查询字符串的键完全匹配，且不能为 null。

内容的提问来源于stack exchange，提问作者Gholamreza Fathpour