「短网址服务」功能设计

短网址服务功能设计文档（FDD v1.1）

1. 概述

本文档基于PRD 文档，对短网址服务的功能模块、交互逻辑、接口协议、数据结构进行细化，旨在保障开发、测试和产品的高效协作。

2. 系统模块划分

  • 前端模块：长链输入生成页面、用户登录注册、Dashboard（短链管理、统计分析、API Key 管理）。
  • 后端模块：短链生成与跳转、API 服务、用户与权限管理、统计分析、风控与安全策略。
  • 数据存储：MySQL（持久化）、Redis（缓存 + 计数器）、对象存储（二维码文件）。
  • 运维支持：Nginx/Gateway、Docker/K8s、监控告警。

3. 功能设计（详细）

3.1 短网址生成

功能点：

  1. 长链输入校验：

    • 格式是否合法（http/https 开头）。
    • 是否命中黑名单（诈骗、钓鱼域名）。
    • 长度上限（例如 ≤ 2048 字符）。

  2. 短码生成策略：

    • 默认：随机 6-8 位 Base62 编码。
    • 自定义：用户输入 custom_code，校验唯一性，避免冲突。

  3. 过期时间：

    • 默认永久有效。
    • 用户可选（7 天 / 30 天 / 自定义到期时间）。

  4. 二维码生成：

    • 同时生成短链对应二维码。
    • 存储至对象存储（OSS/S3），返回 URL。

接口设计：

  • POST /api/shorten

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18

    Request:
{
  "long_url": "https://example.com/product/123",
  "custom_code": "myshop",
  "expire_days": 30,
  "generate_qr": true
}

Response:
{
  "code": 0,
  "message": "success",
  "data": {
    "short_url": "https://s.io/myshop",
    "qr_url": "https://cdn.s.io/qrcode/myshop.png",
    "expire_at": "2025-10-24T00:00:00Z"
  }
}

  • 错误码：

    • 124001：长链格式不合法
    • 124002：短码已存在
    • 124003：域名在黑名单

3.2 短网址跳转

功能点：

  1. 请求进入短码解析模块。
  2. Redis 命中 → 返回 302/301 跳转。
  3. Redis 未命中 → 查询数据库并回写缓存。
  4. 统计数据异步写入（PV/UV/UA/Referer/IP/Geo）。
  5. 过期/无效 → 返回提示页（可自定义文案/品牌页）。

接口设计：

  • GET /{short_code}

    • 正常：302 Found → 长链
    • 过期/无效：404 Not Found 或重定向到错误页面

3.3 访问统计

采集维度：

  • PV（访问次数）
  • UV（独立访客，按 IP+UA 或 Cookie 去重）
  • 来源（Referer 域名）
  • 设备/浏览器（User-Agent 解析）
  • 地理位置（IP → 国家/省/市）

实现方式：

  • 异步消息队列（Kafka/RabbitMQ）写入统计表，避免阻塞跳转。
  • Redis HyperLogLog 实现 UV 去重。
  • 周期性聚合数据至报表表。

接口设计：

  • GET /api/info/{short_code}

     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

    Response:
{
  "code": 0,
  "message": "success",
  "data": {
    "short_code": "myshop",
    "long_url": "https://example.com/product/123",
    "total_clicks": 1560,
    "unique_visitors": 934,
    "referers": { "weibo.com": 600, "wechat": 500 },
    "devices": { "mobile": 1000, "pc": 560 },
    "geo": { "China": 1200, "US": 200, "Others": 160 }
  }
}

3.4 API 服务

接口一览：

  • POST /api/shorten：生成短链
  • GET /api/info/{code}：获取短链信息
  • DELETE /api/{code}：删除短链
  • GET /api/list?page=1&size=20：短链列表

权限控制：

  • 游客：无 API Key，只能前端生成。
  • 注册用户：需登录 JWT。
  • 企业/开发者：使用 API Key 调用，支持限流。

