midway-fatcms 0.0.3 → 0.0.4

package/dist/middleware/rediscache.middleware.js

@@ -1,114 +1,114 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.redisCache = void 0;
-const redis_1 = require("@midwayjs/redis");
-const _ = require("lodash");
-const md5 = require("md5");
-const RedisKeys_1 = require("../models/RedisKeys");
-const exceptions_1 = require("../libs/crud-pro/exceptions");
-const getRedisService = async (ctx) => {
-    const service = await ctx.requestContext.getAsync(redis_1.RedisService);
-    if (!service) {
-        return await ctx.requestContext.getAsync('redisService');
-    }
-    return service;
-};
-const createError = () => {
-    return new exceptions_1.CommonException('redis_cache_middleware_error_config', 'redisCache中间件的第一个参数必须是一个字符串数组, 并且以“query.”或“body.”开头');
-};
-const checkCacheKeyConfigList = (cacheKeyConfigList) => {
-    if (!Array.isArray(cacheKeyConfigList)) {
-        throw createError();
-    }
-    for (let i = 0; i < cacheKeyConfigList.length; i++) {
-        const cacheKeyConfig = cacheKeyConfigList[i];
-        if (typeof cacheKeyConfig !== 'string') {
-            throw createError();
-        }
-        if (!cacheKeyConfig.startsWith('query.') && !cacheKeyConfig.startsWith('body.')) {
-            throw createError();
-        }
-    }
-};
-// {middleware:[redisCache(['query.id'， 'body.id'])]}
-const toCacheKey = (ctx, cacheKeyConfigList) => {
-    checkCacheKeyConfigList(cacheKeyConfigList);
-    const path = ctx.path;
-    const query = ctx.query || {};
-    const body = ctx.request.body || {};
-    const newCtx = { path, query, body };
-    // 至少要根据path缓存
-    const cacheKeyConfigList2 = ['path', ...cacheKeyConfigList];
-    const strArray = cacheKeyConfigList2.map((key) => {
-        const value = _.get(newCtx, key);
-        return { key, value };
-    });
-    const strArrayStr = JSON.stringify(strArray);
-    const strMd5 = md5(strArrayStr);
-    return RedisKeys_1.RedisKeys.REDIS_LOCK_MIDDILEWARE + strMd5;
-};
-function toCacheDataString(resData) {
-    return JSON.stringify(resData);
-}
-function parseCacheData(cacheData) {
-    try {
-        return JSON.parse(cacheData);
-    }
-    catch (e) {
-        return null;
-    }
-}
-/**
- * Redis缓存中间件
- *
- * 应用场景：
- * 1. 高频查询接口：用户列表、商品详情等读多写少的接口
- * 2. 计算密集型接口：统计报表、数据聚合等耗时计算结果
- * 3. 外部API调用：第三方接口响应数据缓存，减少调用次数和费用
- * 4. 数据库压力缓解：热点数据缓存，降低数据库查询压力
- *
- * 使用示例：
- * ```typescript
- * @Get('/product-detail', { middleware: [redisCache(['query.productId'], 300)] }) // 商品详情缓存5分钟
- * async getProductDetail(@Query() query: any) {
- *   // 业务逻辑：查询商品详情
- * }
- *
- * @Post('/report', { middleware: [redisCache(['body.dateRange', 'body.type'], 1800)] }) // 报表数据缓存30分钟
- * async generateReport(@Body() body: any) {
- *   // 业务逻辑：生成统计报表
- * }
- * ```
- *
- * @param cacheKeyConfigList 缓存键配置，如 ['query.id', 'body.type']
- * @param cacheTimeSecond 缓存时长（秒），默认60秒，范围1-3600秒
- */
-function redisCache(cacheKeyConfigList, cacheTimeSecond) {
-    return async (ctx, next) => {
-        const redisService = await getRedisService(ctx);
-        // 生成唯一缓存键（基于path + 指定参数）
-        const cacheKey = toCacheKey(ctx, cacheKeyConfigList);
-        let cacheTime = typeof cacheTimeSecond === 'number' ? cacheTimeSecond : 60; // 默认缓存1分钟
-        cacheTime = Math.max(cacheTime, 1); // 至少缓存1秒
-        cacheTime = Math.min(cacheTime, 60 * 60); // 最长缓存1小时
-        // 尝试从缓存获取数据
-        const cacheData = await redisService.get(cacheKey);
-        if (cacheData) {
-            // 命中缓存，直接返回
-            return parseCacheData(cacheData);
-        }
-        // 缓存未命中，执行业务逻辑
-        try {
-            const resData = await next();
-            const resDataStr = toCacheDataString(resData);
-            // 将结果写入缓存
-            await redisService.set(cacheKey, resDataStr, 'EX', cacheTime);
-            return resData;
-        }
-        catch (e) {
-            console.error('redisCache', e);
-            throw e; // 重新抛出异常，让上层处理
-        }
-    };
-}
-exports.redisCache = redisCache;
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.redisCache = void 0;
+const redis_1 = require("@midwayjs/redis");
+const _ = require("lodash");
+const md5 = require("md5");
+const RedisKeys_1 = require("../models/RedisKeys");
+const exceptions_1 = require("../libs/crud-pro/exceptions");
+const getRedisService = async (ctx) => {
+    const service = await ctx.requestContext.getAsync(redis_1.RedisService);
+    if (!service) {
+        return await ctx.requestContext.getAsync('redisService');
+    }
+    return service;
+};
+const createError = () => {
+    return new exceptions_1.CommonException('redis_cache_middleware_error_config', 'redisCache中间件的第一个参数必须是一个字符串数组, 并且以“query.”或“body.”开头');
+};
+const checkCacheKeyConfigList = (cacheKeyConfigList) => {
+    if (!Array.isArray(cacheKeyConfigList)) {
+        throw createError();
+    }
+    for (let i = 0; i < cacheKeyConfigList.length; i++) {
+        const cacheKeyConfig = cacheKeyConfigList[i];
+        if (typeof cacheKeyConfig !== 'string') {
+            throw createError();
+        }
+        if (!cacheKeyConfig.startsWith('query.') && !cacheKeyConfig.startsWith('body.')) {
+            throw createError();
+        }
+    }
+};
+// {middleware:[redisCache(['query.id'， 'body.id'])]}
+const toCacheKey = (ctx, cacheKeyConfigList) => {
+    checkCacheKeyConfigList(cacheKeyConfigList);
+    const path = ctx.path;
+    const query = ctx.query || {};
+    const body = ctx.request.body || {};
+    const newCtx = { path, query, body };
+    // 至少要根据path缓存
+    const cacheKeyConfigList2 = ['path', ...cacheKeyConfigList];
+    const strArray = cacheKeyConfigList2.map((key) => {
+        const value = _.get(newCtx, key);
+        return { key, value };
+    });
+    const strArrayStr = JSON.stringify(strArray);
+    const strMd5 = md5(strArrayStr);
+    return RedisKeys_1.RedisKeys.REDIS_LOCK_MIDDILEWARE + strMd5;
+};
+function toCacheDataString(resData) {
+    return JSON.stringify(resData);
+}
+function parseCacheData(cacheData) {
+    try {
+        return JSON.parse(cacheData);
+    }
+    catch (e) {
+        return null;
+    }
+}
+/**
+ * Redis缓存中间件
+ *
+ * 应用场景：
+ * 1. 高频查询接口：用户列表、商品详情等读多写少的接口
+ * 2. 计算密集型接口：统计报表、数据聚合等耗时计算结果
+ * 3. 外部API调用：第三方接口响应数据缓存，减少调用次数和费用
+ * 4. 数据库压力缓解：热点数据缓存，降低数据库查询压力
+ *
+ * 使用示例：
+ * ```typescript
+ * @Get('/product-detail', { middleware: [redisCache(['query.productId'], 300)] }) // 商品详情缓存5分钟
+ * async getProductDetail(@Query() query: any) {
+ *   // 业务逻辑：查询商品详情
+ * }
+ *
+ * @Post('/report', { middleware: [redisCache(['body.dateRange', 'body.type'], 1800)] }) // 报表数据缓存30分钟
+ * async generateReport(@Body() body: any) {
+ *   // 业务逻辑：生成统计报表
+ * }
+ * ```
+ *
+ * @param cacheKeyConfigList 缓存键配置，如 ['query.id', 'body.type']
+ * @param cacheTimeSecond 缓存时长（秒），默认60秒，范围1-3600秒
+ */
+function redisCache(cacheKeyConfigList, cacheTimeSecond) {
+    return async (ctx, next) => {
+        const redisService = await getRedisService(ctx);
+        // 生成唯一缓存键（基于path + 指定参数）
+        const cacheKey = toCacheKey(ctx, cacheKeyConfigList);
+        let cacheTime = typeof cacheTimeSecond === 'number' ? cacheTimeSecond : 60; // 默认缓存1分钟
+        cacheTime = Math.max(cacheTime, 1); // 至少缓存1秒
+        cacheTime = Math.min(cacheTime, 60 * 60); // 最长缓存1小时
+        // 尝试从缓存获取数据
+        const cacheData = await redisService.get(cacheKey);
+        if (cacheData) {
+            // 命中缓存，直接返回
+            return parseCacheData(cacheData);
+        }
+        // 缓存未命中，执行业务逻辑
+        try {
+            const resData = await next();
+            const resDataStr = toCacheDataString(resData);
+            // 将结果写入缓存
+            await redisService.set(cacheKey, resDataStr, 'EX', cacheTime);
+            return resData;
+        }
+        catch (e) {
+            console.error('redisCache', e);
+            throw e; // 重新抛出异常，让上层处理
+        }
+    };
+}
+exports.redisCache = redisCache;

