Hyperf 数据库查询构建器(Query Builder)完全指南:从结果获取、条件查询到写入更新与悲观锁

原创2026-10-05 19:08:201,916 阅读
文章标签:后端Web框架微服务RPC框架依赖注入服务注册发现配置中心并发编程API网关消息队列

Hyperf 数据库查询构建器(Query Builder)完全指南:从结果获取、条件查询到写入更新与悲观锁

导读

Hyperf 的数据库查询构建器(Query Builder)是 hyperf/db-connection 组件提供的面向对象的数据库查询接口,它位于框架数据访问层的核心位置:既可以直接通过 Hyperf\DbConnection\Db 门面完成对任意表的增删改查,也构成了 Model 层 ORM 查询的底层基础。本文将以 docs/en/db/querybuilder.md 为主线,完整覆盖查询结果获取、条件构造(Where)、连接查询、原生表达式、聚合与分块处理、插入更新删除以及悲观锁等内容,并结合仓库源码(Builder.php、BuildsQueries.php、Db.php 等)剖析其底层实现,让你在读完本文后既能直接上手编写生产级查询代码,也能理解每条 SQL 背后的构建与绑定机制。

查询构建器简介

Hyperf 的查询构建器为创建和执行数据库查询提供了统一且便捷的接口,能够在所有受支持的数据库系统上执行大部分数据库操作。它最显著的安全特性是:全程使用 PDO 参数绑定(Parameter Binding)来防止 SQL 注入攻击,因此你无需对传入的绑定值做额外的字符串转义处理。

use Hyperf\DbConnection\Db;

$users = Db::select('SELECT * FROM user;');
$users = Db::table('user')->get();
$users = Db::table('user')->select('name', 'gender as user_gender')->get();

从源码结构看,Db 是一个典型的静态门面(Facade):在 Db.php 中,所有静态调用都会经由 __callStatic 从容器中解析出 Db::class 实例,再通过 ConnectionResolverInterface 解析出实际的连接对象(默认使用 default 连接),最终把方法调用转发给 Hyperf\Database\Connection。这意味着:

  • Db::select(...) 等价于 Db::connection()->select(...),即直接执行原生 SQL;
  • Db::table('user') 返回一个 Hyperf\Database\Query\Builder 实例,之后的链式调用全部作用于该构建器;
  • 连接实例来自连接池(见下文配置说明),因此在协程环境下可以安全复用。

连接配置与连接池

查询构建器的底层连接由 hyperf/db-connection 组件管理,其发布配置模板位于 src/db-connection/publish/databases.php。将组件安装后,可通过 php bin/hyperf.php vendor:publish hyperf/db-connection 将配置发布到 config/autoload/databases.php。核心参数如下:

return [
    'default' => [
        'driver' => env('DB_DRIVER', 'mysql'),
        'host' => env('DB_HOST', 'localhost'),
        'port' => env('DB_PORT', '3306'),
        'database' => env('DB_DATABASE', 'hyperf'),
        'username' => env('DB_USERNAME', 'root'),
        'password' => env('DB_PASSWORD', ''),
        'charset' => env('DB_CHARSET', 'utf8'),
        'collation' => env('DB_COLLATION', 'utf8_unicode_ci'),
        'prefix' => env('DB_PREFIX', ''),
        'pool' => [
            'min_connections' => 1,
            'max_connections' => 10,
            'connect_timeout' => 10.0,
            'wait_timeout' => 3.0,
            'heartbeat' => -1,
            'max_idle_time' => (float) env('DB_MAX_IDLE_TIME', 60),
        ],
        // ...
    ],
];

其中 pool 段定义了连接池的最小连接数、最大连接数、连接超时、获取连接等待时间等参数;prefix 可统一为表名添加前缀;commands 段配置了 gen:model 等数据库相关命令的默认行为。需要说明的是,原文档在此并未展开连接池细节,这里补充的配置均来自仓库中真实的发布模板,供你按需查阅 databases.php。

