API优先的短链服务设计：RESTful规范、多语言SDK、Webhook与开发者体验

POST /v1/links HTTP/1.1
Host: api.shortlink.pro
Authorization: Bearer slk_xxxxxxxxxxxx
Content-Type: application/json
X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

{
  "target_url": "https://www.example.com/products/winter-sale-2026?category=coats",
  "custom_slug": "winter26",
  "domain": "go.yourbrand.com",
  "title": "冬季促销活动页",
  "tags": ["campaign", "winter", "wechat"],
  "expires_at": "2026-03-01T00:00:00Z",
  "password": null,
  "utm_source": "newsletter",
  "utm_medium": "email",
  "utm_campaign": "spring_sale",
  "retargeting_pixel": {
    "facebook": "1234567890",
    "google": "AW-123456789"
  }
}

{
  "id": "link_xxxxxxxx",
  "slug": "winter26",
  "short_url": "https://go.yourbrand.com/winter26",
  "target_url": "https://www.example.com/products/winter-sale-2026?category=coats",
  "domain": "go.yourbrand.com",
  "title": "冬季促销活动页",
  "tags": ["campaign", "winter", "wechat"],
  "created_at": "2026-01-15T08:30:00Z",
  "expires_at": "2026-03-01T00:00:00Z",
  "status": "active",
  "clicks": 0,
  "qr_code_url": "https://api.shortlink.pro/v1/links/winter26/qrcode",
  "_links": {
    "self": "https://api.shortlink.pro/v1/links/winter26",
    "stats": "https://api.shortlink.pro/v1/links/winter26/stats",
    "clicks": "https://api.shortlink.pro/v1/links/winter26/clicks"
  }
}

{
  "error": {
    "code": "SLUG_ALREADY_EXISTS",
    "message": "自定义短码 'winter26' 已被使用",
    "target": "custom_slug",
    "details": [
      {
        "code": "DUPLICATE_VALUE",
        "message": "该短码在同一域名下已存在"
      }
    ],
    "request_id": "req_abc123def456",
    "documentation_url": "https://docs.shortlink.pro/errors/SLUG_ALREADY_EXISTS"
  }
}

package middleware

import (
    "context"
    "net/http"
    "strings"
    "time"
)

func APIKeyAuth(service *auth.Service) func(http.Handler) http.Handler {
    return func(next http.Handler) http.Handler {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            // 1. 提取 Key
            authHeader := r.Header.Get("Authorization")
            var apiKey string
            if strings.HasPrefix(authHeader, "Bearer ") {
                apiKey = strings.TrimPrefix(authHeader, "Bearer ")
            } else {
                apiKey = r.URL.Query().Get("api_key")
            }

            if apiKey == "" {
                respondError(w, http.StatusUnauthorized, "MISSING_API_KEY", "API Key 不能为空")
                return
            }

            // 2. 验证 Key
            keyInfo, err := service.ValidateKey(r.Context(), apiKey)
            if err != nil {
                respondError(w, http.StatusUnauthorized, "INVALID_API_KEY", "API Key 无效或已撤销")
                return
            }

            // 3. 检查速率限制
            allowed, resetAt, err := service.CheckRateLimit(r.Context(), keyInfo.ID, keyInfo.Tier)
            if err != nil {
                respondError(w, http.StatusInternalServerError, "RATE_LIMIT_ERROR", "速率限制检查失败")
                return
            }
            if !allowed {
                w.Header().Set("X-RateLimit-Limit", fmt.Sprintf("%d", keyInfo.Tier.Limits.RequestsPerMinute))
                w.Header().Set("X-RateLimit-Remaining", "0")
                w.Header().Set("X-RateLimit-Reset", fmt.Sprintf("%d", resetAt.Unix()))
                respondError(w, http.StatusTooManyRequests, "RATE_LIMIT_EXCEEDED", "请求过于频繁，请稍后重试")
                return
            }

            // 4. 注入上下文
            ctx := context.WithValue(r.Context(), "api_key", keyInfo)
            ctx = context.WithValue(ctx, "request_id", generateRequestID())

            next.ServeHTTP(w, r.WithContext(ctx))
        })
    }
}

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1704067200
X-RateLimit-Retry-After: 60

package ratelimit

import (
    "context"
    "fmt"
    "time"
    "github.com/redis/go-redis/v9"
)

type SlidingWindow struct {
    client *redis.Client
}

