Spatie Laravel Query Builder 多值分隔符深度解析

Spatie Laravel Query Builder 多值分隔符深度解析

laravel-query-builder Easily build Eloquent queries from API requests 项目地址: https://gitcode.com/gh_mirrors/la/laravel-query-builder

什么是多值分隔符

在API开发中，我们经常需要通过URL参数传递多个值。默认情况下，spatie/laravel-query-builder使用逗号(,)作为分隔符来解析这些多值参数。但在实际业务场景中，参数值本身可能包含逗号，这就导致了解析歧义。

为什么需要自定义分隔符

考虑以下场景：我们需要通过API筛选电压值，这些电压值格式为"12,4V"、"4,7V"等。如果使用默认的逗号分隔符，解析结果会出现错误：

?filter=12,4V,4,7V,2,1V

会被错误解析为：

['12', '4V', '4', '7V', '2', '1V']

而实际上我们需要的是：

['12,4V', '4,7V', '2,1V']

如何设置自定义分隔符

spatie/laravel-query-builder提供了灵活的解决方案：

全局设置

在服务提供者中设置全局分隔符：

// AppServiceProvider.php
public function boot()
{
    \Spatie\QueryBuilder\QueryBuilderRequest::setArrayValueDelimiter('|');
}

中间件设置

针对特定路由设置分隔符：

// ApplyCustomDelimiterMiddleware.php
public function handle($request, $next)
{
    \Spatie\QueryBuilder\QueryBuilderRequest::setArrayValueDelimiter('|');
    return $next($request);
}

功能模块单独设置

可以针对不同功能设置不同的分隔符：

// 设置includes的分隔符
QueryBuilderRequest::setIncludesArrayValueDelimiter(';');

// 设置filters的分隔符
QueryBuilderRequest::setFilterArrayValueDelimiter('|');

单个过滤器设置

在定义允许的过滤器时直接指定分隔符：

AllowedFilter::exact('id', 'ref_id', true, ';');

实际应用示例

假设我们需要查询包含特殊字符的ID：

// GET /api/users?filter[id]=h4S4MG3(+>azv4z/I<o>,>XZII/Q1On

// 使用分号作为分隔符
AllowedFilter::exact('id', 'user_id', true, ';');

// 解析结果
['h4S4MG3(+>azv4z/I<o>', 'XZII/Q1On']

最佳实践建议

1. 一致性原则：在整个项目中保持分隔符使用的一致性
2. 安全性考虑：避免使用可能在URL中具有特殊含义的字符作为分隔符
3. 文档记录：在API文档中明确说明使用的分隔符
4. 测试覆盖：编写测试确保分隔符在各种场景下正常工作

注意事项

• 设置的分隔符会应用于所有相关功能（过滤、排序、字段选择等）
• 更改分隔符后，前端调用API时需要使用相同的分隔符
• 在复杂场景中，可以考虑使用URL编码来传递特殊字符

通过合理使用多值分隔符功能，可以大大增强spatie/laravel-query-builder处理复杂查询参数的能力，使API更加健壮和灵活。

laravel-query-builder Easily build Eloquent queries from API requests 项目地址: https://gitcode.com/gh_mirrors/la/laravel-query-builder