从零实现短链服务：Go 后端项目实战

这篇文章记录了我从零实现短链服务的完整过程。这个项目不仅是一个可用的产品，也是我学习后端开发的实践项目，涵盖了 Web 框架、数据库、认证、可观测性等核心技术点。

项目背景

短链服务（URL Shortener）是一个经典的后端项目，核心功能很简单：

用户提交一个长 URL
系统返回一个短码（如 Ab3Kx9）
访问短链时，302 跳转到原始 URL

虽然功能简单，但要做到生产可用，需要考虑很多工程问题：性能、缓存、防刷、可观测性等。

技术栈

组件	选型	说明
Web 框架	扩展后的 gee 及其后端脚手架	学习目的，理解框架原理
数据库	PostgreSQL	现代、功能强大
认证	JWT (HS256)	无状态、易扩展
指标	Prometheus	业界标准
追踪	OpenTelemetry	分布式追踪
部署	Docker	容器化

核心设计

短码生成算法

短码生成是短链服务的核心。常见方案有：

方案	优点	缺点
自增 ID + Base62	简单、无冲突	可被枚举
随机 + 冲突检测	不可枚举	需要重试
预生成号段	高性能	实现复杂

我选择了 自增 ID + Base62 方案，简单高效：

1
const base62Chars = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ"
2

3
func EncodeBase62(n uint64) s
4
    if n == 0 {
5
        return string(base62Chars[0])
6
    }
7
    var result []byte
8
    for n > 0 {
9
        result = append([]byte{base62Chars[n%62]}, result...)
10
        n /= 62
11
    }
12
    return string(result)
13
}

6 位 Base62 可以表示 62^6 = 568 亿 个短链，足够使用。

数据库设计

1
-- 短链表
2
CREATE TABLE shortlinks (
3
    id            BIGSERIAL PRIMARY KEY,
4
    code          TEXT UNIQUE,              -- 短码
5
    url           TEXT UNIQUE NOT NULL,     -- 原始 URL（唯一约束实现去重）
6
    disabled      BOOLEAN NOT NULL DEFAULT FALSE,
7
    redirect_type TEXT NOT NULL DEFAULT '302',
8
    expires_at    TIMESTAMPTZ,
9
    created_at    TIMESTAMPTZ DEFAULT NOW(),
10
    updated_at    TIMESTAMPTZ DEFAULT NOW()
11
);
12

13
-- 用户-短链关联表
14
CREATE TABLE user_shortlinks (
15
    user_id      BIGINT REFERENCES users(id),
16
    shortlink_id BIGINT REFERENCES shortlinks(id),
17
    created_at   TIMESTAMPTZ DEFAULT NOW(),
18
    PRIMARY KEY (user_id, shortlink_id)
19
);

设计要点：

URL 唯一约束：同一个 URL 只生成一个短码，避免重复
关联表：用户和短链是多对多关系（同一短链可被多人”收藏”）
软删除：disabled 字段而非物理删除，便于审计

创建短链流程

1
func (s *ShortlinksRepo) Create(ctx context.Context, url string, userID *int64) (string, error) {
2
    tx, _ := s.db.Begin(ctx)
3
    defer tx.Rollback(ctx)
4

5
    // 1. 插入 URL，利用 ON CONFLICT 实现幂等
6
    var id int64
7
    var code string
8
    tx.QueryRow(ctx,
9
        `INSERT INTO shortlinks (url, disabled)
10
         VALUES ($1, false)
11
         ON CONFLICT (url) DO UPDATE SET url = EXCLUDED.url
12
         RETURNING id, COALESCE(code, '')`,
13
        url).Scan(&id, &code)
14

15
    // 2. 如果是新记录，生成短码
16
    if code == "" {
17
        code = EncodeBase62(uint64(id))
18
        tx.Exec(ctx,
19
            `UPDATE shortlinks SET code = $1 WHERE id = $2`,
20
            code, id)
21
    }
22

23
    // 3. 记录用户关联
24
    if userID != nil {
25
        tx.Exec(ctx,
26
            `INSERT INTO user_shortlinks (user_id, shortlink_id)
27
             VALUES ($1, $2) ON CONFLICT DO NOTHING`,
28
            *userID, id)
29
    }
30

31
    tx.Commit(ctx)
32
    return code, nil
33
}

