【剪映小助手源码精讲】19_草稿管理服务

第十九章：草稿管理服务

概述

草稿管理服务是剪映小助手的核心功能模块，负责剪映草稿文件的创建、获取、保存等全生命周期管理。该服务通过统一的接口封装了复杂的草稿文件操作，为上层业务提供了简洁可靠的草稿管理能力。

核心功能

1. 草稿创建服务

草稿创建服务负责根据指定的宽度和高度参数创建新的剪映草稿文件，并生成唯一的草稿ID。

核心实现

from src.utils.logger import logger
import config
import src.pyJianYingDraft as draft
from src.utils.draft_cache import update_cache
from exceptions import CustomException, CustomError
import datetime
import uuid

def create_draft(width: int, height: int) -> str:
    """
    创建剪映草稿的业务逻辑
    
    Args:
        width: 草稿宽度
        height: 草稿高度
    
    Returns:
        draft_url: 草稿URL

    Raises:
        CustomException: 草稿创建失败
    """
    # 生成一个草稿ID
    timestamp = datetime.datetime.now().strftime("%Y%m%d%H%M%S")
    unique_id = uuid.uuid4().hex[:8]
    draft_id = f"{timestamp}{unique_id}"
    logger.info(f"draft_id: {draft_id}, width: {width}, height: {height}")

    draft_folder = draft.Draft_folder(config.DRAFT_DIR)

    # 创建剪映草稿
    try:
        script = draft_folder.create_draft(draft_id, width, height, allow_replace=True)        
    except Exception as e:
        logger.error(f"create draft failed: {e}")
        raise CustomException(CustomError.DRAFT_CREATE_FAILED)

    # 缓存草稿
    update_cache(draft_id, script)

    logger.info(f"create draft success: {draft_id}")
    return config.DRAFT_URL + "?draft_id=" + draft_id

关键特性

• 唯一ID生成：结合时间戳和UUID生成全局唯一的草稿ID
• 异常处理：捕获草稿创建过程中的异常，转换为统一的业务异常
• 缓存机制：创建成功后立即更新缓存，提升后续访问性能
• 日志记录：详细记录草稿创建的关键信息，便于问题追踪

2. 草稿获取服务

草稿获取服务负责根据草稿ID获取草稿文件列表，并生成可访问的下载URL。

核心实现

from exceptions import CustomException, CustomError
from src.utils.logger import logger
from src.utils import helper
from typing import List
import config
import os

def gen_download_url(file_path: str) -> str:
    """
    生成下载URL，将文件路径中的/app/替换成DOWNLOAD_URL
    
    Args:
        file_path: 文件路径
    
    Returns:
        download_url: 下载URL
    """
    # 替换文件路径中的/app/为DOWNLOAD_URL
    download_url = file_path.replace("/app/", config.DOWNLOAD_URL)
    return download_url

def batch_gen_download_url(file_paths: List[str]) -> List[str]:
    """
    批量生成下载URL
    
    Args:
        file_paths: 文件路径列表
    
    Returns:
        download_urls: 下载URL列表
    """
    download_urls = []
    for file_path in file_paths:
        download_url = gen_download_url(file_path)
        download_urls.append(download_url)
    return download_urls

def get_draft(draft_id: str) -> List[str]:
    """
    获取剪映草稿的业务逻辑
    
    Args:
        draft_url: 草稿URL
    
    Returns:
        files: 文件列表

    Raises:
        CustomException: 自定义异常
    """

    # 1. 从URL中提取草稿ID
    if not draft_id:
        logger.info("draft_id is empty")
        raise CustomException(CustomError.INVALID_DRAFT_URL)

    draft_dir = os.path.join(config.DRAFT_DIR, draft_id)
    if not os.path.exists(draft_dir):
        logger.info(f"draft_dir not exists: {draft_dir}")
        raise CustomException(CustomError.INVALID_DRAFT_URL)
    
    # 2. 从草稿目录中获取文件列表
    files = helper.get_all_files(draft_dir)

    # 3. 批量生成下载URL
    download_urls = batch_gen_download_url(files)

    logger.info(f"get draft success: {draft_id}, download urls: {download_urls}")
    return download_urls

关键特性

• 参数验证：严格验证草稿ID的有效性
• 路径检查：检查草稿目录是否存在，确保数据完整性
• URL转换：智能地将本地文件路径转换为可访问的下载URL
• 批量处理：支持批量生成下载URL，提升处理效率

3. 草稿保存服务

草稿保存服务负责将缓存中的草稿数据持久化到磁盘，确保数据的安全性和一致性。

核心实现

from src.utils.logger import logger
import src.pyJianYingDraft as draft
from src.utils.draft_cache import DRAFT_CACHE
from src.utils import helper
from exceptions import CustomException, CustomError
import config
import os


