FastEndpoints项目中嵌套对象集合验证的Swagger集成问题解析

问题背景

在使用FastEndpoints框架开发Web API时，开发者经常会遇到需要对复杂请求对象进行验证的场景。特别是在处理嵌套对象集合时，如何正确配置验证规则并使其在Swagger文档中正确显示是一个常见的技术挑战。

常见错误做法

许多开发者最初可能会尝试以下验证配置方式：

internal sealed class Request
{
    public CreateNationalityParams[] Nationalities { get; set; } = [];
    
    internal class CreateNationalityParams
    {
        public required string NameAr { get; set; }
    }

    internal sealed class Validator : Validator<Request>
    {
        public Validator()
        {
            RuleFor(x => x.Nationalities)
                .NotEmpty()
                .ForEach(nationality =>
                {
                    nationality.ChildRules(n =>
                    {
                        n.RuleFor(x => x.NameAr)
                            .NotNull()
                            .NotEmpty()
                            .MinimumLength(3)
                            .MaximumLength(50);
                    });
                });
        }
    }
}

这种配置虽然能够正常工作，但存在一个明显问题：验证规则不会显示在Swagger文档中，导致API使用者无法从文档中了解这些重要的验证约束。

正确解决方案

FastEndpoints框架提供了更优雅的验证配置方式，能够同时满足验证功能和Swagger文档展示需求：

1. 为嵌套对象单独创建验证器

sealed class CreateNationalityParams
{
    public required string NameAr { get; set; }

    internal sealed class Validator : Validator<CreateNationalityParams>
    {
        public Validator()
        {
            RuleFor(x => x.NameAr)
                .NotNull()
                .NotEmpty()
                .MinimumLength(3)
                .MaximumLength(50);
        }
    }
}

2. 在主请求验证器中引用嵌套验证器

sealed class Request
{
    public CreateNationalityParams[] Nationalities { get; set; } = [];

    internal sealed class Validator : Validator<Request>
    {
        public Validator()
        {
            RuleFor(x => x.Nationalities).NotEmpty();
            RuleForEach(x => x.Nationalities)
                .SetValidator(new CreateNationalityParams.Validator());
        }
    }
}

技术原理分析

这种解决方案之所以能够正常工作，是因为：

1. 验证器分离：将嵌套对象的验证逻辑独立出来，遵循了单一职责原则，使代码结构更清晰。

2. RuleForEach与SetValidator组合：使用RuleForEach遍历集合中的每个元素，然后通过SetValidator应用独立的验证器，这种方式被Swagger识别并正确解析。

3. 元数据生成：FastEndpoints能够从独立的验证器中提取验证规则并生成相应的OpenAPI/Swagger元数据。

最佳实践建议

1. 对于任何复杂的嵌套对象，都应该为其创建独立的验证器类。

2. 在集合验证场景中，优先使用RuleForEach和SetValidator的组合，而不是嵌套的ChildRules。

3. 验证规则的粒度应该适中，既不要过于笼统，也不要过于细碎。

4. 保持验证器的独立性，便于复用和维护。

通过遵循这些实践原则，开发者可以构建出既功能完善又文档友好的API接口，提高API的可用性和可维护性。