PHP操作MongoDB要注意啥

本文目录导读：

1. 架构与驱动选择（最重要）
2. 连接与配置
3. 数据类型与BSON转换（易踩坑）
4. 查询与操作符（避免性能灾难）
5. 写入与索引（核心性能）
6. 事务与错误处理
7. 内存与性能优化
8. 安全（易忽略）
9. 总结清单（自查表）

在PHP中操作MongoDB，尤其是使用官方mongodb扩展（而非已废弃的mongo扩展）时，有几个关键的注意事项，这些点直接关系到代码的稳定性、性能和数据安全。

以下是核心注意事项,按优先级排序：

架构与驱动选择（最重要）

• 禁用旧驱动：绝对不要使用 mongo 扩展（PHP 5.x时代），它已被官方废弃且存在严重安全漏洞，必须使用 mongodb 扩展 + mongodb/mongodb 库（Composer 包）。
• 版本匹配：你的 mongodb 扩展版本需与PHP版本兼容（如PHP 8.2需使用1.15+），并且客户端库（mongodb/mongodb）版本需与扩展版本匹配。

连接与配置

• 使用连接字符串：建议在配置文件中使用 MongoDB URI（如 mongodb://user:pass@host:27017/?authSource=admin）,便于切换环境和多服务器。
• 禁用危险选项：
  • 生产环境务必设置 retryWrites=true 和 retryReads=true（MongoDB 4.2+ 默认开启，建议显式声明）。
  • 关闭 allow_invalid_hostname（仅限本地测试）。
• 合理设置最大连接数：通过 maxPoolSize 控制连接池,避免高并发下连接数爆炸。

数据类型与BSON转换（易踩坑）

PHP和MongoDB的BSON类型存在映射差异,需特别注意：

• 数字类型：
  • PHP的 int 默认映射为 32位整数，而MongoDB默认是64位，如果你的ID或计数器超过20亿，必须显式使用 new \MongoDB\BSON\Int64($value) 强制转换,否则会溢出。
  • 浮点数建议使用 double，但注意精度（MongoDB的 Decimal128 类型需要 \MongoDB\BSON\Decimal128 类处理，不能直接用PHP浮点）。
• 日期时间：
  • PHP的 DateTime 对象不能直接插入，需转换为 \MongoDB\BSON\UTCDateTime，注意：UTCDateTime 保存的是毫秒级时间戳，不是秒，读取时需 ->toDateTime() 转回。
• 空字符串与NULL：MongoDB中 null 和空字符串是两回事,需确认业务逻辑是否区分。
• ObjectId：
  • 主键 _id 默认是 ObjectId，查询时若用字符串匹配 _id 必须 new \MongoDB\BSON\ObjectId($id),否则查不到数据。
  • 注意时区陷阱：ObjectId 中内置了时间戳，但如果服务器时钟不同步,可能导致排序问题。

查询与操作符（避免性能灾难）

• 使用MongoDB查询语言：PHP驱动支持 $in，$gt，$regex 等，但注意 $regex 必须配合索引使用,否则全表扫描。
• 投影（Projection）：查询时务必使用 ['projection' => ['field' => 1]] 限制返回字段,避免把几MB的文档拖回PHP内存。
• 不要使用 findOneAndUpdate 返回旧数据：默认返回更新前的文档，若需返回更新后的，需设置 'returnDocument' => \MongoDB\Operation\FindOneAndUpdate::RETURN_AFTER。

写入与索引（核心性能）

• 批量写入：循环内单条插入（insertOne）非常慢，务必使用 bulkWrite 或 insertMany（建议每批500-1000条）。
• 索引优先级：
  • 在插入/BulkWrite大量数据时，先删除不需要的索引，插完再重建,否则会拖慢写入速度。
  • 对于读写比例高的集合，必须为高频查询字段（如 status，user_id）建立复合索引，否则MongoDB会警告“COLLSCAN”。
• 避免使用 $lookup 太多：虽然聚合管道强大，但$lookup相当于SQL JOIN，若关联集合大且无索引,会非常慢。

事务与错误处理

• 事务限制：MongoDB 4.0+ 支持多文档事务，但只能用于副本集或分片集群（单机 mongod 不支持）,且事务内不能使用DDL操作。
• 异常捕获：
  • 使用 try...catch 捕获 MongoDB\Driver\Exception\ 相关异常（如 BulkWriteException，ConnectionTimeoutException）。
  • 注意：BulkWriteException 会附带 getWriteResult()，里面包含成功和失败的详细计数，不要只打印 getMessage()。
• 重复插入：处理 duplicate key error（错误码11000）时，必须先检查是否已存在，或捕获后判断错误码,避免将HTTP状态码直接设为500。

内存与性能优化

• 流式读取：当查询返回大量数据（如百万级）时，不要用 toArray() 一次性加载到内存（会OOM），应使用 Cursor 配合 foreach 迭代读取。
• 限制文档大小：MongoDB单文档有 16MB 限制，存储长文本或二进制文件（如头像、文件）时，应使用 GridFS 或存储在外部，数据库只存路径/引用。

安全（易忽略）

• 权限最小化：不要使用 root 账号连接应用服务器，创建专门账号，仅授予所需数据库的 readWrite 权限。
• 避免注入：PHP驱动是防止SQL注入的，但如果你在PHP中拼接查询条件字符串（['name' => $userInput]），MongoDB默认是安全的，但如果你使用了 $where 或 $function 执行JavaScript，则存在注入风险，务必禁用 allowDiskUse 和此类操作。
• SSL/TLS：生产环境连接字符串必须使用 mongodb+srv:// 并开启 TLS,防止中间人攻击。

总结清单（自查表）

• [ ] 是否使用了 mongodb/mongodb 库（Composer）？
• [ ] 是否将所有 _id 字符串转换为 ObjectId？
• [ ] 是否将 DateTime 转换为 UTCDateTime？
• [ ] 写入时是否使用了 bulkWrite 而非循环 insertOne？
• [ ] 查询是否加了 projection 限制字段？
• [ ] 是否为大查询字段创建了索引？
• [ ] 是否捕获了 BulkWriteException 并检查错误码？
• [ ] 生产环境是否禁用 allow_invalid_hostname？

特别提醒：PHP 8.0及以后版本中，类型声明（Type Declarations）更严格，int 类型不会自动转成 Int64，必须显式处理大整数，否则数据会丢失,这是导致数据错误的常见原因。