func (sw *SlidingWindow) Allow(ctx context.Context, key string, limit int, window time.Duration) (bool, time.Time, error) {
    now := time.Now()
    windowStart := now.Add(-window)
    redisKey := fmt.Sprintf("ratelimit:%s", key)

    pipe := sw.client.Pipeline()
    pipe.ZRemRangeByScore(ctx, redisKey, "0", fmt.Sprintf("%d", windowStart.UnixMilli()))
    pipe.ZCard(ctx, redisKey)
    pipe.ZAdd(ctx, redisKey, redis.Z{Score: float64(now.UnixMilli()), Member: now.UnixNano()})
    pipe.Expire(ctx, redisKey, window)

    results, err := pipe.Exec(ctx)
    if err != nil {
        return false, now, err
    }

    currentCount := results[1].(*redis.IntCmd).Val()
    if int(currentCount) >= limit {
        // 获取最早的一条记录，计算下一次可用时间
        oldest, _ := sw.client.ZRangeWithScores(ctx, redisKey, 0, 0).Result()
        if len(oldest) > 0 {
            nextWindow := time.UnixMilli(int64(oldest[0].Score)).Add(window)
            return false, nextWindow, nil
        }
        return false, now.Add(window), nil
    }

    return true, now, nil
}

{
  "event": "link.clicked",
  "timestamp": "2026-01-15T14:30:00Z",
  "request_id": "req_xyz789",
  "data": {
    "link": {
      "id": "link_xxxxxxxx",
      "slug": "winter26",
      "short_url": "https://go.yourbrand.com/winter26",
      "target_url": "https://www.example.com/products/winter-sale-2026"
    },
    "click": {
      "timestamp": "2026-01-15T14:30:00Z",
      "ip_hash": "sha256:abc123...",
      "country_code": "CN",
      "city": "上海",
      "device_type": "mobile",
      "os": "iOS",
      "browser": "Safari",
      "referrer": "https://weixin.qq.com/",
      "utm_source": "newsletter",
      "utm_medium": "email"
    },
    "totals": {
      "clicks": 1234,
      "unique_visitors": 987
    }
  }
}

// 客户端验证签名示例（Go）
func verifyWebhookSignature(payload []byte, signature, secret string) bool {
    // 提取时间戳和签名部分
    parts := strings.Split(signature, ",")
    if len(parts) != 2 {
        return false
    }

    ts := parts[0]
    sig := parts[1]

    // 防重放攻击：时间戳应在5分钟内
    timestamp, _ := strconv.ParseInt(strings.TrimPrefix(ts, "t="), 10, 64)
    if time.Since(time.Unix(timestamp, 0)) > 5*time.Minute {
        return false
    }

    // HMAC-SHA256 验证
    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write([]byte(fmt.Sprintf("%d.%s", timestamp, payload)))
    expectedSig := hex.EncodeToString(mac.Sum(nil))

    return hmac.Equal([]byte(sig), []byte(expectedSig))
}

package shortlink

import (
    "context"
    "net/http"
    "time"
)

// Client SDK 客户端
type Client struct {
    apiKey     string
    baseURL    string
    httpClient *http.Client
}

func NewClient(apiKey string) *Client {
    return &Client{
        apiKey:  apiKey,
        baseURL: "https://api.shortlink.pro/v1",
        httpClient: &http.Client{
            Timeout: 10 * time.Second,
        },
    }
}

func (c *Client) CreateLink(ctx context.Context, req CreateLinkRequest) (*Link, error) {
    return doRequest[Link](ctx, c, http.MethodPost, "/links", req)
}

func (c *Client) GetLink(ctx context.Context, slug string) (*Link, error) {
    return doRequest[Link](ctx, c, http.MethodGet, "/links/"+slug, nil)
}

func (c *Client) DeleteLink(ctx context.Context, slug string) error {
    _, err := doRequest[any](ctx, c, http.MethodDelete, "/links/"+slug, nil)
    return err
}

func (c *Client) ListLinks(ctx context.Context, opts ListOptions) (*PaginatedResult[Link], error) {
    params := url.Values{}
    if opts.Limit > 0 {
        params.Set("limit", strconv.Itoa(opts.Limit))
    }
    if opts.Offset > 0 {
        params.Set("offset", strconv.Itoa(opts.Offset))
    }
    if opts.Tag != "" {
        params.Set("tag", opts.Tag)
    }

    query := "/links?" + params.Encode()
    return doRequest[PaginatedResult[Link]](ctx, c, http.MethodGet, query, nil)
}

# shortlink/client.py
import requests
from typing import Optional, List
from dataclasses import dataclass
from urllib.parse import urljoin