获取查询结果

返回类型与遍历方式

Db::select() 返回数组,而 table(...)->get() 返回 Hyperf\Collection\Collection 集合,集合中的每个元素是 stdClass 对象,因此可以这样遍历:

<?php

foreach ($users as $user) {
    echo $user->name;
}

将结果转换为数组格式

某些场景下你可能希望查询结果以 Array 数组而非 stdClass 对象返回。由于 Eloquent 会移除配置中默认的 FetchMode,此时可以通过监听 Hyperf\Database\Events\StatementPrepared 事件来修改取数模式:

<?php
declare(strict_types=1);

namespace App\Listener;

use Hyperf\Database\Events\StatementPrepared;
use Hyperf\Event\Annotation\Listener;
use Hyperf\Event\Contract\ListenerInterface;
use PDO;

#[Listener]
class FetchModeListener implements ListenerInterface
{
    public function listen(): array
    {
        return [
            StatementPrepared::class,
        ];
    }

    public function process(object $event)
    {
        if ($event instanceof StatementPrepared) {
            $event->statement->setFetchMode(PDO::FETCH_ASSOC);
        }
    }
}

从源码看,StatementPrepared.php 事件对象携带了 ConnectionInterface $connection 与 PDOStatement $statement 两个公共属性,监听器正是通过后者直接设置 PDO 的取数模式(PDO::FETCH_ASSOC)。该事件在每次 SQL 预处理完成后触发,是全局切换返回结构的标准扩展点。

获取单列的值:pluck

如果只需要结果集中的某一列,可以使用 pluck 方法。下面示例获取 roles 表中所有 title 字段的集合:

<?php
use Hyperf\DbConnection\Db;

$names = Db::table('user')->pluck('name');

foreach ($names as $name) {
    echo $name;
}

说明:原文档示例中 echo $names; 为笔误,实际应输出循环变量 $name。

还可以为返回集合中的字段指定自定义键:

<?php
use Hyperf\DbConnection\Db;

$roles = Db::table('roles')->pluck('title', 'name');

foreach ($roles as $name => $title) {
    echo $title;
}

从 Builder.php 的实现看,pluck($column, $key = null) 会借助 onceWithColumns 仅查询所需列,随后根据结果是数组还是对象分别走 pluckFromArrayColumn / pluckFromObjectColumn 组装键值对,并自动剥离 表名. 限定前缀。

分块处理结果:chunk 与 chunkById

当需要处理成千上万条记录时(例如在 Command 命令中批量处理数据),chunk 方法会一次取出一小块结果集交给闭包处理,从而控制内存占用。以下示例将 user 表的数据按每次 100 条切块:

<?php
use Hyperf\DbConnection\Db;

Db::table('user')->orderBy('id')->chunk(100, function ($users) {
    foreach ($users as $user) {
        //
    }
});

在闭包中返回 false 可以终止后续的分块获取:

use Hyperf\DbConnection\Db;

Db::table('user')->orderBy('id')->chunk(100, function ($users) {

    return false;
});

注意:如果在分块处理的同时更新了数据库记录,chunk 的结果可能与预期不一致(因为它是基于 forPage 的页偏移实现)。此时应改用 chunkById——该方法会基于记录的主键自动分页,以下示例在分块中安全地更新记录:

use Hyperf\DbConnection\Db;

Db::table('user')->where('gender', 1)->chunkById(100, function ($users) {
    foreach ($users as $user) {
        Db::table('user')
            ->where('id', $user->id)
            ->update(['update_time' => time()]);
    }
});

在分块回调中更新或删除记录时,对主键或外键的任何更改都可能影响分块查询,从而导致部分记录不会出现在分块结果中。

