全栈URL缩短服务构建

## 🚀 URL 缩短服务 - 全栈应用 ### 📋 项目概述 构建一个生产就绪的全栈 URL 缩短服务，具有现代、可访问的前端和健壮的 RESTful 后端 API。该应用必须处理缩短链接的完整生命周期：创建、重定向、跟踪、管理和过期。优先考虑性能、安全性和跨设备的卓越用户体验。 --- ### 🛠️ 技术栈 **前端：** - 语义化 HTML5，带 ARIA 属性以实现无障碍（WCAG 2.1 AA 合规） - CSS3，使用 CSS 自定义属性（变量）、Flexbox 和 CSS Grid - 原生 JavaScript（ES2022+），使用模块化架构（ES Modules） - 不使用重型框架 - 保持包体积轻量且快速 **后端 API：** - 遵循 OpenAPI 3.0 规范的 RESTful API 设计 - JSON 请求/响应格式，使用正确的 HTTP 状态码 - 为跨域请求配置 CORS - 按 IP 和 API 密钥进行速率限制 **库（CDN 或打包）：** - QR 码生成（例如，`qrcode.js` 或 `qr-creator`） - 用于分析的图表库（例如，Chart.js 或轻量级替代方案） - 用于过期时间的日期选择器（例如，`flatpickr`） - Toast 通知系统（自定义构建，无依赖） --- ### 🎨 前端 - UI/UX 要求 **布局与设计：** - 简洁、极简的设计，英雄区域设有**大型、醒目的 URL 输入框**，居中显示在页面上 - 实现**深色/浅色模式切换**，支持系统偏好检测（`prefers-color-scheme`）和 `localStorage` 持久化 - 使用一致的设计系统：排版比例、间距令牌、调色板 - 所有交互元素具有平滑的微动画和过渡效果（淡入、上滑、按钮涟漪） - 异步内容（分析、历史记录表）的骨架加载状态 **响应式设计：** - 移动优先的方法，断点位于 480px、768px、1024px 和 1440px - 触控友好的点击目标（最小 44×44px） - 移动端可折叠导航菜单（带动画的汉堡菜单） - 使用 `clamp()` 实现流式排版 **无障碍：** - 完整的键盘导航支持（Tab 顺序、模态框中的焦点陷阱） - 动态内容的屏幕阅读器播报（`aria-live` 区域） - 所有交互元素上可见的焦点指示器 - 足够的颜色对比度（文本最低 4.5:1） - 减少动态效果支持（`prefers-reduced-motion`） --- ### ⚙️ 核心功能 #### 1. URL 缩短引擎 - 突出的输入框，带占位符文本和实时验证反馈 - **URL 验证**：检查有效协议（`http://`、`https://`）、正确的域名结构，并使用正则表达式和 `URL` 构造函数 API 拒绝格式错误的 URL - **URL 清理**：去除跟踪参数（UTM、fbclid、gclid）、删除多余斜杠、规范化协议和大小写 - 如果未提供协议，自动添加 `https://` - 创建后立即显示缩短的 URL，并带有成功动画 - **批量 URL 缩短**：允许用户粘贴多个 URL（每行一个）并一次性全部缩短 #### 2. 自定义别名支持 - 可选的自定义别名字段（例如，`short.ly/my-brand`） - 用户输入时实时可用性检查（防抖 API 调用，300ms） - 别名验证规则：仅限字母数字、连字符、下划线；3-30 个字符；保留字黑名单（例如，`admin`、`api`、`login`、`static`） - 如果别名已被占用或无效，提供清晰的错误消息 #### 3. QR 码生成 - 创建时自动为每个缩短的 URL 生成 QR 码 - QR 码模态框/面板，提供以下选项： - 下载为 PNG（高分辨率，1024×1024） - 下载为 SVG（矢量、可缩放） - 自定义前景/背景颜色 - 在中心添加小徽标覆盖（可选） - 确保 QR 码编码完整的缩短 URL，并在小尺寸下可扫描 #### 4. 点击跟踪与分析仪表板 - 跟踪每次重定向，包含以下数据点： - 时间戳（UTC） - 国家和城市（通过 IP 地理位置 API） - 设备类型（移动端、平板、桌面端） - 操作系统和浏览器（通过 User-Agent 解析） - 来源 URL - 唯一访问者与回访者（通过 cookie/指纹） - **每个链接的分析仪表板**，包括： - 总点击数和唯一点击数计数器 - 随时间变化的点击折线图（可筛选：最近 24 小时、7 天、30 天、90 天、全部时间） - 地理分布地图或条形图（前 10 个国家） - 设备/操作系统/浏览器细分（环形图或饼图） - 主要来源表 - 按星期几和小时计算的点击热力图 - 主仪表板上的汇总分析概览（总链接数、总点击数、最热门链接） #### 5. 链接过期 - 创建链接时可选的过期日期/时间选择器 - 支持预设：1 小时、24 小时、7 天、30 天、自定义日期 - 在活动链接上显示倒计时或“X 后过期”徽章 - 自动停用过期链接，并在重定向尝试时显示友好的“此链接已过期”页面 - 允许用户延长或移除现有链接的过期时间 #### 6. 密码保护 - 创建链接时可选的密码开关 - 如果启用，在重定向到目标 URL 之前显示密码输入门页面 - 使用 bcrypt 或 Argon2 在服务器端对密码进行哈希处理（绝不存储明文） - 对密码尝试进行速率限制（每 IP 每分钟最多 5 次），并显示锁定消息 - 在历史记录视图中，受密码保护的链接上显示视觉指示器（锁图标 🔒） #### 7. 复制到剪贴板 - 每个缩短 URL 旁边的一键复制按钮 - 使用 Clipboard API（`navigator.clipboard.writeText()`），并回退到 `document.execCommand('copy')` - 视觉确认：按钮图标变为对勾 ✅，并显示“已复制！”工具提示/Toast，2 秒后自动消失 - 键盘快捷键支持（例如，`Ctrl+Shift+C` 复制最近创建的链接） #### 8. URL 历史记录与管理 - 所有缩短 URL 的持久历史记录表/网格（访客存储在 `localStorage` 中，认证用户存储在数据库中） - 每个条目显示：原始 URL（截断并带工具提示）、短 URL、创建日期、点击数、状态（活动/已过期/受密码保护）和操作按钮 - **搜索**：跨原始 URL、别名和标签进行全文搜索 - **筛选**：按状态（活动、已过期、受保护）、日期范围、点击数范围和标签 - **排序**：按创建日期、点击数、字母顺序（升序/降序） - **分页或无限滚动**用于大型历史记录（每页 25 条） - **批量操作**：选择多个链接以删除、禁用或导出为 CSV/JSON - **标签/标签**：允许用户添加自定义标签以组织链接（例如，“营销”、“社交”、“活动-q4”） --- ### 🔒 安全要求 - 在客户端和服务器端进行输入清理，以防止 XSS 攻击 - 对所有更改状态的 API 端点进行 CSRF 保护 - 验证并清理重定向目标，以防止开放重定向漏洞（白名单允许的协议，阻止 `javascript:`、`data:`、`file:` 方案） - 实施内容安全策略（CSP）标头 - 速率限制：每 IP 每分钟最多创建 20 个链接；每分钟最多 100 个 API 请求 - 安全 HTTP 标头：`X-Content-Type-Options`、`X-Frame-Options`、`Strict-Transport-Security` - 绝不暴露内部 ID；使用 nanoid 或 UUID 作为公共链接标识符 --- ### ⚡ 性能要求 - 目标 Lighthouse 分数：性能 >90，无障碍 >95，最佳实践 >95，SEO >90 - 延迟加载分析图表和非关键资源 - 对所有搜索和验证输入进行防抖 - 使用 `IntersectionObserver` 实现基于滚动的动画和延迟加载 - 最小化回流和重绘；对动画使用 CSS `transform` 和 `opacity` - 在适当的地方缓存 API 响应（例如，分析数据 TTL 为 60 秒） - 重定向应在服务器端 100ms 内解析 --- ### 🧪 错误处理与边界情况 - 优雅的错误消息：网络故障、API 超时、无效 URL、重复别名、服务器错误（500）、超出速率限制（429） - 离线检测：当用户失去连接时显示横幅，并排队操作以便重试 - 处理超长 URL（最长 2048 个字符）而不破坏布局 - 正确处理 Unicode/国际化域名（IDN） - 当用户没有链接或没有分析数据时，显示空状态插图 --- ### 📦 交付物 1. 完整、注释良好的源代码，具有清晰的文件夹结构 2. `README.md`，包含设置说明、API 文档和功能列表 3. API 端点参考表（方法、路径、参数、响应格式） 4. 一个 `demo` 模式，预加载示例数据以供即时预览 5. 在 Chrome、Firefox、Safari 和 Edge（最新 2 个版本）中响应式显示 --- > **注意：** 增量构建此项目 - 从核心缩短流程开始（输入 → 验证 → 缩短 → 显示 → 复制），然后逐步添加 QR 码、分析、自定义别名、过期、密码保护和完整的历史记录仪表板。确保每个功能在进入下一个功能之前完全可用并经过测试。