当前位置：首页 > 文章列表 > 文章 > php教程 > Hyperf模型定义及使用教程详解

Hyperf模型定义及使用教程详解

2026-03-28 21:36:48 0浏览收藏

本文深入解析了 Hyperf 框架中自研 Model 组件的核心用法与最佳实践——它虽非 Laravel Eloquent 的简单复刻，却在表映射、CRUD 操作、关系定义等关键体验上高度相似，更凭借原生协程支持、连接池集成、命令行一键建模、依赖注入安全使用、软删除、字段类型转换、关联预加载及事务封装等能力，为高性能 Swoole 应用提供了兼具简洁性与可靠性的数据库操作方案，是构建现代 PHP 微服务不可或缺的利器。

Hyperf数据库模型怎么定义_Hyperf模型创建和使用方法【操作】

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]：

在控制器中声明私有属性并注入：

```php
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() => { /* 业务逻辑 */ });