源码佐证:chunk 定义于 BuildsQueries.php,它首先调用 enforceOrderBy() 强制要求排序,然后循环执行 forPage($page, $count),直到某次结果数少于 $count 为止;chunkById 则定义于 Builder.php,它使用 forPageAfterId($count, $lastId, $column) 以“上次最后一条记录的 ID”为游标翻页,因此即使分块过程中前面的记录被修改或删除,游标仍然稳健,这正是“更新记录时应使用 chunkById”的底层原因。

聚合查询

框架提供了 count、max、min、avg、sum 等聚合方法:

use Hyperf\DbConnection\Db;

$count = Db::table('user')->count();

判断记录是否存在

除了用 count 判断查询条件是否有结果,还可以使用 exists 与 doesntExist:

return Db::table('orders')->where('finalized', 1)->exists();

return Db::table('orders')->where('finalized', 1)->doesntExist();

从 Builder.php 看,exists() 通过语法器编译出 compileExists 专用的查询(内部形如 select exists(...)),并从首行结果的 exists 字段取值;doesntExist() 则直接取反,两者都不会真的拉取整行数据,性能开销更小。

查询(Select)

指定 Select 字段

使用 select 方法可以只查询指定字段:

$users = Db::table('user')->select('name', 'email as user_email')->get();

distinct 方法强制查询返回去重后的唯一结果:

$users = Db::table('user')->distinct()->get();

如果已有一个查询构建器实例,想在其基础上追加字段,可使用 addSelect:

$query = Db::table('users')->select('name');

$users = $query->addSelect('age')->get();

原生表达式(Raw Expression)

有些场景需要把原生表达式直接嵌入查询,例如实现 COUNT(0) AS count,此时需要使用 raw 方法:

use Hyperf\DbConnection\Db;

$res = Db::table('user')->select('gender', Db::raw('COUNT(0) AS `count`'))->groupBy('gender')->get();

从门面定义看,Db.php 中 raw($value) 的返回类型为 Hyperf\Database\Query\Expression(对应 Expression.php)。Expression 是查询构建器中唯一“不参与 PDO 绑定、原样拼入 SQL”的片段——因此只有当你确信表达式内容安全时(如常量、字段名、由代码拼接的标识符)才应使用它。

原生方法系列

以下方法可以在查询的各个部分直接插入原生表达式,以替代 Db::raw(...) 的写法:

selectRaw 可替代 select(Db::raw(...)),第二个参数可选,为绑定参数数组:

$orders = Db::table('order')
    ->selectRaw('price * ? as price_with_tax', [1.0825])
    ->get();

whereRaw 与 orWhereRaw 用于注入原生 where 条件,第二个参数同样是可选的绑定参数数组:

$orders = Db::table('order')
    ->whereRaw('price > IF(state = "TX", ?, 100)', [200])
    ->get();

havingRaw 与 orHavingRaw 用于以原生字符串设置 having 子句:

$orders = Db::table('order')
    ->select('department', Db::raw('SUM(price) as total_sales'))
    ->groupBy('department')
    ->havingRaw('SUM(price) > ?', [2500])
    ->get();

orderByRaw 用于以原生字符串设置 order by 子句:

$orders = Db::table('order')
    ->orderByRaw('updated_at - created_at DESC')
    ->get();

需要留意的是,上述原生方法中所有 ? 占位符的值都通过绑定数组传入(如 [1.0825]、[200]、[2500]),这部分值同样走 PDO 参数绑定,不会产生注入风险;只有写在 SQL 字符串内的标识符与运算符才是“信任区”。

连接查询(Join)

内连接(Inner Join)

使用 join 方法执行基本的内连接:第一个参数是要连接的表名,其余参数指定连接字段约束,并且可以在单次查询中连接多张表:

$users = Db::table('users')
    ->join('contacts', 'users.id', '=', 'contacts.user_id')
    ->join('orders', 'users.id', '=', 'orders.user_id')
    ->select('users.*', 'contacts.phone', 'orders.price')
    ->get();

左连接 / 右连接

