feat:大规模重构兼容原生写法

Author: rockyshi1993

CHANGELOG.md

@@ -4,6 +4,86 @@
 
 ## [未发布]
 
+### Changed
+- **explain 示例和测试更新**（2025-11-12）
+  - `examples/explain.examples.js`：所有示例从旧版 `explain({ query, verbosity })` 改为原生风格 `find(filter, { explain })`
+  - 示例 1-5 全部更新为使用 options 参数的方式
+  - 保持与 MongoDB 原生 API 完全一致的调用风格
+
+- **explain 链式调用支持**（2025-11-12）
+  - ✨ 新增链式调用支持：
+    - `collection.find({ ... }).explain('executionStats')`
+    - `collection.aggregate([...]).explain('executionStats')`
+  - 完全兼容原生 MongoDB 的链式调用语法
+  - 通过在 Promise 上添加 explain() 方法实现
+  - 同时保留 options 参数方式：
+    - `find(filter, { explain: 'executionStats' })`
+    - `aggregate(pipeline, { explain: 'executionStats' })`
+  - ❌ 删除独立 explain 方法：`collection.explain({ query, verbosity })`（API 与原生不一致）
+  - 现在只支持两种方式：链式调用和 options 参数，都与原生 MongoDB 兼容
+  - 更新所有测试用例，使用新的 API
+
+- **explain 文档重构**（2025-11-12）
+  - 明确使用原生 MongoDB `Cursor.explain()` 方法
+  - 支持两种调用方式：链式调用和 options 参数
+  - 新增与原生 MongoDB 的对比：实现原理和使用示例
+  - 新增聚合管道的 explain 示例：管道分析、优化建议、阶段性能对比
+  - 新增常见问题章节：verbosity 选择、性能影响、执行计划解读、索引问题诊断、聚合管道优化
+
+- **distinct 文档重构**（2025-11-12）  - 明确使用原生 MongoDB `Collection.distinct()` 方法
+  - 扩展 options 参数：新增 `session`（事务支持）、`comment`（查询注释）、`collation`（排序规则）等原生选项
+  - 新增使用模式：事务中的 distinct 查询（第 9 节）
+  - 新增使用建议章节：何时使用 distinct、性能考虑、缓存策略
+  - 优化常见问题：新增 Q1（monSQLize 与原生 MongoDB 的区别）、Q7（事务使用）
+  - 扩展最佳实践：从 7 条增加到 10 条，包含索引优化、缓存策略、事务使用等
+
+- **estimated-count 文档重构**（2025-11-12）
+  - 明确使用原生 MongoDB `estimatedDocumentCount()` 方法
+  - 扩展 options 参数：新增 `maxTimeMS`（超时控制）、`comment`（查询注释）等原生选项
+  - 新增性能对比章节：estimatedDocumentCount vs countDocuments vs count（性能差异对比）
+  - 新增使用建议章节：何时使用 estimatedDocumentCount、性能考虑
+  - 优化最佳实践：从简单列表扩展为详细说明，包含具体代码示例
+
+- **count 文档重构**（2025-11-12）
+  - 明确使用原生 MongoDB `countDocuments()` 方法
+  - 扩展 options 参数：新增 `skip`、`session`、`hint`、`comment` 等原生选项
+  - 新增使用模式：事务中的 count 查询、使用 hint 指定索引
+  - 优化最佳实践：添加具体代码示例和场景说明
+
+- **distinct 方法 API 重构**（2025-11-11）
+  - 方法签名变更：从 `distinct(field, options)` 改为 `distinct(field, query, options)`，将 query 参数独立出来
+  - 新增参数支持：`comment`（查询注释，用于日志和性能分析）
+  - 与 MongoDB 原生 API 保持一致：使用原生 `collection.distinct(field, query, options)` 方法
+  - 更新文档：`docs/distinct.md` - 反映新的 API 格式和参数说明
+  - 更新示例：`examples/distinct.examples.js` - 所有 10 个示例迁移到新 API
+  - ⚠️ **破坏性变更**：不兼容旧版本 `distinct('field', { query: {...} })` 格式，需修改为 `distinct('field', query, options)`
+
+- **count 方法 API 重构**（2025-11-11）
+  - 使用 MongoDB 原生推荐的 API：`countDocuments()` 和 `estimatedDocumentCount()`
+  - 方法签名变更：从 `count(options)` 改为 `count(query, options)`，将 query 参数独立出来
+  - 新增参数支持：`skip`、`limit`（用于分页统计和抽样统计）
+  - 性能优化：空查询自动使用 `estimatedDocumentCount()`（基于元数据，毫秒级）
+  - 更新文档：`docs/count.md` - 反映新的 API 格式和参数说明
+  - 更新示例：`examples/count.examples.js` - 所有示例迁移到新 API
+  - 创建迁移指南：`docs/count-migration-guide.md` - 帮助用户从旧版本迁移
+  - ⚠️ **破坏性变更**：不兼容旧版本 `count({ query: {...} })` 格式，需按迁移指南修改代码
+
+- **find 和 findOne 方法 API 重构**（2025-11-12）
+  - 方法签名变更：从 `find(options)` / `findOne(options)` 改为 `find(query, options)` / `findOne(query, options)`，将 query 参数独立出来
+  - 与 MongoDB 原生 API 保持一致：使用原生 `collection.find(query, options)` / `collection.findOne(query, options)` 方法
+  - 更新文档：
+    - `docs/find.md` - 反映新的 API 格式和参数说明（29 个代码示例全部更新）
+    - `docs/findOne.md` - 反映新的 API 格式和参数说明（15 个代码示例全部更新）
+    - `README.md` - 更新所有代码示例（13 个示例）
+  - 更新示例：
+    - `examples/find.examples.js` - 所有 10 个示例迁移到新 API
+    - `examples/findOne.examples.js` - 所有 7 个示例迁移到新 API
+  - 更新 TypeScript 定义：
+    - `index.d.ts` - 更新方法签名和接口定义
+    - 移除 `FindOptions.query` 字段
+    - 所有方法签名（find/findOne/count/distinct/stream/explain）改为两参数形式
+  - ⚠️ **破坏性变更**：不兼容旧版本 `find({ query: {...} })` 格式，需修改为 `find(query, options)`
+
 ### 新增
 - **insertOne 和 insertMany 写操作文档补充**（2025-11-10）
   - README.md：添加"写入操作"表格和详细使用示例（第 8 节）

