2026最新重史实战：3步告别教程地狱，从零手搓项目

看了一堆教程还是不会写项目？别慌，这不是你笨，是方法错了。2026最新的技术栈更复杂，光看视频等于没看。今天不灌鸡汤，直接上硬菜。

很多转岗的朋友问：为什么大厂看重“重史”（项目历史与重构逻辑）？因为面试官要看你解决过什么坑，而不是背了多少API。这篇文带你手搓一个高可用短链接服务，从需求到上线，全程无废话。

项目目标与痛点拆解

传统短链接服务只做了 Long URL 到 Short Code 的映射，但实战中痛点远不止如此。真正的“重史”在于处理高并发下的幂等性、热点Key击穿以及过期策略的动态调整。

我们目标不是造轮子，而是复现真实业务场景：

生成短码：支持自定义短码（品牌方需求）。
重定向：301 vs 302 的选择与性能差异。
统计能力：记录点击IP、UserAgent、时间戳，用于后续分析。
过期机制：支持设置短链有效期，过期后返回404或提示页。

为什么选Python + FastAPI + Redis + PostgreSQL？ FastAPI 性能在 Python 生态中属于第一梯队，配合异步 I/O，足以应对中高频访问。Redis 做缓存层抗住读流量，PostgreSQL 做持久化存储保证数据不丢。这套组合在 2026 年的中小厂后端面试中依然是高频考点。

目录结构与技术选型

工程化第一步，目录清晰。不要把所有代码堆在一个 main.py 里，那是脚本，不是项目。

short-url-service/
├── app/
│   ├── __init__.py
│   ├── main.py          # 应用入口
│   ├── config.py        # 配置管理
│   ├── models/          # 数据模型 (Pydantic)
│   │   ├── short_url.py
│   │   └── click_log.py
│   ├── schemas/         # API 输入输出定义
│   │   └── short_url.py
│   ├── services/        # 业务逻辑层
│   │   ├── generator.py # 短码生成器
│   │   └── redirect.py  # 重定向逻辑
│   ├── repositories/    # 数据访问层
│   │   ├── base.py
│   │   └── short_url_repo.py
│   └── utils/           # 工具类
│       └── hash_utils.py
├── tests/               # 单元测试
│   └── test_generator.py
├── alembic/             # 数据库迁移
├── requirements.txt
└── docker-compose.yml

关键选型解释：

Alembic：不要手动改数据库表结构。Alembic 是 SQLAlchemy 的配套工具，能自动生成迁移脚本。在 Stack Overflow 上，关于“如何安全修改生产库表结构”的高票答案几乎都推荐 Alembic 或 Flyway。
Pydantic：数据校验与序列化一体。FastAPI 原生支持，能把 JSON 转对象，还能自动做类型检查。

核心代码实现：短码生成的艺术

短码生成是核心难点。简单用 uuid4 生成太长了，用自增 ID 又容易被遍历（安全风险）。

方案对比：

Base62 编码：将自增 ID 转换为 62 进制字符串。优点：短、无规律。缺点：如果 ID 回退，会出现重复短码。
Hash 取模：hash(url) % 62^n。优点：幂等，相同 URL 生成相同短码。缺点：哈希冲突概率高，需要处理冲突。

我们采用 Base62 + 冲突重试 策略。

1. Base62 工具类

# app/utils/hash_utils.py
import stringALPHABET = string.digits + string.ascii_letters
BASE = len(ALPHABET)def int_to_base62(num: int) -> str:"""将整数转换为 Base62 字符串"""if num == 0:return ALPHABET[0]result = []while num:num, remainder = divmod(num, BASE)result.append(ALPHABET[remainder])return ''.join(reversed(result))def base62_to_int(s: str) -> int:"""将 Base62 字符串还原为整数（用于调试或校验）"""num = 0for char in s:num = num * BASE + ALPHABET.index(char)return num

逐行讲解：

divmod：Python 内置函数，同时返回商和余数，比手动 % 和 // 更高效。
reversed：因为进制转换是从低位到高位生成的，最后需要反转。

2. 短码生成服务

