跳至主要內容

秒杀接口设计文档

秒杀接口设计文档

1. 接口概述

1.1 文档说明

本文档描述了秒杀系统的核心接口设计，包括接口定义、请求响应格式、错误码、限流策略等。

1.2 系统架构

  • 前端：React/Vue + CDN
  • 网关：Spring Cloud Gateway + 限流
  • 应用服务：Spring Boot + Redis + MySQL
  • 消息队列：Kafka/RocketMQ

2. 接口规范

2.1 基础规范

  • 协议：HTTPS
  • 数据格式：JSON
  • 编码：UTF-8
  • 时间格式：yyyy-MM-dd HH:mm:ss
  • 接口前缀：/api/seckill/v1

2.2 通用响应格式

{
  "code": 200,
  "message": "success",
  "data": {},
  "timestamp": "2024-01-01 12:00:00",
  "traceId": "abc123"
}

2.3 通用错误码

错误码描述说明
200成功请求成功
400参数错误请求参数有误
401未授权需要登录
403禁止访问权限不足
429请求过快触发限流
500系统错误服务器内部错误
1001活动未开始秒杀活动还未开始
1002活动已结束秒杀活动已经结束
1003库存不足商品库存不足
1004重复下单用户已经购买过该商品
1005验证码错误验证码不正确

3. 核心接口设计

3.1 秒杀商品列表接口

基本信息

  • 接口路径：GET /api/seckill/v1/goods/list
  • 接口描述：获取秒杀商品列表
  • 限流策略：1000 QPS/IP

请求参数

{
  "page": 1,
  "size": 10,
  "status": "ONGOING"
}
参数名类型必填描述示例
pageint否页码，默认11
sizeint否每页数量，默认10，最大5010
statusstring否活动状态：WAITING/ONGOING/FINISHEDONGOING

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "total": 100,
    "list": [
      {
        "goodsId": "123456",
        "goodsName": "iPhone 15",
        "goodsImage": "https://cdn.example.com/iphone15.jpg",
        "originalPrice": 5999.00,
        "seckillPrice": 3999.00,
        "stock": 1000,
        "soldCount": 500,
        "startTime": "2024-01-01 00:00:00",
        "endTime": "2024-01-01 02:00:00",
        "status": "ONGOING",
        "progress": 50
      }
    ]
  },
  "timestamp": "2024-01-01 12:00:00",
  "traceId": "abc123"
}

3.2 秒杀商品详情接口

基本信息

  • 接口路径：GET /api/seckill/v1/goods/{goodsId}
  • 接口描述：获取秒杀商品详情
  • 限流策略：2000 QPS/IP
  • 缓存策略：Redis缓存5分钟

请求参数

参数名类型必填描述示例
goodsIdstring是商品ID123456

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "goodsId": "123456",
    "goodsName": "iPhone 15",
    "goodsDesc": "全新iPhone 15，超强性能",
    "goodsImage": "https://cdn.example.com/iphone15.jpg",
    "goodsImages": [
      "https://cdn.example.com/iphone15_1.jpg",
      "https://cdn.example.com/iphone15_2.jpg"
    ],
    "originalPrice": 5999.00,
    "seckillPrice": 3999.00,
    "stock": 1000,
    "soldCount": 500,
    "startTime": "2024-01-01 00:00:00",
    "endTime": "2024-01-01 02:00:00",
    "status": "ONGOING",
    "rules": [
      "每人限购1件",
      "不支持退换货",
      "全国包邮"
    ],
    "canBuy": true,
    "buyLimit": 1,
    "userBought": 0
  },
  "timestamp": "2024-01-01 12:00:00",
  "traceId": "abc123"
}

3.3 获取验证码接口

基本信息

  • 接口路径：POST /api/seckill/v1/captcha/get
  • 接口描述：获取秒杀验证码
  • 限流策略：10 次/分钟/用户

请求参数

{
  "goodsId": "123456",
  "userId": "789"
}

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "captchaId": "cap_123456",
    "captchaImage": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
    "expireTime": 300
  },
  "timestamp": "2024-01-01 12:00:00",
  "traceId": "abc123"
}

3.4 验证验证码接口

基本信息

  • 接口路径：POST /api/seckill/v1/captcha/verify
  • 接口描述：验证验证码
  • 限流策略：30 次/分钟/用户

请求参数

