easyswoole / fast-db
php stander lib
Requires
- php: >=8.1
- ext-swoole: >=5.1
- easyswoole/mysqli: ^5.1
- easyswoole/pool: ^3.0
- easyswoole/spl: ^2.2
Requires (Dev)
- ext-mysqli: *
- easyswoole/swoole-ide-helper: ^1.0
- phpunit/phpunit: ^13.4
Suggests
None
Provides
None
Conflicts
None
Replaces
None
- 3.x-dev
- 3.1.1
- 3.0.9
- 3.0.8
- 3.0.7
- 3.0.6
- 3.0.5
- 3.0.4
- 3.0.3
- 3.0.2
- 3.0.1
- 2.x-dev
- 2.2.3
- 2.2.2
- 2.2.1
- 2.1.8
- 2.1.7
- 2.1.6
- 2.1.5
- 2.1.4
- 2.1.3
- 2.1.2
- 2.1.1
- 2.0.22
- 2.0.21
- 2.0.20
- 2.0.19
- 2.0.18
- 2.0.17
- 2.0.16
- 2.0.15
- 2.0.14
- 2.0.13
- 2.0.12
- 2.0.11
- 2.0.10
- 2.0.9
- 2.0.8
- 2.0.7
- 2.0.6
- 2.0.5
- 2.0.4
- 2.0.3
- 2.0.2
- 2.0.1
- 1.3.18
- 1.3.17
- 1.3.16
- 1.3.15
- 1.3.14
- 1.3.13
- 1.3.12
- 1.3.11
- 1.3.10
- 1.3.9
- 1.3.8
- 1.3.7
- 1.3.6
- 1.3.5
- 1.3.3
- 1.3.2
- 1.3.1
- 1.2.7
- 1.2.6
- 1.2.5
- 1.2.3
- 1.2.2
- 1.2.1
- 1.1.12
- 1.1.11
- 1.1.10
- 1.1.9
- 1.1.8
- 1.1.7
- 1.1.6
- 1.1.5
- 1.1.4
- 1.1.3
- 1.1.2
- 1.0.11
- 1.0.9
- 1.0.8
- 1.0.6
- 1.0.5
- 1.0.4
- 1.0.3
- 1.0.2
- 1.0.1
- 1.0.0
- dev-main
This package is auto-updated.
Last update: 2026-11-15 16:31:57 UTC
README
FastDb 是面向 Swoole 协程环境的 MySQL 数据访问库,组合连接池、SQL 构建器和基于 PHP Attributes 的实体映射。可以在 EasySwoole 框架内使用,也可以独立使用。
本文面向 3.x 分支,使用 easyswoole/mysqli ^5.1 和 easyswoole/pool 3.x,以当前 src/ 和 composer.json 为准。实体 API 位于 AbstractEntity,数据库与连接管理位于 FastDb,SQL 构建能力由 easyswoole/mysqli 提供。实体查询使用 mysqli 5.1.6 的查询状态和总数设置接口,已锁定较早版本的项目需先更新 easyswoole/mysqli。
内部执行与实体状态
内部组件分工如下:
| 组件 | 职责 |
|---|---|
FastDb |
管理协程连接与事务,记录单条 SQL 的执行结果并通知查询回调 |
Mysql\Connection |
驱动调用、协议事务状态、连接健康及超时上下文;不保存门面执行状态 |
Internal\QueryDiagnostics |
按需保存全局查询回调和每协程有界事件栈;分别记录查询执行与连接获取 |
AbstractInterface\AbstractEntity |
实体映射、字段变更、主键约束、列表组装和分页总数 |
Internal\FieldCodec |
加载赋值转换、写入值转换;与序列化隐藏字段分别处理 |
Internal\FieldSelection |
保存字段白名单、隐藏字段和输出限制,不混入 SQL 构建状态 |
Internal\RelationLoader |
关联结果构造、唯一性检查及实体实例范围的关联缓存 |
Internal\RelationPreloader |
显式预加载时逐父读取声明和应用配置、分批查询,并回填实体缓存或附加数组结果 |
QueryResult 保存查询执行结果及查询执行阶段耗时;连接获取独立记录为 QueryStack 中的 connectionAcquire 事件,使用同一个 duration 字段表示该事件耗时。查询栈默认每协程只保留最近 256 条事件,可按实例调整;未配置查询回调或查询栈时,不创建诊断组件。
FastDb 通过 FastDb::getInstance() 获取固定实例并长期复用。需要通过 getInstance() 获取独立的管理器时,在业务子类中重新引入 Singleton,让子类单独保存自己的实例。
use EasySwoole\Component\Singleton; use EasySwoole\FastDb\FastDb; class ReportingDb extends FastDb { use Singleton; } $mainDb = FastDb::getInstance(); $reportingDb = ReportingDb::getInstance();
Query 仅在首次添加 SQL 条件或显式读取底层构造器时创建 QueryBuilder;只配置输出字段或序列化实体时无需分配 SQL 构造器。序列化保留当前 Query 及其配置;插入结束后消费本次查询配置,只保留 hideFields()。需要保留隐藏字段时会创建新的 Query,外部持有的旧 Query 和构造器引用不会被重新绑定。克隆实体时查询所有者和可变配置继续独立。
加载后的实体不允许修改主键再执行 update() / delete(),以避免定位到其他记录。需要显式修改主键时应自行构造条件明确的 SQL。实体克隆后,比较状态和查询所有者独立。使用 convertObject 的主键按 toValue() 返回的数据库值进行比较,并使用原主键数据库值构建 WHERE;替换为持有相同值的新对象可以正常操作,替换或原地修改为不同值仍会被拒绝。
实体 update() / delete() 和关联查询在最终构建 SQL 前,将全部已有 WHERE 条件整体分组,再以 AND 追加主键或关联外键条件。例如 WHERE (status = ? OR score = ?) AND id = ?,附加 OR 条件始终受实体范围约束。该分组也覆盖 func()、底层构建器和生命周期钩子添加的条件;fastUpdate() / fastDelete() 继续按调用方提供的条件批量执行。
本组件直接使用 mysqli 的 QueryBuilder::groupExistingWhere(),游标分块由 FastDb 组合 WHERE、ORDER BY 和 LIMIT 实现;连接池最小容量维护和创建失败处理沿用上游 pool 的实现。
Connection::isInTransaction(): bool 直接读取底层协议的事务状态;FastDb::isInTransaction() 转发到当前或指定连接,不另外保存事务布尔副本。实体 update() 在查询正常返回且影响行数大于零后接受字段比较基准。后续事务回滚不会恢复模型属性或比较基准,需要由业务重新加载、重建对象或显式修改字段后再保存。
列表查询和两种分块共用结果组装流程。开启总数时,实体在主查询及其回调正常返回后,用同一连接执行 FOUND_ROWS(),然后转换实体并预加载关联。每条 SQL 各自记录结果并通知回调。
insert() 使用 fields() 作为本次写入白名单。插入结束后,只保留用于输出的 hideFields()。插入后如需用白名单限制 toArray() 或 JSON 输出,请重新设置 fields()。
目录
- 内部执行与实体状态
- 特性与运行要求
- 安装与快速开始
- 数据库和连接池配置
- 实体与属性映射
- 查询
- 分页分块与聚合
- 插入更新删除
- 字段筛选与序列化
- 属性转换
- 实体生命周期钩子
- 关联查询
- 事务与行锁
- 多数据库与连接生命周期
- 原始 SQL 与底层构建器
- 查询日志与查询栈
- 记录慢查询日志
- API 速查
- 开发与测试
- 使用边界与常见问题
特性与运行要求
特性
- 每个数据库配置维护独立连接池,同一协程、同一连接名复用当前连接。
- 协程结束后自动归还连接,也可通过
invoke()或recycleContext()提前归还。 - 连接归还时回滚未提交的数据库事务;回滚失败的连接由连接池丢弃。
#[Property]映射属性,支持默认值、nullable 属性和自定义转换。使用#[PrimaryKey]声明主键,使用#[AutoIncrement]指定独立自增列。- 查询结果可返回实体、原始数组或支持遍历/计数/数组访问的
ListResult。 - 条件、排序、连接、分组、分页、分块、聚合与
FOR UPDATE。 - 实体只更新已变化的字段;成功写入后更新比较基准,支持同一对象连续修改和还原。
- 数据库格式数组可通过 iterable 分批直接插入或 upsert,不逐行构造实体。
- 选库作用域退出时恢复连接名;回调事务按实际连接管理提交、回滚及同连接嵌套加入。
- 字段白名单、隐藏字段与可重复序列化的输出限制。
- 插入、更新、删除、初始化钩子,以及一对一/一对多关联与可选批量预加载。
- 全局/单次查询回调、SQL 与连接获取耗时统计,以及每协程容量可配置的查询栈。
- PHPUnit 13.4 测试入口,支持独立单元测试和真实数据库集成测试。
运行要求
| 场景 | 要求 |
|---|---|
| 运行库 | PHP ≥ 8.1、Swoole ≥ 5.1;其余扩展由 Composer 按依赖检查 |
| 数据库 | MySQL;示例表使用 InnoDB、utf8mb4 与 JSON 字段 |
| 开发测试 | PHP ≥ 8.4.1、PHPUnit ^13.4、原生 mysqli 扩展,以及 Composer 安装的开发依赖 |
数据库访问由 easyswoole/mysqli 5.x 的 Swoole 协程 Socket 协议客户端完成,生产环境不需要原生 mysqli 扩展,也不需要为数据库访问启用 runtime hooks。通过连接池使用 FastDb 时,数据库操作应在 Swoole 协程内执行;testDb() 可在协程外调用,内部会创建协程调度器。原生 mysqli 仅用于开发测试中的独立观察连接。
安装与快速开始
安装当前 3.x 开发分支到应用:
composer require easyswoole/fast-db:3.x-dev
克隆本项目进行开发:
composer install
开发依赖包含 PHPUnit 13.4,因此开发环境需要 PHP ≥ 8.4.1;部署不运行测试时可使用 composer install --no-dev。
1. 准备示例表
在自己的数据库执行:
CREATE TABLE users ( id BIGINT UNSIGNED NOT NULL AUTO_INCREMENT, name VARCHAR(100) NOT NULL, status INT NOT NULL DEFAULT 1, score INT NOT NULL DEFAULT 0, tags JSON DEFAULT NULL, meta JSON DEFAULT NULL, PRIMARY KEY (id) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4;
2. 定义实体
例如 App/Model/User.php,并确保应用的 Composer PSR-4 配置包含 App\:
<?php namespace App\Model; use EasySwoole\FastDb\AbstractInterface\AbstractEntity; use EasySwoole\FastDb\Attributes\PrimaryKey; use EasySwoole\FastDb\Attributes\Property; class User extends AbstractEntity { #[Property] #[PrimaryKey] public int $id; #[Property] public string $name; #[Property] public int $status = 1; #[Property] public int $score = 0; #[Property] public ?string $tags; #[Property] public ?string $meta; public function tableName(): string { return 'users'; } }
不设置转换时,JSON 字段使用字符串属性接收数据库的原始 JSON 文本。后文介绍如何映射成数组或对象。
3. 注册连接并执行
<?php require __DIR__ . '/vendor/autoload.php'; use App\Model\User; use EasySwoole\FastDb\Config; use EasySwoole\FastDb\FastDb; $db = FastDb::getInstance(); $db->addDb(new Config([ 'host' => getenv('DB_HOST') ?: '127.0.0.1', 'port' => (int) (getenv('DB_PORT') ?: 3306), 'user' => getenv('DB_USER') ?: 'app', 'password' => (string) getenv('DB_PASSWORD'), 'database' => getenv('DB_DATABASE') ?: 'app_db', 'charset' => 'utf8mb4', 'timeout' => 3.0, 'maxConnectTime' => 5.0, 'compress' => false, 'minObjectNum' => 0, 'maxObjectNum' => 16, ])); Swoole\Coroutine\run(function () use ($db): void { try { $user = new User(['name' => 'Alice', 'score' => 10]); if (!$user->insert()) { throw new RuntimeException('Insert failed'); } $saved = User::findRecord($user->id); if ($saved !== null) { $saved->score = 20; $saved->update(); echo json_encode($saved, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR); } } finally { // 独立 CLI 示例:清理连接池定时器,使进程可以退出。 $db->recycleContext(); $db->reset(); } });
在常驻服务中,通常保持连接池运行,由协程结束自动回收连接;不要在每个请求结束时 reset() 整个连接池。
以下代码片段默认已完成连接注册、运行于协程内,并已导入 App\Model\User。涉及其他实体时,需要定义对应模型和数据库表。 常用类型的导入如下:
use App\Model\User; use EasySwoole\FastDb\Config; use EasySwoole\FastDb\FastDb; use EasySwoole\FastDb\Mysql\Connection; use EasySwoole\FastDb\Mysql\QueryResult; use EasySwoole\Mysqli\QueryBuilder;
数据库和连接池配置
EasySwoole\FastDb\Config 继承 EasySwoole\Pool\Config,支持通过构造数组和对应 setter 设置参数。
数据库参数
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
host |
string | 127.0.0.1 |
数据库地址 |
port |
int | 3306 |
数据库端口 |
user |
string | 空字符串 | 登录用户,按实际账号配置 |
password |
string | 空字符串 | 登录密码 |
database |
string | 空字符串 | 数据库名,按业务配置 |
charset |
string | utf8mb4 |
连接字符集 |
timeout |
float | 3.0 |
默认单次查询、开始事务、提交或回滚的超时,秒 |
maxConnectTime |
float | 5.0 |
完整连接过程的超时上限,秒 |
compress |
bool | false |
请求 MySQL 协议压缩,需服务端支持 |
name |
string | default |
连接池名称 |
isForceRollback |
bool | false |
归还仍有会话的连接时尝试回滚,可用 setForceRollback() 设置。配置不会因一次回收被清除 |
建连和 testDb() 使用相同的驱动参数,包括数据库地址、账号、连接选项和 TLS。连接池参数直接由连接池读取。
配置类型直接由属性声明处理,例如整数 timeout => 3 会保存为 float。timeout 和 maxConnectTime 在实际操作时必须大于零;类型声明本身不校验正数。使用真正的布尔值设置 compress。
getObjectTimeout 限制连接池等待,maxConnectTime 限制建连过程,方法参数 $timeout 限制该次 SQL 操作。FastDb 在获取连接后才执行查询,单次 SQL 超时不包含此前的连接池等待和池内新建连接耗时;它也不是整个业务事务的累计时间限制。
Config 不支持 maxIdleTime、loadAverageTime,连接池负载阈值使用 waitLoadAverageTime。数据库配置 setter 返回 void,应逐条调用。
TLS 连接
TLS 默认关闭。FastDb 支持通过构造数组或 setter 设置下列参数,并传递给 mysqli;连接池创建连接和 testDb() 使用相同配置。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
tlsMode |
`TlsMode | string` | 'disabled' |
tlsCaFile |
string | 空字符串 | PEM CA 文件路径 |
tlsCaPath |
string | 空字符串 | CA 证书目录 |
tlsCertFile |
string | 空字符串 | 客户端证书文件路径 |
tlsKeyFile |
string | 空字符串 | 客户端私钥文件路径 |
tlsKeyPassphrase |
string | 空字符串 | 客户端私钥的解密口令 |
tlsServerName |
string | 空字符串 | SNI 名称及身份校验的预期名称,默认使用 host;不改变 TCP 连接地址 |
tlsVersions |
array | ['TLSv1.2', 'TLSv1.3'] |
可混用 TlsVersion 枚举和对应字符串 |
TlsMode、TlsVersion 均位于 EasySwoole\Mysqli 命名空间。Required 仅要求加密,VerifyCA 验证证书链,VerifyIdentity 还验证服务端名称。示例使用身份校验:
use EasySwoole\FastDb\Config; use EasySwoole\Mysqli\TlsMode; use EasySwoole\Mysqli\TlsVersion; $config = new Config([ 'host' => 'mysql.internal.example', 'user' => 'app', 'password' => 'your_password', 'database' => 'app', 'tlsMode' => TlsMode::VerifyIdentity, 'tlsCaFile' => '/secure/mysql/ca.pem', 'tlsServerName' => 'mysql.internal.example', 'tlsVersions' => [TlsVersion::Tls12, TlsVersion::Tls13], ]); $db->addDb($config);
也可以逐条设置参数:
$config->setTlsMode('verify_identity'); $config->setTlsCaFile('/secure/mysql/ca.pem'); $config->setTlsServerName('mysql.internal.example'); $config->setTlsVersions([TlsVersion::Tls13]);
FastDb 的 TLS getter 返回保存的值,保留枚举或字符串形式。模式及协议版本解析、证书校验、握手均由 mysqli 统一处理;启用 TLS 后,连接失败不会自动退回明文。需要客户端证书认证时,同时配置 tlsCertFile 和 tlsKeyFile,加密私钥另设 tlsKeyPassphrase。Swoole 需编译支持 OpenSSL;TLS 握手使用现有 maxConnectTime 超时预算。协议及校验细节参见 mysqli TLS 配置。
连接池参数
以下默认值对应当前使用的 easyswoole/pool:
| 参数 | 默认值 | 单位与作用 |
|---|---|---|
maxObjectNum |
16 |
单个连接池的最大连接数 |
minObjectNum |
8 |
连接池预热和维持的最小连接数,可设为 0,最大为 maxObjectNum |
getObjectTimeout |
3.0 |
等待可用连接的秒数 |
intervalCheckTime |
5000 |
定时检查间隔,毫秒;0 关闭该定时检查 |
intervalCheckBatchSize |
8 |
每轮定时检查的最大连接数 |
waitLoadAverageTime |
0.001 |
连接池负载判断的平均等待时间阈值,秒 |
extraConf |
无 | 连接池提供的额外配置槽位 |
连接池按进程维护,多个 worker 的连接总量需要合并计算。intervalCheckTime=0 只关闭定时健康检查,连接池还可能有负载维护定时器;独立 CLI 可在工作完成后调用 reset() 清理。
连接在最近 3 秒内成功建连、执行查询或探活后,beforeUse() / intervalCheck() 跳过 select 1;空闲达到 3 秒时恢复探活。查询失败或连接关闭后清除活跃记录,已知断开的连接不会因近期活跃而跳过检查。
常用配置操作
$config = new Config([ 'host' => '127.0.0.1', 'user' => 'app', 'password' => (string) getenv('DB_PASSWORD'), 'database' => 'app_db', ]); $config->setName('default'); $config->setTimeout(3.0); $config->setMaxConnectTime(5.0); $config->setCompress(false); $config->setMinObjectNum(0); $config->setMaxObjectNum(32); $config->setGetObjectTimeout(2.0); $config->setIntervalCheckBatchSize(8); $db = FastDb::getInstance()->addDb($config); $db->testDb(); // 成功返回 true;建连失败抛出原始异常。 $registered = $db->getConfig('default'); // Config 或 false。 $db->preConnect(); // 对已注册的连接池预热到最小连接数。
连接池在首次使用时创建,由池显式调用 connect() 建立会话。借用时由池淘汰已断开的连接并补充新连接。池满、建连等异常保留原类型。池未提供可用连接且返回 null 时,FastDb 抛出 RuntimeError。SQL 发出后若断线或超时,FastDb 将异常交给调用方。持有失效会话的协程应先回收上下文,业务需要继续时再发起独立操作。事务丢失后的提交与回滚报告事务丢失,回收后失效会话由池淘汰。连接池创建后,addDb() 会拒绝覆盖同名连接的配置。请在首次查询或预热前完成注册。addDb() 保存配置副本,getConfig() 返回副本。
实体与属性映射
继承 AbstractEntity 并实现 tableName()。只有带 #[Property] 的 public、非 static 属性参与映射;未知输入键会被 setData() 忽略。
Property 参数
| 参数 | 含义 |
|---|---|
defaultValue |
实体初始化默认值 |
convertObject |
实现 ConvertObjectInterface 的类或枚举 |
use EasySwoole\FastDb\Attributes\PrimaryKey; use EasySwoole\FastDb\Attributes\Property; #[Property] #[PrimaryKey] public int $id; #[Property(defaultValue: 1)] public int $status; #[Property] public ?string $note;
PHP 属性上非 null 的默认值会优先作为初始化值;nullable 属性没有默认值时初始化为 null。没有默认值的非 nullable 属性可能保持未初始化,读取前应先赋值或从数据库加载。
在映射属性上同时声明 #[Property] 和 #[PrimaryKey]。每个实体最多声明一个主键字段,属性必须为 public 且非 static。同一属性重复声明 #[Property] 会在解析实体时抛出异常。主键使用独立注解,Property 的两个参数分别为 defaultValue 和 convertObject。
框架按实体类缓存字段、主键、自增字段、关联和钩子定义。解析后的定义只读,配置通过对应的 PHP Attribute 声明。实体实例的字段值仍可按原有方式修改。
对象默认值(枚举除外)会在每个实体初始化时复制,数组默认值中的对象元素也会复制。读取字段元数据的 getDefaultValue() 同样会取得副本。对象内部的复制深度遵循该类型自身的 __clone()。例如,包含 Bean 实例的自定义 ItemList,应在 ItemList::__clone() 中复制需要独立的元素。
构造和 setData
$user = new User(['id' => 1, 'name' => 'Alice']); $user->setData(['name' => 'Bob']); // 形成待更新变更。 $user->setData(['name' => 'Bob'], true); // 同时接受为比较基准。
构造参数会使用 setData($data, true),表示这些数据是对象的初始基准。手动创建用于更新的对象时,可以先只传主键,再赋待更新值:
$user = new User(['id' => 1]); $user->name = 'Bob'; $user->update();
如果把主键和目标值全部作为构造参数,之后不修改任何值,update() 会认为没有变更而跳过 SQL。setData(..., true) 应用于接受已知数据库状态,不用于提交更改。
查询
查找一条记录
$user = User::findRecord(1); // User|null。 $user = User::findRecord(['name' => 'Alice', 'status' => 1]); $user = User::findRecord(['score' => [10, '>=']]); $user = User::findRecord(function (QueryBuilder $query): void { $query->where('status', 1)->orderBy('id', 'ASC'); });
参数顺序:findRecord($queryLimit, $tableName = null, $selectForUpdate = false, $onQuery = null)。没有命中返回 null;查询失败抛异常。主键条件支持整数和字符串,按属性主键查找;数组/回调可以查询无主键实体。
findRecord() 默认使用 LIMIT 1。在回调中调用 limit(10, 1) 会跳过 10 条后取一条,建议同时指定稳定的排序。
$user = User::findRecord(function (QueryBuilder $query): void { $query->where('status', 1)->orderBy('id', 'ASC')->limit(10, 1); });
limit(0) 返回 null。显式指定取多条时,findRecord() 会在执行 SQL 前抛出 InvalidArgumentException。需要多条结果时使用 findAll()。
查找多条记录
$users = User::findAll(); // 普通 PHP 数组,元素为 User。 $users = User::findAll('1'); // 单个主键条件。 $users = User::findAll(['id' => [[1, 2, 3], 'IN']]); $users = User::findAll(['status' => 1]); $rows = User::findAll(['status' => 1], returnAsArray: true);
参数顺序:findAll($queryLimit = null, $tableName = null, $returnAsArray = false, $selectForUpdate = false, $onQuery = null)。
findAll() 的字符串参数表示单个主键。前导零和逗号都是主键值的一部分。查询多个主键时显式使用 IN。
$users = User::findAll(['id' => [['uuid-a', 'uuid-b'], 'IN']]);
findAll() 返回普通数组,不提供 list() / totalCount()。需要 ListResult、分页或输出字段限制时使用实例 all()。
实例查询与链式条件
$queryEntity = new User(); $queryEntity->queryLimit() ->where('status', 1) ->where('score', 10, '>=') ->orderBy('id', 'DESC') ->limit(20); $result = $queryEntity->all(); foreach ($result as $user) { echo $user->name; }
queryLimit() 返回 Query,可以通过 returnEntity() 返回原实体继续执行:
$result = (new User())->queryLimit() ->where('status', 1) ->returnEntity() ->all();
条件运算、分组与连接
$entity = new User(); $entity->queryLimit() ->where('id', [1, 2, 3], 'IN') ->where('name', 'A%', 'LIKE') ->orWhere('status', 2); $result = $entity->all();
where($column, $value, $operator = '=', $cond = 'AND'),orWhere() 使用 OR。多个 AND/OR 的分组语义由底层 SQL 构建器决定,复杂条件建议通过 func() 或参数化 SQL 明确括号。
$entity = new User(); $entity->queryLimit() ->join('profiles p', 'p.user_id = users.id', 'LEFT') ->fields(['users.id', 'users.name', 'p.bio'], true) ->orderBy('users.id', 'ASC'); $rows = $entity->all()->list();
连接查询的额外列/别名若不是实体声明的属性,实体模式会忽略它们,建议返回原始数组。groupBy($field) 添加分组;func(callable) 接收当前 QueryBuilder,可使用其其他能力:
$entity->queryLimit()->func(function (QueryBuilder $query): void { $query->having('COUNT(*)', 1, '>'); });
列名、表名、排序表达式等 SQL 标识符应由应用控制;绑定参数只处理数据值。
分页分块与聚合
分页与总数
$entity = new User(); $entity->queryLimit() ->where('status', 1) ->orderBy('id', 'ASC') ->page(2, true, 20); $page = $entity->all(); $items = $page->list(); $total = $page->totalCount(); // 请求统计时为总数,否则 null。 $currentSize = count($page); // 本页返回的数量。
page($page, $withTotalCount = false, $pageSize = 10) 从第 1 页开始,偏移量为 ($page - 1) * $pageSize。limit($num, $withTotalCount = false) 只限制数量,不设置偏移量。每次调用都会设置本次查询是否统计总数,传 false 或省略该参数会关闭此前开启的统计。
开启总数统计后,实体列表用 SQL_CALC_FOUND_ROWS 查询当前页。主查询及其回调正常返回后,列表立即在同一个会话执行 SELECT FOUND_ROWS(),再回填实体、预加载关联并通过 ListResult::totalCount() 返回总数。即使当前页为空,也会读取总数。
use EasySwoole\FastDb\Beans\Page; $limit = new Page(); $limit->getPage(); // null,表示 limit 模式。 $limit->toLimitArray(); // [10]。 $page = new Page(3, true, 20); $page->toLimitArray(); // [40, 20]。
指定页码时,页码和每页条数都必须大于零。limit(0) 返回空列表。分块大小必须大于零。
分块处理
$entity = new User(); $entity->queryLimit()->where('status', 1)->orderBy('id', 'ASC'); $entity->chunk(function (User $user): void { // 逐条处理。 echo $user->id; }, 100);
chunk($callback, $chunkSize = 10) 按 OFFSET 分页读取,每次回调接收一条记录,不是一个数组块。各页沿用入口处从发起实体取得的查询配置,并使用首个查询的表和连接。回调可以另选连接执行自己的查询,之后的分页仍使用首个查询的数据源。请提供稳定排序;遍历中删除记录或修改筛选条件可能改变后续页的偏移,不适合需要稳定游标的迁移任务。 chunk() 不主动请求总数统计,按原始页条数判断是否继续;调用前显式开启的总数统计选项仍保留。
$chunkSize 必须大于 0。回调返回严格的 false 时立即停止,不再交付本批剩余记录或查询后续批次;没有返回值或返回其他值时继续。chunk() 本身不返回累计处理条数。
按稳定键分块
需要逐条更新待处理状态、删除记录或扫描较多数据时,可使用键集分页:
$entity = new User(); $entity->queryLimit()->where('status', 0); $processed = $entity->chunkById(function (User $user): void { $user->status = 1; $user->update(); }, 100); echo $processed; // 已交付给回调的记录数。
chunkById(callable $func, int $chunkSize = 10, ?string $column = null): int 和 insert() 自增回填使用同一字段配置,优先使用 #[AutoIncrement],省略该注解时使用 #[PrimaryKey]。也可以显式传入 $column 覆盖游标列。游标必须是稳定、唯一、非 NULL 的整数或字符串,列名必须对应实体映射属性。
JOIN 中有同名列时,调用方在 column 和投影里显式写出表名或别名。SQL 使用完整列引用,结果中的游标仍使用原列名 id。
// 此处 User::tableName() 返回 users。 $entity = new User(); $entity->queryLimit() ->join('profiles AS profile', 'profile.user_id = users.id', 'INNER') ->fields(['users.id', 'users.name', 'profile.name AS profile_name'], returnAsArray: true); $entity->chunkById($processUser, chunkSize: 100, column: 'users.id');
chunkById() 在单个结果集上推进游标。需要对 UNION 后的结果分块时,请用 QueryBuilder 显式构建外层查询、游标条件和排序。
始终按该列 ASC 排序,从首批开始,再用“游标列 > 上一批最后的游标值”读取下一批;已有排序及页码偏移不决定遍历顺序和起点。每次回调接收一条实体;启用 returnAsArray() 时接收一条数组。与 chunk() 一样,后续页使用首个查询的表和连接。
回调返回严格的 false 时立即停止,返回的计数包含触发停止的这一条;没有返回值或返回其他值时继续。每页通过 FastDb 的统一执行入口查询,沿用 all() 的实体转换和输出规则,保留查询条件及查询回调,不自动开启事务或统计总数。方法结束或抛异常后清理本次查询配置。
使用 fields() 时必须显式选中原始游标列,例如 fields(['id', 'name', 'status']),不能只把游标列选为 id AS cursor 这样的别名;库不会为遍历悄悄扩大字段白名单。非空批次的末行缺少游标列或游标值为 null 时,会在交付该批数据前抛出异常。
hideFields() 可以隐藏游标列,方法从只读查询结果取得末行游标和页大小,再转换实体或隐藏输出字段。隐藏游标或修改分块回调收到的实体都不会改变翻页位置。返回实体后持续隐藏字段仍沿用 persistFieldLimit() 的规则。调用者负责选中符合约定的游标列,并保证其稳定、唯一且非 NULL;组件不逐行扫描校验游标。不要在数据库中修改用于本次遍历的游标列。
查询结果必须具有唯一游标;使用 JOIN 时,也要保证连接结果中该列不重复。额外的查询选项沿用调用方配置;显式开启总数统计时,每页的主查询通知全局和实体查询回调,总数查询只通知全局查询回调。复杂分组、联合或关联查询是否符合游标遍历语义,由调用者保证。需要限制扫描范围时,可预先增加游标上界;方法本身不提供跨页的一致性快照。
计数和聚合
$total = (new User())->count(); $nonNullNames = (new User())->count('name'); $entity = new User(); $entity->queryLimit()->fields(['score', 'status']); $counts = $entity->count(); // ['score' => ..., 'status' => ...]。 $sum = (new User())->sum('score'); $average = (new User())->avg('score'); $maximum = (new User())->max('score'); $minimum = (new User())->min('score'); $values = (new User())->sum(['score', 'status']);
count($field = '*', $group = null) 返回整数;通过 fields() 指定多列计数时返回列名到计数的数组。
聚合字段支持普通列名、保留字列名和带表名/别名的列引用;count() 还支持 *。需要 COUNT(DISTINCT ...) 或 COUNT(CASE ...) 时,通过底层 QueryBuilder 的 rawExpression() 显式表达,例如 $query->get('users', null, [QueryBuilder::rawExpression('COUNT(DISTINCT id) AS total')])。字段各段与结果别名分别引用,多列返回值的键保留传入的列名:
$entity->queryLimit()->fields(['users.id', 'users.order']); $counts = $entity->count(); // ['users.id' => ..., 'users.order' => ...]。 $sum = (new User())->sum('order'); // 列名 order 会正确引用。 $values = (new User())->sum(['users.score', 'users.order']);
sum() / avg() / max() / min() 的签名为 ($cols, $group = null, $force = true)。单列返回 int|float|string,多列返回数组。默认将聚合值转为 float。传入 force: false 可保留 mysqli 返回的整数、浮点数或字符串,例如 sum('amount', force: false) 可以得到未经浮点转换的 DECIMAL 数字字符串。没有聚合值时单列按 0 处理。
这些快捷聚合方法只取第一行。传入 $group 或先调用 groupBy() 不会返回所有分组;需要完整分组结果时用 QueryBuilder 查询。
插入更新删除
插入
$user = new User(['name' => 'Alice', 'score' => 10]); $ok = $user->insert(); // bool。 $id = $user->id; // 自增主键由 last insert id 回填。
插入使用字段转换器生成数据库值,fields() 控制写入白名单,hideFields() 只控制输出。属性值为 null 时省略该列,数据库可以应用默认值。转换对象仍按其 toValue() 的返回值写入。查询正常返回后,FastDb 接受本次成功写入字段的比较基准,并按字段的 convertObject 定义回填自增 ID。显式写入的自增字段保留原值。实体保留原有字段对象及其时区。实体插入要求结果能够用于维护比较基准,使用 INSERT IGNORE 时请直接调用 QueryBuilder。后续属性修改可通过 update() 保存。其他数据库默认值、触发器结果等需要重新查询才能获得。
默认用主键接收自增 ID。自增列与主键分开时,在自增列对应的映射属性上加 #[AutoIncrement]。chunkById() 省略游标时也使用该字段。
use EasySwoole\FastDb\Attributes\AutoIncrement; use EasySwoole\FastDb\Attributes\PrimaryKey; use EasySwoole\FastDb\Attributes\Property; // dataKey 对应 PRIMARY KEY,dataIndex 对应 AUTO_INCREMENT。 #[Property] #[PrimaryKey] public string $dataKey; #[Property] #[AutoIncrement] public int $dataIndex;
每个实体最多标记一个字段,必须是带 #[Property] 的 public 非 static 属性。要让 MySQL 生成自增 ID,请省略该字段。insert() 成功且驱动返回正数 insertId 时,将其回填到未写入的自增字段。更新、删除和默认关联键仍以实体主键为准。
支持 MySQL duplicate-key 更新:
$user->insert(['name', 'score']);
在 insert($updateDuplicateCols) 或构建器的 onDuplicate() 中选择一处配置冲突更新。列表形式的列名使用实体属性原名,大小写保持一致。每列只指定一次赋值。
重复键更新成功且数据未变化时,insert() 仍可返回 true。实体只为新增和冲突更新两个分支都能确认写入实体值的字段同步比较基准。未列入更新列表或使用显式冲突更新值的字段保留原基准。要取得数据库中的最终值,请用已知唯一键重新查询。
假设 users.id 是主键,email 也有唯一索引。数据库中已有 id=1、email='a@example.com'、score=10 的记录。
$user = new User(['id' => 9, 'email' => 'a@example.com', 'score' => 20]); $user->score = 21; $user->insert(['score']); // email 冲突时,将 id=1 的 score 更新为 21。 $stored = User::findRecord(['email' => 'a@example.com']); // 取得实际记录 id=1。
这个例子中,insert() 返回 true,$user->id 仍为 9,getChanges() 可以为空。调用方应根据表上的唯一索引决定是否使用重复键更新。后续需要操作实际命中的记录时,请用业务明确知道的唯一键重新查询,并使用查询返回的实体。
检查待保存修改
hasChange(?string $field = null): bool 检查全部或指定映射字段是否相对比较基准发生变化;未映射或不存在的字段返回 false。getChanges(): array 返回全部变化字段的当前属性值,与直接访问属性一致。ConvertBean、ConvertList 等转换字段返回属性持有的同一个对象,不转成 JSON、不克隆;普通数组仍返回数组。变更比较使用转换对象的 toValue() 结果。
$user = User::findRecord(1); // 假设当前 name 为 Alice,score 为 1。 if ($user !== null) { $user->name = 'Bob'; $user->score = 2; $user->hasChange(); // true $user->hasChange('name'); // true $user->hasChange('status'); // false,未修改。 $user->getChanges(); // ['name' => 'Bob', 'score' => 2] $user->queryLimit()->fields(['name']); if ($user->update()) { $user->hasChange('name'); // false,成功写入字段已接受新基准。 $user->getChanges(); // ['score' => 2],未写入字段继续保留。 } }
这两个入口按调用计算,复用现有比较基准,不额外维护历史记录;它们不主动执行 SQL、接受新基准或清理查询配置,也不触发生命周期钩子。fields() / hideFields() 不影响检查范围。hasChange() 在首次发现变化时返回。比较转换对象的 toValue() 可以识别对象内部修改,getChanges() 返回对象本身。通过返回对象修改内容,与直接修改实体属性相同。
修改后还原为原值,变化会消失;成功写入并接受基准的字段不再返回,SQL 失败时修改继续待保存。显式 setData($data, true) 只接受对应字段的基准。事务回滚不改变这套规则,重载和重试仍由业务决定。构造数据也会被接受为初始基准,因此检查结果不表示实体是否已插入数据库。
变更更新
$user = User::findRecord(1); if ($user !== null) { $user->name = 'Bob'; $user->update(); $user->name = 'Alice'; $user->update(); // 比较基准已更新,改回原值也会执行。 }
update():
- 以对象的比较基准识别已变化字段。
- 对
ConvertObjectInterface属性调用toValue()。 - 使用主键定位记录。查询回填的实体须保留原主键,额外 WHERE 条件会先整体分组,再与主键条件组合。
- 有实际变更且影响行数大于 0 时返回
true,影响行数为 0 时返回false;没有待写入变更时返回true并跳过 SQL。 - 成功后仅同步本次写入字段的比较基准,未被字段筛选选中的变更仍待保存;失败不接受新的基准。
$user->name = 'Bob'; $user->score = 50; $user->queryLimit()->fields(['name']); $user->update(); // 只更新 name。 $user->update(); // 保存尚未写入的 score。
toArray() 在转换前应用 fields() 和 hideFields();insert() / update() 在转换及变更比较前只应用 fields()。字段配置为 null 时没有白名单,空数组不选任何写入列,显式 ['*'] 也不会扩展成全部写入列。被排除的字段不会调用转换对象的 toValue(),不会因其转换失败阻止本次操作。部分更新只接受实际写入字段的比较基准,其他修改仍可在后续放开白名单后保存。
实体写入先确定表名和写入配置,再按实体字段限制及底层构建器的白名单筛选,最后转换参与写入的字段。已提供主键且筛选后没有变化时,update() 返回 true 并跳过 SQL。每次更新结束都会清理查询配置。 实体 update() 在执行前拒绝 IGNORE。需要 UPDATE IGNORE 时请直接使用 QueryBuilder,由业务按需重新读取实际写入值。实体写入、快捷写入和批量写入的返回值均使用公开查询回调前的执行结果。
快捷更新
$affected = User::fastUpdate(1, ['status' => 0]); $affected = User::fastUpdate(['id' => [[1, 2], 'IN']], ['status' => 0]); $affected = User::fastUpdate(['status' => 1], ['score' => 5]); $affected = User::fastUpdate(function (QueryBuilder $query): void { $query->where('score', 10, '<'); }, ['status' => 0]);
签名:fastUpdate($updateLimit, $data, $tableName = null, $onQuery = null),通常返回影响行数。它直接写入 $data,不执行实体更新钩子,也不做属性转换或变更比较。
findRecord()、findAll()、fastUpdate() 和 fastDelete() 直接使用显式传入的表名。省略表名时,才构造实体调用 tableName() 推导表名。返回实体的查询仍会按返回行构造实体。
findRecord()、findAll()、fastUpdate()、fastDelete() 共用条件解析规则:条件数组中的普通值表示等值条件(字符串和布尔值作为参数绑定),数组值使用 [值, 运算符] 或 [值, 运算符, AND/OR];回调接收可直接配置的 QueryBuilder。NULL 判断通过条件回调显式调用 whereNull() 或 whereNotNull()。字符串主键完整绑定为单个值。查询多个主键时在条件数组里明确写 IN。
$affected = User::fastUpdate(['score' => [60, '>=']], ['status' => 1]); $affected = User::fastUpdate(['id' => [['uuid-a', 'uuid-b'], 'IN']], ['status' => 1]);
字符串参数表示主键,数组参数表示以列名为键的条件映射。条件回调使用闭包或可调用对象。函数名、静态方法或实例方法可以显式转成闭包。
$affected = User::fastUpdate('is_object', ['status' => 1]); // WHERE id = 'is_object'。 $rows = User::findAll($filter->configure(...), returnAsArray: true); $rows = User::findAll(Closure::fromCallable('configureUserQuery'), returnAsArray: true);
fastUpdate() 和 fastDelete() 在构建 SQL 前要求有 WHERE。传空条件数组、回调没有添加条件,或回调清除了条件时,会抛出 InvalidArgumentException。空字符串作为主键也会报错。条件匹配多少行由调用者决定。需要执行无 WHERE 的整表操作,请显式构建 QueryBuilder 并通过 FastDb::query() 执行,或使用 rawQuery()。
删除
$user = User::findRecord(1); $deleted = $user?->delete(); // bool;没有对象时示例结果为 null。 $affected = User::fastDelete(1); $affected = User::fastDelete(['id' => [[1, 2], 'IN']]); $affected = User::fastDelete(['score' => [10, '<']]); $affected = User::fastDelete(function (QueryBuilder $query): void { $query->where('status', 0); });
delete() 使用对象主键并触发删除钩子,影响至少一行才返回 true。fastDelete($deleteLimit, $tableName = null, $onQuery = null) 直接删除并返回影响行数,不触发实体钩子。快捷删除同样要求在构建 SQL 前提供 WHERE。
实例 update() / delete() 仅将未赋值、null 或空字符串视为缺失主键;整数 0 和字符串 '0' 均可正常更新、删除。fastDelete(0) 与 fastDelete('0') 都会生成主键等值条件。
批量直接写入
fastInsertAll(iterable $rows, ?string $tableName = null, ?callable $onQuery = null, int $batchSize = 500): int|string 把数据库格式的关联数组分批插入:
$affected = User::fastInsertAll([ ['name' => 'Alice', 'status' => 1, 'score' => 10], ['score' => 20, 'name' => 'Bob', 'status' => 1], // 字段顺序可以不同。 ], batchSize: 500);
输入可以是数组、Generator 或其他 iterable。每行必须是非空的数据库字段关联数组,同一批内必须使用相同的字段集合,由 mysqli 构建 SQL 时校验;只重排键顺序可以,不会自动补 null。各批独立执行,允许不同批次使用不同字段集合。每行按迭代读取时的标量值进入缓冲,后续修改行内标量引用不会改写已读取的行。JSON 等属性应先转成数据库可写的值;不会对每行应用实体转换器或插入钩子,也不回填自增 ID 或实体比较基准。
使用生成器控制批次内存
function userRows(): \Generator { for ($i = 1; $i <= 2000; $i++) { yield ['name' => 'User-' . $i, 'status' => 1, 'score' => $i]; } } $affected = User::fastInsertAll(userRows(), tableName: 'users', batchSize: 500);
框架只缓冲当前批次,不会先把整个生成器转成数组,也不逐行创建模型。batchSize 按行数控制,默认 500;小于或等于 0 会抛出 InvalidArgumentException。空输入在 batchSize 有效时返回 0,不构造模型、不执行 SQL,也不校验未使用的更新列。非空有效输入省略表名时,在首次写入前仅初始化一个模型来取得表名,这个模型自身的默认初始化与 OnInitialize 仍会执行;显式给出有效表名则不构造模型。
主键或唯一键冲突时更新
fastUpsert(iterable $rows, array $updateColumns, ?string $tableName = null, ?callable $onQuery = null, int $batchSize = 500): int|string 使用同样的分批规则。冲突由数据库已有的主键或唯一索引决定,不会自行选择业务字段作为唯一键:
$affected = User::fastUpsert([ ['id' => 1, 'name' => 'Alice', 'score' => 10], ['id' => 2, 'name' => 'Bob', 'score' => 20], ], ['name', 'score'], batchSize: 500); // 列表项使用本次输入的对应列;关联项使用固定值或 mysqli Expression。 $affected = User::fastUpsert([ ['id' => 1, 'name' => 'Alice', 'score' => 10], ], [ 'name', 'status' => 1, 'score' => QueryBuilder::rawExpression('`users`.`score` + ?', [5]), ], tableName: 'users', batchSize: 500);
$updateColumns 沿用 mysqli 的 upsert() 规则;列表列名需存在于每条输入行中。非空输入的空更新列由 mysqli 抛出 InvalidArgumentException;$rows 为空时直接返回 0。固定值及表达式应用于发生冲突的行,插入新行仍使用输入值或数据库默认值。需要逐实体转换、钩子和主键回填时,继续使用实体 insert($updateDuplicateCols)。
返回值是各批数据库 affectedRows 的合计,不是输入行数或自增 ID 列表。upsert 的插入、实际更新和未改变值可能产生不同的影响行数,应按数据库语义理解;合计超出 PHP 整数范围时返回十进制字符串,保留精度。
回调、连接与失败处理
每批使用 FastDb 统一执行入口,触发全局查询日志及传入的 $onQuery;该回调收到本批的 QueryResult,不是整次批量操作的累计结果。整次操作固定入口选中的连接;默认表名需要模型初始化时,以该初始化和表名求值后选中的连接为准。生成器可以自行切换选库,后续批次仍写入原定数据库。
方法不自动开启事务,也不自动重试。后续批次的字段校验、生成器、SQL 或回调发生异常时,前面的批次可能已经成功;查询成功后的回调异常也不代表该批 SQL 已回滚。需要整次原子性时,使用同一连接的显式事务,例如:
$db = FastDb::getInstance(); $db->begin(); $connection = $db->currentConnection(); try { $affected = User::fastInsertAll(userRows(), tableName: 'users', batchSize: 500); $db->commit($connection); } catch (\Throwable $error) { $db->rollback($connection); throw $error; }
显式保存连接可以保证生成器改变当前选库后,仍对实际写入连接提交或回滚;提交结果不明时仍需按事务章节说明核实。若调用前已有事务,应由该事务的拥有者决定提交或回滚。需要更多 SQL 构建选项时,仍可通过 FastDb::query() 使用底层 QueryBuilder::insertAll() / upsert()。
字段筛选与序列化
查询列与返回数组
$entity = new User(); $entity->queryLimit()->fields(['id', 'name']); $entities = $entity->all(); $entity = new User(); $entity->queryLimit()->fields(['id', 'name'], true); $rows = $entity->all()->list();
fields($fields = null, $returnAsArray = false) 同时控制查询列和返回模式。returnAsArray() 也可单独开启数组模式;未启用关联预加载时,它返回数据库行,不执行实体转换回调。显式使用 withRelations() 时,为读取关系方法中的父字段,会额外构造临时父模型,详见批量预加载章节;最终数组仍保留数据库原始值。
隐藏字段与限制传播
$entity = new User(); $entity->queryLimit() ->fields(['id', 'name', 'score']) ->hideFields('score') ->persistFieldLimit(); $result = $entity->all(); echo json_encode($result, JSON_THROW_ON_ERROR);
- 查询时,
fields()接受 SQL 投影,例如['users.id', 'users.name']或['*']。返回实体时,结果列名必须与实体映射属性同名,例如users.name AS name会填充name。需要保留任意别名或未映射的列时,使用returnAsArray()。 - 开启
persistFieldLimit()后,all()和分块返回的实体以数据库实际返回的列名作为继承的序列化白名单。表名前缀、通配符和别名均由数据库处理。直接在实体上用fields()控制toArray()时,传入实体属性名。显式fields(null)可临时取消继承的白名单。 hideFields()接受单个名字或名字数组,并在本次查询回填前移除对应的结果列。开启persistFieldLimit()后,这些隐藏名会继续作用于该实体的toArray()和 JSON。实体自己的hideFields()可追加隐藏名,hideFields([])只清除本地设置。继承的输出限制在更新、重新查询或加载关联后仍保留。后续读写使用本次查询的字段选项。
实体初始化可能为省略的属性设置默认值或 null。部分投影需要按实际结果列序列化时,使用 persistFieldLimit() 或直接返回数组。
重复序列化
$user = User::findRecord(1); if ($user !== null) { $user->queryLimit()->hideFields(['tags', 'meta']); $first = $user->toArray(); $second = json_encode($user, JSON_THROW_ON_ERROR); // 两次输出都保留隐藏限制。 $user->queryLimit()->hideFields([]); // 显式取消隐藏。 $user->queryLimit()->fields(null); // 显式取消字段白名单。 }
toArray($filterNull = false) / jsonSerialize() 只读取实体字段、已有的输出配置和查询结果继承的输出限制。业务如需固定的序列化规则,可覆写 toArray()。序列化不调用 queryLimit(),也不消费查询配置。此前设置的 WHERE、排序、分页和预加载声明均保留,记录模型日志不会改变下一次数据库操作。
$user = User::findRecord(1); if ($user !== null) { $user->queryLimit()->where('status', 0); $logData = $user->toArray(); // 保留待执行的 WHERE。 $user->name = 'Bob'; $user->update(); // WHERE (status = ?) AND id = ?。 }
toArray(true) 的 null 过滤位于普通属性分支;带转换对象或 toValue 的字段应通过转换器控制输出,不能假设转换结果为 null 的字段必然被移除。
ListResult 与 ArrayList
all() / relateMany() 返回 ListResult,继承 ArrayList:
$items = $result->list(); // 底层数组,元素仍可能是实体。 $items = $result->toArray(); // 同样返回底层数组,不递归调用实体 toArray。 $first = $result->first(); // 第一项实体或数组,空列表返回 null。 $total = $result->totalCount(); // 未请求总数时 null。 $count = count($result); $result[] = new User(['id' => 100, 'name' => 'Local item']); foreach ($result as $key => $item) { // 支持追加后遍历;保留显式键。 } unset($result[1]); // 保留其他元素的键。
列表实现 IteratorAggregate,每次 foreach 使用独立迭代器,支持嵌套遍历。需要手动移动游标时,从 $result->getIterator() 获取迭代器。
remove($indexOrEntity) 接受数组位置整数或对象实例,对象按身份比较并删除第一个匹配项。整数走 array_splice 的位置语义,与 unset($list[$key]) 的键语义不同。对稀疏索引结果使用 list() 取得数组后自行整理更明确。
json_encode($result) 序列化底层数据;totalCount 不自动写入 JSON,可在响应中自行包装为 ['list' => $result, 'total' => $result->totalCount()]。
属性转换
使用 #[Property(convertObject: ...)] 配置字段双向转换。转换类的 toObject() 将输入转成属性对象,toValue() 提供写入数据库、输出数组及比较变更时使用的值。
ConvertList
在自己的实体中声明:
use EasySwoole\FastDb\AbstractInterface\ConvertList; #[Property(convertObject: ConvertList::class)] public ?ConvertList $tags;
$user = new User(['id' => 1, 'name' => 'Alice', 'tags' => '["php"]']); $user->tags?->append('swoole'); $user->tags?->has('php', true); $user->tags?->length(); $user->tags?->first(); $user->tags?->remove('php', true); $user->tags?->toArray(); // PHP 数组。 $user->tags?->toValue(); // JSON 字符串。 $user->update(); $user->setData(['tags' => null]); $user->update(); // nullable 属性可清空到 SQL NULL。
本节示例需要把快速开始模型的 tags 声明替换为转换属性。实体 toArray() 对转换对象使用 toValue(),因此这里输出的 tags 是 JSON 字符串,不是嵌套数组。
ConvertList::toObject() 接收 PHP 数组或解码结果为数组的 JSON 字符串;直接传入 PHP null 保留默认空列表约定。非法 JSON 抛出 JsonException,其他输入类型或 JSON 标量抛出 InvalidArgumentException。普通列表与类型化列表的 JSON 编码均使用 JSON_THROW_ON_ERROR;非法 UTF-8、NAN、INF 等编码错误会抛出 JsonException,不会转换为空字符串或自动替换业务数据。append(null) 不追加。first() 返回第一个实际存在的元素,空列表返回 null,不要求数组键从 0 开始。remove() 会保留原数组键,删除后 JSON 编码可能呈现对象形式;需要列表 JSON 时可先使用 array_values() 整理数据并重新赋值。
Bean 列表
通过子类的 itemClass() 指定元素类型,支持 SplBean 及其子类(包括 ConvertBean):
class UserBean extends ConvertBean { public string $name = ''; } class UserList extends ConvertList { protected static function itemClass(): ?string { return UserBean::class; } } // 在实体内声明字段。 #[Property(convertObject: UserList::class)] public ?UserList $users; // JSON 字段读取或 setData() 时,数组元素自动转换为 UserBean。 $model->setData(['users' => '[{"name":"张三"}]']); $model->users->first()->name = '李四'; $model->users->append(['name' => '王五']); $model->users->append(new UserBean(['name' => '赵六'])); $model->update(); // Bean 的修改会参与字段变更检测,保存为 JSON 数组。
toArray() 返回 Bean 元素数组;toValue() 返回 JSON 数组字符串,元素不会被重复编码成 JSON 字符串。初始化和 append() 接收元素数组或指定类型的 Bean,已有 Bean 保留原实例,其他元素类型抛出 InvalidArgumentException;append(null) 仍忽略。类型化列表删除元素后,toValue() 会重新排列键,保持 JSON 数组格式。普通 ConvertList 的行为保持不变。
Bean 列表内嵌套 Bean
Bean 内部的属性可以继续转换为另一个 Bean。实体字段使用 FastDb 的 #[Property],Bean 内部属性使用 SPL 的 #[ConvertBean];下面将 SPL 注解起别名为 NestedBean,避免与 FastDb 的 ConvertBean 基类重名。
use EasySwoole\FastDb\AbstractInterface\ConvertBean; use EasySwoole\FastDb\AbstractInterface\ConvertList; use EasySwoole\Spl\Attribute\ConvertBean as NestedBean; class UserAddress extends ConvertBean { public string $city = ''; } class MemberBean extends ConvertBean { public string $name = ''; #[NestedBean(UserAddress::class)] public ?UserAddress $address; } class MemberList extends ConvertList { protected static function itemClass(): ?string { return MemberBean::class; } }
在实体中声明字段(数据库需有对应的 JSON 或文本列):
#[Property(convertObject: MemberList::class)] public ?MemberList $members;
赋值或从数据库读取时,每个元素会转换为 MemberBean,其中的 address 会继续转换为 UserAddress:
$model->setData(['members' => [ ['name' => '张三', 'address' => ['city' => '杭州']], ]]); // 同样支持 JSON 字符串: // $model->setData(['members' => '[{"name":"张三","address":{"city":"杭州"}}]']); $member = $model->members->first(); $member->address->city = '上海'; $model->update(); // 嵌套 Bean 的修改也参与变更检测。 $model->members->append([ 'name' => '李四', 'address' => ['city' => '北京'], ]); $model->update(); // 追加元素时也会转换嵌套的 address。
保存后的字段内容为 JSON 数组,嵌套 Bean 保持 JSON 对象结构:
[
{"name": "张三", "address": {"city": "上海"}},
{"name": "李四", "address": {"city": "北京"}}
]
实体的 toArray() 对该字段仍返回 JSON 字符串;$model->members->toArray() 返回 Bean 元素数组,$member->toArray() 可获得包含嵌套地址数组的数据。此示例的插入、数据库读取还原、嵌套属性修改及追加保存已通过测试数据库验证。
ConvertDateTime
ConvertDateTime 继承 PHP DateTime 并实现 ConvertObjectInterface,用于 MySQL DATETIME / DATETIME(fsp) 字段。
use EasySwoole\FastDb\AbstractInterface\ConvertDateTime; use EasySwoole\FastDb\Attributes\Property; #[Property(convertObject: ConvertDateTime::class)] public ?ConvertDateTime $createdAt;
$user->setData(['createdAt' => '2026-10-07 12:34:56']); $user->createdAt?->format('Y-m-d'); $user->createdAt?->modify('+1 day'); $user->update(); // 写入 2026-10-08 12:34:56。 $user->setData(['createdAt' => new DateTimeImmutable('2026-10-09 12:00:00')]); $user->update(); $user->setData(['createdAt' => null]); $user->update(); // nullable 字段清空为 SQL NULL。
toObject() 接收日期时间字符串、DateTimeInterface 或整数 Unix 时间戳。直接传入 null 表示当前时间,可空实体属性则直接保留 null。转换器接收日期对象时会复制并保留原时间点、时区和微秒。setData() 收到已经是目标转换类型的对象时会直接使用该实例。
toValue() 和实体序列化输出对象所在时区的本地时间,格式为 Y-m-d H:i:s。微秒非零时输出 Y-m-d H:i:s.u,可用 DATETIME(6) 保留完整精度。DATETIME 只保存日期和时间字段。应用应统一写入所用的时区与 PHP 读取普通数据库字符串时的默认时区,并负责提供该时区中有效的本地时间。
转换器拒绝空字符串、不支持的输入类型和标准 MySQL 格式中的无效日期,例如零日期。其他日期字符串及夏令时的本地时间解释沿用 PHP DateTime 规则。
ConvertBean
use EasySwoole\FastDb\AbstractInterface\ConvertBean; class Address extends ConvertBean { public ?string $city = null; public ?string $province = null; }
在实体中:
#[Property(convertObject: Address::class)] public ?Address $address;
ConvertBean 继承 SplBean,可从解码结果为数组的 JSON 或 PHP 数组恢复字段,toValue() 返回其字符串表示,用于数据库存储。直接传入 PHP null 仍按默认对象初始化;非法 JSON 抛出 JsonException,其他输入类型或 JSON 标量抛出 InvalidArgumentException。必须为模型增加相应的数据库字段。
严格解析与业务降级
ConvertBean 和 ConvertList 的 JSON 解析使用 JSON_THROW_ON_ERROR。空字符串、损坏文本、非法 UTF-8 和超出解析深度的 JSON 都会抛出 JsonException。合法 JSON 的 null、布尔值、数字或字符串不符合这两个转换器的数据结构要求,会抛出 InvalidArgumentException;JSON 对象和数组仍解码为 PHP 数组。PHP null 与 JSON 文本 'null' 分别按上述默认值和结构规则处理。
实体构造、setData() 和查询结果转换会向调用方传播这些异常。实体可空属性接收 PHP null 时仍保留 null,不调用转换器;非空属性使用转换器定义的默认对象或空列表约定。
需要“解析失败时返回空列表”等降级行为时,由业务继承转换器并在属性上显式选择:
use EasySwoole\FastDb\AbstractInterface\ConvertList; use EasySwoole\FastDb\Attributes\Property; class TolerantTags extends ConvertList { public static function toObject(mixed $data): static { try { return parent::toObject($data); } catch (\JsonException $exception) { // 业务可在这里记录原始数据和异常,再选择返回空列表。 return new static([]); } } } // 放在实体类中,以该业务转换器替代内置 ConvertList。 #[Property(convertObject: TolerantTags::class)] public TolerantTags $tags;
ConvertBean 同样可以通过子类覆盖 toObject(),捕获 JsonException 后 return new static([]),使用子类定义的默认字段初始化。默认对象仍需满足业务 Bean 自身的必填字段约束。
示例仅降级 JSON 解析错误;结构错误、类型化列表元素校验和 Bean 初始化异常继续抛出。若业务也要处理结构错误,可在子类中明确增加对应的处理规则。FastDb 不统一吞掉转换异常,也不提供全局自动降级策略。
自定义转换对象与枚举
实现 ConvertObjectInterface,提供 toObject(mixed $data) 和 toValue():
use EasySwoole\FastDb\AbstractInterface\ConvertObjectInterface; enum UserState: int implements ConvertObjectInterface { case Disabled = 0; case Enabled = 1; public static function toObject(mixed $data): object { return self::tryFrom((int) $data) ?? self::Disabled; } public function toValue(): int { return $this->value; } }
#[Property(convertObject: UserState::class)] public UserState $status;
非 nullable 转换属性在初始化时也调用转换器,转换器需要能处理默认值或 null。传入已经是目标类型的对象时,setData() 直接接受该对象。
实体生命周期钩子
钩子是类级 Attribute:OnInitialize、OnInsert、OnUpdate、OnDelete。可以使用实例方法名或 callable。
use EasySwoole\FastDb\Attributes\Hook\OnInitialize; use EasySwoole\FastDb\Attributes\Hook\OnInsert; use EasySwoole\FastDb\Attributes\Hook\OnUpdate; use EasySwoole\FastDb\Attributes\Hook\OnDelete; #[OnInitialize('initializeEntity')] #[OnInsert('beforeInsert')] #[OnUpdate('beforeUpdate')] #[OnDelete('beforeDelete')] class AuditedUser extends User { protected function initializeEntity(): void { // 初始化发生在构造数据 setData() 之前。 } protected function beforeInsert(): bool { return isset($this->name) && $this->name !== ''; } protected function beforeUpdate(): bool { return true; } protected function beforeDelete(): bool { return true; } }
插入、更新、删除钩子返回严格的 false 会中止操作;其他返回值继续执行。初始化钩子没有以返回 false 中止构造的机制。
钩子声明只指定回调。字符串表示当前实体的方法名,无参数调用。可调用对象、闭包和数组回调收到当前实体作为唯一参数。回调需要的业务数据和配置由其实现自行获取。使用全局函数时,先用 Closure::fromCallable() 转成闭包。钩子可从父类继承,最近一级的声明优先。同一个类重复声明同一种钩子时,PHP 在解析实体时抛出异常。当前没有 after-insert / after-update / after-delete 钩子,fastUpdate()、fastDelete() 和原始 SQL 不触发这些生命周期钩子。
关联查询
关联用于按父键和外键从单个目标表加载明细。支持过滤、排序和选列。联表、派生表、UNION、分组聚合和行锁由调用者用 QueryBuilder 显式构建并组装结果。
关联默认按需执行独立查询。使用 queryLimit()->withRelations() 可以显式批量预加载;未声明预加载时,不会额外查询关联表。
定义一对一和一对多关联
type 使用 EasySwoole\FastDb\Attributes\RelationType 枚举:RelationType::One 表示单条关联,RelationType::Many 表示多条关联。type 必填且为只读属性。构造参数顺序为 targetEntity、targetProperty、type,其余参数可按名称传入。One 只能调用 relateOne(),Many 只能调用 relateMany();类型与调用不一致时,在执行查询和配置方法前直接抛出 RuntimeError。
例如用户有一条 profile 和多条 order;目标实体要声明 userId 属性,数据库中需要对应字段:
use EasySwoole\FastDb\Attributes\Relate; use EasySwoole\FastDb\Attributes\RelationType; class RelatedUser extends User { #[Relate(targetEntity: Profile::class, targetProperty: 'userId', type: RelationType::One)] public function profile() { return $this->relateOne(); } #[Relate(targetEntity: Order::class, targetProperty: 'userId', selfProperty: 'id', type: RelationType::Many)] public function orders() { return $this->relateMany(); } }
关联条件为“目标表的 targetProperty = 当前实体的 selfProperty 值”。上例中,查询用户 id = 1 的关联时,会自动附加目标表的 userId = 1 条件。属性名称必须与数据库列名一致,FastDb 不会自动转换驼峰和下划线命名。
加载关联和分页
$user = RelatedUser::findRecord(1); if ($user !== null) { $profile = $user->profile(); // 目标实体|null。 $orders = $user->orders(); // ListResult。 // 查询条件作用于目标订单表,并与自动生成的 userId 条件共同生效。 $user->queryLimit() ->where('status', 1) ->orderBy('id', 'DESC') ->page(1, false, 20); $activeOrders = $user->orders(); $list = $activeOrders->list(); // 订单实体数组。 $user->queryLimit()->returnAsArray(); $profileRow = $user->profile(); // 原始数组|null。 }
一对一未命中时返回 null;一对多未命中时返回包含空列表的 ListResult。一对多按需加载支持 limit() 和 page() 限制明细条数,totalCount() 返回 null,设置 withTotalCount() 会抛出异常。一对一拒绝显式 LIMIT,匹配多条时抛出 RuntimeError。取最新一条或第 N 条时请使用 QueryBuilder。
按需关联查询结束时会清理当前实体的查询配置,包括声明解析失败的情况。下一次关联查询需要重新设置过滤、排序、分页和字段限制。
批量预加载关联
列表中需要访问多个父实体的同类关联时,在父查询上声明关系方法名:
$entity = new RelatedUser(); $entity->queryLimit()->where('status', 1)->orderBy('id', 'ASC') ->withRelations(['profile', 'orders']); $users = $entity->all(); foreach ($users as $user) { $profile = $user->profile(); // 实体|null,复用本次预加载结果。 $orders = $user->orders(); // ListResult,复用本次预加载结果。 }
withRelations(string|array $relations) 接受单个方法名或方法名列表,不接受闭包配置或点分嵌套路径。方法名按声明大小写规范化并去重。再次调用会替换本次声明,withRelations([]) 清除声明。关系方法须标注 #[Relate],并显式声明 type: RelationType::One 或 type: RelationType::Many。预加载根据声明和 configure 构建查询,业务 getter 在应用实际调用时执行。
实体模式会把结果注入各父实体的关联缓存,之后相同查询形状的关系 getter 可直接命中,即使 Relate::cacheResult 为 false 也有效。一对一仍返回实体或 null,匹配多条仍抛出 RuntimeError;一对多仍返回 ListResult。关系声明设置 returnAsArray: true 时,按需加载和预加载均返回数组或包含数组的 ListResult。父实体的 toArray() 不会自动把关系变成字段,需要输出时显式调用 getter。
返回数组并附加关联
$entity = new RelatedUser(); $entity->queryLimit()->fields(['id', 'name'], true)->hideFields('id') ->withRelations(['profile', 'orders']); $rows = $entity->all()->list(); foreach ($rows as $row) { $profileRow = $row['profile']; // 原始行数组|null。 $orderRows = $row['orders']; // 原始行数组列表;没有命中时为 [],不是 ListResult。 }
附加键使用关系方法的声明名;如果父数组已经有同名键,会明确报错,不覆盖原字段。数组模式下父行和关联行保持数据库表示,例如 JSON 字段仍是 JSON 字符串,不会把转换对象放进返回数组。
无论返回实体还是数组,父关联键 selfProperty 都必须以原列名被 SELECT 选中。多个关系共享父键时,预加载对每行只检查一次该列。实体模式要求父键保留到回填阶段,隐藏配置会在逐行检查前统一校验。数组模式可以隐藏父键,关联匹配使用原始行。配置方法读取的其他 $this 字段也应由父查询选中。目标关系的 fields() 不必选中 targetProperty:内部匹配辅助列会被移除,不进入关联输出。当前实体的关联字段可以使用 convertObject 值对象或枚举;按需加载与预加载均使用其 toValue() 数据库值生成关联条件和匹配缓存。预加载要求转换后的关联值为整数、字符串或 null。
数组结果启用预加载时,会为每一条父行临时构造父模型,以便实例配置方法读取 $this 字段。实体模式的父模型和数组模式的临时父模型,都在父查询实际使用的连接下初始化、赋值并转换字段。预加载完成后恢复父查询回调选中的连接。未启用预加载的数组查询仍不会逐行构造实体。
可选配置方法与查询数量
预加载和按需加载均从父实体的 queryLimit() 获取查询配置,保留子类及继承的覆写行为。
configure 默认为 null,无附加条件时可以省略。填写方法名时,由 AbstractEntity 直接调用配置方法,传入 QueryBuilder,返回值忽略。通常使用 public/protected 实例方法以读取当前父模型,也可使用 static 方法。方法可见性和参数约束遵循 PHP 调用规则,不额外反射检查或包装调用错误。
use EasySwoole\FastDb\Attributes\Relate; use EasySwoole\FastDb\Attributes\RelationType; use EasySwoole\Mysqli\QueryBuilder; class PreloadUser extends RelatedUser { #[Relate( targetEntity: Order::class, targetProperty: 'userId', type: RelationType::Many, configure: 'configureActiveOrders', returnAsArray: true )] public function activeOrders() { return $this->relateMany(); } protected function configureActiveOrders(QueryBuilder $query): void { $query->where('status', 1)->orderBy('id', 'DESC') ->fields(['id', 'status']); // 需要按父实体区分条件时,可以读取 $this 的已加载属性。 } } $entity = new PreloadUser(); $entity->queryLimit()->withRelations('activeOrders'); $users = $entity->all()->list(); $orders = $users[0]->activeOrders(); // 同样的配置可命中预加载缓存。
按需加载和预加载共用配置方法。配置方法通过传入的构建器设置 SQL 条件、排序或字段;关系返回数组的规则使用 Relate::returnAsArray 声明。预加载从 type 获取关联类型,不执行 getter。
配置会按父实体分别应用,相同连接、目标实体、关联类型、表名、条件参数、排序、字段和返回形式的计划合并查询。目标表由目标实体的 tableName() 确定。按需加载和预加载都先应用关联配置,再确定目标表和连接,最后转换父键到数据库值。一对一返回实体时,按需加载和预加载都先构造目标实例,查询命中后再用 setData() 填充该实例并建立比较基准。自定义构造器在填充数据库字段前执行。关联结果在实际查询连接下转换和填充。一对多预加载在每条子记录回填前选回该连接。即使多个父对象匹配同一行,预加载也会分别填充各自的目标实例。按需加载和预加载都使用调用方的投影,省略投影时沿用 mysqli 的 *。裸 * 已包含预加载的内部匹配索引。使用 表名.* 或具体列时,FastDb 会追加该索引,并统一在回填前移除。
按需加载要求父关联键来自查询结果、构造数据或显式的 setData()。从数据库读取时,用映射字段名选中该键并保留到回填阶段。部分加载省略、改名或隐藏了该键时,用 setData(['group_code' => $value]) 补齐。直接给属性赋值不会补记缺失字段。手工构造时也须传入父键,例如 new ParentModel(['group_code' => null])。缺键时在关联 SQL 执行前抛出异常,显式传入或查询返回的 null 使用 IS NULL 匹配。FastDb 用目标表名或别名限定自己生成的关联外键条件。复杂表源可用 QueryBuilder 显式查询。
关联的附加条件通过 configure 声明。getter 中自行切库、覆盖表名、临时修改父键等业务行为不会参与预加载;需要这些复杂查询时,由业务显式查询和组装结果。预加载结果按声明及配置生成,getter 的后处理仅在业务实际调用 getter 时执行。
常见固定关系、每种关系不超过 250 个唯一父关联键时,通常是 1 条父查询加每种关系 1 条批查询;例如 100 个父实体同时预加载 profile 和 orders,通常为 3 条 SQL。更大的结果按每组查询计划、每 250 个去重父键分批;相同计划还可合并。若动态条件让每个父对象都产生不同计划,关联查询仍可能达到 N 条,不保证任意关系都固定为一条批 SQL。父分页的额外总数查询、业务方法或钩子自己执行的 SQL 另计;空父列表不执行关联 SQL。
预加载关系拒绝 limit() 和 withTotalCount()。父列表仍支持分页和总数统计。all() 预加载当前列表,chunk() / chunkById() 只预加载当前批次,在逐条业务回调前完成。
预加载声明只作用于本次查询,执行后会被消费;查询模板或实体克隆会保留尚未消费的声明,并独立复制查询配置。实体缓存按连接、父键、实际 SQL、参数和返回模式匹配,更改条件、父键、目标表或实体/数组模式不会错误命中旧结果。clearRelationCache() 同时清除预加载结果和普通关联缓存,之后 getter 恢复查询;数组附加值已经是普通数组,不受该方法影响。cacheResult: false 只关闭按需查询缓存,不会禁用显式预加载的结果。缓存不会自动感知外部写入或事务结果,长生命周期实体应按需清理。
字段选择与隐藏字段
只需要部分列时,在父实体上设置目标查询的字段列表。下面直接返回数组,避免未选择的字段在实体序列化时以默认值或 null 出现:
$user = RelatedUser::findRecord(1); if ($user !== null) { $user->queryLimit()->fields(['id', 'userId', 'status'], true); $rows = $user->orders()->list(); // 每项只有所选列。 }
当前关联查询不会把父实体上的 hideFields()、persistFieldLimit() 自动传给关联结果。需要隐藏字段时,应在返回的实体上设置:
$user = RelatedUser::findRecord(1); if ($user !== null) { $profile = $user->profile(); if ($profile !== null) { $profile->queryLimit()->hideFields('privateNote'); } $orders = $user->orders(); foreach ($orders->list() as $order) { $order->queryLimit()->hideFields('internalRemark'); } $json = json_encode([ 'profile' => $profile, 'orders' => $orders->list(), ], JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR); }
示例中的 privateNote、internalRemark 代表业务模型中需要隐藏的字段。返回数组时请使用 fields(..., true) 明确选择列,或自行移除字段。
修改关联实体
关联返回的实体会执行字段转换,并把加载数据作为更新比较基准。未修改时调用 update() 不发送 SQL;修改后只更新发生变化的字段:
$user = RelatedUser::findRecord(1); if ($user !== null) { $profile = $user->profile(); if ($profile !== null) { $profile->setData(['nickname' => 'Alice'])->update(); } }
nickname 需要在目标模型中声明为 Property。需要更新关联实体时,应保留目标实体的主键列;数组结果不能直接调用实体的 update()。修改父实体不会自动保存或删除关联数据,应分别操作各个实体。
缓存关联查询结果
在 Relate 上设置 cacheResult: true,可以缓存当前实体实例的关联结果,重复执行相同关联查询时不再发送 SQL。默认值为 false。
#[Relate(targetEntity: Profile::class, targetProperty: 'userId', type: RelationType::One, cacheResult: true)] public function profile() { return $this->relateOne(); } #[Relate(targetEntity: Order::class, targetProperty: 'userId', type: RelationType::Many, cacheResult: true)] public function orders() { return $this->relateMany(); }
$user = RelatedUser::findRecord(1); if ($user !== null) { $first = $user->orders(); // 首次查询数据库。 $second = $user->orders(); // 复用同一个 ListResult。 $user->clearRelationCache(); // 清空此实体的全部关联缓存。 $fresh = $user->orders(); // 重新查询数据库。 }
缓存按当前连接名称、目标实体、关联类型、生成的 SQL、绑定参数及返回形式区分。改变关联字段值、过滤条件、排序、分页、选择列、目标表或实体/数组返回形式时,会使用不同缓存项。需要重复命中分页查询时,每次设置相同的分页和排序条件。
null 和空列表同样会缓存;查询异常及一对一匹配多条的异常不会缓存。命中缓存时仍清理本次查询配置,但不会触发查询日志回调。不同父实体实例不共享缓存。
返回的关联实体和 ListResult 复用同一对象,修改对象也会影响后续缓存返回值。缓存不会自动感知其他查询、关联写入、事务提交或回滚导致的数据变化;需要最新数据时调用 clearRelationCache()。不使用显式预加载时,也可保持 cacheResult: false 关闭按需查询缓存。长生命周期实体应按需清理缓存。
显式指定关联字段和目标表
selfProperty 省略时使用当前实体主键;targetProperty 和显式 selfProperty 必须是已映射属性。也可以显式传入 Relate 对象和目标表名:relateOne($relate, $tableName) / relateMany($relate, $tableName),这两个方法是 protected,需要从实体方法调用。
use EasySwoole\FastDb\Attributes\Relate; use EasySwoole\FastDb\Attributes\RelationType; class RelatedUser extends User { #[Relate(targetEntity: Order::class, targetProperty: 'userId', selfProperty: 'id', type: RelationType::Many)] public function archivedOrders() { return $this->relateMany( new Relate( targetEntity: Order::class, targetProperty: 'userId', type: RelationType::Many, selfProperty: 'id' ), tableName: 'archived_orders' ); } }
覆盖表名只改变查询目标表,不会切换数据库连接;目标表结构需要与目标实体字段匹配。
遍历大量父实体逐一加载关联会产生多次 SQL;可使用上述 withRelations() 批量预加载,复杂的自定义汇总仍可使用底层查询。
事务与行锁
$db = FastDb::getInstance(); if (!$db->begin()) { throw new RuntimeException('Cannot begin transaction'); } try { $user = User::findRecord(1, selectForUpdate: true); if ($user === null) { throw new RuntimeException('User not found'); } $user->score += 10; if (!$user->update()) { throw new RuntimeException('Update failed'); } if (!$db->commit()) { throw new RuntimeException('Commit failed'); } } catch (Throwable $exception) { if ($db->isInTransaction()) { $db->rollback(); } throw $exception; }
| 方法 | 行为 |
|---|---|
begin($client = null, $flags = TransactionStartFlags::None, $timeout = null) |
默认获取当前连接并开始事务;连接已有活动事务时保留当前事务并返回 true |
commit($client = null, $flags = TransactionCompletionFlags::NoChainNoRelease, $timeout = null) |
默认提交当前连接的事务。没有连接或事务时返回 true,事务已丢失时抛异常 |
rollback($client = null, $flags = TransactionCompletionFlags::NoChainNoRelease, $timeout = null) |
默认回滚当前连接的事务。没有连接或事务时返回 true,事务已丢失时抛异常 |
isInTransaction($connection = null) |
转发到当前或指定 Connection 的协议状态 getter |
上表描述手动事务入口;下面的 transaction() 只根据入口连接是否已有事务,决定本层是否负责开始、提交和异常回滚。
指定连接、flags 和超时
导入对应枚举:
use EasySwoole\Mysqli\Transaction\TransactionStartFlags; use EasySwoole\Mysqli\Transaction\TransactionCompletionFlags;
| 参数 | 类型 | 含义 |
|---|---|---|
$client |
?Connection |
指定操作连接;null 使用当前选中连接,begin 会按需获取连接 |
$flags |
对应事务枚举 | begin 使用 TransactionStartFlags;commit/rollback 使用 TransactionCompletionFlags |
$timeout |
?float |
单次事务 SQL 的超时秒数,必须大于零;null 使用配置 timeout |
$db->invoke(function (Connection $client) use ($db): void { $db->begin($client, TransactionStartFlags::ReadWrite, 1.0); try { // 使用该连接执行本次业务 SQL。 $db->rawQuery('UPDATE users SET score = score + 1 WHERE id = 1', 0.5); } catch (Throwable $error) { $db->rollback($client, TransactionCompletionFlags::NoChainNoRelease, 1.0); throw $error; } $db->commit($client, TransactionCompletionFlags::NoChainNoRelease, 0.5); }); // 命名参数:在当前连接上以默认结束模式提交,最长等待 0.5 秒。 $db->commit(timeout: 0.5);
flags 不接受整数、枚举的 value 或错误的枚举类型;这些输入会在执行前抛出 TypeError。多次 begin 不增加嵌套层级,也不会建立 savepoint。
开始事务的枚举
以下 SQL 由 TransactionStartFlags::toSql() 生成:
| 枚举值 | SQL |
|---|---|
None |
START TRANSACTION |
ConsistentSnapshot |
START TRANSACTION WITH CONSISTENT SNAPSHOT |
ReadWrite |
START TRANSACTION READ WRITE |
ConsistentSnapshotReadWrite |
START TRANSACTION WITH CONSISTENT SNAPSHOT, READ WRITE |
ReadOnly |
START TRANSACTION READ ONLY |
ConsistentSnapshotReadOnly |
START TRANSACTION WITH CONSISTENT SNAPSHOT, READ ONLY |
一致性快照行为取决于服务端隔离级别。ReadOnly 禁止修改非临时表。
提交和回滚的枚举
下表后缀由 TransactionCompletionFlags::toSqlSuffix() 生成,接在 COMMIT 或 ROLLBACK 后:
| 枚举值 | SQL 后缀 | 行为 |
|---|---|---|
None |
无 | 使用服务端 completion_type 默认行为 |
Chain |
AND CHAIN |
结束当前事务并开始新事务 |
NoChain |
AND NO CHAIN |
不开始新事务;连接释放行为取决于服务端默认值 |
Release |
RELEASE |
结束事务并关闭连接 |
NoRelease |
NO RELEASE |
保留连接;是否开始新事务取决于服务端默认值 |
NoChainRelease |
AND NO CHAIN RELEASE |
不开始新事务,关闭连接 |
ChainNoRelease |
AND CHAIN NO RELEASE |
开始新事务并保留连接 |
NoChainNoRelease |
AND NO CHAIN NO RELEASE |
不开始新事务,保留连接;FastDb 默认值 |
使用默认 NoChainNoRelease 可明确结束事务并保留池内连接。Chain / ChainNoRelease 会开始新事务,Release / NoChainRelease 成功时会关闭连接。FastDb 先保存事务 SQL 的执行结果和耗时。池内连接由池淘汰并关闭,显式传入的独立连接直接关闭,之后通知查询观察者。同一协程随后执行独立查询时按需借用新连接。实际事务状态由 Connection 直接读取底层协议。如果会话设置了 completion_type=2,请使用显式 Release 或 NoChainRelease 让 FastDb 清理池内借用,或用默认的 NoChainNoRelease 保留连接。使用 None 等会继承服务端默认释放行为的选项时,由调用者负责该会话的回收。
FastDb 查询和事务执行超时抛出 EasySwoole\FastDb\Exception\TimeoutException,驱动会关闭失步连接。提交超时可能发生在服务端已提交、客户端尚未收到响应时,结果需要结合业务记录核实,不能直接重试提交。事务日志和查询栈中的 SQL 包含 flags 对应的完整语句,例如 START TRANSACTION READ ONLY、COMMIT AND NO CHAIN NO RELEASE。
queryLimit()->selectForUpdate() 或 all(true) 也可生成锁定查询。锁应配合事务使用,并保持查询、更新、提交在同一协程和同一连接名内。
连接被回收时,未提交事务会被回滚。invoke() 只归还本次调用新获取的连接;复用已有连接或嵌套调用时,连接继续由外层作用域管理。
事务内成功执行 update() 后,模型立即接受本次写入字段的比较基准。之后提交、回滚、连接回收或服务端回滚,都不会自动修改模型当前属性、比较基准或已经返回的更新结果。回滚后直接对同一个未修改对象再次 update(),可能没有变化可写;应按业务需要重新查询、重建对象,或显式修改字段。
Connection 直接读取底层协议,不维护额外的本地事务标记,也不保存模型事务快照、归属代次或回滚标记。同一 FastDb 实例在每个协程内只登记一次连接退出清理;归还连接时清理未结束的数据库会话,避免下一次借用继承事务。此资源清理不负责恢复业务对象。
死锁、断线等对事务状态的影响以底层协议为准;异常继续向调用方抛出,不自动重试。普通 SQL 错误也不会自动撤销模型状态;需要回滚和重试哪些操作,由业务决定。
事务操作成功后,底层协议已读取服务端回复,再执行日志回调;回调中的事务 getter 读取当时的协议状态。日志回调异常仍向调用方传播;尤其是 commit() 的日志回调抛异常时,数据库已经提交,调用方不能据此认定提交失败或直接重试。
回调事务 transaction
transaction(callable $callback, TransactionStartFlags $flags = TransactionStartFlags::None, ?float $timeout = null): mixed 在入口选中的实际连接上管理回调事务。回调接收当前 FastDb 实例,也可使用无参数闭包;正常完成时返回回调的原始返回值,包括 false、null 或对象。
$db = FastDb::getInstance(); $updated = $db->transaction(function (FastDb $db): bool { $user = User::findRecord(1, selectForUpdate: true); if ($user === null) { throw new RuntimeException('User not found'); } $user->score += 10; if (!$user->update()) { throw new RuntimeException('Update failed'); } return true; }, flags: TransactionStartFlags::ReadWrite, timeout: 1.0);
transaction() 使用自身的事务生命周期。子类覆写 begin()、commit() 或 rollback() 时,覆写只作用于显式调用这些入口。入口连接没有事务时,本层先开始事务,回调正常返回后提交;开始或业务回调抛异常时,入口连接仍有活动事务才尝试回滚,随后抛出原异常。开始失败不会执行回调。返回严格的 false 也是正常返回,会提交;需要让拥有层回滚时应抛出异常。
同连接嵌套与已有手动事务
入口连接已经有事务时,本层只执行回调,不发送 BEGIN、COMMIT 或 ROLLBACK。flags 和 timeout 仅用于本层实际发送的事务 SQL。
同连接的内层异常被外层业务捕获后,外层可以正常提交,包括内层在异常前已经执行的写入。内层异常若继续逃出最外层拥有者,才由该拥有者回滚:
$db->transaction(function (FastDb $db): void { try { $db->transaction(function (FastDb $db): void { // 与外层使用同一个数据库事务。 throw new RuntimeException('Inner operation failed'); }); } catch (RuntimeException $error) { // 已捕获异常;外层正常返回时仍会提交。 } });
事务原本由手工 begin() 开启时,transaction() 同样只加入并执行回调。无论回调返回还是抛异常,都由手工事务的调用方决定何时提交或回滚;框架不额外标记该事务。
连接选择与 A → B → A
拥有层固定入口的实际 Connection,结束时始终操作该连接;回调改变选库,不会让 helper 提交其他连接。方法本身不恢复选库,也不会把回调中的全部 SQL 强制路由到入口连接。需要退出时恢复连接名,可配合 withConnection()。
A → B → A 时,A、B 各自尚无事务的外层分别开始一个事务,重新进入 A 的内层只加入 A。
假设已通过 addDb() 注册名为 A、B 的连接,进入示例前两者都没有事务。下面在 A 写入、切到 B 读取,再回到 A 写入:
$db = FastDb::getInstance(); $db->withConnection('A', function (FastDb $db): void { $db->transaction(function (FastDb $db): void { // 开始 A 的事务。 User::fastUpdate(1, ['status' => 1]); $db->withConnection('B', function (FastDb $db): void { $db->transaction(function (FastDb $db): void { // 开始 B 的独立事务,当前查询使用 B。 User::findRecord(1); $db->withConnection('A', function (FastDb $db): void { $db->transaction(function (FastDb $db): void { // 复用外层 A 的连接和事务,不重复 BEGIN。 User::fastUpdate(1, ['score' => 20]); }); // 只退出内层回调,不提交 A。 }); // 恢复选择 B。 User::findRecord(2); // 继续使用 B。 }); // 正常返回,提交 B。 }); // 恢复选择 A。 User::fastUpdate(1, ['status' => 2]); // 仍在最外层 A 的事务中。 }); // 正常返回,提交 A,包括内层 A 的写入。 }); // 恢复进入示例前的连接名。
发生异常时:
- 内层 A 的异常被业务捕获后,A、B 都可以继续正常提交;没有自动的局部回滚。
- 异常逐层逃出时,各个拥有层分别回滚自己的连接。
- B 已经提交后,A 随后回滚不会撤销 B;两个连接没有分布式事务协调。
flags、超时和提交失败
拥有层使用 flags 开始事务,timeout 分别传给本层实际发送的 BEGIN、COMMIT、ROLLBACK。每条控制 SQL 都有独立的单次预算;这不是 PHP 回调或整个事务的累计期限,业务 SQL 仍使用各自查询参数或连接配置。连接池等待也不包含在控制 SQL 超时内。
开始或业务回调抛出的异常优先于回滚清理异常,回滚失败不会替换原异常。提交发生在业务回调正常返回之后:提交返回 false 会抛出 RuntimeError,提交本身或其日志回调抛出的异常直接向外传播,不自动重试,也不自动追加 ROLLBACK。尤其 COMMIT 已成功后的日志异常不能视为数据库未提交;提交超时、断线等结果不明时,由业务核实最终状态并处理。
helper 不解析 SQL 白名单,不管理 savepoint,不跟踪事务代次,也不阻止回调手工开始、提交、回滚或执行会隐式提交的 SQL。这些操作对事务边界及业务原子性的影响由调用方负责。
与 invoke 的区别
| 入口 | 回调参数 | 自动管理的范围 |
|---|---|---|
withConnection() |
FastDb | 临时连接名,退出恢复;不借还连接,不开始或结束事务 |
transaction() |
FastDb | 入口实际连接的事务;同连接嵌套加入,不恢复回调选库 |
invoke() |
Connection | 仅归还本层自己借出的连接;不自动开始事务 |
多数据库与连接生命周期
注册和选择连接
$db = FastDb::getInstance(); $db->addDb(new Config($primaryConfig), 'primary'); $db->addDb(new Config($reportingConfig), 'reporting'); $previous = $db->selectConnection(); // 当前连接名,未设置时 default。 $db->selectConnection('reporting'); try { $users = User::findAll(['status' => 1]); } finally { $db->selectConnection($previous); }
addDb() 优先用第二个参数作为连接名,省略时使用 Config::getName()。如果最终名称是空字符串 '' 或 '0',注册时会抛出 InvalidArgumentException。传入的 Config 对象可以继续由调用方使用。
连接选择按协程保存。实体没有自身绑定的连接名,所有实体查询使用 FastDb::getInstance() 当前选择的连接;使用局部 new FastDb() 不会改变实体所使用的单例。
作用域选库 withConnection
withConnection(string $name, callable $callback): mixed 临时选择连接名,并在 try/finally 中恢复进入前的名字:正常返回、回调抛异常、内部又切换其他连接时都恢复。回调接收该 FastDb 实例,也可使用无参闭包,返回值原样返回,包括 false 和 null。
$db = FastDb::getInstance(); $rows = $db->withConnection('reporting', function (FastDb $db): array { return User::findAll(['status' => 1], returnAsArray: true); }); // 回到调用前的连接名。 $db->withConnection('primary', function (FastDb $db): void { $db->withConnection('reporting', function (FastDb $db): void { // 当前为 reporting。 }); // 内层退出后回到 primary。 }); // 外层退出后回到最初的连接名。
$name 必须通过 addDb() 注册。未注册的名称会在执行回调前被拒绝。withConnection() 只切换连接名,连接可用性由后续实际借用时检查。
该方法自己不借连接、不回收连接、不创建事务,也不提交或回滚已有事务。回调里的查询会按需使用现有连接池流程;只改变选库、不执行 SQL 的回调不会因此创建数据库连接。如果回调手工开始事务,退出选库作用域不会自动结束它;需要回调事务管理时显式调用 transaction()。
两个作用域可以组合,例如临时选择 primary,再执行其回调事务:
$value = $db->withConnection('primary', function (FastDb $db): mixed { return $db->transaction(function (FastDb $db): mixed { return User::fastUpdate(1, ['status' => 1]); }); });
新事务的拥有层正常返回时提交,加入已有事务的层不提前提交;返回 false 不表示回滚。选库作用域在事务成功或失败后都恢复原名字。其他协程的连接选择不受影响。
提前归还
$rows = $db->invoke(function (Connection $connection): array { $query = new QueryBuilder(); $query->get('users', 10, ['id', 'name']); return $connection->query($query); });
invoke() 返回回调返回值,finally 中归还由本次调用获取的连接。直接调用 $connection->query() / rawQuery() 直接执行驱动,不创建 QueryResult 或查询计时记录,也不会经过 FastDb 的日志包装;需要全局日志时在回调中调用 $db->query() / rawQuery()。不要保存回调中的连接给后续协程使用。
$db->currentConnection(); // 当前选中连接的 Connection|null,不主动创建连接。 $db->recycleContext(); // 归还当前协程的全部连接,未结束会话由连接池清理。 $db->reset(); // 重置连接池和定时器,用于生命周期管理。
recycleContext(): void 直接归还当前协程持有的全部连接,并清理其查询栈。连接池在归还时回滚未结束的事务,淘汰连接时直接关闭会话。FastDb 在单条归还处隔离异常,使批量归还能继续,并保留 invoke() 回调的返回值或原始异常。模型属性及比较基准不因此改变。
reset() 重置全部连接池和定时器,用于关闭、测试或重新初始化阶段。调用前应先归还上下文连接,并避免其他协程仍在使用连接池。
原始 SQL 与底层构建器
下文需要导入:
use EasySwoole\Mysqli\QueryBuilder; use EasySwoole\FastDb\Mysql\Connection; use EasySwoole\FastDb\Mysql\QueryResult;
参数化 SQL
$query = new QueryBuilder(); $query->raw('SELECT id, name FROM users WHERE status = ? AND score >= ?', [1, 10]); $result = FastDb::getInstance()->query($query, timeout: 1.0); $rows = $result->getResult(); $first = $result->getResultOne(); // 第一行或 null。
原始查询的整数列按驱动类型解析为 PHP 整数;超过 PHP_INT_MAX 的无符号整数保留为十进制字符串。
也可传回调:
$result = FastDb::getInstance()->query(function (QueryBuilder $query): void { $query->where('status', 1)->get('users', 10, ['id', 'name']); });
query() 的构建回调需要完成 get() / insert() / update() / delete() / raw() 等最终构建动作。FastDb 先确定执行连接名,再运行构建回调。构建失败或构建器没有 SQL 时直接抛异常,此次调用不会借连接或通知查询观察者。可以用 onQuery: 为本条 SQL 指定观察回调,接收 QueryResult,在全局查询回调之后执行。实体分页的回调收到主查询结果,分页总数从 ListResult::totalCount() 读取。实体列表和按需加载的关联列表在组装行对象前通知各自的实体回调。
原始 SQL
$result = FastDb::getInstance()->rawQuery('SELECT CURRENT_TIMESTAMP AS now', timeout: 1.0); $row = $result->getResultOne();
rawQuery(string $sql, ?float $timeout = null, ?string $connection = null) 不支持单独的绑定参数。动态数据使用 QueryBuilder::raw($sql, $params),不要拼接输入数据。
通过 currentConnection() 或 invoke() 取得的高级连接接口不提供连接级监听,调用 Connection::onQuery() 会抛出 LogicException。直接使用 Connection 执行 SQL 时,日志由业务代码自行记录;通过 FastDb 执行 SQL 时可使用全局、实体或单次查询回调。
QueryResult
| 方法 | 返回内容 |
|---|---|
getResult() |
SELECT 等返回行数组,写入/DDL 通常返回 bool;查询失败回调中为 null |
getResultOne() |
数组结果的第一行,否则 null |
getException(): ?Throwable |
执行失败时的异常对象;成功或未设置时为 null |
getConnectionName() |
本次查询的执行连接名快照(string),供慢日志和异常定位使用 |
getAffectedRows() |
本次成功查询的影响行数快照;未取得结果或查询失败时为 null |
getInsertId() |
本次成功查询的自增 ID 快照;未取得结果或查询失败时为 null |
getLastQuery(): ?string |
按需展开绑定参数生成日志 SQL |
getLastPrepareQuery(): ?string |
保留占位符的 SQL |
getLastBindParams(): array |
按占位符顺序排列的绑定参数 |
getRawSql() |
原始 SQL 文本;构建器查询时通常 null |
getDuration(): float |
查询执行阶段耗时,秒;不含获取连接及日志回调 |
getStartTime() / getEndTime() |
Unix 时间戳,用于日志定位;查询执行耗时使用 getDuration() |
查询回调接收只读 QueryResult。QueryResult、QueryStack 和 TimeoutException 使用相同的日志读取方法。原始 SQL 和事务操作的 SQL getter 返回执行文本,绑定参数为 []。构建器查询的日志快照保存 mysqli 的只读编译结果,调用 getLastQuery() 时才按编译时的引号规则展开参数。自定义构建器应在构建阶段设置最终 SQL 和绑定参数。
写入结果的影响行数和 insert id 从 QueryResult 快照读取。
$affected = $result->getAffectedRows(); $insertId = $result->getInsertId();
查询结果和查询栈记录实际执行连接的名称。SQL 执行失败时也会记录该名称。
FastDb 的 query() 和 rawQuery() 每次执行一条 SQL。Connection 返回后立即保存结果行、影响行数、自增 ID、SQL、参数和耗时。查询结果只反映本次执行,读取新数据需要再次查询。
Connection 的 getLastAffectRows() / getLastInsertId() 始终表示最后一条实际执行 SQL 的元数据,包括分页总数查询。通过 FastDb 执行时,使用返回的 QueryResult 获取该次操作的影响行数和自增 ID。
影响行数和自增 ID 类型为 int|string|null,超大无符号值保留为字符串,未查询或查询失败时为 null。影响行数与自增 ID 在查询成功后、日志回调执行前记录为快照,不会被后续 SQL 覆盖。query() 和 rawQuery() 的可选 $timeout 控制本次查询超时。
直接使用 FastDb::query() 执行带 SQL_CALC_FOUND_ROWS 的查询时,如需总数,应紧接着调用 rawQuery() 执行 SELECT FOUND_ROWS(),并把主查询的 getConnectionName() 传给 connection:。实体分页入口会执行这一步,总数通过 ListResult::totalCount() 读取。
getDuration() 只记录驱动执行阶段,排除 SQL 构建、获取连接、池连接淘汰和查询观察回调。
连接获取耗时通过查询栈的独立 connectionAcquire 事件读取,不分摊给某条 SQL 或 QueryResult。计时覆盖连接池 getObj() 阶段,包含排队、按需新建连接、健康检查及重试;它不是纯粹的队列等待时间。业务端到端耗时还包含进入查询执行阶段前的构建和业务代码等阶段,需要另行计时。
超时异常定位
FastDb::query()、rawQuery() 及 begin() / commit() / rollback() 的执行超时抛出 EasySwoole\FastDb\Exception\TimeoutException。异常创建时保存只读 SQL 上下文。message 保持底层错误消息,不拼接 SQL 或参数。
| 方法 | 返回内容 |
|---|---|
getRawSql(): ?string |
对应 SQL;预处理查询保留占位符,事务 SQL 包含 flags |
getLastQuery(): ?string |
按需展开绑定参数的日志 SQL |
getLastPrepareQuery(): ?string |
保留占位符的 SQL |
getLastBindParams(): array |
按占位符顺序排列的绑定参数 |
getPrevious() |
原始 mysqli 超时异常;错误码和 message 保持一致 |
use EasySwoole\FastDb\Exception\TimeoutException; $query = new QueryBuilder(); $query->raw('SELECT SLEEP(?)', [1]); try { $db->query($query, timeout: 0.05); } catch (TimeoutException $error) { $sql = $error->getLastPrepareQuery(); // SELECT SLEEP(?) $params = $error->getLastBindParams(); // [1] $message = $error->getMessage(); // 原始超时消息。 $cause = $error->getPrevious(); // 将 message、sql、params 按需交给日志系统。 throw $error; }
原始查询及事务超时可直接使用 getRawSql() 定位,例如 COMMIT AND NO CHAIN NO RELEASE。预处理查询使用 getLastPrepareQuery() 和 getLastBindParams() 获取 SQL 模板及参数。
FastDb 的超时异常继承 EasySwoole\FastDb\Exception\Exception。调用方可捕获 EasySwoole\FastDb\Exception\TimeoutException,或 FastDb 通用 Exception;它不继承 mysqli 异常,原始 mysqli 超时实例保存在 getPrevious() 中。
这里覆盖 FastDb Connection 的 query/rawQuery 执行路径;获取连接前的连接池等待或建连失败、直接使用依赖 Client/prepare 的异常遵循各自入口。记录绑定参数时应按业务需要保护敏感数据。提交超时的结果需要核实,不能据此直接认定回滚。
查询日志与查询栈
onQuery 只用于调试、日志和执行后检查。回调读取只读的 QueryResult,检查未通过时可以抛异常。请把其他查询、切换连接、修改查询配置和事务操作放在回调外。回调在 SQL 执行之后触发。异常会向调用方传播,实体写入的自增 ID 和比较基准仅在查询正常返回后更新。已自动提交的写入仍然生效,需要时由业务核对结果并重新加载实体。日志或检查失败若只应留在回调内,请在回调内用 try/catch 处理。
全局回调
$db->setOnQuery(function (QueryResult $result): void { $durationMs = $result->getDuration() * 1000; $sql = $result->getLastPrepareQuery(); $params = $result->getLastBindParams(); $exception = $result->getException(); $errorMessage = $exception?->getMessage(); $errorCode = $exception?->getCode(); // 写入自己的日志系统:sql、params、durationMs、errorMessage、errorCode。 });
查询执行阶段的开始时间在获得连接之后记录,执行耗时不包含获取连接;获取阶段另记为独立查询栈事件。query() / rawQuery() 结束时间在执行结束或失败后、调用日志回调之前记录,不包含日志回调耗时。begin/commit/rollback 实际执行后,无论成功、SQL 错误或超时,都进入日志回调和查询栈。事务日志、查询栈和驱动执行共用由 flags 生成的同一条 SQL。全局 onQuery 只接收查询执行结果,连接获取成功或失败均不调用它。
query() / rawQuery() 和事务执行抛异常时,回调中的 getException() 返回本条 SQL 的驱动执行异常,getResult() / getResultOne() 为 null。成功执行时 getException() 为 null。回调抛出的异常直接向调用方传播,并中止后续通知。SQL 失败的异常保存在该条 SQL 的查询记录中,观察回调正常返回后向调用方抛出。
getLastQuery() 返回参数展开后的调试文本。排查绑定值和类型时,优先记录 getLastPrepareQuery() 和 getLastBindParams()。
实体与单次回调
$entity = new User(); $entity->setOnQuery(function (QueryResult $result): void { // 此实体调用的查询。 }); $entity->all(); $entity->setOnQuery(null); $user = User::findRecord(1, onQuery: function (QueryResult $result): void { // 本次静态查询。 });
findAll()、fastUpdate()、fastDelete() 也有 $onQuery 参数。全局回调与实体/单次回调可以同时执行。连接获取失败时直接抛异常,全局和单次查询回调都不触发。启用查询栈时,实际借用失败由独立的 connectionAcquire 事件记录。
普通查询、分块和预加载统一在 SQL 实际执行的连接下初始化实体,回填结束后恢复当时选中的连接。
查询栈
$db->configureQueryStack(true, maxStackSize: 2); $db->rawQuery('SELECT 11'); // 首次借连接时先记 connectionAcquire,再记 query,共占两条。 $db->rawQuery('SELECT 22'); $db->rawQuery('SELECT 33'); $stack = $db->getQueryStack(); // 当前协程记录数组,未记录时 null。 $first = $db->getQueryStack(0); // SELECT 22,SELECT 11 已淘汰。 $last = $db->getQueryStack(-1); // SELECT 33。 $previous = $db->getQueryStack(-2); // SELECT 22。 $missing = $db->getQueryStack(100); // null。 $db->configureQueryStack(false, maxStackSize: 2); // 停止追加,保持相同容量下的已有记录。
configureQueryStack(bool $enabled, int $maxStackSize = 256): static 的容量必须是正整数,配置属于该 FastDb 实例;每个协程分别保留最近 N 条事件,包含 query 和 connectionAcquire,达到容量时淘汰最旧项。返回数组始终按保留记录的先后顺序排列;正索引 0 表示当前保留的最旧项,-1 表示最新项,越界返回 null。首次查询若需要借连接会产生两条事件,复用连接的后续查询只有 query 事件。
每次启停调用都会应用 maxStackSize,缩小容量会立即裁剪该实例所有已有协程栈,包括关闭时。关闭只停止追加,不主动清空,但 configureQueryStack(false) 也会应用默认容量 256:此前容量大于 256 时,已有记录会缩到最近 256 条。需要保留更大容量下的现有记录,可显式传原容量,例如 configureQueryStack(false, maxStackSize: 1024)。协程退出或回收上下文时清理其记录。
每项 QueryStack 的公共字段均为只读。
| 字段 | 含义 |
|---|---|
type |
普通 SQL 为 query,独立连接获取事件为 connectionAcquire |
connectionName |
本次操作的连接名快照,失败时也可定位尝试借用的连接 |
rawQuery |
原始 SQL 文本,构建器查询和连接获取事件为 null |
duration |
当前事件耗时,秒;query 为驱动执行阶段,connectionAcquire 为本次 getObj() 的获取总耗时 |
exception |
SQL 执行异常,或连接获取事件中实际向外抛出的借用异常;成功时为 null |
startTime / endTime |
记录的起止 Unix 时间戳,用于日志定位;耗时字段使用单调时钟 |
主查询与 SELECT FOUND_ROWS() as count 各有一条 trace,各自触发全局 onQuery。FastDb 对每条 SQL 先记录 trace,再通知回调。主查询或其回调抛异常时,列表停止执行,总数 SQL 不会发出。总数 SQL 的回调抛异常时,异常直接传播,已记录的 trace 保留。查询栈和查询结果共享同一份 SQL 快照。
普通 SQL 记录的异常来自该 SQL 执行结果,不把 SQL 成功后日志回调再抛出的错误改记为 SQL 失败。获取连接失败时,栈中的 exception 则保留实际向调用方抛出的那个异常。
连接获取的独立事件
通过 FastDb 真正执行一次 getObj() 新借连接,无论由 query()、rawQuery()、直接 begin(),还是 invoke()、transaction() 触发,都生成一条独立的 type = 'connectionAcquire' 事件。复用已有连接不生成获取事件;向 begin() 显式传入已有 Connection 也不借连接。连接池内部的创建、健康检查与重试包含在这一条事件里,不拆成多条。配置校验、testDb() 和 preConnect() 不属于这段借用计时。
借用失败同样记录独立获取事件。duration 是获取历时,连接名及实际向外抛出的异常可见。连接获取事件的两个 SQL getter 返回 null,绑定参数返回 []。没有执行 SQL 时,不生成 query 事件,也不调用全局 onQuery。
仅在借用入口已启用查询栈时启动获取计时,记录完成时若已关闭则丢弃事件;入口关闭、借用过程中才开启时,该次借用不补记获取事件,之后的查询执行可正常入栈。query(callable) 的构建阶段可以开启查询栈,之后执行的 SQL 会按当时的配置记录。
$db->configureQueryStack(true, maxStackSize: 256); try { $db->rawQuery('SELECT 1'); } catch (Throwable $error) { $event = $db->getQueryStack(-1); if ($event !== null && $event->type === 'connectionAcquire') { $acquireMs = $event->duration * 1000; $connectionName = $event->connectionName; $sameException = $event->exception === $error; } throw $error; }
记录慢查询日志
通过 QueryResult::getDuration() 获取耗时,单位为秒。下面以 200 毫秒为慢查询阈值,使用同一个日志方法记录 SQL、绑定参数、执行耗时和异常信息;可将 error_log() 替换为项目中的日志组件。
use EasySwoole\FastDb\Mysql\QueryResult; final class SlowQueryLogger { public static function record(QueryResult $result): void { $durationMs = $result->getDuration() * 1000; if ($durationMs < 200) { return; } $exception = $result->getException(); error_log(json_encode([ 'type' => 'slow_query', 'sql' => $result->getLastPrepareQuery(), 'params' => $result->getLastBindParams(), 'durationMs' => $durationMs, 'startTime' => $result->getStartTime(), 'errorMessage' => $exception?->getMessage(), 'errorCode' => $exception?->getCode(), ], JSON_UNESCAPED_UNICODE | JSON_INVALID_UTF8_SUBSTITUTE | JSON_PARTIAL_OUTPUT_ON_ERROR)); } }
耗时使用 hrtime() 的单调时钟计算,系统时间调整不会影响耗时测量;startTime 仍为 Unix 时间戳,便于定位日志发生时间。示例按查询执行阶段达到 200 毫秒判定慢查询,排除 SQL 构建、获取连接及日志回调。若需要发现查询执行很快、连接获取很慢的情况,应读取已开启的查询栈,对 type === 'connectionAcquire' 事件的 duration 设置独立阈值;获取事件不进入全局 onQuery。
方法一:FastDb 全局 onQuery
在应用初始化时注册,统一追踪通过该 FastDb 实例执行的查询,包括模型查询、直接调用 query() / rawQuery(),以及实际执行的 begin/commit/rollback。
use EasySwoole\FastDb\FastDb; FastDb::getInstance()->setOnQuery([SlowQueryLogger::class, 'record']);
setOnQuery() 会替换已有的全局回调。如果项目已经注册查询日志回调,应把慢查询判断加入现有回调,或在其中调用 SlowQueryLogger::record($result)。
方法二:在基础模型构造方法中设置 onQuery
需要按模型选择追踪范围时,可以定义一个基础模型,在构造方法中调用父类初始化,并注册实体级回调。需要记录慢查询日志的模型继承这个基础模型。
use EasySwoole\FastDb\AbstractInterface\AbstractEntity; use EasySwoole\FastDb\Attributes\PrimaryKey; use EasySwoole\FastDb\Attributes\Property; abstract class SlowQueryModel extends AbstractEntity { public function __construct(?array $data = null) { parent::__construct($data); $this->setOnQuery([SlowQueryLogger::class, 'record']); } } class ConfigModel extends SlowQueryModel { #[Property] #[PrimaryKey] public int $configId; #[Property] public ?string $configContent; public function tableName(): string { return 'config'; } } $config = new ConfigModel(); $config->queryLimit()->where('configId', 1); $result = $config->all(); // 本次查询达到阈值时记录慢日志。
此方式覆盖实体实例调用的查询,例如 all()、insert()、update()、delete() 和关联查询。子类如果重写构造方法,需要调用 parent::__construct($data) 才能保留初始化及日志注册。
静态方法 findRecord()、findAll()、fastUpdate()、fastDelete() 使用各自的 $onQuery 参数,不会自动使用基础模型构造方法中设置的实体回调。需要追踪这些调用时,显式传入回调:
$config = ConfigModel::findRecord( 1, onQuery: [SlowQueryLogger::class, 'record'] );
全局回调与实体/单次回调可以同时触发。若两处都调用同一个慢日志方法,同一次执行可能记录两条日志,应按需要选择注册范围。
API 速查
AbstractEntity
| API | 用途 / 返回 |
|---|---|
new Entity(?array $data) |
初始化并接受输入为比较基准 |
tableName(): string |
子类必须实现表名 |
setData(array $data, bool $mergeCompare = false) |
输入转换、赋值;返回当前实体 |
queryLimit(): Query |
取得当前查询限制 |
all(bool $selectForUpdate = false): ListResult |
执行实例查询 |
findRecord($queryLimit, $tableName, $selectForUpdate, $onQuery) |
单条实体或 null |
findAll($queryLimit, $tableName, $returnAsArray, $selectForUpdate, $onQuery) |
普通数组 |
insert(?array $updateDuplicateCols = null) |
插入/重复键更新;bool |
update() / delete() |
按对象主键更新/删除;bool |
fastUpdate($limit, array $data, $tableName, $onQuery) |
直接更新;影响行数 |
fastDelete($limit, $tableName, $onQuery) |
直接删除;影响行数 |
fastInsertAll(iterable $rows, ?string $tableName = null, ?callable $onQuery = null, int $batchSize = 500) |
分批直接插入;合计影响行数 int|string |
fastUpsert(iterable $rows, array $updateColumns, ?string $tableName = null, ?callable $onQuery = null, int $batchSize = 500) |
主键/唯一键冲突时更新;合计影响行数 int|string |
count($field = '*', $group = null) |
整数或多列计数数组 |
sum/avg/max/min($cols, $group = null, $force = true) |
单列 int|float|string 或多列聚合数组 |
chunk(callable $func, int $chunkSize = 10) |
OFFSET 分页逐条回调;false 停止,不返回累计条数 |
chunkById(callable $func, int $chunkSize = 10, ?string $column = null): int |
按稳定唯一列 ASC 键集分页;返回已交付条数 |
hasChange(?string $field = null): bool |
检查全部或指定映射字段的待保存修改 |
getChanges(): array |
返回全部变化字段的当前属性值,Bean 等转换对象保持原实例 |
toArray(bool $filterNull = false): array |
属性转换并筛选输出 |
jsonSerialize() |
使用 toArray 输出 |
setOnQuery(?callable $call) |
当前实体查询回调;返回实体 |
relateOne() / relateMany() |
protected 关联查询,需要实体方法包装 |
Query
| API | 用途 |
|---|---|
where($column, $value, $operator = '=', $cond = 'AND') |
条件 |
orWhere($column, $value, $operator = '=') |
OR 条件 |
orderBy($field, $direction = 'DESC', $customFieldsOrRegExp = null) |
排序 |
groupBy(string $field) |
分组 |
join($table, $condition, $type = '') |
JOIN |
page(?int $page, bool $withTotalCount = false, int $pageSize = 10) |
分页 |
limit(int $num, bool $withTotalCount = false) |
数量限制 |
fields(?array $fields = null, bool $returnAsArray = false) |
字段白名单与返回模式 |
returnAsArray() |
开启原始数组模式 |
hideFields(array|string $fields) |
隐藏字段 |
persistFieldLimit(bool $enabled = true) |
all() 子实体输出限制传播 |
getFields() / getHideFields() / isPersistFieldLimit() |
读取限制 |
withRelations(string|array $relations): Query |
本次 all/chunk/chunkById 批量预加载关系;空数组清除声明 |
func(callable $func) |
操作底层构建器 |
selectForUpdate() |
添加行锁查询 |
returnEntity() |
返回发起查询的实体 |
__getQueryBuilder() |
获取底层 QueryBuilder |
除读取方法、返回实体和获取构建器外,以上方法返回 Query 支持链式调用。
FastDb
| API | 用途 |
|---|---|
getInstance() |
数据库管理单例 |
addDb(Config $config, ?string $name = null) |
注册配置;返回管理器 |
getConfig(string $name = 'default') |
Config 或 false |
selectConnection(?string $name = null) |
设置连接名时返回管理器;省略时返回名字 |
withConnection(string $name, callable $callback): mixed |
临时选库并恢复;回调接收 FastDb,不借还连接或改变事务 |
testDb(string $connectionName = 'default') |
检查连接,成功 true,失败异常 |
query(QueryBuilder|callable $queryBuilder, ?float $timeout = null, ?string $connection = null, ?callable $onQuery = null) |
构建器查询,返回 QueryResult |
rawQuery(string $sql, ?float $timeout = null, ?string $connection = null) |
原始 SQL,返回 QueryResult |
begin(?Connection $client = null, TransactionStartFlags $flags = TransactionStartFlags::None, ?float $timeout = null) |
开始事务;bool |
commit(?Connection $client = null, TransactionCompletionFlags $flags = TransactionCompletionFlags::NoChainNoRelease, ?float $timeout = null) |
提交事务;bool |
rollback(?Connection $client = null, TransactionCompletionFlags $flags = TransactionCompletionFlags::NoChainNoRelease, ?float $timeout = null) |
回滚事务;bool |
transaction(callable $callback, TransactionStartFlags $flags = TransactionStartFlags::None, ?float $timeout = null): mixed |
回调事务;已有事务只执行回调,拥有层负责结束;返回回调值 |
isInTransaction(?Connection $connection = null) |
转发 Connection 的协议状态 getter;bool |
invoke(callable $call) |
将连接交给回调。只归还本次新借的连接,返回回调值 |
currentConnection() |
当前 Connection 或 null |
recycleContext(): void |
归还当前协程全部连接,未结束数据库事务由池清理 |
preConnect() |
预热各连接池 |
reset() |
重置全部连接池和定时器 |
setOnQuery(callable $call) |
设置全局回调;返回管理器 |
configureQueryStack(bool $enabled, int $maxStackSize = 256): static |
每协程保留最近 N 条查询/获取连接事件;启停均应用容量,缩小时立即裁剪已有栈 |
getQueryStack(?int $index = null) |
整栈、单项或 null;事件类型由 type 区分 |
开发与测试
composer install composer test:unit
完整测试需要独立测试数据库,会建表、TRUNCATE 和写入数据。凭据从环境变量读取,不写入项目配置:
export FAST_DB_TEST_HOST=127.0.0.1 export FAST_DB_TEST_PORT=3306 export FAST_DB_TEST_USER=test export FAST_DB_TEST_DATABASE=test read -s FAST_DB_TEST_PASSWORD export FAST_DB_TEST_PASSWORD composer test:integration composer test
还可使用自定义 PHPUnit 选项:
php tests/run.php --filter TransactionTest --display-all-issues php tests/run.php --filter ScopeIntegrationTest --display-all-issues php tests/run.php --list-tests php tests/run.php --log-junit ./test-results.xml
tests/run.php 使用 PHPUnit 13 的 TextUI\Application 并在 Swoole 协程内执行测试,信息查询命令在协程外运行。单元与集成测试均使用协程入口,也可通过 composer test:unit 或 composer test:integration 执行。
配置位于 phpunit.xml.dist,分为 unit 与 integration。数据库用例结束后回收上下文、重置池并清理测试定时器。更多说明见 tests/README.md。
使用边界与常见问题
查询后不能反复复用同一套条件吗?
all()、更新/删除、聚合和关联查询会消费本次查询配置;没有变化而直接返回的 update() 也会清理一次性的限制。toArray() / jsonSerialize() 保留全部查询配置。建议每次数据库操作明确设置所需条件。
chunk() 与 chunkById() 应该怎么选?
只读遍历、需要保留自定义排序,且遍历期间筛选结果不会移动时,可以使用 chunk()。它按 OFFSET 分页;处理时会删除记录或修改筛选字段时,优先使用 chunkById()。深页的 OFFSET 还需要扫描并跳过前面的记录,而键集分页可以利用游标列索引从上次的位置继续。
例如有 id = 1..6 的六条记录,起初均为 status = 0,每次读取两条,并在回调中把状态更新为 1。chunk() 的查询过程是:
-- 首批返回 1、2,处理后这两条不再满足 status = 0。 SELECT * FROM users WHERE status = 0 ORDER BY id ASC LIMIT 0, 2; -- 现在待处理记录为 3、4、5、6;OFFSET 2 跳过 3、4,返回 5、6。 SELECT * FROM users WHERE status = 0 ORDER BY id ASC LIMIT 2, 2; -- 最后只剩 3、4,但 OFFSET 4 已无结果,遍历结束,3、4 被漏掉。 SELECT * FROM users WHERE status = 0 ORDER BY id ASC LIMIT 4, 2;
chunkById() 使用上一批末尾的游标,而不按当前结果集的位置跳过记录:
-- 首批返回 1、2。 SELECT * FROM users WHERE status = 0 ORDER BY id ASC LIMIT 2; -- 1、2 的状态改变后,仍从 id > 2 继续,返回 3、4。 SELECT * FROM users WHERE (status = 0) AND id > 2 ORDER BY id ASC LIMIT 2; -- 下一批返回 5、6。 SELECT * FROM users WHERE (status = 0) AND id > 4 ORDER BY id ASC LIMIT 2;
两者都逐条回调、只保留当前批次的数据,并保留实体或数组返回模式;回调返回严格的 false 都会提前停止,其他返回值或没有返回值时继续。chunk() 使用 OFFSET 分页,保留调用方排序,不返回累计条数;chunkById() 固定按稳定唯一列 ASC 键集分页,并返回已交付给回调的条数,包含触发停止的那一条。游标列应建立索引、保持唯一且非 NULL,遍历过程中不要修改该列;按其他非唯一列排序或对分组结果分块,应自行设计相应查询。
隐藏字段会不会改变数据库写入?
insert() / update() 使用 fields() 作为写入白名单;hideFields() 控制序列化输出,不会排除数据库写入字段。
查询少量字段后能直接把结果完整写回吗?
需要写入查询得到的实体时,应按原列名选入主键并保留该字段。查询结果缺少主键,例如省略、改名或隐藏主键时,实例写入会抛出异常。部分投影仍可读取。需要从外部提供已知主键时,可用 setData(['id' => $id], true) 显式建立基准。其他未加载字段能保留默认值,写入时用 fields() 指定范围。
关联查询是否自动走其他数据库?
不会。关联和普通实体一样使用当前选中的单例连接。目标表名可以覆盖,连接需要由调用方选择。
列表里逐一调用关系方法,怎样避免 N+1 查询?
在父查询上使用 queryLimit()->withRelations(['profile', 'orders'])。实体列表通过 getter 读取关系;父查询启用 returnAsArray() 时,会把关系数组附加到同名键。未启用 withRelations() 时,调用 getter 按需查询。
固定关系且每种关系不超过 250 个唯一父键时,通常从“1 条父查询 + 每个父对象的关联查询”变成“1 条父查询 + 每种关系 1 条批查询”。大列表会分批,动态条件不同的父对象按计划分组;不要把它理解为任何场景都只发一条关联 SQL。chunk() 和 chunkById() 会针对每个当前批次分别预加载。
父关联键必须被选中;实体模式不能隐藏该键,数组模式可以隐藏,但启用预加载后会临时构造父模型并应用显式配置。关系内的复杂分页、分组和统计由业务显式查询和组装,详见批量预加载章节。需要最新关联值时调用实体的 clearRelationCache()。
原始写入为什么没有执行钩子/转换?
fastInsertAll()、fastUpsert()、fastUpdate()、fastDelete()、QueryBuilder 与原始 SQL 是直接数据库操作。需要实体转换与钩子时通过实体 insert() / update() / delete();单实体重复键更新可使用 insert($updateDuplicateCols)。
批量写入报错后,能否直接重试整个输入?
fastInsertAll() / fastUpsert() 不提供自动重试或自动事务。后批校验或执行失败时,前批可能已落库;回调抛异常时,本批 SQL 也可能已经成功。先核实哪些批次已经写入,再按业务唯一键、幂等规则或显式事务处理;生成器也可能已经被部分消费。
返回的合计是数据库影响行数,不能用它推断处理到第几个输入行;upsert 的更新影响行数与插入不同。需要全部成功或全部回滚时,在调用前为实际写入连接开启事务,并由事务拥有者提交或回滚。
如何批量查询 UUID 主键?
可以使用 findAll(['id' => [['uuid-a', 'uuid-b'], 'IN']]),或在回调中调用 whereIn()。
事务中能使用 invoke() 吗?
可以。invoke() 复用当前连接时不会归还外层连接,嵌套调用也不会提前结束外层事务。手动事务仍由原调用方提交或回滚;使用 transaction() 时,只有入口原本没有事务的拥有层负责结束。重复 begin() 继续使用当前事务,后续 begin() 的 flags 不会重设事务。事务结束后再次 commit() 或 rollback() 直接返回 true。以上重复调用均不发送额外 SQL。同连接嵌套的 transaction() 加入当前事务。
withConnection 会自动提交或归还连接吗?
不会。它临时选库并在退出时恢复原连接名,不借还连接或管理事务。需要回调事务时,在其中调用 transaction();需要本层借用结束后归还连接时,使用 invoke()。withConnection() 和 transaction() 的回调参数是 FastDb,invoke() 的回调参数是 Connection。
transaction 返回 false,或捕获内层异常后,会提交吗?
false 是正常返回值,拥有层会提交并返回 false。同连接的加入层不单独提交或回滚;内层异常被外层捕获后,外层正常返回仍会提交全部已经执行的写入。需要整笔回滚时,让异常逃出拥有层,或由业务显式管理事务结束。
回滚后,为什么同一模型再 update() 没有写入?
模型在 SQL 成功时就接受了新的比较基准,数据库回滚不会恢复模型属性和基准。对象未发生新变化时,再次 update() 可能没有字段需要写入;请重新查询、重建对象,或按业务需要显式修改字段。之前 SQL 成功的更新返回值也不会因为后续回滚而改写。
transaction 抛异常,是否一定代表所有写入都没有提交?
不能这样推断。开始或业务回调异常会使拥有层尝试回滚,但业务手工提交、DDL 隐式提交、COMMIT 已成功后的日志异常,以及提交超时或断线,都可能留下已提交或结果不明的状态。提交阶段失败不会自动追加 ROLLBACK;B 独立事务已经提交的内容也不会被 A 的回滚撤销。请按业务记录核实数据库结果,再决定后续处理。
目前没有哪些功能?
当前实体没有 migration/schema builder、save()、软删除、自动时间戳、复合主键映射、savepoint 嵌套事务、自动读写分离。需要这些能力时通过应用封装或底层 SQL 明确实现。批量数据库格式写入使用 fastInsertAll() / fastUpsert(),不提供逐实体生命周期的批量保存;关联批量加载需要显式声明 withRelations(),不会自动开启。
许可证
本项目采用 Apache License 2.0,详见 LICENSE。