package/dist/middleware/redislock.middleware.d.ts

@@ -1,29 +1,29 @@
-import { Context, NextFunction } from '@midwayjs/koa';
-/**
- * Redis分布式锁中间件
- *
- * 应用场景：
- * 1. 防止重复提交：用户短时间内多次点击提交按钮
- * 2. 防止并发冲突：同一用户同时发起多个相同请求
- * 3. 资源竞争保护：多个请求同时操作同一资源（如订单、库存）
- * 4. 导出任务控制：防止用户重复触发耗时的导出任务
- *
- * 使用示例：
- * ```typescript
- * @Post('/submit-order', { middleware: [redisLock(['body.orderId'], 30)] })  // 根据orderId锁定30秒
- * async submitOrder(@Body() body: any) {
- *   // 业务逻辑：处理订单
- * }
- *
- *
- * @Post('/createApp', { middleware: [redisLock(['query.userId'], 60)] }) // 根据userId锁定60秒
- * async exportData(@Query() query: any) {
- *   // 业务逻辑：导出数据
- * }
- * ```
- *
- * @param lockKeyConfigList 锁定的键配置，如 ['query.id', 'body.userId']
- * @param maxLockTimeSecond 锁定时长（秒），默认60秒，范围1-300秒
- */
-declare function redisLock(lockKeyConfigList: string[], maxLockTimeSecond?: number): (ctx: Context, next: NextFunction) => Promise<any>;
-export { redisLock };
+import { Context, NextFunction } from '@midwayjs/koa';
+/**
+ * Redis分布式锁中间件
+ *
+ * 应用场景：
+ * 1. 防止重复提交：用户短时间内多次点击提交按钮
+ * 2. 防止并发冲突：同一用户同时发起多个相同请求
+ * 3. 资源竞争保护：多个请求同时操作同一资源（如订单、库存）
+ * 4. 导出任务控制：防止用户重复触发耗时的导出任务
+ *
+ * 使用示例：
+ * ```typescript
+ * @Post('/submit-order', { middleware: [redisLock(['body.orderId'], 30)] })  // 根据orderId锁定30秒
+ * async submitOrder(@Body() body: any) {
+ *   // 业务逻辑：处理订单
+ * }
+ *
+ *
+ * @Post('/createApp', { middleware: [redisLock(['query.userId'], 60)] }) // 根据userId锁定60秒
+ * async exportData(@Query() query: any) {
+ *   // 业务逻辑：导出数据
+ * }
+ * ```
+ *
+ * @param lockKeyConfigList 锁定的键配置，如 ['query.id', 'body.userId']
+ * @param maxLockTimeSecond 锁定时长（秒），默认60秒，范围1-300秒
+ */
+declare function redisLock(lockKeyConfigList: string[], maxLockTimeSecond?: number): (ctx: Context, next: NextFunction) => Promise<any>;
+export { redisLock };

