# short-url

**Repository Path**: alonStudy/short-url

## Basic Information

- **Project Name**: short-url
- **Description**: 长链转短链，短链重定向
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 11
- **Created**: 2024-11-18
- **Last Updated**: 2025-03-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 短链项目

## 目录

- [简介](#简介)
- [背景](#背景)
    - [什么是短链](#什么是短链)
    - [短链原理](#短链原理)
    - [为什么需要短链](#为什么需要短链)
- [功能](#功能)
- [技术栈](#技术栈)
- [核心职责](#核心职责)
- [架构图](#架构图)
- [数据库设计](#数据库设计)
- [安装与配置](#安装与配置)
    - [前置条件](#前置条件)
    - [安装步骤](#安装步骤)
- [使用方法](#使用方法)
    - [生成短链](#生成短链)
    - [短链重定向](#短链重定向)
- [常见问题](#常见问题)
- [面试问题挖掘](#面试问题挖掘)
- [贡献](#贡献)
- [许可证](#许可证)
- [联系方式](#联系方式)

---

## 简介

本项目是一个基于 **SpringBoot** 的短链接服务，旨在将原始的长网址转换为简短易记的短网址，方便用户在各种场景中分享和传播链接。通过高效的算法和稳定的架构设计，确保生成的短链唯一性并提供快速的重定向服务。

## 背景

### 什么是短链

短链，即短链接，是将原始长网址压缩而成的短网址。它不仅使链接更加简洁美观，还便于在字符受限的环境中使用，如短信、推特等。

### 短链原理

短链服务通过将原始的长链接映射到一个唯一的短链接。当用户访问短链接时，系统会解析并重定向到对应的原始长链接地址。

### 为什么需要短链

- **节省字符空间**：在短信、推特等有限字符的平台上，短链可以节省宝贵的字符空间。
- **美观简洁**：短链看起来更加整洁，提升用户体验。
- **跟踪与分析**：短链服务通常集成了点击统计和分析功能，帮助用户了解链接的传播效果。
- **隐私保护**：通过短链可以隐藏原始链接的具体结构，提升安全性。

## 功能

- **生成短链**：将长链接转换为唯一的短链接。
- **短链重定向**：访问短链接时，自动重定向到对应的长链接。
- **唯一性保证**：确保每个短链接对应唯一的长链接，防止冲突。
- **高性能**：利用 Redis 缓存和布隆过滤器，提高查询和生成的效率。
- **可扩展性**：采用模块化设计，便于功能扩展和维护。
- **安全性**：防止恶意链接和滥用行为，保障服务的安全稳定。

## 技术栈

- **SpringBoot**：作为项目的核心框架，提供快速开发和集成能力。
- **Redis**：用作缓存，提高查询和重定向的响应速度。
- **通用 Mapper**：简化数据库操作，提升开发效率。
- **Guava**：提供高效的工具库，支持布隆过滤器等功能。

## 核心职责

1. **生成唯一短链地址**：通过高效的算法将原始长链接转换为唯一的短链接。
2. **短链地址重定向**：接收短链请求，解析并重定向到对应的长链接地址。

## 架构图

以下是该项目的架构图：

![架构图](sql/短链架构图.png)


## 数据库设计

### 创建数据库模式

```sql
CREATE SCHEMA shortUrl COLLATE utf8mb4_bin;
```

### 创建 `url_map` 表

```sql
create table url_map
(
    id        int auto_increment comment '主键'
        primary key,
    short_url varchar(200) default '' not null comment '短链接',
    long_url  varchar(500) default '' not null comment '长链接',
    name      varchar(500) default '' not null comment '名称',
    remark    varchar(500) default '' not null comment '备注',
    constraint uk_short_url
        unique (short_url)
)
    comment '长链短链对应表';


create table request_record
(
    id         int auto_increment comment '主键'
        primary key,
    url_id     int                     not null comment '链接 id',
    ip_address varchar(500) default '' not null comment 'ip地址',
    ip_belong  varchar(500) default '' not null comment 'ip 归属地'
)
    comment '链接访问记录表';
```

*表说明：*

- **id**：自增主键。
- **short_url**：唯一的短链接地址。
- **long_url**：对应的原始长链接地址。

## 安装与配置

### 前置条件

- **Java 8 或以上**：确保已安装并配置好 Java 环境。
- **Maven**：用于项目的依赖管理和构建。
- **Redis**：用于缓存数据，加快查询速度。
- **MySQL**：作为关系型数据库，存储短链与长链的映射关系。

### 安装步骤

1. **克隆仓库**

    ```bash
    git clone https://gitee.com/huaixia18/short-url
    cd short-url
    ```

2. **配置数据库**

    - 创建数据库：

        ```sql
        CREATE SCHEMA shortUrl COLLATE utf8mb4_bin;
        ```

    - 导入表结构：

      执行 `database/schema.sql` 中的 SQL 语句，创建 `url_map` 表。

3. **配置应用程序**

    - 复制 `application.example.properties` 为 `application.properties`：

        ```bash
        cp src/main/resources/application.example.properties src/main/resources/application.properties
        ```

    - 编辑 `application.properties`，配置数据库和 Redis 连接信息：

        ```properties
        # 数据库配置
        spring.datasource.url=jdbc:mysql://localhost:3306/shortUrl?useUnicode=true&characterEncoding=utf8&useSSL=false
        spring.datasource.username=你的数据库用户名
        spring.datasource.password=你的数据库密码

        # Redis配置
        spring.redis.host=localhost
        spring.redis.port=6379
        ```

4. **构建项目**

   使用 Maven 进行项目构建：

    ```bash
    mvn clean install
    ```

5. **运行项目**

    ```bash
    mvn spring-boot:run
    ```

   或者，使用生成的 JAR 文件运行：

    ```bash
    java -jar target/shortUrl-0.0.1-SNAPSHOT.jar
    ```

## 使用方法

### 生成短链

发送 POST 请求到 `/api/shorten`，并在请求体中包含要缩短的长链接。

**示例请求**

```bash
POST http://localhost:8080/createShortUrl
Content-Type: application/json

{
    "longUrl": "https://www.example.com/some/very/long/url"
}
```

**示例响应**

```json
{
    "shortUrl": "http://localhost:8080/abc1234"
}
```

### 短链重定向

访问生成的短链 `http://localhost:8080/abc1234`，系统会自动重定向到对应的长链接 `https://www.example.com/some/very/long/url`。

## 常见问题

### 问题 1：短链生成后无法访问

**解决方法：**

- 确认服务已正确启动并监听在预期的端口。
- 检查防火墙设置，确保端口未被阻塞。
- 查看日志文件，寻找可能的错误信息。

### 问题 2：生成短链后访问时长链未重定向

**解决方法：**

- 确认 `url_map` 表中存在对应的短链与长链映射。
- 检查 Redis 缓存是否正常工作，必要时清空缓存重新尝试。
- 确认应用程序具备访问数据库的权限。

### 问题 3：生成的短链不唯一

**解决方法：**

- 确保生成短链的算法未被修改，并且使用了正确的哈希和编码方式。
- 检查数据库的唯一索引约束是否生效，防止重复插入。

## 面试问题挖掘

以下为本项目的面试问题挖掘，可用于自我评估或面试准备：

### 1. 如何保证短链唯一性？

**回答：**

本项目通过哈希算法结合六十二进制表示法生成短链。六十二进制使用 `0-9`、`a-z`、`A-Z` 共计 62 个字符。生成7位长度的六十二进制短链，可以表示的范围为 `62^7 = 3,521,614,606,208`，足以覆盖 3.5 万亿个不同的短链，确保高唯一性。

### 2. 如何判断是否发生 HASH 冲突？

**回答：**

在生成短链时，首先使用布隆过滤器快速判断短链是否已存在。由于布隆过滤器可能有误判，本项目在布隆过滤器之后，还会在数据库中进行唯一性校验，通过数据库的唯一索引约束来最终判断是否发生冲突。

### 3. 如何处理 HASH 冲突？

**回答：**

如果在生成短链过程中检测到冲突（即短链已存在），系统会在原有短链后面追加随机字符串，重新生成新的短链。如果再次发生冲突，继续在后面拼接新的字符，直到生成一个唯一的短链为止。

### 4. 如何解决布隆过滤器误判的情况？

**回答：**

布隆过滤器在提示存在某个短链时，会进一步在数据库中进行校验，确保该短链确实存在。这样即使布隆过滤器出现误判，系统也能通过数据库校验避免错误处理。

## 贡献

欢迎各位开发者为本项目贡献代码或提出建议！请按照以下步骤进行贡献：

1. **Fork 本仓库**
2. **创建新的分支**

    ```bash
    git checkout -b feature/新功能名称
    ```

3. **提交更改**

    ```bash
    git commit -m "添加新功能: 描述"
    ```

4. **推送到分支**

    ```bash
    git push origin feature/新功能名称
    ```

5. **创建 Pull Request**

   请确保您的代码遵循项目的编码规范，并附上相关的测试和文档更新。

## 许可证

本项目采用 [MIT 许可证](LICENSE) 进行许可。详情请参阅 `LICENSE` 文件。

## 联系方式

如果您有任何问题或建议，欢迎通过以下方式联系我：

- **邮箱**：huaixia18@2925.com
- **GitHub**：[槐夏十八](https://gitee.com/huaixia18)

---

感谢您使用本短链项目！希望它能为您的业务和应用带来便利和价值。