feat: add findAndCount core implementation

Author: rockyshi1993

lib/mongodb/index.js

@@ -12,7 +12,8 @@ const {
     createFindOps,
     createFindOneOps,
     createFindOneByIdOps,  // findOneById 快捷方法
-    createFindByIdsOps,    // 新增：findByIds 快捷方法
+    createFindByIdsOps,    // findByIds 快捷方法
+    createFindAndCountOps, // 新增：findAndCount 快捷方法
     createCountOps,
     createAggregateOps,
     createDistinctOps,
@@ -228,7 +229,8 @@ module.exports = class {
             // 基础查询方法
             ...createFindOneOps(moduleContext),
             ...createFindOneByIdOps(moduleContext),  // findOneById 便利方法
-            ...createFindByIdsOps(moduleContext),    // 新增：findByIds 便利方法
+            ...createFindByIdsOps(moduleContext),    // findByIds 便利方法
+            ...createFindAndCountOps(moduleContext), // 新增：findAndCount 便利方法
             ...createFindOps(moduleContext),
             // 聚合与统计方法
             ...createCountOps(moduleContext),

lib/mongodb/queries/find-and-count.js

@@ -0,0 +1,174 @@
+/**
+ * findAndCount 查询操作模块
+ * @description 便利方法：同时返回数据和总数
+ */
+
+const { createError, ErrorCodes } = require('../../errors');
+
+/**
+ * 创建 findAndCount 操作
+ * @param {Object} context - 上下文对象
+ * @returns {Function} findAndCount 方法
+ */
+function createFindAndCountOps(context) {
+    const {
+        collection,
+        defaults,
+        instanceId,
+        effectiveDbName,
+        logger,
+        emit,
+        mongoSlowLogShaper,
+        cache,
+        type
+    } = context;
+
+    /**
+     * 查询数据并返回总数（同时执行）
+     * @param {Object} [query={}] - 查询条件
+     * @param {Object} [options={}] - 查询选项
+     * @param {Object} [options.projection] - 字段投影
+     * @param {Object} [options.sort] - 排序方式
+     * @param {number} [options.limit] - 限制返回数量
+     * @param {number} [options.skip] - 跳过数量
+     * @param {number} [options.cache] - 缓存时间（毫秒）
+     * @param {number} [options.maxTimeMS] - 查询超时（毫秒）
+     * @param {string} [options.comment] - 查询注释
+     * @returns {Promise<Object>} { data, total }
+     *
+     * @example
+     * // 基础用法
+     * const { data, total } = await collection('users').findAndCount(
+     *   { status: 'active' },
+     *   { limit: 10, skip: 0 }
+     * );
+     *
+     * @example
+     * // 分页查询
+     * const page = 1;
+     * const pageSize = 20;
+     * const { data, total } = await collection('users').findAndCount(
+     *   { role: 'user' },
+     *   { limit: pageSize, skip: (page - 1) * pageSize }
+     * );
+     * const totalPages = Math.ceil(total / pageSize);
+     */
+    const findAndCount = async function findAndCount(query = {}, options = {}) {
+        const startTime = Date.now();
+
+        // 1. 参数验证
+        if (query !== null && typeof query !== 'object' || Array.isArray(query)) {
+            throw createError(
+                ErrorCodes.INVALID_ARGUMENT,
+                'query 必须是对象',
+                [{ field: 'query', type: 'type', message: 'query 必须是对象', received: typeof query }]
+            );
+        }
+
+        // 2. 提取选项
+        const projection = options.projection;
+        const sort = options.sort;
+        const limit = options.limit !== undefined ? options.limit : defaults.findLimit;
+        const skip = options.skip || 0;
+        const cacheTime = options.cache !== undefined ? options.cache : defaults.cache;
+        const maxTimeMS = options.maxTimeMS !== undefined ? options.maxTimeMS : defaults.maxTimeMS;
+        const comment = options.comment;
+
+        // 3. 缓存键（包含 query, projection, sort, limit, skip）
+        const cacheKey = cache ? `${instanceId}:${type}:${effectiveDbName}:${collection.collectionName}:findAndCount:${JSON.stringify({ query, projection, sort, limit, skip })}` : null;
+
+        // 4. 检查缓存
+        if (cache && cacheTime > 0) {
+            try {
+                const cached = await cache.get(cacheKey);
+                if (cached !== null) {
+                    logger?.debug?.('[findAndCount] 缓存命中', {
+                        ns: `${effectiveDbName}.${collection.collectionName}`,
+                        query: query
+                    });
+                    return cached;
+                }
+            } catch (cacheError) {
+                logger?.warn?.('[findAndCount] 缓存读取失败', { error: cacheError.message });
+            }
+        }
+
+        // 5. 构建查询选项
+        const findOptions = { maxTimeMS };
+        if (projection) findOptions.projection = projection;
+        if (sort) findOptions.sort = sort;
+        if (limit !== undefined && limit !== null) findOptions.limit = limit;
+        if (skip) findOptions.skip = skip;
+        if (comment) findOptions.comment = comment;
+
+        const countOptions = { maxTimeMS };
+        if (comment) countOptions.comment = comment;
+
+        // 6. 并行执行查询和计数
+        let data, total;
+        try {
+            [data, total] = await Promise.all([
+                collection.find(query, findOptions).toArray(),
+                collection.countDocuments(query, countOptions)
+            ]);
+        } catch (error) {
+            throw error;
+        }
+
+        // 7. 构建结果
+        const result = { data, total };
+
+        // 8. 写入缓存
+        if (cache && cacheTime > 0) {
+            try {
+                await cache.set(cacheKey, result, cacheTime);
+            } catch (cacheError) {
+                logger?.warn?.('[findAndCount] 缓存写入失败', { error: cacheError.message });
+            }
+        }
+
+        // 9. 慢查询日志
+        const duration = Date.now() - startTime;
+        const slowQueryMs = defaults?.slowQueryMs || 1000;
+
+        if (duration >= slowQueryMs) {
+            try {
+                const meta = {
+                    operation: 'findAndCount',
+                    durationMs: duration,
+                    iid: instanceId,
+                    type: type,
+                    db: effectiveDbName,
+                    collection: collection.collectionName,
+                    dataCount: data.length,
+                    total: total,
+                    query: mongoSlowLogShaper?.sanitize ? mongoSlowLogShaper.sanitize(query) : query,
+                    projection: projection,
+                    sort: sort,
+                    limit: limit,
+                    skip: skip,
+                    comment: comment
+                };
+                logger?.warn?.('🐌 Slow query: findAndCount', meta);
+                emit?.('slow-query', meta);
+            } catch (_) {
+                // 忽略日志错误
+            }
+        }
+
+        // 10. 日志记录
+        logger?.debug?.('[findAndCount] 查询完成', {
+            ns: `${effectiveDbName}.${collection.collectionName}`,
+            duration: duration,
+            dataCount: data.length,
+            total: total
+        });
+
+        return result;
+    };
+
+    return { findAndCount };
+}
+
+module.exports = { createFindAndCountOps };
+

lib/mongodb/queries/index.js

@@ -35,12 +35,13 @@ function createFindPageOps(context) {
 module.exports = {
     createFindOps: require('./find'),
     createFindOneOps: require('./find-one'),
-    createFindOneByIdOps: require('./find-one-by-id').createFindOneByIdOps,  // ✅ findOneById 便利方法
-    createFindByIdsOps: require('./find-by-ids').createFindByIdsOps,  // ✅ 新增：findByIds 便利方法
+    createFindOneByIdOps: require('./find-one-by-id').createFindOneByIdOps,  // findOneById 便利方法
+    createFindByIdsOps: require('./find-by-ids').createFindByIdsOps,  // findByIds 便利方法
+    createFindAndCountOps: require('./find-and-count').createFindAndCountOps,  // 新增：findAndCount 便利方法
     createCountOps: require('./count'),
     createAggregateOps: require('./aggregate'),
     createDistinctOps: require('./distinct'),
-    createFindPageOps,  // ✅ 新增工厂函数
+    createFindPageOps,  // 新增工厂函数
     // 导出原始函数和辅助函数供 bookmark 模块使用
     createFindPage,
     bookmarkKey,