链接提取接口

目录

1. 简介
2. 项目结构
3. 核心组件
4. 架构总览
5. 详细组件分析
6. 依赖关系分析
7. 性能考虑
8. 故障排查指南
9. 结论
10. 附录

简介

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

项目结构

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

• 文档层：接口文档位于 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

核心组件

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

架构总览

下图展示了从客户端请求到响应返回的完整链路，包括路由、服务层、日志与异常处理的协作关系。

详细组件分析

路由与端点

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

数据模型

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

业务逻辑

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

错误处理与日志

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

中间件与应用入口

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

依赖关系分析

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

性能考虑

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