使用 leftJoin 或 rightJoin 代替内连接,用法与 join 完全一致:

$users = Db::table('users')
    ->leftJoin('posts', 'users.id', '=', 'posts.user_id')
    ->get();
$users = Db::table('users')
    ->rightJoin('posts', 'users.id', '=', 'posts.user_id')
    ->get();

交叉连接(Cross Join)

crossJoin 会在第一张表与连接表之间产生笛卡尔积:

$users = Db::table('sizes')
    ->crossJoin('colours')
    ->get();

高级连接语句

可以为 join 传入闭包作为第二个参数,闭包接收一个 JoinClause 对象,用于指定更复杂的连接约束:

Db::table('users')
    ->join('contacts', function ($join) {
        $join->on('users.id', '=', 'contacts.user_id')->orOn(...);
    })
    ->get();

若要在连接条件中使用“where 风格”的语句(列与值比较,而非列与列比较),可以在 $join 上调用 where 与 orWhere:

Db::table('users')
    ->join('contacts', function ($join) {
        $join->on('users.id', '=', 'contacts.user_id')
                ->where('contacts.user_id', '>', 5);
    })
    ->get();

源码佐证: JoinClause.php 继承自 Builder,并在构造时从父查询构建器接管 type(连接类型)、table(连接表)以及父级的 Grammar、Processor 与 Connection。这意味着闭包内的 on/orOn/where/orWhere 全部复用 Builder 的条件构造逻辑,最终由同一套语法器编译出完整的 join ... on ... and ... 语句。

子查询连接

joinSub、leftJoinSub、rightJoinSub 可以将一个子查询作为表进行连接。三个方法各接收三个参数:子查询、表别名、以及定义关联字段的闭包:

$latestPosts = Db::table('posts')
    ->select('user_id', Db::raw('MAX(created_at) as last_post_created_at'))
    ->where('is_published', true)
    ->groupBy('user_id');

$users = Db::table('users')
    ->joinSub($latestPosts, 'latest_posts', function($join) {
        $join->on('users.id', '=', 'latest_posts.user_id');
    })->get();

联合查询(Union)

查询构建器还提供了“联合”两个查询的快捷方式:先创建第一个查询,再用 union 与第二个查询联合:

$first = Db::table('users')->whereNull('first_name');

$users = Db::table('users')
    ->whereNull('last_name')
    ->union($first)
    ->get();

Where 条件语句

简单 Where

where 方法最基础的调用方式是传三个参数:列名、数据库系统支持的任意运算符、用于比较的值。例如验证 gender 字段值等于 1:

$users = Db::table('user')->where('gender', '=', 1)->get();

如果只是将列值与给定值做相等比较,可以直接把值作为第二个参数传入:

$users = Db::table('user')->where('gender', 1)->get();

当然也可以使用其他运算符:

$users = Db::table('users')->where('gender', '>=', 0)->get();

$users = Db::table('users')->where('gender', '<>', 1)->get();

$users = Db::table('users')->where('name', 'like', 'T%')->get();

还可以把一组条件以数组形式传给 where:

$users = Db::table('user')->where([
    ['status', '=', '1'],
    ['gender', '=', '1'],
])->get();

Or 语句

可以链式拼接 where 约束,或通过 orWhere 追加 or 子句,其参数与 where 相同:

$users = Db::table('user')
    ->where('gender', 1)
    ->orWhere('name', 'John')
    ->get();

其他 Where 语句

whereBetween / whereNotBetween

whereBetween 验证字段值介于给定的两个值之间:

$users = Db::table('users')->whereBetween('votes', [1, 100])->get();

whereNotBetween 验证字段值在给定的两个值之外:

$users = Db::table('users')->whereNotBetween('votes', [1, 100])->get();

从源码看,whereBetween($column, array $values, $boolean = 'and', $not = false) 定义于 Builder.php,not 参数控制取反,其内部实际编译为 where column between ? and ?,两个边界值同样作为绑定参数处理。

