kooldev/pdf

PDF微服务

概述

PDF微服务是一个用于生成PDF的微服务，可轻松集成到基于kool和docker-compose的环境中，支持从任意URL或给定的HTML内容生成PDF文件。

核心功能与特性

• 从URL或HTML内容生成PDF
• 支持自定义PDF生成选项（基于puppeteer）
• 易于集成到docker-compose环境
• 提供健康检查接口
• 轻量级API设计，便于快速调用

使用场景与适用范围

适用于需要在项目中快速添加PDF生成功能的场景，如：

• Web应用中的报告生成
• 动态内容转换为PDF文档
• 自动化生成PDF格式的票据、合同等
• 基于docker-compose或kool的开发/生产环境

使用方法

在项目中集成使用

如果使用Docker Compose（建议配合https://github.com/kool-dev/kool%E7%AE%80%E5%8C%96%E6%93%8D%E4%BD%9C%EF%BC%89%EF%BC%8C%E5%8F%AA%E9%9C%80%E5%87%A0%E6%AD%A5%E5%8D%B3%E5%8F%AF%E5%9C%A8%E9%A1%B9%E7%9B%AE%E4%B8%AD%E6%B7%BB%E5%8A%A0PDF%E7%94%9F%E6%88%90%E5%8A%9F%E8%83%BD%EF%BC%9A

1. 在docker-compose.yml中添加服务：

yaml
  pdf:
    image: "kooldev/pdf:latest"
    expose:
      - 3000

2. 启动服务容器（使用kool start或docker-compose up -d）后，即可开始使用微服务生成PDF。以下是PHP调用示例：

php
use GuzzleHttp\Client;

$pdf = (new Client())->post('http://pdf_dev/from-html', [
    'form_params' => [
        'html' => '<h1>这是我想要转换为PDF的超酷HTML内容！</h1> <p>这是一个简单示例，但您可以看到其强大之处 <b>:)</b> </p>',
        'options' => json_encode([
            'format' => 'A4',
            'printBackground' => false,
        ]),
    ],
])->getBody();

file_put_contents('path/to/my/super-kool.pdf', $pdf);

注意：上述代码假设从同一Docker Compose应用中的另一个容器运行，因此pdf域名会解析到微服务。options参数应为JSON格式，所有可用选项可参考https://github.com/puppeteer/puppeteer/blob/main/docs/api.md#pagepdfoptions%E3%80%82

本地开发

要在本地开发此微服务（需使用https://github.com/kool-dev/kool%EF%BC%89%EF%BC%9A

1. Fork仓库并克隆到本地
2. 安装依赖：kool run yarn install
3. 启动API服务：kool start（服务将运行在localhost:3000）
4. 查看日志：docker-compose logs -f

提示：管理依赖和运行命令时，请使用kool run yarn以确保使用统一的yarn版本。

API接口

微服务提供以下API端点用于生成PDF并即时返回结果：

从URL生成PDF

• 端点：GET /from-url?url=
• 参数：url - 需要转换为PDF的页面URL
• 返回：生成的PDF文件，或包含错误信息和状态的JSON

从HTML生成PDF

• 端点：POST /from-html
• 参数：
  • html - 需要转换为PDF的HTML内容
  • options - JSON格式的PDF生成选项（参考https://github.com/puppeteer/puppeteer/blob/main/docs/api.md#pagepdfoptions%EF%BC%89
• 返回：生成的PDF文件，或包含错误信息和状态的JSON

健康检查

• 端点：GET /health
• 返回：JSON格式的当前状态，状态码为200（活跃）或503（未就绪）

路线图

即将添加的功能：

• 更好地控制JavaScript执行/等待条件的参数
• 支持转换为图片格式
• 如有其他需求，欢迎提交issue建议！