package/dist/middleware/redislock.middleware.js

@@ -1,106 +1,106 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.redisLock = void 0;
-const redis_1 = require("@midwayjs/redis");
-const _ = require("lodash");
-const md5 = require("md5");
-const RedisKeys_1 = require("../models/RedisKeys");
-const exceptions_1 = require("../libs/crud-pro/exceptions");
-const getRedisService = async (ctx) => {
-    const service = await ctx.requestContext.getAsync(redis_1.RedisService);
-    if (!service) {
-        return await ctx.requestContext.getAsync('redisService');
-    }
-    return service;
-};
-const createError = () => {
-    return new exceptions_1.CommonException('redis_lock_middleware_error_config', 'redisLock中间件的第一个参数必须是一个字符串数组, 并且以“query.”或“body.”开头');
-};
-const checkLockKeyConfigList = (lockKeyConfigList) => {
-    if (!Array.isArray(lockKeyConfigList)) {
-        throw createError();
-    }
-    for (let i = 0; i < lockKeyConfigList.length; i++) {
-        const lockKeyConfig = lockKeyConfigList[i];
-        if (typeof lockKeyConfig !== 'string') {
-            throw createError();
-        }
-        if (!lockKeyConfig.startsWith('query.') && !lockKeyConfig.startsWith('body.')) {
-            throw createError();
-        }
-    }
-};
-// {middleware:[redisLock(['query.id'， 'body.id'])]}
-const toLockKey = (ctx, lockKeyConfigList) => {
-    checkLockKeyConfigList(lockKeyConfigList);
-    const path = ctx.path;
-    const query = ctx.query || {};
-    const body = ctx.request.body || {};
-    const newCtx = { path, query, body };
-    // 至少要根据path锁
-    const lockKeyConfigList2 = ['path', ...lockKeyConfigList];
-    const strArray = lockKeyConfigList2.map((key) => {
-        const value = _.get(newCtx, key);
-        return { key, value };
-    });
-    const strArrayStr = JSON.stringify(strArray);
-    const strMd5 = md5(strArrayStr);
-    return RedisKeys_1.RedisKeys.REDIS_LOCK_MIDDILEWARE + strMd5;
-};
-/**
- * Redis分布式锁中间件
- *
- * 应用场景：
- * 1. 防止重复提交：用户短时间内多次点击提交按钮
- * 2. 防止并发冲突：同一用户同时发起多个相同请求
- * 3. 资源竞争保护：多个请求同时操作同一资源（如订单、库存）
- * 4. 导出任务控制：防止用户重复触发耗时的导出任务
- *
- * 使用示例：
- * ```typescript
- * @Post('/submit-order', { middleware: [redisLock(['body.orderId'], 30)] })  // 根据orderId锁定30秒
- * async submitOrder(@Body() body: any) {
- *   // 业务逻辑：处理订单
- * }
- *
- *
- * @Post('/createApp', { middleware: [redisLock(['query.userId'], 60)] }) // 根据userId锁定60秒
- * async exportData(@Query() query: any) {
- *   // 业务逻辑：导出数据
- * }
- * ```
- *
- * @param lockKeyConfigList 锁定的键配置，如 ['query.id', 'body.userId']
- * @param maxLockTimeSecond 锁定时长（秒），默认60秒，范围1-300秒
- */
-function redisLock(lockKeyConfigList, maxLockTimeSecond) {
-    return async (ctx, next) => {
-        const redisService = await getRedisService(ctx);
-        // 生成唯一锁键（基于path + 指定参数）
-        const lockKey = toLockKey(ctx, lockKeyConfigList);
-        let lockTime = typeof maxLockTimeSecond === 'number' ? maxLockTimeSecond : 60; // 默认锁住1分钟（失败的情况）
-        lockTime = Math.max(lockTime, 1); // 至少锁一秒 （失败的情况）
-        lockTime = Math.min(lockTime, 5 * 60); // 最长锁 5分钟（失败的情况）
-        // 尝试获取锁（SET key value EX seconds NX）
-        // NX：只在键不存在时设置，实现互斥
-        // EX：设置过期时间，防止死锁
-        const lock = await redisService.set(lockKey, 1, 'EX', lockTime, 'NX');
-        if (lock !== 'OK') {
-            // 获取锁失败，说明有其他请求正在处理
-            return {
-                success: false,
-                message: '您请求的接口当前正在处理中，请稍后再试',
-                code: 'redis_lock_middleware_error_locked',
-            };
-        }
-        // 执行业务逻辑
-        try {
-            return await next();
-        }
-        finally {
-            // 无论成功失败，业务逻辑执行完毕，都立即释放锁
-            await redisService.del(lockKey);
-        }
-    };
-}
-exports.redisLock = redisLock;
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.redisLock = void 0;
+const redis_1 = require("@midwayjs/redis");
+const _ = require("lodash");
+const md5 = require("md5");
+const RedisKeys_1 = require("../models/RedisKeys");
+const exceptions_1 = require("../libs/crud-pro/exceptions");
+const getRedisService = async (ctx) => {
+    const service = await ctx.requestContext.getAsync(redis_1.RedisService);
+    if (!service) {
+        return await ctx.requestContext.getAsync('redisService');
+    }
+    return service;
+};
+const createError = () => {
+    return new exceptions_1.CommonException('redis_lock_middleware_error_config', 'redisLock中间件的第一个参数必须是一个字符串数组, 并且以“query.”或“body.”开头');
+};
+const checkLockKeyConfigList = (lockKeyConfigList) => {
+    if (!Array.isArray(lockKeyConfigList)) {
+        throw createError();
+    }
+    for (let i = 0; i < lockKeyConfigList.length; i++) {
+        const lockKeyConfig = lockKeyConfigList[i];
+        if (typeof lockKeyConfig !== 'string') {
+            throw createError();
+        }
+        if (!lockKeyConfig.startsWith('query.') && !lockKeyConfig.startsWith('body.')) {
+            throw createError();
+        }
+    }
+};
+// {middleware:[redisLock(['query.id'， 'body.id'])]}
+const toLockKey = (ctx, lockKeyConfigList) => {
+    checkLockKeyConfigList(lockKeyConfigList);
+    const path = ctx.path;
+    const query = ctx.query || {};
+    const body = ctx.request.body || {};
+    const newCtx = { path, query, body };
+    // 至少要根据path锁
+    const lockKeyConfigList2 = ['path', ...lockKeyConfigList];
+    const strArray = lockKeyConfigList2.map((key) => {
+        const value = _.get(newCtx, key);
+        return { key, value };
+    });
+    const strArrayStr = JSON.stringify(strArray);
+    const strMd5 = md5(strArrayStr);
+    return RedisKeys_1.RedisKeys.REDIS_LOCK_MIDDILEWARE + strMd5;
+};
+/**
+ * Redis分布式锁中间件
+ *
+ * 应用场景：
+ * 1. 防止重复提交：用户短时间内多次点击提交按钮
+ * 2. 防止并发冲突：同一用户同时发起多个相同请求
+ * 3. 资源竞争保护：多个请求同时操作同一资源（如订单、库存）
+ * 4. 导出任务控制：防止用户重复触发耗时的导出任务
+ *
+ * 使用示例：
+ * ```typescript
+ * @Post('/submit-order', { middleware: [redisLock(['body.orderId'], 30)] })  // 根据orderId锁定30秒
+ * async submitOrder(@Body() body: any) {
+ *   // 业务逻辑：处理订单
+ * }
+ *
+ *
+ * @Post('/createApp', { middleware: [redisLock(['query.userId'], 60)] }) // 根据userId锁定60秒
+ * async exportData(@Query() query: any) {
+ *   // 业务逻辑：导出数据
+ * }
+ * ```
+ *
+ * @param lockKeyConfigList 锁定的键配置，如 ['query.id', 'body.userId']
+ * @param maxLockTimeSecond 锁定时长（秒），默认60秒，范围1-300秒
+ */
+function redisLock(lockKeyConfigList, maxLockTimeSecond) {
+    return async (ctx, next) => {
+        const redisService = await getRedisService(ctx);
+        // 生成唯一锁键（基于path + 指定参数）
+        const lockKey = toLockKey(ctx, lockKeyConfigList);
+        let lockTime = typeof maxLockTimeSecond === 'number' ? maxLockTimeSecond : 60; // 默认锁住1分钟（失败的情况）
+        lockTime = Math.max(lockTime, 1); // 至少锁一秒 （失败的情况）
+        lockTime = Math.min(lockTime, 5 * 60); // 最长锁 5分钟（失败的情况）
+        // 尝试获取锁（SET key value EX seconds NX）
+        // NX：只在键不存在时设置，实现互斥
+        // EX：设置过期时间，防止死锁
+        const lock = await redisService.set(lockKey, 1, 'EX', lockTime, 'NX');
+        if (lock !== 'OK') {
+            // 获取锁失败，说明有其他请求正在处理
+            return {
+                success: false,
+                message: '您请求的接口当前正在处理中，请稍后再试',
+                code: 'redis_lock_middleware_error_locked',
+            };
+        }
+        // 执行业务逻辑
+        try {
+            return await next();
+        }
+        finally {
+            // 无论成功失败，业务逻辑执行完毕，都立即释放锁
+            await redisService.del(lockKey);
+        }
+    };
+}
+exports.redisLock = redisLock;