whereIn / whereNotIn

whereIn 验证字段值必须存在于指定数组中:

$users = Db::table('users')->whereIn('id', [1, 2, 3])->get();

whereNotIn 验证字段值必须不存在于指定数组中:

$users = Db::table('users')->whereNotIn('id', [1, 2, 3])->get();

参数分组

有时需要构造更高级的 where 子句,例如 where exists 或嵌套的参数分组。下面是在括号中分组约束的示例:

Db::table('users')->where('name', '=', 'John')
    ->where(function ($query) {
        $query->where('votes', '>', 100)
                ->orWhere('title', '=', 'Admin');
    })
    ->get();

如上所示,where 方法接收一个 Closure,闭包内拿到一个独立的查询构建器实例,用于设置要包含的约束。以上示例生成的 SQL 为:

select * from users where name = 'John' and (votes > 100 or title = 'Admin')

建议将这种分组与 orWhere 搭配使用时要格外谨慎,以避免意外引入全局性影响。

Where Exists 语句

whereExists 允许你使用 where exists SQL 语句,它接收一个 Closure 参数,闭包内使用查询构建器实例定义放入 exists 子句的查询:

Db::table('users')->whereExists(function ($query) {
    $query->select(Db::raw(1))
            ->from('orders')
            ->whereRaw('orders.user_id = users.id');
})
->get();

以上查询生成的 SQL 为:

select * from users
where exists (
    select 1 from orders where orders.user_id = users.id
)

JSON Where 语句

Hyperf 还支持查询 JSON 类型的字段(仅限支持 JSON 类型的数据库):

$users = Db::table('users')
    ->where('options->language', 'en')
    ->get();

$users = Db::table('users')
    ->where('preferences->dining->meal', 'salad')
    ->get();

也可以使用 whereJsonContains 查询 JSON 数组:

$users = Db::table('users')
    ->whereJsonContains('options->languages', 'en')
    ->get();

还可以使用 whereJsonLength 查询 JSON 数组的长度:

$users = Db::table('users')
    ->whereJsonLength('options->languages', 0)
    ->get();

$users = Db::table('users')
    ->whereJsonLength('options->languages', '>', 1)
    ->get();

从源码看,whereJsonContains($column, $value, $boolean = 'and', $not = false) 位于 Builder.php,whereJsonLength($column, $operator, $value = null, $boolean = 'and') 位于 Builder.php。-> 语法会被 JsonExpression 与各数据库方言的语法器转换为对应方言的 JSON 路径表达式(如 MySQL 的 JSON_CONTAINS、JSON_LENGTH 等),因此实际 SQL 形态取决于当前使用的数据库驱动。

排序、分组、限制与偏移

orderBy

orderBy 方法按给定字段排序结果集:第一个参数为排序字段,第二个参数控制排序方向(asc 或 desc):

$users = Db::table('users')
    ->orderBy('name', 'desc')
    ->get();

latest / oldest

latest 与 oldest 方法可便捷地按日期排序,默认使用 created_at 列作为排序依据,也可以传入自定义列名:

$user = Db::table('users')->latest()->first();

inRandomOrder

inRandomOrder 方法用于随机排序结果,例如查找一个随机用户:

$randomUser = Db::table('users')->inRandomOrder()->first();

groupBy / having

groupBy 与 having 方法用于结果分组,having 的用法与 where 非常相似:

$users = Db::table('users')
    ->groupBy('account_id')
    ->having('account_id', '>', 100)
    ->get();

groupBy 可以传入多个参数:

$users = Db::table('users')
    ->groupBy('first_name', 'status')
    ->having('account_id', '>', 100)
    ->get();

更高级的 having 语法可参考 havingRaw 方法(见上文“原生方法系列”)。

skip / take 与 offset / limit

要限制返回的结果数量或跳过指定数量的结果,可以使用 skip 与 take:

