链接提取接口
目录
简介
本接口用于从输入内容中提取链接信息，当前版本实现为“多值返回变成单值返回”的直通逻辑，即直接返回输入内容，不做额外处理。接口遵循统一的请求/响应模型与错误处理机制，便于在内容处理流程中作为上游数据清洗与标准化环节使用。
项目结构
与链接提取接口相关的模块分布如下：
- 文档层：接口文档位于 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
graph TB
A["应用入口<br/>main.py"] --> B["路由注册<br/>/openapi/capcut-mate/v1"]
B --> C["路由分发<br/>src/router/v1.py"]
C --> D["业务服务<br/>src/service/get_url.py"]
C --> E["数据模型<br/>src/schemas/get_url.py"]
D --> F["日志记录<br/>src/utils/logger.py"]
D --> G["异常处理<br/>exceptions.py"]
C --> H["统一响应中间件<br/>src/middlewares/response.py"]
A --> I["准备中间件<br/>src/middlewares/prepare.py"]
核心组件
- 接口路径与方法
- HTTP 方法：POST
- 路径：/openapi/capcut-mate/v1/get_url
- 请求模型
- 字段：output（字符串，必填）
- 响应模型
- 字段：output（字符串）
- 业务逻辑
- 当前版本：直接返回输入的 output，不做链接识别与提取
- 设计意图：为后续扩展“链接识别与提取”能力预留接口形态
架构总览
下图展示了从客户端请求到响应返回的完整链路，包括路由、服务层、日志与异常处理的协作关系。
sequenceDiagram
participant Client as "客户端"
participant Router as "路由层<br/>src/router/v1.py"
participant Service as "服务层<br/>src/service/get_url.py"
participant Logger as "日志<br/>src/utils/logger.py"
participant Exceptions as "异常<br/>exceptions.py"
participant Middleware as "统一响应中间件<br/>src/middlewares/response.py"
Client->>Router : POST /openapi/capcut-mate/v1/get_url
Router->>Service : 调用 get_url(output)
Service->>Logger : 记录开始与结果
Service-->>Router : 返回 output
Router-->>Middleware : 包装为统一响应
Middleware-->>Client : {code, message, output}
Note over Service,Exceptions : 异常时抛出自定义异常，由中间件统一处理
详细组件分析
路由与端点
- 路由定义
- 路径：/openapi/capcut-mate/v1/get_url
- 方法：POST
- 响应模型：GetUrlResponse
- 控制器职责
- 从请求体中接收 GetUrlRequest
- 调用 service.get_url 并返回 GetUrlResponse
数据模型
- 请求模型 GetUrlRequest
- 字段：output（字符串，必填）
- 响应模型 GetUrlResponse
- 字段：output（字符串）
classDiagram
class GetUrlRequest {
+string output
}
class GetUrlResponse {
+string output
}
业务逻辑
- 函数签名：get_url(output: str) -> str
- 行为说明
- 记录开始与结束日志
- 直接返回输入的 output
- 发生异常时抛出自定义异常（UNKNOWN_ERROR）
- 当前实现特点
- 无链接识别与提取逻辑
- 为后续扩展“链接识别与提取”预留接口形态
flowchart TD
Start(["函数入口"]) --> LogStart["记录开始日志"]
LogStart --> TryBlock["执行业务逻辑"]
TryBlock --> DirectReturn["直接返回输入 output"]
DirectReturn --> LogEnd["记录成功日志"]
LogEnd --> End(["函数退出"])
TryBlock --> |异常| Catch["捕获异常并抛出自定义异常"]
Catch --> End
错误处理与日志
- 日志
- 使用统一日志配置，记录请求与结果
- 异常
- 自定义异常类型与错误码枚举
- 业务异常由统一响应中间件转换为标准响应格式
- 统一响应中间件
- 成功响应：包装为 {code, message, ...}
- 非200响应：统一错误格式
- 422参数校验错误：提取字段级错误信息
中间件与应用入口
- 应用入口
- 创建 FastAPI 实例，注册路由与中间件
- 中间件
- PrepareMiddleware：确保必要目录存在
- ResponseMiddleware：统一响应与异常处理
依赖关系分析
- 组件耦合
- 路由层依赖服务层与数据模型
- 服务层依赖日志与异常模块
- 应用入口依赖路由与中间件
- 外部依赖
- FastAPI（路由与中间件）
- Pydantic（数据模型）
- Python 标准库（logging、json 等）
graph LR
Router["路由层<br/>src/router/v1.py"] --> Service["服务层<br/>src/service/get_url.py"]
Router --> Schema["数据模型<br/>src/schemas/get_url.py"]
Service --> Logger["日志<br/>src/utils/logger.py"]
Service --> Exceptions["异常<br/>exceptions.py"]
App["应用入口<br/>main.py"] --> Router
App --> PrepareMW["准备中间件<br/>src/middlewares/prepare.py"]
App --> ResponseMW["统一响应中间件<br/>src/middlewares/response.py"]
性能考虑
- 当前实现为直通逻辑，无复杂计算，延迟极低
- 建议在扩展链接识别功能时：
- 使用高效的正则表达式或解析库
- 对超长输入进行分块处理
- 结合缓存策略减少重复处理
- 日志级别与格式已优化，避免在高频场景中产生过多 I/O
故障排查指南
- 常见问题与定位
- 参数缺失：422 参数校验错误会被统一响应中间件转换为标准格式
- 业务异常：服务层抛出的自定义异常会被中间件转换为 {code, message}
- 服务器异常：未知异常会被转换为内部错误
- 排查步骤
- 检查请求体是否符合 GetUrlRequest 模型
- 查看服务层日志以确认输入与输出
- 关注中间件对非200与422响应的统一处理
结论
当前链接提取接口以“直通返回”为核心行为，满足“多值返回变成单值返回”的设计目标。其清晰的路由、模型与中间件架构为后续扩展链接识别与提取能力提供了良好基础。建议在保持现有接口不变的前提下，逐步引入链接识别算法与标准化流程，以提升内容处理流程的自动化与一致性。
附录
接口定义与使用示例
- 接口信息
- 方法：POST
- 路径：/openapi/capcut-mate/v1/get_url
- 请求参数
- output：字符串，必填
- 响应字段
- output：字符串
- 错误码
- 400：参数校验失败（如缺少 output）
- 500：内部错误（未知异常）
