Laravel MongoDB Eloquent 模型实战指南:从 `_id`、ObjectId 转换到加密字段的完整用法

原创2026-10-14 11:35:431,847 阅读
文章标签:后端数据库

Laravel MongoDB Eloquent 模型实战指南:从 _id、ObjectId 转换到加密字段的完整用法

本文围绕 laravel-mongodb 包的 Eloquent 模型层展开,讲解如何基于 MongoDB 编写文档模型:正确选择基类与 DocumentModel trait、理解 _id 与 id 的关系、为外键配置 ObjectId 转换、在非 MongoDB 基类上复用文档能力,以及使用 encrypted 转换实现字段加密。读完后,你将能独立设计、调试并产出可直接运行的 MongoDB 文档模型,并知道每个关键结论对应的源码位置。

一、为什么不能直接用标准 Eloquent 基类

MongoDB 的文档模型与 SQL 表模型有一个根本差异:标准 Eloquent 的 Illuminate\Database\Eloquent\Model 面向关系型数据库设计,不理解 BSON 类型(ObjectId、UTCDateTime、Binary、Decimal128 等)。因此,laravel-mongodb 包提供了一整套继承自 Laravel Eloquent 的模型实现,正确写法如下:

// WRONG — standard Eloquent does not understand MongoDB types
use Illuminate\Database\Eloquent\Model;

// CORRECT
use MongoDB\Laravel\Eloquent\Model;

MongoDB\Laravel\Eloquent\Model(src/Eloquent/Model.php)是一个抽象类,继承 Laravel 的 BaseModel 并 use DocumentModel trait。它在默认情况下已经做好了两件关键的事:

  • $keyType = 'string':主键类型默认为字符串。ObjectId 在 PHP 侧以字符串形式呈现,因此「字符串」是文档模型的主键默认形态。
  • 集成 HybridRelations 与 EmbedsRelations 两个 trait(见 src/Eloquent/DocumentModel.php),分别提供跨 MongoDB/SQL 连接的混合关系与内嵌文档关系能力。

一个最小可用的文档模型长这样:

<?php

namespace App\Models;

use MongoDB\Laravel\Eloquent\Model;

final class Movie extends Model
{
    protected $connection = 'mongodb';
    protected $table      = 'movies';   // $table not $collection
    protected $keyType    = 'string';   // ObjectId surfaced as string (already default)

    protected $fillable = ['title', 'year', 'released_at'];

    protected $casts = [
        'year'        => 'integer',
        'released_at' => 'datetime',
        // Do NOT cast native MongoDB arrays to 'array' — stored natively;
        // 'array' cast triggers deprecation and may serialize as JSON.
    ];
}

注意 $table 而非 $collection:为了贴合 Laravel 开发者习惯,包沿用 Eloquent 的 $table 属性来指定 MongoDB 集合名。keyType 即便不写也默认是 'string',写上便于显式表达意图。

集合名与属性声明的补充:#[Table] 属性

如果你使用 Laravel 13+,DocumentModel 还会读取 Illuminate\Database\Eloquent\Attributes\Table 属性来初始化模型属性。initializeModelAttributes() 会解析 keyType 并覆盖默认值(src/Eloquent/DocumentModel.php)。测试 tests/Eloquent/ModelAttributesTest.php 覆盖了 #[Table('custom_collection')] 设置集合名、主键、keyType 等场景,并验证「显式声明的 $keyType 属性优先于 #[Table] 属性」(testKeyTypePropertyTakesPrecedenceOverTableAttribute)。这意味着:属性声明是便捷写法,但传统属性仍是权威来源。

二、_id 与 id:一个字段,两种读法

BSON 层面,文档主键字段是 _id(默认 ObjectId,但 BSON 允许任意类型作为 _id)。包在 PHP 侧同时暴露 $model->id 和 $model->_id 两种访问方式,让模型用起来更接近 SQL 习惯。

这一行为的实现位于 src/Eloquent/DocumentModel.php 的 getIdAttribute():当 id 没有对应属性值时,回退到 _id 属性;如果值是 MongoDB\BSON\ObjectID 则转换为字符串,如果是 Binary 则取出二进制数据转字符串。因此在模型代码里,$model->id 与 $model->_id 是等价的:

public function toArray(Request $request): array
{
    return [
        'id'    => (string) $this->_id,  // or $this->id — equivalent
        'title' => $this->title,
    ];
}