$users = Db::table('users')->skip(10)->take(5)->get();

也可以使用 offset 与 limit 方法:

$users = Db::table('users')->offset(10)->limit(5)->get();

条件语句(when)

有时你希望仅在某个条件成立时才执行相应的查询子句。例如仅当请求中存在某个值时,才应用对应的 where 语句,此时可以使用 when 方法:

$role = $request->input('role');

$users = Db::table('users')
    ->when($role, function ($query, $role) {
        return $query->where('role_id', $role);
    })
    ->get();

when 仅在第一个参数为 true 时执行给定闭包;如果第一个参数为 false,则闭包不会执行。

还可以给 when 传入第三个闭包参数,该闭包在第一个参数为 false 时执行。以下示例为查询配置默认排序:

$sortBy = null;

$users = Db::table('users')
    ->when($sortBy, function ($query, $sortBy) {
        return $query->orderBy($sortBy);
    }, function ($query) {
        return $query->orderBy('name');
    })
    ->get();

从实现看,when 由 BuildsQueries.php 引入的 Hyperf\Conditionable\Conditionable trait 提供,这也是 Hyperf 将 Laravel 风格的 when / unless 条件链能力抽离为独立组件(hyperf/conditionable)的体现,使得查询构建器与模型构建器可以复用同一套条件逻辑。

插入(Insert)

insert 方法用于向数据库插入记录,它接收包含字段名与字段值的数组:

Db::table('users')->insert(
    ['email' => 'john@example.com', 'votes' => 0]
);

也可以传入数组的数组,一次插入多条记录:

Db::table('users')->insert([
    ['email' => 'taylor@example.com', 'votes' => 0],
    ['email' => 'dayle@example.com', 'votes' => 0]
]);

自增 ID

如果表存在自增 ID,可以使用 insertGetId 插入记录并返回 ID 值:

$id = Db::table('users')->insertGetId(
    ['email' => 'john@example.com', 'votes' => 0]
);

从 Builder.php 看,insertGetId(array $values, $sequence = null) 先由语法器编译出 compileInsertGetId,再交由处理器(Processor)执行并返回自增主键;$sequence 参数可用于在个别数据库上显式指定序列名。

更新(Update)

除了插入,查询构建器还通过 update 方法更新已有记录。与 insert 类似,update 接收包含字段与值的数组,并可以配合 where 约束更新范围:

Db::table('users')->where('id', 1)->update(['votes' => 1]);

更新或插入(Update or Insert)

当需要“存在则更新、不存在则创建”时,可使用 updateOrInsert 方法。它接收两个参数:用于查找记录的字段条件数组,以及包含待更新字段的键值对数组。

updateOrInsert 首先用第一个参数(键值对)尝试查找匹配记录:若记录存在,则用第二个参数的值更新该记录;若未找到,则插入一条新记录,插入的数据是两个数组的合并:

Db::table('users')->updateOrInsert(
    ['email' => 'john@example.com', 'name' => 'John'],
    ['votes' => '2']
);

从 Builder.php 的实现看,该方法的逻辑是:先 $this->where($attributes)->exists() 判断是否存在,存在则 take(1)->update($values),不存在则 insert(array_merge($attributes, $values))。仓库源码中还提供了功能更强的 upsert 方法(Builder.php),它基于唯一键一次批量执行“插入或更新”,适合需要保证原子性的批量写入场景。

更新 JSON 字段

更新 JSON 字段时,可以使用 -> 语法访问 JSON 对象中对应的值,该语法仅在 MySQL 5.7+ 上受支持:

Db::table('users')->where('id', 1)->update(['options->enabled' => true]);

自增与自减

查询构建器还提供了自增/自减的便捷方法,比手写 update 语句更简洁。两个方法至少接收一个参数:需要修改的列;第二个参数可选,控制自增/自减的幅度:

Db::table('users')->increment('votes');

Db::table('users')->increment('votes', 5);

