【剪映小助手】链接提取接口

链接提取接口

简介

本接口用于从输入内容中提取链接信息，当前版本实现为"多值返回变成单值返回"的直通逻辑，即直接返回输入内容，不做额外处理。接口遵循统一的请求/响应模型与错误处理机制，便于在内容处理流程中作为上游数据清洗与标准化环节使用。

项目结构

与链接提取接口相关的模块分布如下：

文档层：接口文档位于 docs/get_url.md
路由层：FastAPI 路由定义于 src/router/v1.py
业务层：链接提取逻辑位于 src/service/get_url.py
数据模型：请求/响应模型位于 src/schemas/get_url.py
异常与日志：异常定义位于 exceptions.py，日志配置位于 src/utils/logger.py
中间件：统一响应处理与准备中间件位于 src/middlewares/response.py 与 src/middlewares/prepare.py
应用入口：FastAPI 应用与路由挂载位于 main.py

应用入口

main.py
路由注册

/openapi/capcut-mate/v1
路由分发

src/router/v1.py
业务服务

src/service/get_url.py
数据模型

src/schemas/get_url.py
日志记录

src/utils/logger.py
异常处理

exceptions.py
统一响应中间件

src/middlewares/response.py
准备中间件

src/middlewares/prepare.py

核心组件

接口路径与方法
- HTTP 方法：POST
- 路径：/openapi/capcut-mate/v1/get_url
请求模型
- 字段：output（字符串，必填）
响应模型
- 字段：output（字符串）
业务逻辑
- 当前版本：直接返回输入的 output，不做链接识别与提取
- 设计意图：为后续扩展"链接识别与提取"能力预留接口形态

架构总览

下图展示了从客户端请求到响应返回的完整链路，包括路由、服务层、日志与异常处理的协作关系。
"统一响应中间件 src/middlewares/response.py" "异常 exceptions.py" "日志 src/utils/logger.py" "服务层 src/service/get_url.py" "路由层 src/router/v1.py" "客户端" "统一响应中间件 src/middlewares/response.py" "异常 exceptions.py" "日志 src/utils/logger.py" "服务层 src/service/get_url.py" "路由层 src/router/v1.py" "客户端" 异常时抛出自定义异常，由中间件统一处理 POST /openapi/capcut-mate/v1/get_url 调用 get_url(output) 记录开始与结果返回 output 包装为统一响应 {code, message, output}

详细组件分析

路由与端点

路由定义
- 路径：/openapi/capcut-mate/v1/get_url
- 方法：POST
- 响应模型：GetUrlResponse
控制器职责
- 从请求体中接收 GetUrlRequest
- 调用 service.get_url 并返回 GetUrlResponse

数据模型

请求模型 GetUrlRequest
- 字段：output（字符串，必填）
响应模型 GetUrlResponse
- 字段：output（字符串）

GetUrlRequest
+string output
GetUrlResponse
+string output

业务逻辑

函数签名：get_url(output: str) -> str
行为说明
- 记录开始与结束日志
- 直接返回输入的 output
- 发生异常时抛出自定义异常（UNKNOWN_ERROR）
当前实现特点
- 无链接识别与提取逻辑
- 为后续扩展"链接识别与提取"预留接口形态

异常
函数入口
记录开始日志
执行业务逻辑
直接返回输入 output
记录成功日志
函数退出
捕获异常并抛出自定义异常

错误处理与日志

日志
- 使用统一日志配置，记录请求与结果
异常
- 自定义异常类型与错误码枚举
- 业务异常由统一响应中间件转换为标准响应格式
统一响应中间件
- 成功响应：包装为 {code, message, ...}
- 非200响应：统一错误格式
- 422参数校验错误：提取字段级错误信息

中间件与应用入口

应用入口
- 创建 FastAPI 实例，注册路由与中间件
中间件
- PrepareMiddleware：确保必要目录存在
- ResponseMiddleware：统一响应与异常处理

依赖关系分析

组件耦合
- 路由层依赖服务层与数据模型
- 服务层依赖日志与异常模块
- 应用入口依赖路由与中间件
外部依赖
- FastAPI（路由与中间件）
- Pydantic（数据模型）
- Python 标准库（logging、json 等）

路由层

src/router/v1.py
服务层

src/service/get_url.py
数据模型

src/schemas/get_url.py
日志

src/utils/logger.py
异常

exceptions.py
应用入口

main.py
准备中间件

src/middlewares/prepare.py
统一响应中间件

src/middlewares/response.py

性能考虑

当前实现为直通逻辑，无复杂计算，延迟极低
建议在扩展链接识别功能时：
- 使用高效的正则表达式或解析库
- 对超长输入进行分块处理
- 结合缓存策略减少重复处理
日志级别与格式已优化，避免在高频场景中产生过多 I/O

故障排查指南

常见问题与定位
- 参数缺失：422 参数校验错误会被统一响应中间件转换为标准格式
- 业务异常：服务层抛出的自定义异常会被中间件转换为 {code, message}
- 服务器异常：未知异常会被转换为内部错误
排查步骤
- 检查请求体是否符合 GetUrlRequest 模型
- 查看服务层日志以确认输入与输出
- 关注中间件对非200与422响应的统一处理

结论

当前链接提取接口以"直通返回"为核心行为，满足"多值返回变成单值返回"的设计目标。其清晰的路由、模型与中间件架构为后续扩展链接识别与提取能力提供了良好基础。建议在保持现有接口不变的前提下，逐步引入链接识别算法与标准化流程，以提升内容处理流程的自动化与一致性。

附录

接口定义与使用示例

接口信息
- 方法：POST
- 路径：/openapi/capcut-mate/v1/get_url
请求参数
- output：字符串，必填
响应字段
- output：字符串
错误码
- 400：参数校验失败（如缺少 output）
- 500：内部错误（未知异常）

文档信息

接口文档： docs.jcaigc.cn
效果案例： www.jcaigc.cn/workflow
开源仓库： capcut-mate