laravel-mongodb 问题排查与 Issue 上报指南：三层架构诊断法

在使用 laravel-mongodb（MongoDB 官方的 Laravel Eloquent 模型与查询构造器集成包，即 Moloquent 的官方接续项目）时，你遇到的报错可能来自多个不同的软件层：可能是包本身的 Eloquent 集成逻辑，可能是底层 PHP 查询库，也可能是 C 驱动与 PHP 扩展。本文围绕仓库中 support.md 的官方支持指南，系统讲解如何按"层"精准定位问题、判断该把 Issue 报到哪个仓库，以及如何撰写高质量的最小复现用例，帮助维护者快速确认问题范围并修复。

读完本文你将掌握：识别 MongoDB\Laravel\*、MongoDB\Driver\* 与 MongoDB\* 三类错误归属的判断方法；Issue 上报前的检索、上报流程与信息清单；以及如何用最小复现程序（minimal reproducer）加速问题闭环。

为什么先分层，再报 Issue

laravel-mongodb 不是单体的"魔盒"，而是一条清晰的分层调用链。从 composer.json 的依赖声明可以看出，包的运行依赖以下三层：

• Laravel 集成层（本包）：mongodb/laravel-mongodb，提供 Eloquent 模型、查询构造器、Schema、缓存、队列、事务等 Laravel 特有的行为，其 PSR-4 命名空间映射为 MongoDB\Laravel\ → src/。
• PHP 查询库（语言库）：mongodb/mongodb（要求 ^1.21.2|^2.1.1），提供 MongoDB\Client、MongoDB\Database、MongoDB\Collection、BSON 类型等高级 API，对应 MongoDB\*（非 Laravel）命名空间。
• C 驱动 + PHP 扩展：ext-mongodb（要求 ^1.21|^2），提供 MongoDB\Driver\* 底层类、连接管理与 libmongoc 能力。

从源码结构看，Connection 正是这三层的汇合点：src/Connection.php 同时引用了 MongoDB\Client、MongoDB\Collection、MongoDB\Database 以及 MongoDB\Driver\* 下的 ReadPreference、ClientEncryption 和各类驱动异常，并将 MongoDB\Driver\Exception\AuthenticationException、ConnectionException 等异常向上抛给 Laravel 层处理。这意味着同一个"连不上数据库"的现象，根因可能落在任何一层，而分层诊断能把范围从"整个技术栈"迅速缩小到"一个仓库"。

因此，官方支持文档（support.md）给出的核心纪律是：把 Issue 报到拥有"出问题的那个层"的仓库，而不是一律报给 laravel-mongodb。分层归属如下表：

层	出现什么问题时上报	归属仓库
Eloquent 集成、Laravel 特有行为	MongoDB\Laravel\* 类或 Eloquent 方法报错	mongodb/laravel-mongodb issues
PHP 查询 API、BSON、GridFS	MongoDB\*（不含 Laravel）类报错	mongodb/mongo-php-library issues
C 驱动、连接、PHP 扩展	MongoDB\Driver\* 或 ext-mongodb 报错	mongodb/mongo-php-driver issues
文档问题	文档页面内容有误或无法理解	在相关文档页用 Rate this page 标签提交反馈

动手之前：先检索，再上报

support.md 强调的第一条纪律是：打开 Issue 之前，先搜索现有 Issue 与 Pull Request——你要报告的 bug 可能已经被报告，甚至已经被修复。

具体做法：

1. 在对应仓库的 Issues 列表中搜索关键词，包括错误消息原文、涉及的类名/方法名、PHP/Laravel/扩展版本号。
2. 同步查看 Pull Requests，确认该问题是否已有修复在进行中（CONTRIBUTING.md 的提交规范也明确要求：提 Issue 前检查 pull requests 标签，确认 bug 没有正在进行中的修复）。
3. 如果找到匹配的既有 Issue，不要新开重复 Issue，而是在该 Issue 下补充评论，附上你自己的复现用例——这能帮助维护者确认问题影响范围（scope）并排定修复优先级。

这一"先检索"步骤既是社区礼仪，也直接关系到问题解决速度：重复 Issue 会稀释维护者精力，而带复现的补充评论则能推动既有 Issue 从"待确认"走向"已定位"。

分层诊断：从错误消息反推归属层

support.md 提供了一套极简的"症状 → 归属层"判别规则。结合本仓库源码，可以给出更精确的判别清单：