Db::table('users')->decrement('votes');

Db::table('users')->decrement('votes', 5);

还可以在操作过程中指定其他要更新的字段:

Db::table('users')->increment('votes', 1, ['name' => 'John']);

从 Builder.php 看,increment(Expression|string $column, mixed $amount = 1, array $extra = []) 会先校验 $amount 必须为数值,随后将列包装为 列名 + 幅度 的原生表达式,与 $extra 字段合并后走一次 update;decrement 则调用 increment 并传入负值。

删除(Delete)

查询构建器同样支持使用 delete 方法删除记录。调用前可以通过 where 子句约束删除范围:

Db::table('users')->delete();

Db::table('users')->where('votes', '>', 100)->delete();

如需清空整张表,可以使用 truncate 方法,它会删除所有行并将自增 ID 重置为零:

Db::table('users')->truncate();

悲观锁(Pessimistic Locking)

查询构建器还包含一些帮助你在 select 语句上实现悲观锁的函数。要在查询中使用“共享锁”,可以调用 sharedLock 方法。共享锁会阻止被选中的数据行在事务提交前被篡改:

Db::table('users')->where('votes', '>', 100)->sharedLock()->get();

也可以使用 lockForUpdate 方法。更新锁会阻止其他共享锁修改或选择这些行:

Db::table('users')->where('votes', '>', 100)->lockForUpdate()->get();

从 Builder.php 看,lockForUpdate() 与 sharedLock() 都是通过设置 lock 属性,由各数据库方言的语法器在编译 select 语句时追加对应的锁子句(MySQL 中分别对应 FOR UPDATE 与 LOCK IN SHARE MODE)。需要强调的是,悲观锁必须配合事务使用才能生效,通常与 Db::transaction(...) 或 beginTransaction() / commit() 成对出现,这一点在原文档中虽未展开,但属于锁语义的内在前提。

总结:查询构建器的完整能力图谱

纵观 docs/en/db/querybuilder.md 与仓库源码,Hyperf 查询构建器的能力可以归纳为以下几条主线:

  1. 结果获取:get 返回 Collection 集合(元素为 stdClass),select 返回数组,pluck 提取单列,chunk / chunkById 分块处理大数据集,count/max/min/avg/sum/exists/doesntExist 完成聚合与存在性判断;
  2. 查询构造:select/distinct/addSelect 控制投影,raw 及 selectRaw/whereRaw/havingRaw/orderByRaw 系列注入原生表达式,join/leftJoin/rightJoin/crossJoin/joinSub 实现各类连接,union 完成联合查询,where 家族(含 whereBetween/whereIn/whereExists、JSON 查询与参数分组)构造复杂过滤条件;
  3. 排序与分页:orderBy/latest/oldest/inRandomOrder/groupBy/having/skip/take/offset/limit 控制结果集的排序、分组与截取;
  4. 写入与删除:insert/insertGetId、update/updateOrInsert/upsert/increment/decrement、delete/truncate 覆盖完整的增删改能力;
  5. 并发控制:sharedLock/lockForUpdate 提供悲观锁支持,需配合事务使用。

所有值类型参数(where 的值、绑定数组、插入/更新的值等)都统一走 PDO 参数绑定通道(见 Builder.php 中按 select/from/join/where/having/order/union 分类维护的 bindings 属性),这是查询构建器抵御 SQL 注入的根本机制;唯一的例外是 Db::raw 生成的 Expression 片段,它会原样进入 SQL,使用时必须保证其内容安全。

如果需要进一步验证各方法的实际 SQL 编译结果,可以直接阅读仓库中的 QueryBuilderTest.php 等测试文件,其中覆盖了大量构建器方法的断言用例;若你的业务需要更接近 ORM 的封装(如模型、关联、事件),则可以继续查阅仓库中 hyperf/database 的 Model 层实现(Model 目录),查询构建器正是这一切的底层基石。

登录后查看全文
hyperf