Apiato如何通过URL搜索条件实现null与非null值查询

Apiato默认的搜索解析逻辑不支持直接识别null值语法，传入search=email:null时框架会默认把null当做普通字符串做等值匹配，无法生成WHERE email IS NULL的SQL语句，可通过以下方式扩展实现需求：

1. 扩展搜索条件解析逻辑 #

• 单Repository生效：找到对应业务的Repository类（路径一般为app/Containers/{所属Section}/{业务Container}/Data/Repositories/xxxRepository.php），覆写搜索条件组装方法，增加空值判断逻辑：

protected function applySearchCondition($query, $field, $value)
{
    // 匹配IS NULL查询
    if (strtolower($value) === 'null') {
        return $query->whereNull($field);
    }
    // 匹配IS NOT NULL查询，约定传值为not null
    if (strtolower($value) === 'not null') {
        return $query->whereNotNull($field);
    }
    // 保留框架原生的其他搜索逻辑
    return parent::applySearchCondition($query, $field, $value);
}

• 全局生效：新建一个基础Repository类继承框架自带的核心Repository，把上述空值解析逻辑写在基类中，后续所有业务Repository统一继承这个自定义基类即可，无需重复编写逻辑。
• 配置搜索白名单：在对应Repository的$fieldSearchable属性数组中，把需要支持空值检索的字段（比如示例中的email）加入白名单，否则搜索条件会被框架自动过滤。

2. 接口传参规则 #

配置完成后即可直接通过URL参数实现空值检索：

• 查询email字段为NULL的记录：api.domain.test/v1/endpoint?search=email:null
• 查询email字段非NULL的记录：api.domain.test/v1/endpoint?search=email:not null

3. 结果同组展示实现 #

• 若需要在接口返回层就把空值记录归为同一组，直接在查询逻辑中增加自定义排序规则即可，示例：

public function boot()
{
    parent::boot();
    // 把email为null的记录统一排在最前，实现同组聚合
    $this->orderByRaw('CASE WHEN email IS NULL THEN 0 ELSE 1 END');
}

• 如果需要前端自定义分组渲染，可在对应Model的返回资源类中增加一个标识字段，比如is_email_null，返回布尔值标记当前记录的email是否为空，前端拿到数据后直接按该字段分组即可。

注意：不要把未做校验的敏感字段加入搜索白名单，避免产生越权查询、SQL注入等安全风险。

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