README.md

@@ -46,27 +46,33 @@ const MonSQLize = require('monsqlize');
   }).connect();
 
   // 查询单个文档
-  const one = await collection('test').findOne({
-    query: { status: 'active' },
-    cache: 5000,            // 缓存 5 秒
-    maxTimeMS: 1500         // 覆盖全局超时
-  });
+  const one = await collection('test').findOne(
+    { status: 'active' },
+    {
+      cache: 5000,            // 缓存 5 秒
+      maxTimeMS: 1500         // 覆盖全局超时
+    }
+  );
   console.log('findOne ->', one);
 
   // 查询多个文档
-  const list = await collection('test').find({
-    query: { category: 'electronics' },
-    limit: 10,              // 限制 10 条
-    cache: 3000             // 缓存 3 秒
-  });
+  const list = await collection('test').find(
+    { category: 'electronics' },
+    {
+      limit: 10,              // 限制 10 条
+      cache: 3000             // 缓存 3 秒
+    }
+  );
   console.log('find ->', list.length);
 
   // 跨库访问
-  const event = await db('analytics').collection('events').findOne({
-    query: { type: 'click' },
-    cache: 3000,
-    maxTimeMS: 1500
-  });
+  const event = await db('analytics').collection('events').findOne(
+    { type: 'click' },
+    {
+      cache: 3000,
+      maxTimeMS: 1500
+    }
+  );
   console.log('跨库查询 ->', event);
 })();
 ```
@@ -138,22 +144,26 @@ const MonSQLize = require('monsqlize');
 
 ```js
 // 数组模式（默认）
-const products = await collection('products').find({
-  query: { category: 'electronics', inStock: true },
-  projection: { name: 1, price: 1 },
-  sort: { price: -1 },
-  limit: 20,
-  cache: 5000,
-  comment: 'ProductAPI:listProducts:user_123'  // 生产环境日志跟踪（可选）
-});
+const products = await collection('products').find(
+  { category: 'electronics', inStock: true },
+  {
+    projection: { name: 1, price: 1 },
+    sort: { price: -1 },
+    limit: 20,
+    cache: 5000,
+    comment: 'ProductAPI:listProducts:user_123'  // 生产环境日志跟踪（可选）
+  }
+);
 
 // 流式传输（大数据量）
