@maiyunnet/kebab 9.14.0 → 9.14.2

package/index.d.ts

@@ -5,7 +5,7 @@
  * --- 本文件用来定义每个目录实体地址的常量 ---
  */
 /** --- 当前系统版本号 --- */
-export declare const VER = "9.14.0";
+export declare const VER = "9.14.2";
 /** --- 框架根目录，以 / 结尾  --- */
 export declare const ROOT_PATH: string;
 /** --- 框架的 LIB，以 / 结尾 --- */

package/index.js

@@ -6,7 +6,7 @@
  * --- 本文件用来定义每个目录实体地址的常量 ---
  */
 /** --- 当前系统版本号 --- */
-export const VER = '9.14.0';
+export const VER = '9.14.2';
 // --- 服务端用的路径 ---
 const imu = decodeURIComponent(import.meta.url).replace('file://', '').replace(/^\/(\w:)/, '$1');
 /** --- /xxx/xxx --- */

package/lib/core.d.ts

@@ -133,6 +133,23 @@ export declare const REAL_IP_CF = "cf-connecting-ip";
  * @param name 输入安全的 header
  */
 export declare function realIP(ctr: sCtr.Ctr, name?: string): string;
+/**
+ * --- 截取 IP 的限速段 ---
+ * --- IPv4 原样返回；IPv6 截取前 mask 位（默认 /64），防止同一人使用大量 IPv6 地址绕过限速 ---
+ * @param ip IP 地址
+ * @param mask IPv6 前缀长度，0-128 的整数，默认 64
+ * @returns 限速段，如 192.168.1.1、2001:db8:1234:5678::
+ */
+export declare function ipLimit(ip: string, mask?: number): string;
+/**
+ * --- 获取安全 IP 的限速段（用于 ratelimit 库的 key） ---
+ * --- IPv4 原样返回；IPv6 截取前 mask 位（默认 /64） ---
+ * @param ctr Ctr 实例
+ * @param name 输入安全的 header
+ * @param mask IPv6 前缀长度，0-128 的整数，默认 64
+ * @returns 限速段，如 192.168.1.1、2001:db8:1234:5678::
+ */
+export declare function realIPLimit(ctr: sCtr.Ctr, name?: string, mask?: number): string;
 /**
  * --- 间隔一段时间 ---
  * @param ms 间隔毫秒

package/lib/core.js

@@ -307,10 +307,11 @@ export function muid(ctr, opt = {}) {
 export function ip(ctr, req) {
     const headers = ctr instanceof sCtr.Ctr ? ctr.getPrototype('_headers') : ctr;
     if (typeof headers['cf-connecting-ip'] === 'string') {
-        return headers['cf-connecting-ip'];
+        return normalizeIP(headers['cf-connecting-ip']);
     }
     else if (typeof headers['x-forwarded-for'] === 'string') {
-        return headers['x-forwarded-for'];
+        // --- X-Forwarded-For 可能为逗号分隔的多个 IP，取第一个即客户端 IP ---
+        return normalizeIP(headers['x-forwarded-for'].split(',')[0].trim());
     }
     else {
         if (!req) {
@@ -321,21 +322,37 @@ export function ip(ctr, req) {
                 return '';
             }
         }
-        return req.socket.remoteAddress ?? '';
+        return normalizeIP(req.socket.remoteAddress ?? '');
     }
 }
 /** --- 获取 CF 和 X 的 IP --- */
 export function ips(ctr) {
     const headers = ctr instanceof sCtr.Ctr ? ctr.getPrototype('_headers') : ctr;
     return {
-        'cf': typeof headers['cf-connecting-ip'] === 'string' ? headers['cf-connecting-ip'] : '',
-        'x': typeof headers['x-forwarded-for'] === 'string' ? headers['x-forwarded-for'] : ''
+        'cf': typeof headers['cf-connecting-ip'] === 'string' ? normalizeIP(headers['cf-connecting-ip']) : '',
+        'x': typeof headers['x-forwarded-for'] === 'string' ? normalizeIP(headers['x-forwarded-for'].split(',')[0].trim()) : ''
     };
 }
 /** --- 使用 X-Forwarded-For 的 CDN 厂商 --- */
 export const REAL_IP_X = 'x-forwarded-for';
 /** --- 使用的是 Cloudflare --- */
 export const REAL_IP_CF = 'cf-connecting-ip';