# app/services/generator.py
import asyncio
import random
import string
from sqlalchemy import select
from app.repositories.short_url_repo import ShortUrlRepository
from app.utils.hash_utils import int_to_base62class ShortCodeGenerator:def __init__(self, repo: ShortUrlRepository):self.repo = repoself.lock = asyncio.Lock() # 简单的异步锁，防止并发生成冲突async def generate_code(self, long_url: str, custom_code: str = None) -> str:"""生成唯一短码1. 如果有自定义短码，先检查是否存在2. 否则，基于时间戳+随机数生成初始ID，转Base623. 检查冲突，冲突则重试"""if custom_code:# 业务方指定短码，如 "2026-promo"exists = await self.repo.check_exists(custom_code)if exists:raise ValueError(f"Short code {custom_code} already exists")return custom_codeasync with self.lock:# 使用毫秒级时间戳 + 随机数，确保初始值不重复# 注意：在生产环境，建议使用雪花算法或分布式ID生成器timestamp = int(time.time() * 1000)random_part = random.randint(0, 9999)unique_id = (timestamp << 14) | random_partshort_code = int_to_base62(unique_id)# 检查冲突，最多重试3次for _ in range(3):if not await self.repo.check_exists(short_code):return short_code# 冲突，重新生成随机部分random_part = random.randint(0, 9999)unique_id = (timestamp << 14) | random_partshort_code = int_to_base62(unique_id)raise RuntimeError("Failed to generate unique short code")

避坑指南：

异步锁 asyncio.Lock：在单进程环境下够用。如果是多进程部署（如 Gunicorn 多 worker），asyncio.Lock 无效，必须使用 Redis 分布式锁（如 redis-py 的 lock 模块）。很多初学者在这里踩坑，导致并发下短码重复。
时间戳左移：<< 14 是为了给随机数留出 14 位空间（约 16000 个随机值），保证同一毫秒内生成的 ID 不重复。

运行与测试：别让 Bug 活过本地

代码写完，必须跑通。2026 年的开发标准，没有测试的项目等于裸奔。

1. 启动服务

使用 docker-compose 一键拉起环境：

# docker-compose.yml
version: '3.8'
services:api:build: .ports:- "8000:8000"environment:- REDIS_URL=redis://redis:6379- DB_URL=postgresql://user:pass@db:5432/shorturldepends_on:- redis- dbredis:image: redis:7-alpinedb:image: postgres:16-alpineenvironment:POSTGRES_USER: userPOSTGRES_PASSWORD: passPOSTGRES_DB: shorturl

2. 单元测试：聚焦核心逻辑

不要测试 HTTP 请求本身，测试业务逻辑。

# tests/test_generator.py
import pytest
from unittest.mock import AsyncMock, patch
from app.services.generator import ShortCodeGenerator
from app.repositories.short_url_repo import ShortUrlRepository@pytest.mark.asyncio
async def test_generate_unique_code():mock_repo = AsyncMock(spec=ShortUrlRepository)# 模拟第一次检查存在，第二次不存在mock_repo.check_exists = AsyncMock(side_effect=[True, False])generator = ShortCodeGenerator(mock_repo)with patch('time.time', return_value=1700000000):code = await generator.generate_code("https://example.com/long-url")assert len(code) >= 6 # Base62 编码后长度assert mock_repo.check_exists.call_count == 2

Stack Overflow 实战经验： 在 Stack Overflow 的 "Python Asyncio Mock" 标签下，高票答案强调：AsyncMock 是测试异步函数的关键。如果你用普通的 Mock，异步调用会报错 coroutine object was never awaited。这是转岗后端面试中常见的“隐形坑”。

优化扩展：从能用到高可用

项目能跑了，但离生产还有距离。以下是三个关键优化点：

1. 缓存策略：Redis 读写分离

问题：每次重定向都查数据库，QPS 上不去。方案：

写：生成短码时，同时写入 Redis SET short_url:{code} {long_url}，设置过期时间。
读：重定向时，先查 Redis。命中则直接返回；未命中则查 DB，查到后回填 Redis。

async def get_long_url(self, short_code: str) -> str:# 1. 查缓存cached = await self.redis.get(f"short_url:{short_code}")if cached:return cached# 2. 查数据库db_result = await self.repo.get_by_code(short_code)if db_result:# 3. 回填缓存，设置随机过期时间防止雪崩ttl = 3600 + random.randint(0, 300)await self.redis.setex(f"short_url:{short_code}", ttl, db_result.long_url)return db_result.long_urlreturn None