BookLore电子书格式转换API：开发自定义转换工具的接口指南-优快云博客

BookLore电子书格式转换API：开发自定义转换工具的接口指南

【免费下载链接】BookLore BookLore is a web app for hosting and managing books on a home server. It allows users to view PDFs, eBooks, and track reading progress. With features like metadata management and reading stats, BookLore provides an easy way to organize and explore your personal library. 项目地址: https://gitcode.com/GitHub_Trending/bo/BookLore

概述

BookLore作为一款家庭服务器电子书管理系统，提供了丰富的API接口来支持电子书格式转换功能。本文将详细介绍如何利用这些接口开发自定义转换工具，实现PDF、ePub等格式的相互转换，以及与系统的无缝集成。

API基础架构

接口设计原则

BookLore的API遵循RESTful设计规范，所有转换相关接口均以/api/v1/convert为基础路径。系统采用JSON格式进行数据交换，标准响应结构如下：

{
  "success": true,
  "data": {},
  "message": "操作成功",
  "timestamp": 1620000000000
}

核心配置定义在booklore-ui/src/app/config/api-config.ts中，包含基础URL和超时设置：

export const API_CONFIG = {
  BASE_URL: 'http://localhost:8080',
  TIMEOUT: 30000
};

认证机制

所有转换API均需要认证，支持JWT令牌认证方式。在请求头中添加：

Authorization: Bearer {your_token}

认证相关实现可参考booklore-ui/src/app/core/service/auth.service.ts。

格式转换核心接口

转换任务创建

请求: POST /api/v1/convert

请求体:

{
  "sourceFileId": "123e4567-e89b-12d3-a456-426614174000",
  "targetFormats": ["epub", "mobi"],
  "options": {
    "quality": "high",
    "compress": true
  }
}

响应:

{
  "success": true,
  "data": {
    "taskId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "estimatedTime": 120
  }
}

转换任务状态查询

请求: GET /api/v1/convert/{taskId}

响应:

{
  "success": true,
  "data": {
    "taskId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "status": "PROCESSING",
    "progress": 65,
    "resultFiles": []
  }
}

自定义转换工具开发

接口调用流程

获取文件信息：调用GET /api/v1/files/{fileId}获取源文件元数据
创建转换任务：使用上述转换任务创建接口
轮询任务状态：定期查询任务进度
获取转换结果：任务完成后获取输出文件URL

错误处理机制

系统定义了以下与转换相关的错误码：

错误码	描述	解决方案
4001	不支持的源格式	检查源文件格式是否在支持列表中
4002	转换资源不足	尝试降低转换质量或分批次处理
4003	格式转换失败	检查源文件完整性或尝试其他转换选项

错误处理实现可参考booklore-ui/src/app/core/service/toast.service.ts。

高级功能

批量转换接口

请求: POST /api/v1/convert/batch

请求体:

{
  "sourceFileIds": ["123e4567-e89b-12d3-a456-426614174000", "123e4567-e89b-12d3-a456-426614174001"],
  "targetFormat": "pdf",
  "options": {
    "quality": "medium"
  }
}

WebSocket通知

客户端可通过WebSocket接收实时转换进度通知，连接地址：ws://localhost:8080/ws/convert/{taskId}

实际应用示例

以下是一个使用TypeScript实现的转换工具示例：

import { HttpClient } from '@angular/common/http';
import { API_CONFIG } from './config/api-config';

export class ConvertService {
  constructor(private http: HttpClient) {}
  
  createConvertTask(sourceFileId: string, targetFormats: string[]) {
    return this.http.post(`${API_CONFIG.BASE_URL}/api/v1/convert`, {
      sourceFileId,
      targetFormats
    });
  }
  
  getTaskStatus(taskId: string) {
    return this.http.get(`${API_CONFIG.BASE_URL}/api/v1/convert/${taskId}`);
  }
}

扩展与集成

自定义格式支持

要添加新的转换格式，需实现以下两个接口：

转换器接口：booklore-api/src/main/java/com/adityachandel/booklore/service/convert/Converter.java
格式检测器：booklore-api/src/main/java/com/adityachandel/booklore/service/detect/FormatDetector.java

与存储系统集成

转换后的文件默认存储在本地文件系统，可通过实现booklore-api/src/main/java/com/adityachandel/booklore/service/storage/StorageService.java接口将其集成到S3、FTP等外部存储系统。

部署与配置

服务端配置

转换服务的配置文件位于booklore-api/src/main/resources/application.properties，关键配置项：

# 转换服务配置
convert.enabled=true
convert.max-parallel-tasks=5
convert.timeout-minutes=30

# 格式支持配置
convert.supported-formats=pdf,epub,mobi,cbz

资源需求

CPU：至少4核心（转换为CPU密集型操作）
内存：每并发任务建议2GB
存储空间：根据预期转换文件数量配置，建议至少100GB可用空间

总结

BookLore提供了强大的电子书格式转换API，支持自定义转换工具的开发与集成。通过本文介绍的接口，开发者可以快速构建符合个人需求的转换工具，扩展系统的格式支持能力。无论是简单的格式转换，还是复杂的批量处理，BookLore的API都能提供稳定可靠的基础支持。

更多API细节可参考官方文档：docs/forward-auth-with-proxy.md

附录：支持的格式矩阵

源格式	目标格式	支持程度	转换时间估计
PDF	ePub	★★★★☆	中
ePub	PDF	★★★☆☆	长
MOBI	ePub	★★★★★	短
CBZ	PDF	★★★★☆	中
PDF	MOBI	★★☆☆☆	长

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考