package/dist/middleware/tx.middleware.d.ts

@@ -1,55 +1,55 @@
-import { NextFunction, Context } from '@midwayjs/koa';
-/**
- * 事务中间件 - 数据库事务自动管理
- *
- * 核心职责：
- * 1. 自动开启事务：请求开始时自动调用 beginTx() 开启数据库事务
- * 2. 自动提交事务：请求成功完成后自动调用 commitTx() 提交所有变更
- * 3. 自动回滚事务：请求异常时自动调用 rollbackTx() 回滚所有变更
- * 4. 自动释放连接：无论成功或失败都调用 releaseTx() 释放数据库连接
- *
- * 应用场景：
- * 1. 订单处理：创建订单 + 扣减库存 + 生成物流单，任一步骤失败全部回滚
- * 2. 资金转账：扣款账户减少 + 收款账户增加，保证两步同时成功或同时失败
- * 3. 批量操作：导入100条数据，要么全部成功，要么全部不导入（避免脏数据）
- * 4. 状态关联更新：更新订单状态 + 更新用户积分 + 更新商品销量，保证数据一致性
- * 5. 工作流审批：审批通过 + 更新流程状态 + 发送通知，确保流程完整性
- *
- * 使用方式：
- * 在 Controller 方法的 middleware 配置中使用：
- *
- * @example
- * ```typescript
- * import { Controller, Post, Inject } from '@midwayjs/core';
- * import { startTransaction } from '../middleware/tx.middleware';
- *
- * @Controller('/api/order')
- * export class OrderController {
- *   @Inject()
- *   orderService: OrderService;
- *
- *   @Post('/create', { middleware: [startTransaction()] })  // 在路由配置中使用
- *   async createOrder(@Body() dto: CreateOrderDto) {
- *     // 1. 创建订单记录
- *     const order = await this.orderService.create(dto);
- *
- *     // 2. 扣减商品库存
- *     await this.productService.decreaseStock(dto.productId, dto.quantity);
- *
- *     // 3. 生成支付单
- *     await this.paymentService.createPayment(order.id, dto.amount);
- *
- *     // 如果任何一步失败，以上所有操作都会自动回滚
- *     return order;
- *   }
- * }
- * ```
- *
- * 注意事项：
- * - 事务中的所有数据库操作必须使用同一个 ctx.transaction 实例
- * - 避免在事务中执行长时间操作（如HTTP请求、文件IO），会长时间占用数据库连接
- * - 事务嵌套需要特别注意，确保内层事务与外层事务共享同一连接
- * - 异常会被捕获、记录日志并重新抛出，由全局中间件统一处理
- */
-declare function startTransaction(): (ctx: Context, next: NextFunction) => Promise<any>;
-export { startTransaction };
+import { NextFunction, Context } from '@midwayjs/koa';
+/**
+ * 事务中间件 - 数据库事务自动管理
+ *
+ * 核心职责：
+ * 1. 自动开启事务：请求开始时自动调用 beginTx() 开启数据库事务
+ * 2. 自动提交事务：请求成功完成后自动调用 commitTx() 提交所有变更
+ * 3. 自动回滚事务：请求异常时自动调用 rollbackTx() 回滚所有变更
+ * 4. 自动释放连接：无论成功或失败都调用 releaseTx() 释放数据库连接
+ *
+ * 应用场景：
+ * 1. 订单处理：创建订单 + 扣减库存 + 生成物流单，任一步骤失败全部回滚
+ * 2. 资金转账：扣款账户减少 + 收款账户增加，保证两步同时成功或同时失败
+ * 3. 批量操作：导入100条数据，要么全部成功，要么全部不导入（避免脏数据）
+ * 4. 状态关联更新：更新订单状态 + 更新用户积分 + 更新商品销量，保证数据一致性
+ * 5. 工作流审批：审批通过 + 更新流程状态 + 发送通知，确保流程完整性
+ *
+ * 使用方式：
+ * 在 Controller 方法的 middleware 配置中使用：
+ *
+ * @example
+ * ```typescript
+ * import { Controller, Post, Inject } from '@midwayjs/core';
+ * import { startTransaction } from '../middleware/tx.middleware';
+ *
+ * @Controller('/api/order')
+ * export class OrderController {
+ *   @Inject()
+ *   orderService: OrderService;
+ *
+ *   @Post('/create', { middleware: [startTransaction()] })  // 在路由配置中使用
+ *   async createOrder(@Body() dto: CreateOrderDto) {
+ *     // 1. 创建订单记录
+ *     const order = await this.orderService.create(dto);
+ *
+ *     // 2. 扣减商品库存
+ *     await this.productService.decreaseStock(dto.productId, dto.quantity);
+ *
+ *     // 3. 生成支付单
+ *     await this.paymentService.createPayment(order.id, dto.amount);
+ *
+ *     // 如果任何一步失败，以上所有操作都会自动回滚
+ *     return order;
+ *   }
+ * }
+ * ```
+ *
+ * 注意事项：
+ * - 事务中的所有数据库操作必须使用同一个 ctx.transaction 实例
+ * - 避免在事务中执行长时间操作（如HTTP请求、文件IO），会长时间占用数据库连接
+ * - 事务嵌套需要特别注意，确保内层事务与外层事务共享同一连接
+ * - 异常会被捕获、记录日志并重新抛出，由全局中间件统一处理
+ */
+declare function startTransaction(): (ctx: Context, next: NextFunction) => Promise<any>;
+export { startTransaction };