+/**
+ * --- 规范化 IP 地址 ---
+ * --- 将 IPv4-mapped IPv6（如 ::ffff:127.0.0.1）转换为纯 IPv4，原生 IPv6 保持不变 ---
+ * @param ip 原始 IP 地址
+ */
+function normalizeIP(ip) {
+    if (!ip) {
+        return '';
+    }
+    const value = ip.trim();
+    const mapped = /^::ffff:(\d{1,3}(?:\.\d{1,3}){3})$/i.exec(value);
+    if (mapped) {
+        return mapped[1];
+    }
+    return value;
+}
 /**
  * --- 获取直连 IP（安全 IP） ---
  * @param ctr
@@ -346,11 +363,150 @@ export function realIP(ctr, name = '') {
     if (name !== '') {
         const value = headers[name];
         if (typeof value === 'string') {
-            return value;
+            return normalizeIP(value);
         }
     }
     const req = ctr.getPrototype('_req');
-    return req.socket.remoteAddress ?? '';
+    return normalizeIP(req.socket.remoteAddress ?? '');
+}
+/**
+ * --- 截取 IP 的限速段 ---
+ * --- IPv4 原样返回；IPv6 截取前 mask 位（默认 /64），防止同一人使用大量 IPv6 地址绕过限速 ---
+ * @param ip IP 地址
+ * @param mask IPv6 前缀长度，0-128 的整数，默认 64
+ * @returns 限速段，如 192.168.1.1、2001:db8:1234:5678::
+ */
+export function ipLimit(ip, mask = 64) {
+    if (!ip) {
+        return '';
+    }
+    const value = ip.trim();
+    if (net.isIP(value) === 6) {
+        return ipv6Segment(value, mask);
+    }
+    // --- IPv4 或无法识别的字符串原样返回 ---
+    return value;
+}
+/**
+ * --- 获取安全 IP 的限速段（用于 ratelimit 库的 key） ---
+ * --- IPv4 原样返回；IPv6 截取前 mask 位（默认 /64） ---
+ * @param ctr Ctr 实例
+ * @param name 输入安全的 header
+ * @param mask IPv6 前缀长度，0-128 的整数，默认 64
+ * @returns 限速段，如 192.168.1.1、2001:db8:1234:5678::
+ */
+export function realIPLimit(ctr, name = '', mask = 64) {
+    return ipLimit(realIP(ctr, name), mask);
+}
+/**
+ * --- 截取 IPv6 地址的前缀段 ---
+ * @param ip IPv6 地址
+ * @param mask 前缀长度，0-128
+ */
+function ipv6Segment(ip, mask) {
+    if (mask >= 128) {
+        return ip;
+    }
+    if (mask <= 0) {
+        return '::';
+    }
+    // --- 展开为 8 组 16 进制字符串 ---
+    const groups = expandIPv6(ip);
+    if (!groups) {
+        return ip;
+    }
+    /** --- 完整保留的组数 --- */
+    const full = Math.floor(mask / 16);
+    /** --- 下一组需保留的位数 --- */
+    const bits = mask % 16;
+    const parts = groups.slice(0, full);
+    if (bits > 0) {
+        // --- 保留下一组的高 bits 位，其余位清零 ---
+        const next = parseInt(groups[full], 16);
+        parts.push((next & (0xFFFF << (16 - bits))).toString(16));
+    }
+    // --- 补零到 8 组后按标准压缩 ---
+    while (parts.length < 8) {
+        parts.push('0');
+    }
+    return compressIPv6(parts);
+}
+/**
+ * --- 将 8 组 IPv6 分组压缩为标准 RFC 5952 表示（最长连续零段压缩为 ::） ---
+ * @param groups 8 组 16 进制字符串
+ */
+function compressIPv6(groups) {
+    /** --- 最长连续零组的起始位置与长度 --- */
+    let bestStart = -1;
+    let bestLen = 1;
+    let curStart = -1;
+    let curLen = 0;
+    for (let i = 0; i < groups.length; ++i) {
+        if (parseInt(groups[i], 16) === 0) {
+            if (curStart === -1) {
+                curStart = i;
+                curLen = 0;
+            }
+            ++curLen;
+            if (curLen > bestLen) {
+                bestLen = curLen;
+                bestStart = curStart;
+            }
+        }
+        else {
+            curStart = -1;
+            curLen = 0;
+        }
+    }
+    /** --- 统一为小写无前导零 --- */
+    const norm = (g) => parseInt(g, 16).toString(16);
+    if (bestLen < 2) {
+        // --- 无连续零段，直接拼接 ---
+        return groups.map(norm).join(':');
+    }
+    const left = groups.slice(0, bestStart).map(norm);
+    const right = groups.slice(bestStart + bestLen).map(norm);
+    return (left.length ? left.join(':') : '') + '::' + (right.length ? right.join(':') : '');
+}
+/**
+ * --- 将 IPv6 地址展开为 8 组 16 进制字符串数组 ---
+ * @param ip IPv6 地址
+ * @returns 8 组字符串数组，解析失败返回 null
+ */
+function expandIPv6(ip) {
+    // --- 处理内嵌 IPv4（如 ::ffff:1.2.3.4、1:2:3:4:5:6:1.2.3.4） ---
+    let value = ip;
+    const ipv4Match = /^(.*:)(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/.exec(value);
+    if (ipv4Match) {
+        const v4 = ipv4Match[2].split('.').map((n) => parseInt(n, 10).toString(16).padStart(2, '0'));
+        value = ipv4Match[1] + v4[0] + v4[1] + ':' + v4[2] + v4[3];
+    }
+    // --- 处理 :: 压缩 ---
+    const dc = value.indexOf('::');
+    let groups;
+    if (dc !== -1) {
+        const left = value.slice(0, dc);
+        const right = value.slice(dc + 2);
+        const leftGroups = left ? left.split(':') : [];
+        const rightGroups = right ? right.split(':') : [];
+        const missing = 8 - leftGroups.length - rightGroups.length;
+        if (missing < 1) {
+            return null;
+        }
+        groups = leftGroups.concat(new Array(missing).fill('0'), rightGroups);
+    }
+    else {
+        groups = value.split(':');
+    }
+    if (groups.length !== 8) {
+        return null;
+    }
+    for (const group of groups) {
+        if (!/^[\da-f]{1,4}$/i.test(group)) {
+            return null;
+        }
+    }
+    return groups;
 }
 /**
  * --- 间隔一段时间 ---

package/lib/db/pool.js

@@ -82,11 +82,12 @@ async function checkConnection() {
     }
     setTimeout(function () {
         checkConnection().catch(e => { lCore.display('[DB][checkConnection]', e); });
-    }, 10_000);
+    }, 10_000).unref();
 }
+// --- 模块级巡检定时器，unref 防止在一次性 CLI 进程中阻止退出（服务进程内有其他句柄保持存活，行为不变） ---
 setTimeout(function () {
     checkConnection().catch(e => { lCore.display('[DB][checkConnection]', e); });
-}, 10_000);
+}, 10_000).unref();
 /** --- 数据库连接池对象 --- */
 export class Pool {
     /** --- SQL 执行次数 --- */

package/lib/sql.d.ts

@@ -42,6 +42,8 @@ export declare class Sql {
     private _placeholderCounter;
     /** --- 是否忽略错误 --- */
     private _ignore;
+    /** --- MySQL 优化器 Hint，如 INDEX(table idx) --- */
+    private _hint;
     constructor(opt: {
         'service': ESERVICE;
         'ctr'?: ctr.Ctr;
@@ -51,6 +53,30 @@ export declare class Sql {
         'sql'?: string[];
         'alias'?: string[];
     });
+    /**
+     * --- 设置 MySQL 优化器 Hint ---
+     * --- 会以 Optimizer Hint 注释语法注入到 SELECT 关键字后 ---
+     * --- 传入 hint 内容即可，无需包裹注释符号 ---
+     * @param h Hint 内容
+     * @example
+     * // --- 强制走指定索引（最常用） ---
+     * INDEX(`supply_date_0_0` `idx_supply_date_query`)
+     *
+     * // --- 指定某表不用某索引 ---
+     * NO_INDEX(`supply_date_0_0` `idx_old`)
+     *
+     * // --- 指定 JOIN 顺序和索引 ---
+     * JOIN_ORDER(`a` `b`) INDEX(`a` `idx_a`) INDEX(`b` `idx_b`)
+     *
+     * // --- 指定 JOIN 中某表使用的索引 ---
+     * JOIN_INDEX(`supply_date_0_0` `idx_supply_date_query`)
+     *
+     * // --- 多表多索引组合 ---
+     * INDEX(`t1` `idx_a`) JOIN_INDEX(`t2` `idx_b`)
+     *
+     * // --- 官方文档: https://dev.mysql.com/doc/refman/8.0/en/optimizer-hints.html ---
+     */
+    hint(h: string): this;
     /**
      * --- 插入数据前导 ---
      * @param table 表名

package/lib/sql.js

@@ -45,6 +45,8 @@ export class Sql {
     _placeholderCounter = 1;
     /** --- 是否忽略错误 --- */
     _ignore = false;
+    /** --- MySQL 优化器 Hint，如 INDEX(table idx) --- */
+    _hint = '';
     // --- 实例化 ---
     constructor(opt) {
         this._ctr = opt.ctr;
@@ -60,6 +62,33 @@ export class Sql {
             this._alias = opt.alias;
         }
     }
+    /**
+     * --- 设置 MySQL 优化器 Hint ---
+     * --- 会以 Optimizer Hint 注释语法注入到 SELECT 关键字后 ---
+     * --- 传入 hint 内容即可，无需包裹注释符号 ---
+     * @param h Hint 内容
+     * @example
+     * // --- 强制走指定索引（最常用） ---
+     * INDEX(`supply_date_0_0` `idx_supply_date_query`)
+     *
+     * // --- 指定某表不用某索引 ---
+     * NO_INDEX(`supply_date_0_0` `idx_old`)
+     *
+     * // --- 指定 JOIN 顺序和索引 ---
+     * JOIN_ORDER(`a` `b`) INDEX(`a` `idx_a`) INDEX(`b` `idx_b`)
+     *
+     * // --- 指定 JOIN 中某表使用的索引 ---
+     * JOIN_INDEX(`supply_date_0_0` `idx_supply_date_query`)
+     *
+     * // --- 多表多索引组合 ---
+     * INDEX(`t1` `idx_a`) JOIN_INDEX(`t2` `idx_b`)
+     *
+     * // --- 官方文档: https://dev.mysql.com/doc/refman/8.0/en/optimizer-hints.html ---
+     */
+    hint(h) {
+        this._hint = h;
+        return this;
+    }
     // --- 前导 ---
     /**
      * --- 插入数据前导 ---
@@ -880,7 +909,7 @@ export class Sql {
             'data': data,
             'sql': sql,
             'alias': lCore.clone(this._alias),
-        });
+        }).hint(this._hint);
     }
     // --- 操作 ---
     /**
@@ -888,6 +917,10 @@ export class Sql {
      */
     getSql() {
         let sql = this._sql.join('');
+        // --- 注入优化器 Hint 到 SELECT 关键字后 ---
+        if (this._hint && !sql.includes('/*+')) {
+            sql = sql.replace(/^SELECT /i, `SELECT /*+ ${this._hint} */ `);
+        }
         if (this._pre) {
             return this._alias.reduce((result, item) => {
                 if (this._service === ESERVICE.MYSQL) {

package/lib/text.d.ts

@@ -1,8 +1,3 @@
-/**
- * Project: Kebab, User: JianSuoQiYue
- * Date: 2019-5-15 16:49:39
- * Last: 2020-04-06 20:51:06, 2022-9-29 15:18:16, 2022-12-29 00:01:30, 2024-3-6 17:53:14, 2024-5-31 17:29:52, 2025-6-13 15:47:02, 2025-9-23 12:51:49
- */
 import * as kebab from '#kebab/index.js';
 /**
  * --- 将文件大小格式化为带单位的字符串 ---
@@ -42,15 +37,13 @@ export declare const REGEXP_EMAIL: RegExp;
  * @param email
  */
 export declare function isEMail(email: string): boolean;
-export declare const REGEXP_IPV4: RegExp;
 /**
- * --- 是否是 IPv4 ---
+ * --- 是否是 IPv4（基于 Node 原生 net.isIP，严格校验） ---
  * @param ip
  */
 export declare function isIPv4(ip: string): boolean;
-export declare const REGEXP_IPV6: RegExp;
 /**
- * --- 是否是 IPv6 ---
+ * --- 是否是 IPv6（基于 Node 原生 net.isIP，严格校验） ---
  * @param ip
  */
 export declare function isIPv6(ip: string): boolean;

package/lib/text.js

@@ -3,6 +3,7 @@
  * Date: 2019-5-15 16:49:39
  * Last: 2020-04-06 20:51:06, 2022-9-29 15:18:16, 2022-12-29 00:01:30, 2024-3-6 17:53:14, 2024-5-31 17:29:52, 2025-6-13 15:47:02, 2025-9-23 12:51:49
  */
+import * as net from 'net';
 import * as kebab from '#kebab/index.js';
 import * as lFs from './fs.js';
 import * as lCore from './core.js';
@@ -219,21 +220,19 @@ export const REGEXP_EMAIL = /^[-_\w.]+@[-_\w.]+\.([a-zA-Z]+)$/i;
 export function isEMail(email) {
     return REGEXP_EMAIL.test(email);
 }
-export const REGEXP_IPV4 = /^[0-9]{1,3}(\.[0-9]{1,3}){3}$/i;
 /**
- * --- 是否是 IPv4 ---
+ * --- 是否是 IPv4（基于 Node 原生 net.isIP，严格校验） ---
  * @param ip
  */
 export function isIPv4(ip) {
-    return REGEXP_IPV4.test(ip);
+    return net.isIP(ip) === 4;
 }
-export const REGEXP_IPV6 = /^(\w*?:){2,7}[\w.]*$/i;
 /**
- * --- 是否是 IPv6 ---
+ * --- 是否是 IPv6（基于 Node 原生 net.isIP，严格校验） ---
  * @param ip
  */
 export function isIPv6(ip) {
-    return REGEXP_IPV6.test(ip);
+    return net.isIP(ip) === 6;
 }
 export const REGEXP_DOMAIN = /^.+?\.((?![0-9]).)+$/i;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maiyunnet/kebab",
-  "version": "9.14.0",
+  "version": "9.14.2",
   "description": "Simple, easy-to-use, and fully-featured Node.js framework that is ready-to-use out of the box.",
   "type": "module",
   "keywords": [

package/sys/ctr.d.ts

@@ -342,5 +342,9 @@ export declare class Ctr {
         'maxFileSize'?: number;
         /** --- 允许的文件扩展名（含点号），如 ['.jpg', '.png', '.pdf'] --- */
         'allowedExts'?: string[];
+        /** --- 单个字段（非文件）最大字节数，默认 1 MB --- */
+        'maxFieldSize'?: number;
+        /** --- 整体请求超时时间（毫秒），默认 5 分钟，设为 0 禁用超时 --- */
+        'timeout'?: number;
     }): Promise<boolean>;
 }

package/sys/mod.d.ts

@@ -80,6 +80,8 @@ export default class Mod {
             'key': string;
             'list': string[];
         };
+        /** --- MySQL 优化器 Hint，如 `INDEX(\`t\` \`idx_xx\`)`，注入到 SELECT 后 --- */
+        'hint'?: string;
         /** --- MySQL 表前缀或 PostgreSQL Schema 名，优先级：选项 > 类属性 > 配置 --- */
         'pre'?: string;
     });
@@ -208,6 +210,7 @@ export default class Mod {
             'key': string;
             'list': string[];
         };
+        'hint'?: string;
     }): T & Record<string, any>;
     /**
      * --- 通过 where 条件获取模型 ---
@@ -224,6 +227,7 @@ export default class Mod {
             'key': string;
             'list': string[];
         };
+        'hint'?: string;
     }): T & Record<string, any>;
     /**
      * --- 获取创建对象，通常用于新建数据库条目 ---
@@ -248,6 +252,7 @@ export default class Mod {
         'index'?: string | string[];
         /** --- 通过 key 字段获取，默认为 false，即从主键获取 --- */
         'key'?: boolean;
+        'hint'?: string;
     }): Promise<false | null | (T & Record<string, any>)>;
     static one(db: lDb.Pool | lDb.Transaction, s: string | kebab.Json, opt: {
         'ctr'?: sCtr.Ctr;
@@ -256,6 +261,7 @@ export default class Mod {
         'index'?: string | string[];
         'select'?: string | string[];
         'by'?: [string | string[], 'DESC' | 'ASC'];
+        'hint'?: string;
         'array': true;
     }): Promise<false | null | Record<string, any>>;
     static one<T extends Mod>(db: lDb.Pool | lDb.Transaction, s: string | kebab.Json, opt?: {
@@ -265,6 +271,7 @@ export default class Mod {
         'index'?: string | string[];
         'select'?: string | string[];
         'by'?: [string | string[], 'DESC' | 'ASC'];
+        'hint'?: string;
         'array'?: false;
     }): Promise<false | null | (T & Record<string, any>)>;
     /**
@@ -279,6 +286,7 @@ export default class Mod {
         'pre'?: string;
         'index'?: string | string[];
         'select'?: string | string[];
+        'hint'?: string;
     }): Promise<false | null | Record<string, any>>;
     /**
      * --- 根据 where 条件获取主键值列表 ---
@@ -414,6 +422,30 @@ export default class Mod {
      * @param pre 前缀，仅与主表的 pre 不同时传入
      */
     crossJoin(f: string, s: kebab.Json, index?: string, pre?: string): this;
+    /**
+     * --- 设置 MySQL 优化器 Hint ---
+     * --- 内容会以 Optimizer Hint 注释语法注入到 SELECT 关键字后 ---
+     * --- 必须在查询入口调用之后、执行方法之前链式调用 ---
+     * @param h Hint 内容
+     * @example
+     * // 强制走指定索引（最常用）
+     * .hint("INDEX(`supply_date_0_0` `idx_supply_date_query`)")
+     *
+     * // 指定某表不用某索引
+     * .hint("NO_INDEX(`supply_date_0_0` `idx_old`)")
+     *
+     * // 指定 JOIN 顺序和索引
+     * .hint("JOIN_ORDER(`a` `b`) INDEX(`a` `idx_a`) INDEX(`b` `idx_b`)")
+     *
+     * // 指定 JOIN 中某表使用的索引
+     * .hint("JOIN_INDEX(`supply_date_0_0` `idx_supply_date_query`)")
+     *
+     * // 多表多索引组合
+     * .hint("INDEX(`t1` `idx_a`) JOIN_INDEX(`t2` `idx_b`)")
+     *
+     * // 官方文档: https://dev.mysql.com/doc/refman/8.0/en/optimizer-hints.html
+     */
+    hint(h: string): this;
     /**
      * --- 筛选器 ---
      * @param s 筛选条件数组或字符串

package/sys/mod.js

@@ -89,6 +89,10 @@ export default class Mod {
             'ctr': opt.ctr,
             'pre': opt.pre ?? this.constructor._$pre,
         });
+        /** --- 设置优化器 Hint --- */
+        if (opt.hint) {
+            this._sql.hint(opt.hint);
+        }
         if (opt.index) {
             this._index = typeof opt.index === 'string' ? [opt.index] : [...new Set(opt.index)];
         }
@@ -375,7 +379,8 @@ export default class Mod {
             'select': c,
             'index': opt.index,
             'alias': opt.alias,
-            'contain': opt.contain
+            'contain': opt.contain,
+            'hint': opt.hint,
         });
     }
     /**
@@ -393,6 +398,7 @@ export default class Mod {
             'index': opt.index,
             'contain': opt.contain,
             'alias': opt.alias,
+            'hint': opt.hint,
         });
     }
     /**
@@ -427,6 +433,7 @@ export default class Mod {
                     [opt.key ? this._$key : this._$primary]: val,
                 }],
             'index': opt.index,
+            'hint': opt.hint,
         }).first(opt.lock);
     }
     /**
@@ -444,6 +451,7 @@ export default class Mod {
                 'ctr': opt.ctr,
                 'pre': opt.pre,
                 'where': s,
+                'hint': opt.hint,
             });
             if (opt.by) {
                 o.by(opt.by[0], opt.by[1]);
@@ -459,6 +467,7 @@ export default class Mod {
                 'pre': opt.pre,
                 'where': s,
                 'index': item,
+                'hint': opt.hint,
             });
             if (opt.by) {
                 row.by(opt.by[0], opt.by[1]);
@@ -1307,6 +1316,33 @@ export default class Mod {
         this._sql.crossJoin(f, s, index ? '_' + index : '', pre);
         return this;
     }
+    /**
+     * --- 设置 MySQL 优化器 Hint ---
+     * --- 内容会以 Optimizer Hint 注释语法注入到 SELECT 关键字后 ---
+     * --- 必须在查询入口调用之后、执行方法之前链式调用 ---
+     * @param h Hint 内容
+     * @example
+     * // 强制走指定索引（最常用）
+     * .hint("INDEX(`supply_date_0_0` `idx_supply_date_query`)")
+     *
+     * // 指定某表不用某索引
+     * .hint("NO_INDEX(`supply_date_0_0` `idx_old`)")
+     *
+     * // 指定 JOIN 顺序和索引
+     * .hint("JOIN_ORDER(`a` `b`) INDEX(`a` `idx_a`) INDEX(`b` `idx_b`)")
+     *
+     * // 指定 JOIN 中某表使用的索引
+     * .hint("JOIN_INDEX(`supply_date_0_0` `idx_supply_date_query`)")
+     *
+     * // 多表多索引组合
+     * .hint("INDEX(`t1` `idx_a`) JOIN_INDEX(`t2` `idx_b`)")
+     *
+     * // 官方文档: https://dev.mysql.com/doc/refman/8.0/en/optimizer-hints.html
+     */
+    hint(h) {
+        this._sql.hint(h);
+        return this;
+    }
     /**
      * --- 筛选器 ---
      * @param s 筛选条件数组或字符串

package/sys/route.d.ts

@@ -77,6 +77,10 @@ export declare function getFormData(req: http2.Http2ServerRequest | http.Incomin
     'maxFileSize'?: number;
     /** --- 允许的文件扩展名（含点号），如 ['.jpg', '.png', '.pdf'] --- */
     'allowedExts'?: string[];
+    /** --- 单个字段（非文件）最大字节数，默认 1 MB --- */
+    'maxFieldSize'?: number;
+    /** --- 整体请求超时时间（毫秒），默认 5 分钟，设为 0 禁用超时 --- */
+    'timeout'?: number;
 }): Promise<{
     'post': Record<string, kebab.Json>;
     'files': Record<string, kebab.IPostFile | kebab.IPostFile[]>;