关键点：

使用事务保证一致性
ON CONFLICT 实现幂等（同一 URL 多次提交返回相同短码）
先插入获取 ID，再用 ID 生成短码

跳转流程

1
func NewRedirectHandler(repo *ShortlinksRepo) gee.HandlerFunc {
2
    return func(c *gee.Context) {
3
        code := c.Param("code")
4
        url := repo.Resolve(c.Request.Context(), code)
5

6
        if url == "" {
7
            c.AbortWithStatus(http.StatusNotFound)
8
            return
9
        }
10

11
        c.SetHeader("Location", url)
12
        c.Status(http.StatusFound) // 302
13
    }
14
}

跳转逻辑非常简单：查询 -> 设置 Location -> 返回 302。

301 vs 302 的选择

状态码	行为	优点	缺点
301	永久重定向，浏览器缓存	减少服务器压力	无法统计、无法更新
302	临时重定向，每次经过服务	可统计、可更新	服务器压力大

我默认使用 302，因为需要统计点击次数。

API 设计

1
# 公开接口
2
POST /api/v1/shortlinks          # 创建短链
3
GET  /r/:code                    # 短链跳转
4

5
# 需要登录
6
GET  /api/v1/shortlinks/:code    # 查询短链信息
7
POST /api/v1/shortlinks/:code/disable  # 禁用短链
8
GET  /api/v1/users/me            # 当前用户信息
9
GET  /api/v1/users/mine          # 我的短链列表
10

11
# 用户认证
12
POST /api/v1/register            # 注册
13
POST /api/v1/login               # 登录（返回 JWT）

创建短链示例

1
# 请求
2
curl -X POST http://localhost:9999/api/v1/shortlinks \
3
  -H "Content-Type: application/json" \
4
  -d '{"url": "https://github.com/yourname"}'
5

6
# 响应
7
{
8
  "code": "1",
9
  "short_url": "http://localhost:9999/r/1",
10
  "url": "https://github.com/yourname"
11
}

访问短链

1
curl -i http://localhost:9999/r/1
2

3
# 响应
4
HTTP/1.1 302 Found
5
Location: https://github.com/yourname

用户认证

JWT 认证流程

1
1. 用户登录 -> 验证密码 -> 签发 JWT
2
2. 后续请求携带 Authorization: Bearer <token>
3
3. 中间件解析 JWT -> 注入用户信息到 Context

密码存储

使用 bcrypt 哈希，不存储明文：

1
// 注册时
2
hash, _ := bcrypt.GenerateFromPassword([]byte(password), bcrypt.DefaultCost)
3

4
// 登录时
5
err := bcrypt.CompareHashAndPassword([]byte(user.PasswordHash), []byte(password))

可选认证中间件

创建短链接口支持匿名和登录两种模式：

1
func AuthOptional(jwt auth.JWT) gee.HandlerFunc {
2
    return func(c *gee.Context) {
3
        token := extractToken(c)
4
        if token == "" {
5
            c.Next()
6
            return
7
        }
8

9
        identity, err := jwt.Verify(token)
10
        if err != nil {
11
            c.Next() // token 无效也放行，只是不注入用户信息
12
            return
13
        }
14

15
        c.Set("identity", identity)
16
        c.Next()
17
    }
18
}

可观测性

Prometheus 指标

1
// 请求计数
2
httpRequestsTotal := prometheus.NewCounterVec(
3
    prometheus.CounterOpts{
4
        Name: "http_requests_total",
5
        Help: "Total HTTP requests",
6
    },
7
    []string{"method", "path", "status"},
8
)
9