为什么 API 资源里必须转字符串

在 toArray()(或 API Resource)中强制 (string) 转换非常关键:如果不转,_id 的 ObjectId 会被序列化成扩展 JSON 形态 {"$oid":"6708..."},而不是客户端期望的裸字符串 "6708..."。attributesToArray() 同样会在数组/JSON 输出时把 ObjectId 与 Binary 统一转为字符串(src/Eloquent/DocumentModel.php),与 SQL 模型输出标量的行为对齐。

主键写入时的智能转换

当给 id / _id 赋值一个恰好 24 位的十六进制字符串时,setAttribute() 会通过查询构造器的 convertKey() 把它转换为原生 ObjectID(src/Eloquent/DocumentModel.php、src/Query/Builder.php)。转换逻辑是:24 位且全部为十六进制字符 → ObjectID;16 位且含不可打印字符 → UUID Binary;其余原样保留。此外,convertKey() 内部的 assertKeyIsNotOperator() 会拒绝包含 $ 前缀键的数组作为主键,防止将 MongoDB 操作符注入文档主键(复合 _id 的普通数组仍被允许)。

三、外键与 ObjectId 转换:让 belongsTo() 稳定匹配

Eloquent 在关系匹配时会做类型强制转换(coercion),因此 belongsTo() 即使不写任何转换也能工作:$author->id 是字符串,$book->author_id 也以字符串形态参与匹配。这一点在测试中有直接体现:RelationsTest 中 Book::create(<a href="https://link.gitcode.com/i/e4e6b54db77293fb9bb8b492187116f5" target="_blank">'title' => ..., 'author_id' => $author->id]) 之后断言 $author->id === $book->author_id(见 [tests/RelationsTest.php)。

但当外键值可能来自模型属性之外(数据导入、直接拿到的原生 ObjectId)时,就需要显式声明转换,保证写入时 BSON 类型被归一化、where() 直接查询不会因类型不匹配而查不到数据:

protected $casts = [
    'author_id' => 'string',   // simplest: store/read as string for Eloquent matching

    // OR preserve native BSON ObjectId:
    // 'author_id' => MongoDB\Laravel\Eloquent\Casts\ObjectId::class,
    // (use the package cast, NOT \MongoDB\BSON\ObjectId::class)
];

两种策略各有取舍:

策略 $casts 声明 写入形态 适用场景
字符串归一化 'author_id' => 'string' 字符串 追求与 Eloquent 匹配逻辑一致、可读性好
原生 ObjectId 'author_id' => ObjectId::class BSON ObjectId 数据来自原生 ObjectId、需要保持 BSON 原貌

包级 ObjectId cast 的底层行为

MongoDB\Laravel\Eloquent\Casts\ObjectId(src/Eloquent/Casts/ObjectId.php)实现了 Laravel 的 CastsAttributes 接口:

  • get():如果底层值已是 MongoDB\BSON\ObjectId,转为字符串返回;
  • set():如果传入的不是 ObjectId,则 new BSONObjectId($value) 构造原生 ObjectId 落库。

文档特别强调:必须使用包的 cast(MongoDB\Laravel\Eloquent\Casts\ObjectId::class),而不是 \MongoDB\BSON\ObjectId::class——后者只是 BSON 类型类,并不实现 Eloquent 的 cast 契约,直接使用会报错或行为不符。

配套测试 tests/Casts/ObjectIdTest.php 验证了关键行为:

  • 用 ObjectId 或字符串保存,再用 ObjectId 查询都能命中(testStoreObjectId 两个用例);
  • 若字段以原生 ObjectId 落库,却用字符串去 firstWhere('oid', $stringObjectId) 查询,会查不到结果(testQueryByStringDoesNotCast)——这正是文档「防止 where() 直接查询失配」的由来。测试模型 tests/Models/CastObjectId.php 中 'oid' => ObjectId::class 即官方用法示范。

相关:UUID 主键的 BinaryUuid cast

同类场景还包括 MongoDB\Laravel\Eloquent\Casts\BinaryUuid(src/Eloquent/Casts/BinaryUuid.php):get() 将 UUID 二进制还原成标准连字符格式,set() 把字符串或 16 字节二进制包装成 Binary::TYPE_UUID。如果需要用 UUID 而非 ObjectId 做主键,可参照 tests/Models/IdIsBinaryUuid.php 与 tests/Casts/BinaryUuidTest.php 的用法。

四、扩展非 MongoDB 基类:用 DocumentModel trait 组合复用

如果你必须继承第三方包的基类(比如自定义的审计基类、多租户基类),无法改为继承 MongoDB\Laravel\Eloquent\Model,可以退而使用 DocumentModel trait——它承载了全部 MongoDB 文档模型能力:

<?php

namespace App\Models;

use MongoDB\Laravel\Eloquent\DocumentModel;
use Vendor\Package\BaseModel;

final class AuditLog extends BaseModel
{
    use DocumentModel;

    protected $connection = 'mongodb';
    protected $table      = 'audit_logs';
    protected $keyType    = 'string';
}

DocumentModel 聚合了 HybridRelations、EmbedsRelations、点号嵌套属性读写、_id 别名、$unset 字段删除、push/pull 数组操作、UTC 时间戳、ObjectID/Binary 序列化、加密字段保护等全部文档模型特性(src/Eloquent/DocumentModel.php)。测试 tests/Eloquent/ModelTest.php 中 Model::isDocumentModel() 的判定逻辑也印证了这一点:一个模型要成为「文档模型」,必须是 Laravel BaseModel 的子类 并且 使用 DocumentModel trait(匿名类 new class extends BaseModel { use DocumentModel; } 判为 true,而 new class extends BaseModel {} 判为 false)。仓库内置的认证模型 src/Auth/User.php 正是「继承 Illuminate\Foundation\Auth\User + use DocumentModel」的真实范例。

五、加密转换:encrypted 与应用级 vs 服务端加密

laravel-mongodb 直接兼容 Laravel 自带的 encrypted cast,用于把字段加密后写入 MongoDB:

protected $casts = [
    'ssn' => 'encrypted',   // Laravel encrypted cast; use Queryable Encryption for server-side equality
];

文档特别提醒:encrypted 是应用级加密(使用 Laravel Encrypter、APP_KEY),适用于「读取时才解密」的字段;如果需要在服务端按字段值做等值查询(如按身份证号查询),则应改用 MongoDB 的 Queryable Encryption,两者用途不同。

源码印证:加密在模型中如何流转

  • 加密转换的常规流转由 Laravel HasAttributes 完成;laravel-mongodb 在此基础上补充了 getRawOriginal() 可见的密文与 Json::decode 解密两种断言路径。测试 tests/Casts/EncryptionTest.php 对字符串、数组、对象、集合四种形态做了完整验证:写入后 getRawOriginal($key) 拿到的是密文,用 Encrypter::decryptString() 能还原明文,encrypted:array、encrypted:object、encrypted:collection 分别对应 Casting 测试模型的数组/对象/集合加密(tests/Models/Casting.php)。
  • 与 Queryable Encryption 的衔接由 src/Encryption/AutoEncryption.php 承担:当连接配置了 keyVaultNamespace 时启用加密(isEncryptionEnabled()),并禁止应用写入服务端托管字段 __safeContent__——setAttribute() 与 offsetUnset() 都会对 __safeContent__ 及其实点号子路径抛出 MassAssignmentException(src/Eloquent/DocumentModel.php),确保该字段只能由服务端维护。
  • 参考模型 tests/Models/EncryptedUser.php 展示了 Queryable Encryption 教程中的典型做法:加密字段在连接的 encryptedFieldsMap 中声明(name 随机化、email/phone 等值、date_of_birth 范围),模型里只保留 'password' => 'hashed' 这类常规转换,并 protected $hidden = ['password', 'remember_token'] 避免泄露。

六、常用 cast 与「数组」警告的进阶说明

文档模型对 Laravel 原生 cast 的适配是渐进的,以下几点在实操中值得注意:

  • 原生数组与 'array' cast 的冲突:MongoDB 原生存储数组,如果给数组字段加 'array' cast,会被序列化成 JSON 字符串而非 BSON 数组。DocumentModel::isJsonCastable() 检测到 array cast 时会触发 E_USER_DEPRECATED 弃用警告,提示移除 cast 以存储原生 BSON 数组,或显式改用 json cast(src/Eloquent/DocumentModel.php)。文档中 Movie 模型的注释即为此意。
  • 需要保 BSON 数组/文档形态时,可使用包提供的 AsBsonArray 与 AsBsonDocument:它们在读写时构造 BSONArray / BSONDocument,并在 dirty 比较时按 BSON 序列化归一化(compare()),可避免因对象包装差异导致的「误判为已修改」。
  • 日期与时间戳:freshTimestamp() 返回 UTCDateTime,fromDateTime() 把 DateTimeInterface 转为 UTCDateTime 落库,读取时 asDateTime() 将 UTCDateTime 还原为 Carbon 并转回应用时区(src/Eloquent/DocumentModel.php)。因此 'released_at' => 'datetime' 这类 cast 在 MongoDB 下语义与 SQL 一致,且支持 datetime:Y-m-d 自定义格式。
  • decimal 支持:'decimal:2' 这类 cast 在写入时会被转换为原生 MongoDB\BSON\Decimal128(fromDecimal(),见 src/Eloquent/DocumentModel.php),读取时还原为字符串,规避浮点精度问题。

七、模型中的文档特有操作与安全护栏

DocumentModel 还带来一批 SQL 模型没有的文档级操作,它们在编写模型代码时会经常用到:

  • unset($columns)(以及已弃用的 drop()):标记字段在下次 save() 时通过 $unset 从文档中移除。offsetUnset() 会记录到 $unset 列表,getDirty() 会把 <a href="https://link.gitcode.com/i/3bbbf9e4e6edde50c069b8ebc15aced4" target="_blank">'$unset' => [...]] 并入 dirty 数据([src/Eloquent/DocumentModel.php)。
  • push($column, $values, $unique) / pull($column, $values):直接对数组字段追加/移除元素,底层转化为查询构造器的 $push / $pull 操作(src/Eloquent/DocumentModel.php)。
  • 点号属性支持:setAttribute() 用临时键把 profile.name 这类点号键写入嵌套文档,getAttribute() 与 getAttributeFromArray() 也支持点号读取(src/Eloquent/DocumentModel.php)。测试模型 tests/Models/User.php 中 'entry.date' => 'datetime' 即为嵌套字段 cast 的官方示例。
  • 主键安全:assertKeyIsNotOperator() 拒绝 $ 前缀键数组作为 _id,从模型层杜绝 MQL 操作符注入主键(src/Query/Builder.php)。

八、快速落地:从连接配置到模型清单

要让上述模型真正跑起来,还需确认连接配置。包默认走 mongodb 连接,在 config/database.php 中注册(完整示例见 resources/boost/skills/laravel-mongodb/references/connection.md):

'connections' => [
    'mongodb' => [
        'driver'   => 'mongodb',
        'dsn'      => env('MONGODB_URI', 'mongodb://localhost:27017'),
        'database' => env('MONGODB_DATABASE', 'laravel'),
        'options'  => [
            'appName' => env('APP_NAME', 'laravel'),
        ],
    ],
],

.env 中对应:

DB_CONNECTION=mongodb
MONGODB_URI="mongodb+srv://user:pass@cluster0.mongodb.net/?retryWrites=true&w=majority"
MONGODB_DATABASE=laravel

服务提供者 MongoDB\Laravel\MongoDBServiceProvider 会通过包发现自动注册(需手动注册时写入 bootstrap/providers.php)。池大小、超时与 TLS 等参数统一放入连接 URI(如 serverSelectionTimeoutMS=5000&socketTimeoutMS=30000);注意 maxPoolSize/minPoolSize 对 PHP 扩展无效——libmongoc 在单线程模式下每个服务器最多持有一个 socket、无连接池(见 resources/boost/skills/laravel-mongodb/references/connection.md)。

小结

本文从五个核心实践点出发梳理了 laravel-mongodb 的 Eloquent 模型层:选用 MongoDB\Laravel\Eloquent\Model 基类、理解 _id/id 双别名与字符串序列化、用 string 或包级 ObjectId cast 稳定外键匹配、通过 DocumentModel trait 扩展现有基类、按需使用 encrypted 或 Queryable Encryption。配合 src/Eloquent/Model.php、src/Eloquent/DocumentModel.php、src/Eloquent/Casts/ObjectId.php 及 tests/Casts/ObjectIdTest.php、tests/Casts/EncryptionTest.php、tests/Eloquent/ModelTest.php 等源码与测试,你可以逐一验证每个行为,并按本文模板直接落地自己的 MongoDB 文档模型。

登录后查看全文
laravel-mongodb