Hyperf新手模型操作入门_HyperfCRUD基础指南【技巧】

hyperf 是基于 swoole 的高性能协程 php 框架，其模型操作需继承 hyperfdatabasemodelmodel，配置表名、连接、主键；crud 遵循 eloquent 规范但注意协程安全；事务须在同协程内完成；推荐使用 casts、显式 select、paginate 及语义化方法命名。

Hyperf 是基于 Swoole 的高性能协程 PHP 框架，模型（Model）操作是日常开发中最基础也最频繁的部分。刚上手时容易卡在连接配置、查询写法、事务处理等细节上。掌握核心 CRUD 流程 + 少量关键技巧，就能快速写出稳定、可读、符合 Hyperf 风格的数据库代码。

模型定义与数据库连接对齐

Hyperf 使用 eloquent 作为默认 ORM（通过 hyperf/database 组件），模型需继承 HyperfDatabaseModelModel。注意两点：

• 模型类名默认对应表名（驼峰转下划线），如 UserProfile → user_profile；若不一致，需显式设置 protected $table = 'my_users';
• 确保 config/autoload/databases.php 中已正确配置 default 连接，并在模型中指定连接名（如多库场景）：protected $connection = 'mysql';
• 主键默认为 id，若为其他字段（如 uid），需声明：protected $primaryKey = 'uid';

增删改查（CRUD）写法要点

Hyperf 的 Eloquent 写法和 laravel 高度一致，但要注意协程环境下的调用方式：

• 查（Read）：支持链式查询，推荐使用 where + firstOrFail() 或 get()；避免直接用 find(1)（它会走主键缓存，且不触发事件）
• 增（Create）：用 create() 前确保模型设置了 $fillable 白名单，或用 new Model([...])->save() 手动赋值
• 改（Update）：推荐先 find() 或 where()->first() 获取模型实例再调用 save()；批量更新用 where()->update([...])（不触发模型事件和访问器）
• 删（delete）：软删除需开启 use SoftDeletes; 并设置 $dates = ['deleted_at'];；硬删除直接 delete()，软删除后记录仍可通过 withTrashed() 查出

事务与协程安全写法

在协程中执行数据库事务，必须确保整个事务块在同一个协程上下文内完成，否则可能跨协程导致连接错乱：

• 不要在事务中 await 其他协程 IO（如 http 请求、redis 调用），除非你明确控制了上下文
• 标准事务写法：DB::transaction(function () { ... });，内部所有模型操作自动绑定同一连接
• 手动事务（需 try/catch）：DB::beginTransaction(); → 操作 → DB::commit(); 或 DB::rollback();
• 注意：模型事件（creating, saving 等）在事务中正常触发，可用于数据校验或关联写入

常用技巧与避坑提醒

这些小细节常被忽略，却直接影响代码健壮性：

• 模型中定义 casts 属性，让 json、datetime、Boolean 字段自动转换：protected $casts = ['options' => 'Array', 'is_active' => 'boolean'];
• 使用 select(['id', 'name']) 显式指定字段，避免 SELECT * 在表结构变更时引发意外
• 分页统一用 paginate(15)，它自动处理偏移、总数和游标逻辑，返回 Hyperf 标准分页响应结构
• 模型方法命名建议用语义化动词，如 scopeActive()（作用域）、toSimpleArray()（自定义导出），避免和内置方法冲突