短网址服务功能设计文档（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

  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}

  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 用户表

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

4.2 短链表

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 统计表（明细）

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 聚合表（报表）

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 表

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

5. 系统流程图

5.1 短链生成流程

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

5.2 短链跳转流程

用户访问短链
   ↓
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 字段）。