@kne/fastify-puppeteer 1.1.9 → 1.1.11

package/libs/controllers.js

@@ -1,5 +1,10 @@
 const fp = require('fastify-plugin');
 const { decode } = require('plantuml-encoder');
+const { pdfFile, photoFile, zipFile, filename, encodedContent } = require('./schema/response');
+
+const PDF_TAG = '无头浏览器-PDF生成';
+const PHOTO_TAG = '无头浏览器-网页截图';
+const CACHE_HINT = '相同参数的结果会缓存在本地目录，命中缓存时直接返回已生成的文件';
 
 module.exports = fp(async (fastify, options) => {
   const { services } = fastify.puppeteer;
@@ -9,16 +14,19 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.authenticate,
       schema: {
-        description: '接口说明',
+        tags: [PDF_TAG],
         summary: 'html生成pdf文件流',
+        description: `用无头浏览器加载 HTML 内容并生成PDF；${CACHE_HINT}`,
         body: {
           type: 'object',
           required: ['content'],
           properties: {
             options: pdfSchema,
-            content: { type: 'string' }
+            content: { type: 'string', description: '要渲染的 HTML 内容' },
+            filename
           }
-        }
+        },
+        response: pdfFile
       }
     },
     async (request, reply) => {
@@ -30,15 +38,19 @@ module.exports = fp(async (fastify, options) => {
   fastify.get(
     `${options.prefix}/parseHtmlToPdf`,
     {
-      description: '接口说明',
-      summary: 'html生成pdf文件流',
-      query: {
-        type: 'object',
-        required: ['content'],
-        properties: {
-          options: pdfSchema,
-          content: { type: 'string' }
-        }
+      schema: {
+        tags: [PDF_TAG],
+        summary: 'html生成pdf文件流',
+        description: `GET 方式把 HTML 渲染为 PDF，content 需先用 plantuml-encoder 压缩编码；${CACHE_HINT}。注意：该路由未做参数校验，也未挂 authenticate 鉴权`,
+        query: {
+          type: 'object',
+          properties: {
+            options: { description: 'PDF 生成参数，结构同 POST /parseHtmlToPdf 的 options（按 querystring 嵌套格式传递）；该路由不校验也不填充默认值' },
+            content: { description: `要渲染${encodedContent}` },
+            filename
+          }
+        },
+        response: pdfFile
       }
     },
     async (request, reply) => {
@@ -53,8 +65,9 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.authenticate,
       schema: {
-        description: '接口说明',
+        tags: [PDF_TAG],
         summary: '批量将html生成pdf的zip文件流',
+        description: `把多段 HTML 分别渲染为PDF并打包为 zip 返回，数量不能超过插件配置 maxCacheKeys；${CACHE_HINT}`,
         body: {
           type: 'object',
           required: ['contentList'],
@@ -62,12 +75,15 @@ module.exports = fp(async (fastify, options) => {
             options: pdfSchema,
             contentList: {
               type: 'array',
+              description: '要渲染的 HTML 内容列表，每一项生成一个文件',
               items: {
                 type: 'string'
               }
-            }
+            },
+            filename
           }
-        }
+        },
+        response: zipFile('PDF')
       }
     },
     async (request, reply) => {
@@ -85,8 +101,9 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.authenticate,
       schema: {
-        description: '接口说明',
+        tags: [PDF_TAG],
         summary: '批量将html生成pdf的zip文件流',
+        description: `把多段 HTML 分别渲染为PDF并打包为 zip 返回，数量不能超过插件配置 maxCacheKeys；GET 方式的 HTML 内容需先用 plantuml-encoder 压缩编码；${CACHE_HINT}`,
         query: {
           type: 'object',
           required: ['contentList'],
@@ -94,12 +111,15 @@ module.exports = fp(async (fastify, options) => {
             options: pdfSchema,
             contentList: {
               type: 'array',
+              description: `要渲染的 HTML 内容列表，每一项都是需先用 plantuml-encoder 的 encode 压缩编码的 HTML`,
               items: {
                 type: 'string'
               }
-            }
+            },
+            filename
           }
-        }
+        },
+        response: zipFile('PDF')
       }
     },
     async (request, reply) => {
@@ -117,8 +137,9 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.authenticate,
       schema: {
-        description: '接口说明',
+        tags: [PHOTO_TAG],
         summary: '批量将html生成png的zip文件流',
+        description: `把多段 HTML 分别渲染为图片并打包为 zip 返回，数量不能超过插件配置 maxCacheKeys；${CACHE_HINT}`,
         body: {
           type: 'object',
           required: ['contentList'],
@@ -126,12 +147,15 @@ module.exports = fp(async (fastify, options) => {
             options: photoSchema,
             contentList: {
               type: 'array',
+              description: '要渲染的 HTML 内容列表，每一项生成一个文件',
               items: {
                 type: 'string'
               }
-            }
+            },
+            filename
           }
-        }
+        },
+        response: zipFile('图片')
       }
     },
     async (request, reply) => {
@@ -149,8 +173,9 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.authenticate,
       schema: {
-        description: '接口说明',
+        tags: [PHOTO_TAG],
         summary: '批量将html生成png的zip文件流',
+        description: `把多段 HTML 分别渲染为图片并打包为 zip 返回，数量不能超过插件配置 maxCacheKeys；GET 方式的 HTML 内容需先用 plantuml-encoder 压缩编码；${CACHE_HINT}`,
         query: {
           type: 'object',
           required: ['contentList'],
@@ -158,12 +183,15 @@ module.exports = fp(async (fastify, options) => {
             options: photoSchema,
             contentList: {
               type: 'array',
+              description: `要渲染的 HTML 内容列表，每一项都是需先用 plantuml-encoder 的 encode 压缩编码的 HTML`,
               items: {
                 type: 'string'
               }
-            }
+            },
+            filename
           }
-        }
+        },
+        response: zipFile('图片')
       }
     },
     async (request, reply) => {
@@ -181,16 +209,19 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.authenticate,
       schema: {
-        description: '接口说明',
+        tags: [PHOTO_TAG],
         summary: 'html生成png文件流',
+        description: `用无头浏览器加载 HTML 内容并生成图片；${CACHE_HINT}`,
         body: {
           type: 'object',
           required: ['content'],
           properties: {
             options: photoSchema,
-            content: { type: 'string' }
+            content: { type: 'string', description: '要渲染的 HTML 内容' },
+            filename
           }
-        }
+        },
+        response: photoFile
       }
     },
     async (request, reply) => {
@@ -208,16 +239,19 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.authenticate,
       schema: {
-        description: '接口说明',
+        tags: [PHOTO_TAG],
         summary: 'html生成png文件流',
+        description: `用无头浏览器加载 HTML 内容并生成图片；GET 方式的 HTML 内容需先用 plantuml-encoder 压缩编码；${CACHE_HINT}`,
         query: {
           type: 'object',
           required: ['content'],
           properties: {
             options: photoSchema,
-            content: { type: 'string' }
+            content: { type: 'string', description: `要渲染${encodedContent}` },
+            filename
           }
-        }
+        },
+        response: photoFile
       }
     },
     async (request, reply) => {
@@ -235,16 +269,19 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.authenticate,
       schema: {
-        description: '接口说明',
+        tags: [PDF_TAG],
         summary: 'url生成pdf文件流',
+        description: `用无头浏览器打开网页地址（等待网络空闲）后生成PDF；${CACHE_HINT}`,
         body: {
           type: 'object',
           required: ['url'],
           properties: {
             options: pdfSchema,
-            url: { type: 'string' }
+            url: { type: 'string', description: '要打开的网页地址' },
+            filename
           }
-        }
+        },
+        response: pdfFile
       }
     },
     async (request, reply) => {
@@ -259,16 +296,19 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.authenticate,
       schema: {
-        description: '接口说明',
+        tags: [PDF_TAG],
         summary: 'url生成pdf文件流',
+        description: `用无头浏览器打开网页地址（等待网络空闲）后生成PDF；${CACHE_HINT}`,
         query: {
           type: 'object',
           required: ['url'],
           properties: {
             options: pdfSchema,
-            url: { type: 'string' }
+            url: { type: 'string', description: '要打开的网页地址' },
+            filename
           }
-        }
+        },
+        response: pdfFile
       }
     },
     async (request, reply) => {
@@ -278,21 +318,54 @@ module.exports = fp(async (fastify, options) => {
     }
   );
 
+  fastify.post(
+    `${options.prefix}/parseUrlToPdfBatch`,
+    {
+      onRequest: options.authenticate,
+      schema: {
+        tags: [PDF_TAG],
+        summary: 'url批量生成pdf的zip文件流',
+        description: `逐个打开网页地址生成PDF并打包为 zip 返回，数量不能超过插件配置 maxCacheKeys；${CACHE_HINT}`,
+        body: {
+          type: 'object',
+          required: ['urlList'],
+          properties: {
+            options: pdfSchema,
+            urlList: { type: 'array', items: { type: 'string' }, description: '要打开的网页地址列表，每一项生成一个文件' },
+            filename
+          }
+        },
+        response: zipFile('PDF')
+      }
+    },
+    async (request, reply) => {
+      const filename = await services.parseUrlToPdfBatch({
+        urlList: request.body.urlList,
+        options: request.body.options
+      });
+      request.body.filename && reply.header('Content-Disposition', `attachment; filename=${encodeURIComponent(request.body.filename)}`);
+      return reply.sendFile(filename, { root: options.root });
+    }
+  );
+
   fastify.get(
     `${options.prefix}/parseUrlToPdfBatch`,
     {
       onRequest: options.authenticate,
       schema: {
-        description: '接口说明',
-        summary: 'url生成pdf文件流',
+        tags: [PDF_TAG],
+        summary: 'url批量生成pdf的zip文件流',
+        description: `逐个打开网页地址生成PDF并打包为 zip 返回，数量不能超过插件配置 maxCacheKeys；${CACHE_HINT}`,
         query: {
           type: 'object',
           required: ['urlList'],
           properties: {
             options: pdfSchema,
-            urlList: { type: 'array', items: { type: 'string' } }
+            urlList: { type: 'array', items: { type: 'string' }, description: '要打开的网页地址列表，每一项生成一个文件' },
+            filename
           }
-        }
+        },
+        response: zipFile('PDF')
       }
     },
     async (request, reply) => {
@@ -310,17 +383,20 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.authenticate,
       schema: {
-        description: '接口说明',
+        tags: [PHOTO_TAG],
         summary: 'url生成png文件流',
+        description: `用无头浏览器打开网页地址（等待网络空闲）后生成图片；传 selector 时只截取该元素区域；${CACHE_HINT}`,
         body: {
           type: 'object',
           required: ['url'],
           properties: {
             options: photoSchema,
-            url: { type: 'string' },
-            selector: { type: 'string' }
+            url: { type: 'string', description: '要打开的网页地址' },
+            selector: { type: 'string', description: 'CSS 选择器；传入时等待该元素出现并只截取其区域，不传截取整个页面' },
+            filename
           }
-        }
+        },
+        response: photoFile
       }
     },
     async (request, reply) => {
@@ -339,17 +415,20 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.authenticate,
       schema: {
-        description: '接口说明',
+        tags: [PHOTO_TAG],
         summary: 'url生成png文件流',
+        description: `用无头浏览器打开网页地址（等待网络空闲）后生成图片；传 selector 时只截取该元素区域；${CACHE_HINT}`,
         query: {
           type: 'object',
           required: ['url'],
           properties: {
             options: photoSchema,
-            url: { type: 'string' },
-            selector: { type: 'string' }
+            url: { type: 'string', description: '要打开的网页地址' },
+            selector: { type: 'string', description: 'CSS 选择器；传入时等待该元素出现并只截取其区域，不传截取整个页面' },
+            filename
           }
-        }
+        },
+        response: photoFile
       }
     },
     async (request, reply) => {
@@ -368,17 +447,20 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.authenticate,
       schema: {
-        description: '接口说明',
-        summary: 'url生成png文件流',
+        tags: [PHOTO_TAG],
+        summary: 'url批量生成png的zip文件流',
+        description: `逐个打开网页地址生成图片并打包为 zip 返回，数量不能超过插件配置 maxCacheKeys。注意：当前实现实际调用的是 url 生成 PDF，压缩包内为 PDF 文件且 selector 不生效；${CACHE_HINT}`,
         body: {
           type: 'object',
           required: ['urlList'],
           properties: {
             options: photoSchema,
-            urlList: { type: 'array', items: { type: 'string' } },
-            selector: { type: 'string' }
+            urlList: { type: 'array', items: { type: 'string' }, description: '要打开的网页地址列表，每一项生成一个文件' },
+            selector: { type: 'string', description: 'CSS 选择器，只截取该元素区域（当前实现未生效，见接口说明）' },
+            filename
           }
-        }
+        },
+        response: zipFile('图片')
       }
     },
     async (request, reply) => {
@@ -397,17 +479,20 @@ module.exports = fp(async (fastify, options) => {
     {
       onRequest: options.authenticate,
       schema: {
-        description: '接口说明',
-        summary: 'url生成png文件流',
+        tags: [PHOTO_TAG],
+        summary: 'url批量生成png的zip文件流',
+        description: `逐个打开网页地址生成图片并打包为 zip 返回，数量不能超过插件配置 maxCacheKeys。注意：当前实现实际调用的是 url 生成 PDF，压缩包内为 PDF 文件且 selector 不生效；${CACHE_HINT}`,
         query: {
           type: 'object',
           required: ['urlList'],
           properties: {
             options: photoSchema,
-            urlList: { type: 'array', items: { type: 'string' } },
-            selector: { type: 'string' }
+            urlList: { type: 'array', items: { type: 'string' }, description: '要打开的网页地址列表，每一项生成一个文件' },
+            selector: { type: 'string', description: 'CSS 选择器，只截取该元素区域（当前实现未生效，见接口说明）' },
+            filename
           }
-        }
+        },
+        response: zipFile('图片')
       }
     },
     async (request, reply) => {

package/libs/schema/response.js

@@ -0,0 +1,13 @@
+// 接口均通过 reply.sendFile 返回文件流，响应 schema 只写说明、不声明类型，避免干扰输出
+const fileResponse = description => ({ 200: { description } });
+
+const DISPOSITION = '；请求传 filename 时附带 Content-Disposition: attachment 下载头';
+const pdfFile = fileResponse(`PDF 文件流（application/pdf）${DISPOSITION}`);
+const photoFile = fileResponse(`图片文件流，格式由 options.type 决定，默认 png${DISPOSITION}`);
+const zipFile = kind => fileResponse(`zip 压缩包文件流，按输入顺序包含每一项生成的${kind}${DISPOSITION}`);
+
+// filename 原本未声明、无类型约束，这里只补说明不加 type
+const filename = { description: '下载文件名；传入后响应附带 Content-Disposition: attachment 头，不传则浏览器按文件流直接展示' };
+const encodedContent = '的 HTML 内容，需先用 plantuml-encoder 的 encode 压缩编码后放入 query';
+
+module.exports = { fileResponse, pdfFile, photoFile, zipFile, filename, encodedContent };

package/libs/services.js

@@ -7,6 +7,7 @@ const createDeferred = require('@kne/create-deferred');
 
 const pdfSchema = {
   type: 'object',
+  description: 'PDF 生成参数，透传给 puppeteer page.pdf；不传 options 时按 A4、打印背景、显示页眉页脚生成，传了 options 则未填的项按各字段 default 填充',
   properties: {
     scale: {
       type: 'number',
@@ -61,6 +62,7 @@ const pdfSchema = {
     },
     margin: {
       type: 'object',
+      description: '页边距',
       properties: {
         top: {
           oneOf: [{ type: 'number' }, { type: 'string' }],
@@ -105,10 +107,11 @@ const pdfSchema = {
       description: '生成带标签的 PDF（增强可访问性）',
       default: false
     },
-    waitForMaxTime: { type: 'number' },
-    waitForVisible: { type: 'boolean' },
+    waitForMaxTime: { type: 'number', description: '等待 waitForSelector 元素的超时时间（毫秒），默认 10000；仅 url 类接口有效' },
+    waitForVisible: { type: 'boolean', description: '等待 waitForSelector 元素时是否要求元素可见；仅 url 类接口有效' },
     waitForSelector: {
-      oneOf: [{ type: 'array', items: { type: 'string' } }, { type: 'string' }]
+      oneOf: [{ type: 'array', items: { type: 'string' } }, { type: 'string' }],
+      description: '打开网页后、生成前需等待出现的 CSS 选择器（单个或数组）；注意当前实现读取的是 waitForSelectors，该参数实际未生效'
     },
     timezone: {
       type: 'string',
@@ -117,6 +120,7 @@ const pdfSchema = {
     },
     viewport: {
       type: 'object',
+      description: '浏览器视口尺寸，不传使用插件配置 pageWidth / pageHeight',
       properties: {
         width: {
           type: 'number',
@@ -136,6 +140,7 @@ const pdfSchema = {
 
 const photoSchema = {
   type: 'object',
+  description: '截图参数，透传给 puppeteer page.screenshot；不传 options 时按 png、仅可视区域截图，传了 options 则未填的项按各字段 default 填充（如 fullPage 为 true）',
   properties: {
     type: {
       type: 'string',
@@ -190,10 +195,11 @@ const photoSchema = {
       type: 'boolean',
       description: '是否捕获视口外的内容（仅当 fullPage 为 true 时有效）'
     },
-    waitForMaxTime: { type: 'number' },
-    waitForVisible: { type: 'boolean' },
+    waitForMaxTime: { type: 'number', description: '等待 waitForSelector 元素的超时时间（毫秒），默认 10000；仅 url 类接口有效' },
+    waitForVisible: { type: 'boolean', description: '等待 waitForSelector 元素时是否要求元素可见；仅 url 类接口有效' },
     waitForSelector: {
-      oneOf: [{ type: 'array', items: { type: 'string' } }, { type: 'string' }]
+      oneOf: [{ type: 'array', items: { type: 'string' } }, { type: 'string' }],
+      description: '打开网页后、生成前需等待出现的 CSS 选择器（单个或数组）；注意当前实现读取的是 waitForSelectors，该参数实际未生效'
     },
     timezone: {
       type: 'string',
@@ -202,6 +208,7 @@ const photoSchema = {
     },
     viewport: {
       type: 'object',
+      description: '浏览器视口尺寸，不传使用插件配置 pageWidth / pageHeight',
       properties: {
         width: {
           type: 'number',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kne/fastify-puppeteer",
-  "version": "1.1.9",
+  "version": "1.1.11",
   "description": "用于操作无头浏览器截图保存pdf等",
   "main": "index.js",
   "scripts": {