本文介绍如何在 APIATO 框架中通过 URL 参数安全、规范地查询数据库中的 NULL 值，避免直接使用 email:null 等易混淆的字符串解析方式，推荐采用显式参数设计与 Eloquent 查询逻辑结合的解决方案。
本文介绍如何在 apiato 框架中通过 url 参数安全、规范地查询数据库中的 null 值，避免直接使用 `email:null` 等易混淆的字符串解析方式，推荐采用显式参数设计与 eloquent 查询逻辑结合的解决方案。
在 APIATO 中，默认的搜索机制（如 SearchCriteria 或 FilterCriteria）通常基于字符串匹配或模糊查询，并不原生支持 field:null 这类语义化空值判断。若直接在 URL 中传递 ?search=email:null，框架会将其视为普通字符串搜索，而非 SQL 的 IS NULL 条件，导致查询失败或结果错误。
✅ 正确做法：使用专用查询参数替代模糊 search 字段
推荐为 NULL 查询设计独立、语义清晰的参数，例如：
GET /v1/users?email_is_null=1 GET /v1/users?email_is_null=0 // 表示 IS NOT NULL
在对应 Action 或 Criteria 类中处理该参数：
// app/Ship/Criteria/EmailNullCriteria.php
<?php namespace App\Ship\Criteria;
use Prettus\Repository\Contracts\CriteriaInterface;
use Prettus\Repository\Contracts\RepositoryInterface;
class EmailNullCriteria implements CriteriaInterface
{
public function apply($model, RepositoryInterface $repository)
{
$request = request();
if ($request->filled('email_is_null')) {
$isNull = filter_var($request->email_is_null, FILTER_VALIDATE_BOOLEAN);
return $isNull
? $model->whereNull('email')
: $model->whereNotNull('email');
}
return $model;
}
}
然后在你的 Endpoint 的 Action 中注册该 Criteria：
// app/Containers/User/Actions/FindUsersAction.php
public function handle()
{
return $this->repository
->withCriteria(new EmailNullCriteria())
->paginate();
}
⚠️ 注意事项：
- ❌ 避免在 search 参数中硬编码 :null 解析逻辑（如 $request->search === 'email:null'），这违反单一职责原则，且难以维护、易出错、无法扩展；
- ✅ 使用布尔型参数（如 email_is_null=1）更符合 REST 规范，也便于前端统一构造请求；
- ? 若需支持多字段空值查询（如 phone_is_null=1&name_is_null=1），可将 Criteria 改为动态字段识别，或使用数组式参数（如 is_null[]=email&is_null[]=phone）；
- ? 测试时务必覆盖 NULL / NOT NULL 两种场景，并验证数据库索引是否生效（WHERE email IS NULL 可利用允许 NULL 的索引）。
总结：APIATO 本身不内置 :null 语法支持，但通过自定义 Criteria + 显式参数设计，可安全、高效、可读性强地实现空值筛选。这是符合 Laravel 生态惯例与 APIATO 架构思想的最佳实践。
大量免费API接口：立即使用
涵盖生活服务API、金融科技API、企业工商API、等相关的API接口服务。免费API接口可安全、合规地连接上下游，为数据API应用能力赋能！