{
  "captchaId": "cap_123456",
  "captchaCode": "A3B7",
  "userId": "789"
}

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "verified": true,
    "token": "verify_token_123456",
    "expireTime": 600
  },
  "timestamp": "2024-01-01 12:00:00",
  "traceId": "abc123"
}

3.5 秒杀下单接口

基本信息

  • 接口路径：POST /api/seckill/v1/order/create
  • 接口描述：创建秒杀订单
  • 限流策略：100 QPS/用户
  • 幂等性：基于用户ID+商品ID+时间窗口

请求头

Authorization: Bearer {token}
X-Verify-Token: {verifyToken}
X-Request-Id: {requestId}

请求参数

{
  "goodsId": "123456",
  "quantity": 1,
  "addressId": "addr_123",
  "timestamp": 1704067200000,
  "sign": "a1b2c3d4e5f6"
}
参数名类型必填描述示例
goodsIdstring是商品ID123456
quantityint是购买数量，固定为11
addressIdstring是收货地址IDaddr_123
timestamplong是请求时间戳（毫秒）1704067200000
signstring是请求签名a1b2c3d4e5f6

签名算法

sign = MD5(goodsId + quantity + addressId + timestamp + secretKey)

响应示例

{
  "code": 200,
  "message": "下单成功",
  "data": {
    "orderId": "order_123456789",
    "status": "SUCCESS",
    "queuePosition": 0,
    "estimatedTime": 0,
    "payUrl": "https://pay.example.com/order_123456789"
  },
  "timestamp": "2024-01-01 12:00:00",
  "traceId": "abc123"
}

特殊状态响应

排队中：

{
  "code": 200,
  "message": "正在排队中",
  "data": {
    "orderId": "order_123456789",
    "status": "QUEUING",
    "queuePosition": 15,
    "estimatedTime": 30
  }
}

库存不足：

{
  "code": 1003,
  "message": "库存不足",
  "data": null
}

3.6 订单状态查询接口

基本信息

  • 接口路径：GET /api/seckill/v1/order/{orderId}/status
  • 接口描述：查询订单状态
  • 限流策略：500 QPS/用户

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "orderId": "order_123456789",
    "status": "UNPAID",
    "goodsInfo": {
      "goodsId": "123456",
      "goodsName": "iPhone 15",
      "goodsImage": "https://cdn.example.com/iphone15.jpg",
      "seckillPrice": 3999.00
    },
    "quantity": 1,
    "totalAmount": 3999.00,
    "createTime": "2024-01-01 12:00:00",
    "payExpireTime": "2024-01-01 12:15:00",
    "payUrl": "https://pay.example.com/order_123456789"
  },
  "timestamp": "2024-01-01 12:00:00",
  "traceId": "abc123"
}

3.7 用户秒杀记录接口

基本信息

  • 接口路径：GET /api/seckill/v1/user/orders
  • 接口描述：获取用户秒杀订单列表
  • 限流策略：100 QPS/用户

请求参数

{
  "page": 1,
  "size": 10,
  "status": "ALL"
}

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "total": 5,
    "list": [
      {
        "orderId": "order_123456789",
        "goodsId": "123456",
        "goodsName": "iPhone 15",
        "goodsImage": "https://cdn.example.com/iphone15.jpg",
        "seckillPrice": 3999.00,
        "quantity": 1,
        "status": "PAID",
        "createTime": "2024-01-01 12:00:00",
        "payTime": "2024-01-01 12:02:00"
      }
    ]
  },
  "timestamp": "2024-01-01 12:00:00",
  "traceId": "abc123"
}

3.8 排队状态查询接口

基本信息

  • 接口路径：GET /api/seckill/v1/queue/{queueId}/status
  • 接口描述：查询排队状态
  • 限流策略：1000 QPS/IP

响应示例

{
  "code": 200,
  "message": "success",
  "data": {
    "queueId": "queue_123456",
    "position": 15,
    "estimatedTime": 30,
    "status": "WAITING",
    "canEnter": false
  },
  "timestamp": "2024-01-01 12:00:00",
  "traceId": "abc123"
}

4. 限流策略

4.1 接口级限流

接口限流策略说明
商品列表1000 QPS/IP基于IP限流
商品详情2000 QPS/IP基于IP限流
获取验证码10次/分钟/用户基于用户限流
验证验证码30次/分钟/用户基于用户限流
秒杀下单100 QPS/用户基于用户限流
订单查询500 QPS/用户基于用户限流