@dataclass
class Link:
    id: str
    slug: str
    short_url: str
    target_url: str
    clicks: int
    status: str
    created_at: str

class Client:
    def __init__(self, api_key: str, base_url: str = "https://api.shortlink.pro/v1"):
        self.api_key = api_key
        self.base_url = base_url.rstrip("/")
        self.session = requests.Session()
        self.session.headers.update({
            "Authorization": f"Bearer {api_key}",
            "Content-Type": "application/json"
        })

    def create_link(self, target_url: str, **kwargs) -> Link:
        """创建短链

        Args:
            target_url: 目标长链接
            custom_slug: 自定义短码
            title: 链接标题
            tags: 标签列表
            expires_at: 过期时间 (ISO 8601)

        Returns:
            Link 对象
        """
        payload = {"target_url": target_url, **kwargs}
        resp = self.session.post(
            f"{self.base_url}/links",
            json=payload
        )
        resp.raise_for_status()
        return Link(**resp.json())

    def get_link(self, slug: str) -> Link:
        resp = self.session.get(f"{self.base_url}/links/{slug}")
        resp.raise_for_status()
        return Link(**resp.json())

    def shorten(self, url: str) -> str:
        """极简模式：传入长链接，返回短链接"""
        link = self.create_link(url)
        return link.short_url

// src/client.ts
export class ShortlinkClient {
  private apiKey: string;
  private baseURL: string;

  constructor(apiKey: string, options?: { baseURL?: string }) {
    this.apiKey = apiKey;
    this.baseURL = options?.baseURL ?? 'https://api.shortlink.pro/v1';
  }

  async createLink(request: CreateLinkRequest): Promise<Link> {
    const response = await fetch(`${this.baseURL}/links`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(request),
    });

    if (!response.ok) {
      const error = await response.json();
      throw new APIError(error.error.code, error.error.message, response.status);
    }

    return response.json();
  }

  async shorten(url: string): Promise<string> {
    const link = await this.createLink({ target_url: url });
    return link.short_url;
  }

  // 分页迭代器
  async *listLinks(options?: ListOptions): AsyncGenerator<Link> {
    let offset = 0;
    const limit = options?.limit ?? 100;

    while (true) {
      const result = await this.request<PaginatedResult<Link>>(
        `/links?limit=${limit}&offset=${offset}`
      );

      for (const link of result.data) {
        yield link;
      }

      if (!result.has_more) break;
      offset += limit;
    }
  }
}

type Link {
  id: ID!
  slug: String!
  shortUrl: String!
  targetUrl: String!
  title: String
  tags: [String!]
  status: LinkStatus!
  createdAt: DateTime!
  expiresAt: DateTime
  clicks: Int!
  stats: LinkStats
  domain: Domain
  qrcode(size: Int = 256): String
}

type LinkStats {
  totalClicks: Int!
  uniqueVisitors: Int!
  countries: [CountryStat!]!
  devices: [DeviceStat!]!
  dailyClicks(days: Int = 30): [DailyClick!]!
}

type Query {
  link(slug: String!): Link
  links(
    filter: LinkFilter
    orderBy: LinkOrderBy
    first: Int = 20
    after: String
  ): LinkConnection!
  
  # 聚合查询
  topLinks(
    period: TimePeriod!
    limit: Int = 10
  ): [Link!]!
}

type Mutation {
  createLink(input: CreateLinkInput!): Link!
  updateLink(slug: String!, input: UpdateLinkInput!): Link!
  deleteLink(slug: String!): Boolean!
  bulkCreateLinks(inputs: [CreateLinkInput!]!): [Link!]!
}

# 一次请求获取链接列表 + 统计 + 域名
query DashboardQuery {
  links(filter: { status: ACTIVE }, first: 10, orderBy: { field: CLICKS, direction: DESC }) {
    edges {
      node {
        slug
        shortUrl
        targetUrl
        clicks
        stats {
          uniqueVisitors
          countries(limit: 5) {
            code
            name
            count
          }
        }
        domain {
          hostname
          status
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

{
  "error": {
    "code": "INVALID_TARGET_URL",
    "message": "目标链接格式无效",
    "target": "target_url",
    "suggestion": "请确保链接包含协议（https://）且为有效URL",
    "example": "https://www.example.com/page",
    "documentation_url": "https://docs.shortlink.pro/errors/INVALID_TARGET_URL",
    "request_id": "req_abc123"
  }
}

# Postman
https://api.shortlink.pro/docs/postman-collection.json

# OpenAPI
https://api.shortlink.pro/docs/openapi.yaml