10
// 请求延迟
11
httpRequestDuration := prometheus.NewHistogramVec(
12
    prometheus.HistogramOpts{
13
        Name:    "http_request_duration_seconds",
14
        Help:    "HTTP request duration",
15
        Buckets: prometheus.DefBuckets,
16
    },
17
    []string{"method", "path"},
18
)

OpenTelemetry 追踪

集成 otelhttp 中间件，自动为每个请求创建 span：

1
handler := otelhttp.NewHandler(engine, "http-server")

健康检查

1
// /healthz - 存活检查
2
func Healthz(c *gee.Context) {
3
    c.JSON(200, map[string]string{"status": "ok"})
4
}
5

6
// /readyz - 就绪检查（含数据库）
7
func Readyz(db *pgxpool.Pool) gee.HandlerFunc {
8
    return func(c *gee.Context) {
9
        if err := db.Ping(c.Request.Context()); err != nil {
10
            c.JSON(503, map[string]string{"status": "not ready"})
11
            return
12
        }
13
        c.JSON(200, map[string]string{"status": "ready"})
14
    }
15
}

项目结构

1
internal/
2
├── app/shortlink/           # 短链业务
3
│   ├── service.go           # 领域接口
4
│   ├── base62.go            # 编码算法
5
│   ├── validate.go          # URL 校验
6
│   ├── httpapi/             # HTTP 层
7
│   │   ├── register.go      # 路由注册
8
│   │   ├── shortlinks.go    # 短链 handlers
9
│   │   └── users.go         # 用户 handlers
10
│   └── repo/                # 数据访问层
11
│       ├── shortlinks.go
12
│       └── users.go
13
│
14
└── platform/                # 通用基础设施
15
    ├── config/              # 配置管理
16
    ├── db/                  # 数据库连接
17
    ├── auth/                # JWT 认证
18
    ├── httpmiddleware/      # HTTP 中间件
19
    ├── metrics/             # Prometheus
20
    └── trace/               # OpenTelemetry

分层原则：

platform/：可复用的基础设施，不依赖具体业务
app/shortlink/：短链业务代码
httpapi/：HTTP 传输层，负责请求/响应
repo/：数据访问层，负责数据库操作

待实现功能

高优先级

Redis 缓存：跳转时先查缓存，减少 DB 压力
点击统计：记录每个短链的访问次数
限流：防止恶意刷接口

功能扩展

自定义短码：允许用户指定短码（如 /r/github）
二维码生成：为短链生成二维码图片
批量创建：一次创建多个短链
过期时间：支持设置短链有效期

性能优化

布隆过滤器：快速判断短码是否存在，防止缓存穿透
singleflight：防止缓存击穿
本地缓存：热点短链使用本地缓存 + Redis 二级缓存

部署

Docker 构建

1
FROM golang:1.23-alpine AS builder
2
WORKDIR /app
3
COPY go.mod go.sum ./
4
RUN go mod download
5
COPY . .
6
RUN go build -o api ./cmd/api
7

8
FROM alpine:latest
9
COPY --from=builder /app/api /api
10
EXPOSE 9999
11
CMD ["/api"]

环境变量

1
ADDR=:9999                    # HTTP 端口
2
ADMIN_ADDR=127.0.0.1:6060     # 管理端口（不对外暴露）
3
JWT_SECRET=<随机字符串>        # JWT 签名密钥
4
DB_DSN=postgres://user:pass@host:5432/db?sslmode=disable

运行

1
docker run -d \
2
  --name shortlink \
3
  -p 9999:9999 \
4
  -e ADDR=:9999 \
5
  -e JWT_SECRET=your_secret \
6
  -e DB_DSN=postgres://... \
7
  your-image:tag

总结

这个项目虽然功能不复杂，但涵盖了后端开发的核心技术点：

Web 框架：路由、中间件、请求处理
数据库：连接池、事务、SQL 优化
认证：JWT、密码哈希、权限控制
可观测性：日志、指标、追踪
工程化：分层架构、配置管理、容器化部署

后续会继续完善缓存、限流、统计等功能，让它更接近生产级服务。