Hyperf 的数据库模型基于自研 Model 组件，非 Laravel Eloquent 复刻但设计相似，支持表映射、CRUD、关系定义，并深度集成协程与连接池；提供命令行生成模型、依赖注入使用、软删除、类型转换、预加载及事务等能力。
Hyperf 的数据库模型基于其自研的 Model 组件，不是 Laravel Eloquent 的直接复刻，但设计哲学高度相似：每个模型类对应一张数据表，封装数据操作逻辑，支持查询、新增、更新、删除及关系定义。它深度集成协程与连接池，能安全运行在 Swoole 协程环境下[^2]。
模型创建：用命令行一键生成
Hyperf 提供了内置命令快速生成模型类，自动完成命名空间、表名映射、主键配置等基础设置：
- 执行命令（如为
b_order表生成模型）：php bin/hyperf.php gen:model BOrder - 默认生成路径为
app/Model/BOrder.php - 生成后会自动设置表名（
b_order）、主键（id）、时间戳字段（created_at/updated_at），并启用软删除（若表含deleted_at字段） - 若需指定数据库连接或禁用时间戳，可加参数：
php bin/hyperf.php gen:model BOrder --connection=master --without-timestamps
模型基础用法：查增改删（CRUD）
模型实例化不依赖 new，推荐通过静态方法调用，所有操作天然支持协程调度：
-
查询单条：
BOrder::find(123)或BOrder::where('order_id', 1)->first() -
查询多条：
BOrder::where('status', 'paid')->get()返回Collection对象 -
新增记录：
(new BOrder())->fill(['order_id' => 'ORD2026001', 'amount' => 99.9])->save()，或更简洁地BOrder::create(['order_id' => 'ORD2026001', 'amount' => 99.9]) -
更新记录：
BOrder::where('id', 1)->update(['status' => 'shipped'])（批量）；或先查后改：$order = BOrder::find(1); $order->status = 'done'; $order->save(); -
删除记录：
BOrder::destroy(1)（物理删除）；BOrder::where('id', 1)->delete()（软删除，若启用）
在控制器中使用模型：依赖注入 + 注解
Hyperf 推荐通过构造函数依赖注入模型，由容器自动解析和管理生命周期，避免手动 new 或静态调用带来的协程上下文风险[^4]：
- 在控制器中声明私有属性并注入：
use App\Model\BOrder;
#[Controller]
class OrderController
{
public function __construct(
private BOrder $bOrder
) {}
#[GetMapping("/order/{id}")]
public function show(int $id)
{
return $this->bOrder->find($id) ?? ['message' => 'not found'];
}
}
```
- 注意：注入的模型实例是“原型作用域”，每次请求新建，无需担心状态污染
- 若需跨方法复用查询条件，可配合局部作用域（Local Scopes）或查询构建器链式调用
常用模型函数与技巧
除基础 CRUD 外，以下方法高频实用：
-
toArray()/jsonSerialize()：转数组或 JSON 兼容格式，适合 API 返回 -
casts属性：声明字段类型转换，如protected $casts = ['amount' => 'float', 'is_paid' => 'boolean']; -
fillable或guarded：控制批量赋值白名单/黑名单，防 mass assignment 漏洞 -
with()：预加载关联数据（需先定义hasMany、belongsTo等关系方法） -
transaction()：模型级事务封装，BOrder::transaction(fn() => { /* 业务逻辑 */ });