3.5 用户管理

功能点：

  1. 注册/登录：

    • 邮箱 + 密码注册。
    • 密码加密存储（BCrypt/Argon2）。

  2. JWT 鉴权：

    • Access Token（15min-1h）
    • Refresh Token（7-30 天，可刷新 Access Token）。

  3. API Key 管理：

    • 用户可创建多个 API Key。
    • 可设置有效期、调用上限。

接口设计：

  • POST /api/auth/register
  • POST /api/auth/login
  • POST /api/auth/refresh
  • POST /api/auth/logout

3.6 用户 Dashboard

功能点：

  1. 短链列表

    • 支持搜索（短码/原始 URL）。
    • 支持修改长链、过期时间。
    • 支持删除。

  2. 数据统计可视化

    • 折线图：每日点击趋势。
    • 饼图：来源/设备分布。
    • 地图：地理分布。

  3. 用户设置

    • 修改账号信息。
    • 管理 API Key。
    • 绑定自定义域名。

前端技术：React/Vue + TailwindCSS + Recharts/ECharts。

4. 数据库设计（表级别）

4.1 用户表

1
2
3
4
5
6
7
8

users (
  id BIGINT PK,
  email VARCHAR(128) UNIQUE,
  password_hash VARCHAR(255),
  role ENUM('user','admin'),
  created_at DATETIME,
  updated_at DATETIME
)

4.2 短链表

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

urls (
  id BIGINT PK,
  user_id BIGINT,
  short_code VARCHAR(16) UNIQUE,
  long_url TEXT,
  custom_code VARCHAR(32) UNIQUE,
  expire_at DATETIME,
  created_at DATETIME,
  updated_at DATETIME
)

4.3 统计表（明细）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

url_stats (
  id BIGINT PK,
  url_id BIGINT,
  ip VARCHAR(45),
  user_agent VARCHAR(255),
  referer VARCHAR(255),
  country VARCHAR(64),
  city VARCHAR(64),
  created_at DATETIME
)

4.4 聚合表（报表）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

url_reports (
  id BIGINT PK,
  url_id BIGINT,
  date DATE,
  pv BIGINT,
  uv BIGINT,
  mobile BIGINT,
  pc BIGINT,
  country VARCHAR(64),
  count BIGINT
)

4.5 API Key 表

1
2
3
4
5
6
7

api_keys (
  id BIGINT PK,
  user_id BIGINT,
  api_key VARCHAR(64) UNIQUE,
  created_at DATETIME,
  expired_at DATETIME
)

5. 系统流程图

5.1 短链生成流程

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

用户输入长链
   ↓
校验URL合法性
   ↓
短码生成（随机/自定义）
   ↓
存储DB & 缓存Redis
   ↓
生成二维码
   ↓
返回短链 & 二维码

5.2 短链跳转流程

1
2
3
4
5
6
7
8
9

用户访问短链
   ↓
Redis缓存查询
   ↓ 命中？ Yes → 跳转
   ↓ No → 查询DB → 回写Redis
   ↓
异步写入统计数据
   ↓
返回302跳转

6. 非功能设计（加强版）

  • 性能：

    • 单节点跳转服务支持 ≥ 10k QPS；
    • Redis 缓存命中率 ≥ 95%；
    • 延迟 ≤ 50ms。

  • 安全：

    • HTTPS 全覆盖；
    • API 限流：默认 100 req/min/user；
    • 黑名单库接入（腾讯安全、Google Safe Browsing）。

  • 可用性：

    • MySQL 主从复制，支持读写分离；
    • Redis Sentinel/Cluster 高可用；
    • 定时快照 & WAL 归档。

7. 未来扩展

  • 短链批量生成（CSV 上传 & 导出）。
  • 动态跳转（按地域/设备跳不同目标）。
  • 访问控制（密码保护、IP 白名单）。
  • 团队协作 & 多租户模式（tenant_id 字段）。