def save_draft(draft_url: str) -> str:
    """
    保存剪映草稿的业务逻辑
    
    Args:
        draft_url: 草稿URL
    
    Returns:
        draft_url: 草稿URL
        message: 响应消息，如果成功就返回"草稿保存成功"，失败就返回具体错误信息
    """

    # 从URL中提取草稿ID
    draft_id = helper.get_url_param(draft_url, "draft_id")
    if (not draft_id) or (draft_id not in DRAFT_CACHE):
        logger.info("invalid draft url: %s", draft_url)
        raise CustomException(CustomError.INVALID_DRAFT_URL)

    # 从缓存中获取草稿
    script = DRAFT_CACHE[draft_id]

    # 保存草稿
    script.save()

    logger.info(f"save draft success: %s", os.path.join(config.DRAFT_DIR, draft_id))
    return draft_url

关键特性

• 缓存依赖：依赖草稿缓存机制，确保数据的一致性
• 参数解析：从URL中准确提取草稿ID参数
• 异常处理：对无效URL进行严格的异常处理
• 持久化操作：调用底层ScriptFile的save方法完成数据持久化

缓存集成

草稿管理服务深度集成了缓存机制，通过src.utils.draft_cache模块实现高效的草稿数据管理。

缓存更新机制

# 在草稿创建时更新缓存
update_cache(draft_id, script)

# 在草稿获取时验证缓存
if draft_id not in DRAFT_CACHE:
    raise CustomException(CustomError.INVALID_DRAFT_URL)

缓存数据结构

# 全局草稿缓存，使用OrderedDict实现LRU策略
DRAFT_CACHE: OrderedDict[str, draft.ScriptFile] = OrderedDict()

# 缓存大小限制
MAX_CACHE_SIZE = 10000

错误处理

草稿管理服务采用统一的异常处理机制，通过exceptions模块定义了标准化的错误类型。

异常类型

• DRAFT_CREATE_FAILED：草稿创建失败
• INVALID_DRAFT_URL：无效的草稿URL
• DRAFT_NOT_FOUND：草稿未找到

异常处理策略

try:
    script = draft_folder.create_draft(draft_id, width, height, allow_replace=True)
except Exception as e:
    logger.error(f"create draft failed: {e}")
    raise CustomException(CustomError.DRAFT_CREATE_FAILED)

日志记录

草稿管理服务通过src.utils.logger模块实现了完善的日志记录机制。

日志级别

• INFO：记录关键业务操作信息
• ERROR：记录异常和错误信息
• DEBUG：记录详细的调试信息（开发模式）

日志内容

logger.info(f"draft_id: {draft_id}, width: {width}, height: {height}")
logger.error(f"create draft failed: {e}")
logger.info(f"get draft success: {draft_id}, download urls: {download_urls}")

配置依赖

草稿管理服务依赖多个配置项，通过config模块统一管理。

核心配置

DRAFT_DIR = "/app/draft"          # 草稿存储目录
DRAFT_URL = "http://localhost:8080/draft"  # 草稿访问URL
DOWNLOAD_URL = "http://localhost:8080/download"  # 文件下载URL

配置管理

• 集中管理：所有配置项集中在config模块中
• 环境隔离：支持不同环境的配置切换
• 动态加载：支持运行时配置更新

性能优化

缓存策略

• LRU淘汰：使用OrderedDict实现最近最少使用淘汰策略
• 批量操作：支持批量URL生成，减少循环开销
• 内存管理：设置合理的缓存大小限制，防止内存溢出

异常优化

• 提前返回：在参数验证阶段尽早发现异常
• 异常转换：将底层异常转换为业务异常，提升可读性
• 日志优化：记录关键信息，避免冗余日志

安全性考虑

输入验证

• 参数检查：严格验证输入参数的合法性
• 路径检查：检查文件路径的有效性，防止路径穿越攻击
• URL验证：验证URL格式和内容的有效性

数据保护

• 异常信息：避免在异常信息中暴露敏感数据
• 日志脱敏：在日志中脱敏处理敏感信息
• 访问控制：通过URL签名等方式控制访问权限

扩展性设计

接口设计

• 统一接口：提供统一的草稿管理接口
• 参数标准化：使用标准化的参数格式和命名规范
• 返回值规范：定义统一的返回值格式

模块化设计

• 职责分离：将创建、获取、保存功能分离到不同模块
• 依赖注入：通过配置和参数注入依赖，提升可测试性
• 插件机制：支持自定义草稿处理插件

最佳实践

使用示例

# 创建草稿
draft_url = create_draft(1920, 1080)

# 获取草稿文件列表
files = get_draft(draft_id)

# 保存草稿
saved_url = save_draft(draft_url)

注意事项

1. 异常处理：始终捕获并处理可能的业务异常
2. 日志记录：记录关键操作信息，便于问题追踪
3. 缓存管理：合理使用缓存，避免内存溢出
4. 配置管理：使用统一的配置管理，避免硬编码
5. 性能监控：监控服务性能，及时发现瓶颈

总结

草稿管理服务通过统一的接口封装了复杂的草稿文件操作，提供了创建、获取、保存等核心功能。服务深度集成了缓存机制、异常处理和日志记录，确保了数据的一致性、可靠性和可追溯性。通过合理的配置管理、性能优化和安全性考虑，草稿管理服务为剪映小助手提供了稳定可靠的草稿管理能力。

---

相关资源

• GitHub代码仓库: https://github.com/Hommy-master/capcut-mate
• Gitee代码仓库: https://gitee.com/taohongmin-gitee/capcut-mate
• API文档地址: https://docs.jcaigc.cn