Scramble项目中处理FormRequest与Query Builder参数重复问题的最佳实践

问题背景

在使用Laravel开发API时，开发者经常会遇到表单验证(FormRequest)与查询构建器(Query Builder)配合使用的情况。Scramble作为API文档生成工具，在处理这种组合时可能会出现参数重复文档化的问题。

典型场景分析

一个常见的开发模式是：

1. 使用FormRequest进行输入验证
2. 使用Spatie的Query Builder处理过滤条件

例如开发者可能这样定义验证规则：

public function rules(): array
{
    return [
        'filter.date' => 'sometimes|date',
    ];
}

同时在控制器中使用Query Builder：

$query = QueryBuilder::for($baseQuery)
    ->allowedFilters([
        AllowedFilter::scope('date'),
    ]);

问题表现

这种实现方式会导致Scramble文档中出现两个相似的参数：

• filter[date] (来自Query Builder)
• filter.date (来自FormRequest)

解决方案

目前有两种处理方式可以避免参数重复：

临时解决方案：使用@ignoreParam注解

在FormRequest的验证规则中添加@ignoreParam注解，明确告诉Scramble忽略此参数的文档化：

public function rules(): array
{
    return [
        /** @ignoreParam */
        'filter.date' => 'sometimes|date',
    ];
}

未来优化方向

根据项目维护者的说明，未来版本计划实现参数的自动合并功能，这将从根本上解决此类问题，开发者无需手动处理参数重复的情况。

最佳实践建议

1. 明确职责划分：FormRequest应专注于输入验证，Query Builder处理数据过滤
2. 文档一致性：优先保留Query Builder生成的参数文档，因其通常包含更丰富的过滤说明
3. 版本规划：关注Scramble的更新，及时采用自动参数合并功能

总结

在现有版本中，使用@ignoreParam注解是解决参数重复文档化问题的有效方案。随着Scramble的迭代更新，这一问题将得到更优雅的解决。开发者应理解问题本质，根据项目需求选择合适的处理方式。