prd

「小游戏服务平台」API

用户服务 1.1 登录接口 POST /api/v1/auth/login 入参出参 1.2 刷新 Token POST /api/v1/auth/refresh 入参出参 1.3 获取用户信息 GET /api/v1/users/{user_id} 出参 2.

Leeting Yan 2025-09-26 2 分钟阅读 549 字

小游戏服务平台 - 接口详细设计（入参/出参）

1. 用户服务

1.1 登录接口

POST /api/v1/auth/login

入参

{
  "login_type": "password",   // password / oauth
  "username": "test_user",    // 当 login_type=password
  "password": "123456",
  "oauth_provider": "wechat", // 当 login_type=oauth
  "oauth_token": "wx_xxx"
}

出参

{
  "code": 0,
  "message": "success",
  "data": {
    "user_id": "100928374923",
    "access_token": "eyJhbGciOiJIUzI1...",
    "refresh_token": "eyJhbGciOiJIUzI1...",
    "expires_in": 1800
  }
}

1.2 刷新 Token

POST /api/v1/auth/refresh

入参

{
  "refresh_token": "eyJhbGciOiJIUzI1..."
}

出参

{
  "code": 0,
  "message": "success",
  "data": {
    "access_token": "new_token_xxx",
    "expires_in": 1800
  }
}

1.3 获取用户信息

GET /api/v1/users/{user_id}

出参

{
  "code": 0,
  "message": "success",
  "data": {
    "user_id": "100928374923",
    "username": "test_user",
    "age": 22,
    "gender": 1,
    "region": "Beijing",
    "status": 1,
    "created_at": "2025-09-26T10:00:00Z"
  }
}

2. 游戏服务

2.1 上传游戏

POST /api/v1/games/upload

入参

multipart/form-data

file: game.zip
metadata: {
  "name": "Jump Game",
  "description": "A casual jump game",
  "version": "1.0.0",
  "tags": ["casual","jump"]
}

出参

{
  "code": 0,
  "message": "upload success",
  "data": {
    "game_id": "200123891237",
    "status": "pending_review"
  }
}

2.2 获取游戏详情

GET /api/v1/games/{id}

出参

{
  "code": 0,
  "message": "success",
  "data": {
    "game_id": "200123891237",
    "name": "Jump Game",
    "description": "A casual jump game",
    "version": "1.0.0",
    "status": "online",
    "cdn_url": "https://cdn.xxx.com/games/200123891237/v1/index.html",
    "tags": ["casual","jump"],
    "created_at": "2025-09-26T12:00:00Z"
  }
}

2.3 搜索游戏

GET /api/v1/games?tag=casual&keyword=jump&page=1&size=10

出参

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 125,
    "list": [
      {
        "game_id": "200123891237",
        "name": "Jump Game",
        "tags": ["casual","jump"],
        "status": "online"
      }
    ]
  }
}

3. 广告服务

3.1 请求广告

GET /api/v1/ads/request?slot_id=3001&user_id=100928374923

出参

{
  "code": 0,
  "message": "success",
  "data": {
    "ad_id": "ad_789123",
    "type": "reward",
    "material_url": "https://cdn.xxx.com/ads/ad_789123.mp4",
    "duration": 30,
    "click_url": "https://track.xxx.com/click?ad_id=ad_789123&user_id=100928374923"
  }
}

3.2 上报广告事件

POST /api/v1/ads/report

入参

{
  "user_id": "100928374923",
  "game_id": "200123891237",
  "ad_id": "ad_789123",
  "event_type": "click",
  "ts": "2025-09-26T12:00:00Z"
}

出参

{
  "code": 0,
  "message": "event logged"
}

4. 支付服务

4.1 创建订单

POST /api/v1/payments/create

入参

{
  "user_id": "100928374923",
  "game_id": "200123891237",
  "amount": 9.99,
  "currency": "USD",
  "pay_method": "wechat"   // wechat / alipay / stripe / paypal
}

出参

{
  "code": 0,
  "message": "order created",
  "data": {
    "order_id": "500123981273",
    "out_trade_no": "wx202509261200xx",
    "pay_url": "https://pay.wechat.com/order/wx202509261200xx"
  }
}

4.2 支付回调

POST /api/v1/payments/notify

入参（由支付网关推送）

{
  "out_trade_no": "wx202509261200xx",
  "status": "paid",
  "transaction_id": "wx_txn_001",
  "paid_at": "2025-09-26T12:01:00Z"
}

出参

{
  "code": 0,
  "message": "callback processed"
}

4.3 开发者提现

POST /api/v1/developers/withdraw

入参

{
  "developer_id": "dev_1001",
  "amount": 500.00,
  "currency": "USD",
  "account": {
    "method": "paypal",
    "account_id": "dev@example.com"
  }
}

出参

{
  "code": 0,
  "message": "withdraw request submitted",
  "data": {
    "settlement_id": "600918237182",
    "status": "pending"
  }
}

总结

我为 用户、游戏、广告、支付 四大模块整理了接口的 详细入参/出参 JSON 格式，同时包含：

错误码规范（code）
状态字段（status）
时间戳统一 ISO8601 UTC
幂等保障字段（如订单 out_trade_no）

← 上一篇 「小游戏服务平台」技术方案 下一篇 → 「小游戏服务平台」ADR

继续阅读

探索更多技术文章

浏览归档，发现更多关于系统设计、工具链和工程实践的内容。

全部文章返回首页