hyperf 是基于 swoole 的高性能协程 php 框架，其模型操作需继承 hyperf\database\model\model，配置表名、连接、主键；crud 遵循 eloquent 规范但注意协程安全；事务须在同协程内完成；推荐使用 casts、显式 select、paginate 及语义化方法命名。
Hyperf 是基于 Swoole 的高性能协程 PHP 框架，模型（Model）操作是日常开发中最基础也最频繁的部分。刚上手时容易卡在连接配置、查询写法、事务处理等细节上。掌握核心 CRUD 流程 + 少量关键技巧，就能快速写出稳定、可读、符合 Hyperf 风格的数据库代码。
模型定义与数据库连接对齐
Hyperf 使用 eloquent 作为默认 ORM（通过 hyperf/database 组件），模型需继承 Hyperf\Database\Model\Model。注意两点：
- 模型类名默认对应表名（驼峰转下划线），如
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()（自定义导出），避免和内置方法冲突