4.2 限流算法

  • 令牌桶算法：用于平滑突发流量
  • 滑动窗口：用于精确控制时间窗口内请求数
  • 分布式限流：基于Redis实现

4.3 限流响应

{
  "code": 429,
  "message": "请求过快，请稍后再试",
  "data": {
    "retryAfter": 5
  },
  "timestamp": "2024-01-01 12:00:00",
  "traceId": "abc123"
}

5. 安全策略

5.1 防刷机制

  1. 验证码验证：下单前必须通过验证码验证
  2. 签名验证：关键接口需要签名验证
  3. 时间戳验证：请求时间戳不能超过5分钟
  4. 幂等性控制：防止重复提交
  5. 黑名单机制：恶意用户加入黑名单

5.2 接口加密

// 前端签名示例
function generateSign(params, secretKey) {
    const sortedKeys = Object.keys(params).sort();
    const signString = sortedKeys.map(key => `${key}=${params[key]}`).join('&') + `&key=${secretKey}`;
    return md5(signString);
}

5.3 请求头验证

Authorization: Bearer {userToken}
X-Verify-Token: {captchaToken}
X-Request-Id: {uniqueRequestId}
X-Timestamp: {timestamp}
X-Sign: {signature}

6. 性能优化

6.1 缓存策略

数据类型缓存时间更新策略
商品列表5分钟定时更新
商品详情5分钟主动更新
库存信息实时实时更新
用户信息30分钟被动更新

6.2 数据库优化

  1. 索引优化：关键字段建立合适索引
  2. 读写分离：读操作走从库
  3. 分库分表：订单表按用户ID分表
  4. 连接池：合理配置数据库连接池

6.3 异步处理

  1. 订单创建：异步处理订单详情
  2. 库存同步：异步同步库存到数据库
  3. 消息通知：异步发送下单成功通知

7. 监控告警

7.1 关键指标

  • QPS：每秒请求数
  • RT：响应时间
  • 成功率：接口成功率
  • 库存准确性：库存一致性检查
  • 下单成功率：下单成功的比例

7.2 告警策略

  • QPS > 阈值：扩容告警
  • RT > 1s：性能告警
  • 成功率 < 99%：异常告警
  • 库存不一致：数据告警

8. 部署方案

8.1 服务器配置

  • 应用服务器：8C16G * 10台
  • Redis集群：16G * 6台
  • MySQL主从：32G * 3台
  • Kafka集群：16G * 3台

8.2 容器化部署

# docker-compose.yml
version: '3.8'
services:
  seckill-app:
    image: seckill:v1.0
    ports:
      - "8080:8080"
    environment:
      - SPRING_PROFILES_ACTIVE=prod
    deploy:
      replicas: 10
      resources:
        limits:
          cpus: '2'
          memory: 4G

8.3 自动扩缩容

# k8s HPA配置
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: seckill-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: seckill-app
  minReplicas: 5
  maxReplicas: 50
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 70

9. 接口测试

9.1 测试用例

  1. 正常流程测试：完整秒杀流程
  2. 并发测试：高并发下单测试
  3. 限流测试：触发限流机制
  4. 异常测试：各种异常场景
  5. 性能测试：压力测试

9.2 性能基准

  • 商品详情接口：RT < 100ms，QPS > 10000
  • 秒杀下单接口：RT < 500ms，QPS > 5000
  • 订单查询接口：RT < 200ms，QPS > 3000

10. 版本变更记录

版本日期变更内容作者
v1.02024-01-01初始版本牛哥
v1.12024-01-15新增排队机制牛哥
v1.22024-02-01优化限流策略牛哥

文档维护者：牛哥
最后更新时间：2024-01-01
文档状态：已发布

学习交流
如果你在编程面试、技术提升的路上苦苦摸索，别错过牛哥的公众号牛牛码特，定期更新系列知识，帮你精准攻克面试难关。点个关注👆，优质内容不错过!
公众号二维码
关注牛哥公众号：牛牛码特，回复：1，即可获得秋招大礼包
面经统计表/Java Top100面试题/秋招企业投递表
© 2025 牛牛码特 - 让技术学习更简单
Copyright © 2026 牛牛码特
公众号
公众号