123 lines
4.5 KiB
Markdown
123 lines
4.5 KiB
Markdown
# 短链接生成API Spec
|
|
|
|
## Why
|
|
当前系统缺少短链接生成功能，用户无法将长URL转换为便于分享的短链接。需要开发短链接生成API后端及前端API详情页，提供链接缩短、自定义短码、过期设置和点击统计能力。
|
|
|
|
## What Changes
|
|
|
|
### 后端变更
|
|
- 新增 `shorturl/` Django应用，实现短链接生成和管理API
|
|
- 使用自增ID+Base62编码生成短码，支持自定义短码
|
|
- 数据模型存储：短码、原始URL、自定义短码、过期时间、创建者、点击次数
|
|
- 支持链接过期和访问次数统计
|
|
- 添加Swagger文档支持
|
|
- 注册URL路由 `/api/shorturl/`
|
|
|
|
### 前端变更
|
|
- 新增 `ShortUrlDetail` 页面，提供API文档和在线测试功能
|
|
- 包含API文档标签页和在线测试标签页
|
|
- 支持输入长URL、自定义短码、设置过期时间
|
|
- 显示生成的短链接和二维码
|
|
- 添加路由配置
|
|
|
|
## Impact
|
|
- Affected specs: 无
|
|
- Affected code:
|
|
- `chunyu_project/shorturl/` (新增Django应用)
|
|
- `chunyu_project/api/urls.py` (修改，添加shorturl路由)
|
|
- `chunyu_project_react/src/pages/ShortUrlDetail/` (新增)
|
|
- `chunyu_project_react/src/utils/request.ts` (修改，添加shorturl API)
|
|
- `chunyu_project_react/src/App.tsx` (修改，添加路由)
|
|
|
|
## ADDED Requirements
|
|
|
|
### Requirement: 短链接生成API
|
|
系统SHALL提供短链接生成API，支持将长URL转换为短链接。
|
|
|
|
#### Scenario: 成功生成短链接
|
|
- **WHEN** 用户发送 POST 请求到 `/api/shorturl/shorten/`，携带有效的 `url` 参数
|
|
- **THEN** 系统返回 200 状态码及生成的短链接信息（短码、短链接URL、原始URL、过期时间）
|
|
|
|
#### Scenario: 自定义短码
|
|
- **WHEN** 用户发送 POST 请求时携带 `custom_code` 参数
|
|
- **THEN** 系统使用用户指定的短码，若已被占用则返回 409 冲突错误
|
|
|
|
#### Scenario: 设置过期时间
|
|
- **WHEN** 用户发送 POST 请求时携带 `expire_days` 参数
|
|
- **THEN** 系统记录该短链接的过期时间
|
|
|
|
#### Scenario: URL格式校验
|
|
- **WHEN** 用户发送 POST 请求时携带无效的URL格式
|
|
- **THEN** 系统返回 400 错误提示
|
|
|
|
#### Scenario: 短码已存在
|
|
- **WHEN** 用户自定义的短码已被其他链接使用
|
|
- **THEN** 系统返回 409 错误及提示信息
|
|
|
|
### Requirement: 短链接解析API
|
|
系统SHALL提供短链接解析API，支持通过短码获取原始URL信息。
|
|
|
|
#### Scenario: 查询短链接信息
|
|
- **WHEN** 用户发送 GET 请求到 `/api/shorturl/info/<code>/`
|
|
- **THEN** 系统返回该短码对应的原始URL、创建时间、点击次数、过期时间
|
|
|
|
#### Scenario: 短码不存在
|
|
- **WHEN** 用户查询不存在的短码
|
|
- **THEN** 系统返回 404 错误
|
|
|
|
### Requirement: 短链接重定向
|
|
系统SHALL提供短链接重定向功能。
|
|
|
|
#### Scenario: 访问有效短链接
|
|
- **WHEN** 用户访问 `/s/<code>/`
|
|
- **THEN** 系统将用户重定向到原始URL，并将点击次数加1
|
|
|
|
#### Scenario: 短链接已过期
|
|
- **WHEN** 用户访问已过期的短链接
|
|
- **THEN** 系统返回 410 Gone 错误页面
|
|
|
|
### Requirement: 链接列表API
|
|
系统SHALL提供用户创建的短链接列表查询API。
|
|
|
|
#### Scenario: 查询链接列表
|
|
- **WHEN** 已登录用户发送 GET 请求到 `/api/shorturl/list/`
|
|
- **THEN** 系统返回当前用户创建的所有短链接列表（分页）
|
|
|
|
#### Scenario: 匿名用户查询
|
|
- **WHEN** 未登录用户发送 GET 请求到 `/api/shorturl/list/`
|
|
- **THEN** 系统返回 401 错误，提示需要登录
|
|
|
|
### Requirement: 前端API详情页
|
|
系统SHALL提供短链接生成API的前端详情页。
|
|
|
|
#### Scenario: 查看API文档
|
|
- **WHEN** 用户访问短链接API详情页
|
|
- **THEN** 系统显示API接口文档，包含请求参数、响应示例、错误码说明
|
|
|
|
#### Scenario: 在线生成短链接
|
|
- **WHEN** 用户在测试页面输入长URL和可选参数，点击生成
|
|
- **THEN** 系统向 `/api/shorturl/shorten/` 发起真实请求并显示生成的短链接
|
|
|
|
#### Scenario: 复制短链接
|
|
- **WHEN** 用户点击复制按钮
|
|
- **THEN** 生成的短链接被复制到剪贴板
|
|
|
|
### Requirement: API文档集成
|
|
短链接API SHALL自动集成到Swagger API文档中。
|
|
|
|
#### Scenario: Swagger文档显示
|
|
- **WHEN** 管理员访问 `/swagger/`
|
|
- **THEN** 短链接API出现在API文档列表中
|
|
|
|
## MODIFIED Requirements
|
|
|
|
### Requirement: 前端路由
|
|
前端路由SHALL包含新的短链接详情页路由。
|
|
|
|
#### Scenario: 访问短链接详情页
|
|
- **WHEN** 用户访问 `/shorturl-detail`
|
|
- **THEN** 系统显示短链接生成API详情页
|
|
|
|
## REMOVED Requirements
|
|
无
|