• MongoDB\Laravel\* 类或 Eloquent 方法报错 → 归属 laravel-mongodb。例如使用 App\Models\User::where(...)、withAggregate()、嵌入关系 EmbedsOne/EmbedsMany、缓存 MongoStore 等时抛出的异常，通常是本包的 Eloquent 集成问题。判断方法是看异常消息中是否出现 MongoDB\Laravel\ 命名空间前缀，或堆栈中是否有 src/ 下的类参与。
• MongoDB\Driver\* 或 ext-mongodb 报错 → 归属 mongo-php-driver。MongoDB\Driver\Exception\ConnectionException、AuthenticationException、BulkWriteException 等都来自扩展层。注意：本包源码中大量直接引用了这些驱动类，例如 src/Query/Builder.php 使用 MongoDB\Driver\Cursor 与 ReadPreference，src/Concerns/ManagesTransactions.php 使用 MongoDB\Driver\Session 与驱动级 RuntimeException，src/CommandSubscriber.php 使用 MongoDB\Driver\Monitoring\CommandStartedEvent 等监控事件——这些类的行为由驱动仓库决定，即使报错发生在调用链深处，归属仍是驱动层。
• MongoDB\*（不含 Laravel）类报错 → 归属 mongo-php-library。例如 MongoDB\Client、MongoDB\Database、MongoDB\Collection、BSON 类型与 GridFS 相关操作。从 src/Connection.php 可见，连接层的 Client/Database/Collection 均来自 MongoDB\* 命名空间；src/Cache/MongoStore.php、src/Bus/MongoBatchRepository.php 也直接使用 MongoDB\BSON\UTCDateTime、MongoDB\BSON\ObjectId 等类型。若异常消息中类名形如 MongoDB\Collection\... 或 MongoDB\BSON\...，且不带 Laravel，大概率是语言库层问题。
• 文档页内容不对 → 使用页面上的 Rate this page 标签提交反馈，而不是开 GitHub Issue。

一句话记忆：看异常类的命名空间前缀，Laravel 归包、Driver 归扩展、其余 MongoDB\* 归语言库、文档归文档反馈。

撰写高质量 Issue：最小复现 + 版本信息

确认归属层后，support.md 要求新 Issue 必须包含三要素：

1. 最小复现程序（minimal reproducer）：能复现 bug 的"最小可行代码"。理想形态是几十行以内、不依赖你业务私有数据的独立脚本或测试用例；如果是配置相关，给出完整的 config/database.php 连接配置片段（参考 resources/boost/skills/laravel-mongodb/references/installation.md 中的连接配置格式）。
2. PHP 与包版本：本包在 composer.json 中明确要求 php ^8.2、ext-mongodb ^1.21|^2、mongodb/mongodb ^1.21.2|^2.1.1，因此至少要报告：PHP 版本、ext-mongodb 版本、mongodb/laravel-mongodb 版本、mongodb/mongodb 版本、Laravel（illuminate/*）版本。版本组合直接决定行为，例如 src/Encryption/AutoEncryption.php 中引用了 ext-mongodb 2.4.0 或更高版本才支持的 keyAltName 引用加密字段特性——低版本扩展会直接抛错。
3. 错误消息或意外输出：贴出完整异常消息与堆栈（去掉敏感信息），或描述"期望行为 vs 实际行为"的差异。

如果已有 Issue 匹配，则把上述复现信息以评论形式追加，帮助维护者确认 scope 并优先处理。

一个可落地的排查流程

把 support.md 的方法论落到日常开发，可以归纳为如下五步：

1. 复现：确认问题可稳定复现，排除偶发或环境因素（CONTRIBUTING.md 同样建议先尝试复现，确保不是巧合事件）。
2. 检索：搜索对应仓库的 Issues 与 Pull Requests，判断是否已报告或已修复。
3. 分层：按本文"命名空间前缀"规则，把异常归属到 laravel-mongodb / mongo-php-library / mongo-php-driver / docs 四者之一。
4. 提炼：构造最小复现，收集 PHP 版本、扩展版本、包版本、Laravel 版本与完整错误消息。
5. 上报或补充：无既有 Issue 则新开，并填入三要素；有既有 Issue 则评论补充你的复现。

其中第 3 步是 laravel-mongodb 特有的关键动作——由于本包大量封装底层 API，同一个故障点在不同版本组合下可能表现为不同层的异常，养成"先看异常类前缀"的习惯，能让你少走弯路。

小结

• 报错先检索：搜索 Issues 与 Pull Requests，避免重复报告。
• 报错找对门：MongoDB\Laravel\* → laravel-mongodb；MongoDB\Driver\* / ext-mongodb → mongo-php-driver；MongoDB\*（无 Laravel）→ mongo-php-library；文档问题走 Rate this page 反馈。
• 复现三要素：最小复现程序 + PHP/包版本 + 错误消息或意外输出；已有匹配 Issue 时用评论补充，而非新开。

按这套分层诊断法操作，既能帮助维护者更快定位与修复，也能让你自己的问题更快得到解答。