-const stream = await collection('products').find({
-  query: { category: 'electronics' },
-  stream: true,              // 返回流
-  cache: 0,                  // 禁用缓存
-  comment: 'ExportService:streamProducts'      // 标识查询来源
-});
+const stream = await collection('products').find(
+  { category: 'electronics' },
+  {
+    stream: true,              // 返回流
+    cache: 0,                  // 禁用缓存
+    comment: 'ExportService:streamProducts'      // 标识查询来源
+  }
+);
 
 stream.on('data', (doc) => {
   console.log('处理文档:', doc);
@@ -172,34 +182,40 @@ stream.on('end', () => {
 
 ```js
 // 游标分页（推荐）
-const page1 = await collection('products').findPage({
-  query: { category: 'electronics' },
-  limit: 20,
-  sort: { createdAt: -1 },
-  bookmarks: {
-    step: 10,                // 每 10 页缓存一个书签
-    maxHops: 20,             // 最多跳跃 20 次
-    ttlMs: 3600000           // 书签缓存 1 小时
+const page1 = await collection('products').findPage(
+  { category: 'electronics' },
+  {
+    limit: 20,
+    sort: { createdAt: -1 },
+    bookmarks: {
+      step: 10,                // 每 10 页缓存一个书签
+      maxHops: 20,             // 最多跳跃 20 次
+      ttlMs: 3600000           // 书签缓存 1 小时
+    }
   }
-});
+);
 
 console.log('第 1 页:', page1.data);
 console.log('下一页游标:', page1.cursor);
 
 // 使用游标获取下一页
-const page2 = await collection('products').findPage({
-  query: { category: 'electronics' },
-  limit: 20,
-  cursor: page1.cursor       // 传入上一页的游标
-});
+const page2 = await collection('products').findPage(
+  { category: 'electronics' },
+  {
+    limit: 20,
+    cursor: page1.cursor       // 传入上一页的游标
+  }
+);
 
 // 跳页模式（跳到第 100 页）
-const page100 = await collection('products').findPage({
-  query: { category: 'electronics' },
-  limit: 20,
-  page: 100,                 // 跳到第 100 页
-  bookmarks: { step: 10, maxHops: 20, ttlMs: 3600000 }
-});
+const page100 = await collection('products').findPage(
+  { category: 'electronics' },
+  {
+    limit: 20,
+    page: 100,                 // 跳到第 100 页
+    bookmarks: { step: 10, maxHops: 20, ttlMs: 3600000 }
+  }
+);
 ```
 
 **详细文档**: [docs/findPage.md](./docs/findPage.md)
@@ -248,11 +264,13 @@ const msq = new MonSQLize({
 });
 
 // 查询级缓存
-const products = await collection('products').find({
-  query: { category: 'electronics' },
-  cache: 5000,               // 缓存 5 秒
-  maxTimeMS: 3000
-});
+const products = await collection('products').find(
+  { category: 'electronics' },
+  {
+    cache: 5000,               // 缓存 5 秒
+    maxTimeMS: 3000
+  }
+);
 
 // 获取缓存统计
 const stats = msq.getCacheStats();
@@ -284,10 +302,12 @@ const msq = new MonSQLize({
 const { db, collection } = await msq.connect();
 
 // 跨库访问
-const analyticsEvent = await db('analytics').collection('events').findOne({
-  query: { type: 'click' },
-  cache: 3000
-});
+const analyticsEvent = await db('analytics').collection('events').findOne(
+  { type: 'click' },
+  {
+    cache: 3000
+  }
+);
 
 // 关闭连接
 await msq.close();
@@ -314,9 +334,9 @@ await msq.connect();
 const { collection } = msq;
 
 // 所有查询自动从从节点读取（降低主节点负载）
-const products = await collection('products').find({
-  query: { category: 'electronics' }
-});
+const products = await collection('products').find(
+  { category: 'electronics' }
+);
 
 console.log(`✅ 从从节点读取 ${products.length} 条数据`);
 ```
@@ -436,18 +456,22 @@ const msq = new MonSQLize({
 const { collection } = await msq.connect();
 
 // 第 1 次查询：缓存 miss → 查询 MongoDB → 存入本地 + Redis
-const products1 = await collection('products').find({
-  query: { category: 'electronics' },
-  cache: 10000,                           // 缓存 10 秒
-  maxTimeMS: 3000
-});
+const products1 = await collection('products').find(
+  { category: 'electronics' },
+  {
+    cache: 10000,                           // 缓存 10 秒
+    maxTimeMS: 3000
+  }
+);
 
 // 第 2 次查询：本地缓存命中（0.001ms）
-const products2 = await collection('products').find({
-  query: { category: 'electronics' },
-  cache: 10000,
-  maxTimeMS: 3000
-});
+const products2 = await collection('products').find(
+  { category: 'electronics' },
+  {
+    cache: 10000,
+    maxTimeMS: 3000
+  }
+);
 
 // 如果本地缓存过期，但 Redis 还有 → 从 Redis 读取（1-2ms）并回填本地
 ```