@maiyunnet/kebab 2.0.6 → 2.0.8

package/sys/route.js

@@ -39,9 +39,16 @@ exports.unlinkUploadFiles = unlinkUploadFiles;
 exports.waitCtr = waitCtr;
 exports.trimPost = trimPost;
 exports.getFormData = getFormData;
+/**
+ * Project: Kebab, User: JianSuoQiYue
+ * Date: 2019-4-15 13:40
+ * Last: 2020-4-14 13:52:00, 2022-09-07 01:43:31, 2023-12-29 17:24:03, 2024-2-7 00:28:50, 2024-6-6 15:15:54, 2025-6-13 19:23:53
+ */
 const http = __importStar(require("http"));
 const stream = __importStar(require("stream"));
+// --- 第三方 ---
 const ws = __importStar(require("@litert/websocket"));
+// --- 库和定义 ---
 const lFs = __importStar(require("../lib/fs"));
 const lZlib = __importStar(require("../lib/zlib"));
 const lCore = __importStar(require("../lib/core"));
@@ -51,18 +58,29 @@ const lResponse = __importStar(require("../lib/net/response"));
 const lWs = __importStar(require("../lib/ws"));
 const sCtr = __importStar(require("./ctr"));
 const kebab = __importStar(require("../index"));
+/** --- 动态层 kebab.json 缓存（文件路径: 最终合并值） --- */
 let kebabConfigs = {};
+/**
+ * --- 清除已经加载的虚拟主机配置文件 ---
+ */
 function clearKebabConfigs() {
     kebabConfigs = {};
 }
