5.2 短链接、安全与高级路由接口

a month ago

5b14042

5.2 短链接接口

所有接口前缀 /api/v1/short_links，均需认证。

创建短链接

POST /api/v1/short_links
Content-Type: application/json
Authorization: Bearer <token>

{
  "original_url": "https://example.com/very/long/path?x=1",
  "domain": "s.example.com",
  "custom_code": "promo2026",
  "title": "春促活动",
  "expire_at": "2026-06-01T00:00:00Z"
}

请求字段：

字段	必填	说明
`original_url`	是	原始 URL
`domain`	否	绑定域名，省略时使用默认域
`custom_code`	否	自定义短码
`title`	否	备注
`expire_at`	否	过期时间（RFC3339）

响应：

{
  "code": 0,
  "data": {
    "id": 42,
    "code": "promo2026",
    "short_url": "https://s.example.com/promo2026",
    "original_url": "https://example.com/very/long/path?x=1",
    "created_at": "2026-04-15T10:00:00Z"
  }
}

获取列表

GET /api/v1/short_links?page=1&page_size=20&keyword=promo

查询参数：page、page_size、keyword、domain、status、created_from、created_to

获取详情

GET /api/v1/short_links/{id}

更新

PUT /api/v1/short_links/{id}
Content-Type: application/json

{
  "original_url": "https://new.example.com",
  "title": "新标题"
}

切换状态

PUT /api/v1/short_links/{id}/status
Content-Type: application/json

{ "status": "inactive" }

删除

DELETE /api/v1/short_links/{id}

单条统计

GET /api/v1/short_links/{id}/statistics?from=2026-04-01&to=2026-04-15

批量创建

POST /api/v1/short_links/batch
Content-Type: application/json

{
  "items": [
    { "original_url": "https://a.example.com" },
    { "original_url": "https://b.example.com", "custom_code": "bbb" }
  ]
}

返回每条的创建结果，部分失败不会回滚其他成功项。