+/**
+ * --- 若为动态路径则执行此函数，此函数不进行判断 kebab.json 是否存在 ---
+ * @param data 传导的数据
+ */
 async function run(data) {
+    // --- 检测 path 是否是静态文件 ---
     if (/^(stc\/.*|favicon.\w+?\??.*|apple[\w-]+?\.png\??.*|[\w-]+?\.txt\??.*|[\w-]+?\.html\??.*)/.test(data.path)) {
         return false;
     }
+    // --- 根据 res 还是 socket 进行初始化设置 ---
     if (data.res) {
         data.res.setHeader('expires', 'Mon, 26 Jul 1994 05:00:00 GMT');
         data.res.setHeader('cache-control', 'no-store');
     }
+    // --- 判断 kebab config 是否已经读取过 ---
     if (!kebabConfigs[data.rootPath + 'kebab.json']) {
         const configContent = await lFs.getContent(data.rootPath + 'kebab.json', 'utf8');
         if (!configContent) {
@@ -81,6 +99,7 @@ async function run(data) {
         if (routeContent) {
             kebabConfigs[data.rootPath + 'kebab.json'].route = lText.parseJson(routeContent);
         }
+        // --- 将全局的项目应用到 vhostConfigs 里，但当 vhostConfigs 有项，则不应用 ---
         for (const name in lCore.globalConfig) {
             if (typeof lCore.globalConfig[name] !== 'object') {
                 if (kebabConfigs[data.rootPath + 'kebab.json'][name] === undefined) {
@@ -98,6 +117,7 @@ async function run(data) {
             }
         }
     }
+    // --- 加载 kebab config ---
     const config = {};
     const configData = kebabConfigs[data.rootPath + 'kebab.json'];
     for (const name in configData) {
@@ -108,6 +128,7 @@ async function run(data) {
         'qs': data.uri.query ?? '',
         'startTime': process.hrtime.bigint(),
         'startMemory': process.memoryUsage().rss,
+        // --- 环境判断 ---
         'mobile': data.req.headers['user-agent'] ? data.req.headers['user-agent'].includes('mobile') : false,
         'wechat': data.req.headers['user-agent'] ? data.req.headers['user-agent'].includes('micromessenger') : false,
         'https': data.uri.protocol === 'https' ? true : false,
@@ -115,12 +136,14 @@ async function run(data) {
         'hostname': data.uri.hostname ?? '',
         'hostport': data.uri.port ? parseInt(data.uri.port) : (data.uri.protocol === 'https' ? 443 : 80),
         'uri': data.uri,
+        // --- 服务端用的路径 ---
         'rootPath': data.rootPath,
         'ctrPath': data.rootPath + 'ctr/',
         'viewPath': data.rootPath + 'view/',
         'dataPath': data.rootPath + 'data/',
         'modPath': data.rootPath + 'mod/',
         'wsPath': data.rootPath + 'ws/',
+        // --- 前端用的路径 ---
         'urlBase': data.urlBase,
         'urlStc': data.urlBase + 'stc/',
         'urlFull': (data.uri.protocol ?? '') + '//' + (data.uri.host ?? '') + data.urlBase,
@@ -133,13 +156,18 @@ async function run(data) {
     if (!config.set.staticPathFull) {
         config.set.staticPathFull = config.const.urlStcFull;
     }
+    // --- data.path 是安全的，不会是 ../../ 来访问到了外层，已经做过处理 ---
     let path = data.path;
+    // --- 如果为空则定义为 @ ---
     if (path === '') {
         path = '@';
     }
+    // --- 检测是否托管语言页面 ---
     const param = [];
     if (config.lang && data.res) {
+        // --- 仅仅 res 模式支持 config.lang ---
         if (path[2] !== '/') {
+            // --- 不管是首页还是 @ 页，都会到此处 ---
             let isDirect = false;
             if (!path) {
                 if (config.lang.direct.includes('@')) {
@@ -151,11 +179,13 @@ async function run(data) {
                     if (!path.startsWith(ditem)) {
                         continue;
                     }
+                    // --- 放行 ---
                     isDirect = true;
                     break;
                 }
             }
             if (!isDirect) {
+                // --- 不放行 ---
                 const alang = data.req.headers['accept-language']?.toLowerCase() ?? config.lang.list[0];
                 const apath = config.const.path + (config.const.qs ? '?' + config.const.qs : '');
                 for (const lang of config.lang.list) {
@@ -181,6 +211,7 @@ async function run(data) {
             }
         }
         else {
+            // --- 已经是含语言的路径了 --
             param.push(path.slice(0, 2));
             path = path.slice(3);
             if (!path) {
@@ -188,6 +219,7 @@ async function run(data) {
             }
         }
     }
+    // --- 检查路由表 ---
     let match = null;
     let pathLeft = '', pathRight = '';
     for (const rule in config.route) {
@@ -213,6 +245,7 @@ async function run(data) {
             pathLeft = getWsCtrName(path);
         }
     }
+    // --- 若文件名为保留的 middle 将不允许进行 ---
     if (pathLeft.startsWith('middle')) {
         const text = '[Error] Controller not found, path: ' + path + '.';
         if (data.res) {
@@ -232,7 +265,9 @@ async function run(data) {
         }
         return true;
     }
+    // --- 原始 GET ---
     const get = data.uri.query ? lText.queryParse(data.uri.query) : {};
+    // --- Cookie ---
     const cookies = {};
     if (data.req.headers['cookie']) {
         const hcookies = data.req.headers['cookie'].split(';');
@@ -241,20 +276,26 @@ async function run(data) {
             cookies[co[0].trim()] = decodeURIComponent(co[1]);
         }
     }
+    // --- 处理 headers ---
     const headers = {};
     for (const key in data.req.headers) {
         headers[key.toLowerCase()] = data.req.headers[key];
     }
     headers['authorization'] ??= '';
+    /** --- 开发者返回值 --- */
     let rtn;
     if (data.socket && data.req instanceof http.IncomingMessage) {
+        // --- socket 模式，判断真实控制器文件是否存在 ---
         const filePath = config.const.wsPath + pathLeft + '.js';
         if (!await lFs.isFile(filePath)) {
+            // --- 指定的控制器不存在 ---
             data.socket?.destroy();
             return true;
         }
+        // --- 加载控制器文件 ---
         const ctrCtr = (await Promise.resolve(`${filePath}`).then(s => __importStar(require(s)))).default;
         const cctr = new ctrCtr(config, data.req);
+        // --- 先处理 web socket 的情况 ---
         let wsSocket;
         try {
             const options = await cctr.onUpgrade();
@@ -327,6 +368,7 @@ async function run(data) {
                                     return;
                                 }
                                 if (typeof wrtn === 'object') {
+                                    // --- 返回的是数组，那么代表可能是 JSON，可能是对象序列 ---
                                     wsSocket.writeResult(wrtn);
                                     return;
                                 }
@@ -337,6 +379,7 @@ async function run(data) {
                             break;
                         }
                         default: {
+                            // --- nothing ---
                         }
                     }
                 }).on('drain', async () => {
@@ -368,22 +411,34 @@ async function run(data) {
     if (!data.res) {
         return true;
     }
+    // --- 加载中间控制器 ---
     const middleCtr = (await Promise.resolve(`${config.const.ctrPath + 'middle'}`).then(s => __importStar(require(s)))).default;
     const middle = new middleCtr(config, data.req, data.res);
+    /** --- 可能存在的最终控制器 --- */
     let cctr = null;
+    // --- 对信息进行初始化 ---
     if (data.timer) {
         middle.setPrototype('_timer', data.timer);
     }
+    // --- 路由定义的参数序列 ---
     middle.setPrototype('_param', param);
+    // --- action 名 ---
     middle.setPrototype('_action', pathRight);
     middle.setPrototype('_headers', headers);
     middle.setPrototype('_get', get);
     const rawPost = await getPost(data.req);
+    // --- 原始 POST ---
     middle.setPrototype('_rawPost', rawPost[1]);
+    // --- 原始 input ---
     middle.setPrototype('_input', rawPost[0]);
+    // --- 处理 POST 的值 JSON 上面就同时处理了 ---
+    // --- 格式化 post 数据 ---
+    // --- assign 是为了创建一份拷贝 ---
     const post = Object.assign({}, rawPost[1]);
     trimPost(post);
     middle.setPrototype('_post', post);
+    // --- form data 格式交由用户自行获取，可以直接获取文件流，然后做他想做的事情 ---
+    // --- 执行中间控制器的 onLoad ---
     try {
         rtn = await middle.onLoad();
     }
@@ -398,8 +453,11 @@ async function run(data) {
     let cacheTTL = middle.getPrototype('_cacheTTL');
     let httpCode = middle.getPrototype('_httpCode');
     if (rtn === undefined || rtn === true) {
+        // --- 只有不返回或返回 true 时才加载控制文件 ---
+        // --- 判断真实控制器文件是否存在 ---
         const filePath = config.const.ctrPath + pathLeft + '.js';
         if (!await lFs.isFile(filePath)) {
+            // --- 指定的控制器不存在 ---
             const text = '[Error] Controller not found, path: ' + path + '.';
             if (config.route['#404']) {
                 data.res.setHeader('location', lText.urlResolve(config.const.urlBase, config.route['#404']));
@@ -413,10 +471,13 @@ async function run(data) {
             data.res.end(text);
             return true;
         }
+        // --- 加载控制器文件 ---
         const ctrCtr = (await Promise.resolve(`${filePath}`).then(s => __importStar(require(s)))).default;
         cctr = new ctrCtr(config, data.req, data.res ?? data.socket);
+        // --- 对信息进行初始化 ---
         cctr.setPrototype('_timer', middle.getPrototype('_timer'));
         cctr.setPrototype('_waitInfo', middle.getPrototype('_waitInfo'));
+        // --- 路由定义的参数序列 ---
         cctr.setPrototype('_param', param);
         cctr.setPrototype('_action', middle.getPrototype('_action'));
         cctr.setPrototype('_headers', headers);
@@ -435,12 +496,15 @@ async function run(data) {
         cctr.setPrototype('_xsrf', middle.getPrototype('_xsrf'));
         cctr.setPrototype('_httpCode', middle.getPrototype('_httpCode'));
         await lCore.log(cctr, '', '-visit');
+        // --- 强制 HTTPS ---
         if (config.set.mustHttps && !config.const.https) {
             data.res.setHeader('location', data.req.url ?? '');
             data.res.writeHead(302);
             return true;
         }
+        // --- 检测 action 是否存在，以及排除内部方法 ---
         if (pathRight.startsWith('_') || pathRight === 'onUpgrade' || pathRight === 'onLoad' || pathRight === 'onData' || pathRight === 'onDrain' || pathRight === 'onClose' || pathRight === 'setPrototype' || pathRight === 'getPrototype' || pathRight === 'getAuthorization') {
+            // --- _ 开头的 action 是内部方法，不允许访问 ---
             if (config.route['#404']) {
                 data.res.setHeader('location', lText.urlResolve(config.const.urlBase, config.route['#404']));
                 data.res.writeHead(302);
@@ -471,8 +535,10 @@ async function run(data) {
             data.res.end(text);
             return true;
         }
+        // --- 执行 onLoad 方法 ---
         try {
             rtn = await cctr.onLoad();
+            // --- 执行 action ---
             if (rtn === undefined || rtn === true) {
                 rtn = await cctr[pathRight]();
                 rtn = await cctr.onUnload(rtn);
@@ -482,6 +548,7 @@ async function run(data) {
                     await sess.update();
                 }
             }
+            // --- 获取 ctr 设置的 cache 和 hcode ---
             cacheTTL = cctr.getPrototype('_cacheTTL');
             httpCode = cctr.getPrototype('_httpCode');
         }
@@ -495,15 +562,19 @@ async function run(data) {
             return true;
         }
     }
+    // --- 设置缓存 ---
     if (!data.res.headersSent && (cacheTTL > 0)) {
         data.res.setHeader('expires', lTime.format(0, 'D, d M Y H:i:s', Date.now() + cacheTTL * 1000) + ' GMT');
         data.res.setHeader('cache-control', 'max-age=' + cacheTTL.toString());
     }
+    // --- 设置自定义 hcode ---
     if (httpCode === 0) {
         httpCode = 200;
     }
+    // --- 判断返回值 ---
     if (rtn === undefined || typeof rtn === 'boolean' || rtn === null) {
         if (data.res.headersSent) {
+            // --- 已经自行输出过 writeHead，可能自行处理了内容，如 pipe，则不再 writeHead ---
         }
         else {
             if (data.res.getHeader('location')) {
@@ -514,12 +585,15 @@ async function run(data) {
             }
         }
         if (!data.res.writableEnded) {
+            // --- 如果当前还没结束，则强制关闭连接，一切 pipe 请自行在方法中 await，否则会被中断 ---
             data.res.end('');
         }
         await waitCtr(cctr ?? middle);
         return true;
     }
     if (typeof rtn === 'string' || rtn instanceof Buffer) {
+        // --- 返回的是纯字符串，直接输出 ---
+        /** --- 当前的压缩对象 --- */
         let compress = null;
         if (!data.res.headersSent) {
             if (!data.res.getHeader('content-type')) {
@@ -545,7 +619,9 @@ async function run(data) {
         }
     }
     else if (rtn instanceof stream.Readable || rtn instanceof lResponse.Response) {
+        // --- 返回的是流，那就以管道的形式输出 ---
         const stm = rtn instanceof stream.Readable ? rtn : rtn.getStream();
+        /** --- 当前的压缩对象 --- */
         let compress = null;
         if (!data.res.headersSent) {
             if (!data.res.getHeader('content-type')) {
@@ -567,8 +643,11 @@ async function run(data) {
         }
     }
     else if (typeof rtn === 'object') {
+        // --- 返回的是数组，那么代表可能是 JSON，可能是对象序列 ---
         if (Array.isArray(rtn)) {
+            // --- [0, 'xxx'] 模式，或 [string, Readable] 模式 ---
             if (rtn.length === 0) {
+                // --- 异常 ---
                 if (!data.res.headersSent) {
                     data.res.writeHead(500);
                 }
@@ -578,14 +657,17 @@ async function run(data) {
             }
             else {
                 if (typeof rtn[0] === 'number') {
+                    // --- 1. ---
                     const json = { 'result': rtn[0] };
                     if (rtn[1] !== undefined) {
                         if (typeof rtn[1] === 'object') {
+                            // --- [0, ...{'xx': 'xx'}] ---
                             for (let i = 1; i < rtn.length; ++i) {
                                 Object.assign(json, rtn[i]);
                             }
                         }
                         else {
+                            // --- [0, 'xxx'], [0, 'xxx', ...{'xx': 'xx'}] ---
                             json['msg'] = rtn[1];
                             for (let i = 2; i < rtn.length; ++i) {
                                 Object.assign(json, rtn[i]);
@@ -593,6 +675,7 @@ async function run(data) {
                         }
                     }
                     const writeData = lText.stringifyJson(json);
+                    /** --- 当前的压缩对象 --- */
                     let compress = null;
                     if (!data.res.headersSent) {
                         data.res.setHeader('content-type', 'application/json; charset=utf-8');
@@ -616,6 +699,8 @@ async function run(data) {
                     }
                 }
                 else {
+                    // --- 2. 字符串与 Readable 的组合 ---
+                    /** --- 当前的压缩对象 --- */
                     let compress = null;
                     if (!data.res.headersSent) {
                         if (!data.res.getHeader('content-type')) {
@@ -629,6 +714,7 @@ async function run(data) {
                     }
                     if (!data.res.writableEnded) {
                         const passThrough = new stream.PassThrough();
+                        // --- 先进行 pipe 绑定，之后 write 或 pipe 进 pass 的数据，直接就可以消费 ---
                         if (compress) {
                             passThrough.pipe(compress.compress).pipe(data.res);
                         }
@@ -641,7 +727,9 @@ async function run(data) {
             }
         }
         else {
+            // --- 直接是个 json 对象 ---
             const writeData = lText.stringifyJson(rtn);
+            /** --- 当前的压缩对象 --- */
             let compress = null;
             if (!data.res.headersSent) {
                 data.res.setHeader('content-type', 'application/json; charset=utf-8');
@@ -666,6 +754,7 @@ async function run(data) {
         }
     }
     else {
+        // --- 异常 ---
         if (!data.res.headersSent) {
             data.res.writeHead(500);
         }
@@ -676,6 +765,10 @@ async function run(data) {
     await waitCtr(cctr ?? middle);
     return true;
 }
+/**
+ * --- 获取控制器 left 和 action ---
+ * @param path 相对路径
+ */
 function getPathLeftRight(path) {
     const pathLio = path.lastIndexOf('/');
     if (pathLio === -1) {
@@ -684,6 +777,10 @@ function getPathLeftRight(path) {
     const right = path.slice(pathLio + 1);
     return [path.slice(0, pathLio), right === '' ? 'index' : right];
 }
+/**
+ * --- 根据 path 获取 ws 的控制器类名, Mutton: false, Kebab: true ---
+ * @param path 路径
+ */
 function getWsCtrName(path) {
     const pathLio = path.lastIndexOf('/');
     if (pathLio === -1) {
@@ -691,6 +788,10 @@ function getWsCtrName(path) {
     }
     return path.slice(pathLio + 1).toLowerCase();
 }
+/**
+ * --- 删除本次请求所有已上传的临时文件, Mutton: false, Kebab: true ---
+ * @param cctr Ctr 对象 或 files
+ */
 async function unlinkUploadFiles(cctr) {
     const cfiles = cctr instanceof sCtr.Ctr ? cctr.getPrototype('_files') : cctr;
     for (const name in cfiles) {
@@ -703,18 +804,31 @@ async function unlinkUploadFiles(cctr) {
         }
     }
 }
+/**
+ * --- 等待异步任务结束，并删除临时文件，如果结束后还有事务没关闭，则会在本函数中打印控制台并且写入 log 文件 ---
+ * --- 此时其实已经给客户端返回了，此处等待不消耗客户端的等待时间 ---
+ * @param cctr 要等待的控制器 ---
+ */
 async function waitCtr(cctr) {
+    // --- 先判断异步任务是否结束 ---
     const waitInfo = cctr.getPrototype('_waitInfo');
     if (waitInfo.asyncTask.count) {
         await waitInfo.asyncTask.callback();
     }
+    // --- 判断事务 ---
     if (waitInfo.transaction) {
+        // --- 有事务未关闭 ---
         const msg = 'transaction(' + waitInfo.transaction + ') not be closed';
         lCore.display('[ERROR][ROUTE][WAITCTR] ' + msg + ': ', cctr.getPrototype('_config').const.path);
         await lCore.log(cctr, msg, '-error');
     }
+    // --- 彻底结束，删除文件 ---
     await unlinkUploadFiles(cctr);
 }
+/**
+ * --- 将 POST 数据的值执行 trim ---
+ * @param post
+ */
 function trimPost(post) {
     for (const key in post) {
         const val = post[key];
@@ -726,6 +840,10 @@ function trimPost(post) {
         }
     }
 }
+/**
+ * --- 内部使用，获取 post 对象，如果是文件上传（formdata）的情况则不获取 ---
+ * @param req 请求对象
+ */
 function getPost(req) {
     return new Promise(function (resolve) {
         const ct = req.headers['content-type'] ?? '';
@@ -733,6 +851,7 @@ function getPost(req) {
             resolve(['', {}]);
             return;
         }
+        // --- json 或普通 post ---
         let buffer = Buffer.from('');
         req.on('data', function (chunk) {
             buffer = Buffer.concat([buffer, chunk], buffer.length + chunk.length);
@@ -743,6 +862,7 @@ function getPost(req) {
                 resolve(['', {}]);
                 return;
             }
+            // --- 判断 json 还是普通 ---
             if (ct.includes('json')) {
                 try {
                     resolve([s, lText.parseJson(s)]);
@@ -756,6 +876,11 @@ function getPost(req) {
         });
     });
 }
+/**
+ * --- 获取 formdata 的 post ---
+ * @param req 请求头
+ * @param events 文件处理情况
+ */
 function getFormData(req, events = {}) {
     return new Promise(function (resolve) {
         const ct = req.headers['content-type'] ?? '';
@@ -763,54 +888,80 @@ function getFormData(req, events = {}) {
             resolve({ 'post': {}, 'files': {} });
             return;
         }
+        /** --- boundary 位置 --- */
         const clio = ct.lastIndexOf('boundary=');
         if (clio === -1) {
             resolve({ 'post': {}, 'files': {} });
             return;
         }
+        /** --- 最终返回 --- */
         const rtn = {
             'post': {},
             'files': {}
         };
+        /** --- 获取的 boundary 文本 --- */
         const boundary = ct.slice(clio + 9);
+        // 一下变量是相对于 data 事件的全局变量 ---
+        /** --- 当前临时读入的还未处理的 buffer --- */
         let buffer = Buffer.from('');
+        /** --- 状态机 --- */
         let EState;
         (function (EState) {
+            /** --- 判断头部是什么 --- */
             EState[EState["WAIT"] = 0] = "WAIT";
+            /** --- 当前是文件 --- */
             EState[EState["FILE"] = 1] = "FILE";
+            /** --- 当前是 post 数据 --- */
             EState[EState["POST"] = 2] = "POST";
         })(EState || (EState = {}));
+        /** --- 当前所处状态 --- */
         let state = EState.WAIT;
+        /** --- 当前处理中的 post 的 name --- */
         let name = '';
+        /** --- 当前处理中的 file 的 name --- */
         let fileName = '';
+        /** --- 当前处理中的临时文件名 --- */
         let ftmpName = '';
+        /** --- 当前正在写入的临时文件流 --- */
         let ftmpStream;
+        /** --- 当前临时文件已写入的流大小 --- */
         let ftmpSize = 0;
+        /** --- 当前正在写入的文件数量 --- */
         let writeFileLength = 0;
+        /** --- 当前读取是否已经完全结束 --- */
         let readEnd = false;
+        // --- 开始读取 ---
         req.on('data', function (chunk) {
             buffer = Buffer.concat([buffer, chunk], buffer.length + chunk.length);
             while (true) {
                 switch (state) {
                     case EState.WAIT: {
+                        /** --- 中断符位置 --- */
                         const io = buffer.indexOf('\r\n\r\n');
                         if (io === -1) {
                             return;
                         }
+                        // --- 头部已经读取完毕 ---
                         const head = buffer.subarray(0, io).toString();
+                        // --- 除头部外剩下的 buffer ---
                         buffer = buffer.subarray(io + 4);
+                        // --- 获取 name ---
                         let match = /name="(.+?)"/.exec(head);
                         name = match ? match[1] : '';
+                        // --- 判断是 post 还是文件 ---
                         match = /filename="(.+?)"/.exec(head);
                         if (!match) {
+                            // --- 普通 post ---
                             state = EState.POST;
                         }
                         else {
+                            // --- 文件 ---
                             ++writeFileLength;
                             state = EState.FILE;
                             fileName = match[1];
                             const fr = events.onfilestart?.(name);
                             if (fr !== true) {
+                                // --- 创建文件流 ---
                                 const date = new Date();
                                 ftmpName = date.getUTCFullYear().toString() +
                                     (date.getUTCMonth() + 1).toString().padStart(2, '0') +
@@ -827,10 +978,12 @@ function getFormData(req, events = {}) {
                         break;
                     }
                     case EState.POST: {
+                        // --- POST 模式 ---
                         const io = buffer.indexOf('\r\n--' + boundary);
                         if (io === -1) {
                             return;
                         }
+                        // --- 找到结束标语，写入 POST ---
                         const val = buffer.subarray(0, io).toString();
                         if (rtn.post[name]) {
                             if (Array.isArray(rtn.post[name])) {
@@ -843,13 +996,16 @@ function getFormData(req, events = {}) {
                         else {
                             rtn.post[name] = val;
                         }
+                        // --- 重置状态机 ---
                         state = EState.WAIT;
                         buffer = buffer.subarray(io + 4 + boundary.length);
                         break;
                     }
                     case EState.FILE: {
+                        // --- FILE 模式 ---
                         const io = buffer.indexOf('\r\n--' + boundary);
                         if (io === -1) {
+                            // --- 没找到结束标语，将预留 boundary 长度之前的写入到文件 ---
                             const writeBuffer = buffer.subarray(0, -boundary.length - 4);
                             if (ftmpName === '') {
                                 events.onfiledata?.(writeBuffer);
@@ -861,6 +1017,7 @@ function getFormData(req, events = {}) {
                             buffer = buffer.subarray(-boundary.length - 4);
                             return;
                         }
+                        // --- 找到结束标语，结束标语之前的写入文件，之后的重新放回 buffer ---
                         const writeBuffer = buffer.subarray(0, io);
                         if (ftmpName === '') {
                             events.onfileend?.();
@@ -871,13 +1028,17 @@ function getFormData(req, events = {}) {
                             ftmpStream.end(() => {
                                 --writeFileLength;
                                 if (!readEnd) {
+                                    // --- request 没读完，不管 ---
                                     return;
                                 }
                                 if (writeFileLength) {
+                                    // --- req 读完了但文件还没写完，不管 ---
                                     return;
                                 }
+                                // --- 文件也写完了 ---
                                 resolve(rtn);
                             });
+                            // --- POST 部分 ---
                             let fname = fileName.replace(/\\/g, '/');
                             const nlio = fname.lastIndexOf('/');
                             if (nlio !== -1) {
@@ -901,6 +1062,7 @@ function getFormData(req, events = {}) {
                                 rtn.files[name] = val;
                             }
                         }
+                        // --- 重置状态机 ---
                         state = EState.WAIT;
                         buffer = buffer.subarray(io + 4 + boundary.length);
                         break;
@@ -914,8 +1076,10 @@ function getFormData(req, events = {}) {
         req.on('end', function () {
             readEnd = true;
             if (writeFileLength) {
+                // --- 文件没写完 ---
                 return;
             }
+            // --- 文件写完了 ----
             resolve(rtn);
         });
     });

package/www/example/ctr/test.d.ts

@@ -90,5 +90,8 @@ export default class extends sCtr.Ctr {
     zip(): Promise<string>;
     buffer(): string;
     lan(): Promise<string>;
+    /**
+     * --- END ---
+     */
     private _getEnd;
 }