羊多多APP · 激流勇往直前对接API文档

版本: v1.0
Base URL: https://<your-domain>（服务器地址，从客户端APP获取）
认证: 登录后返回 token，后续接口通过请求头 Authorization: Bearer <token> 访问

业务流程

APP 启动小游戏后，小游戏先调用APP接口，获取用户信息与服务器配置信息。
小游戏根据认证结果决定是否进入：
- 已在 APP 登录：继续加载配置资源，拉取用户数据并进入首页；
- 未在 APP 登录：弹窗提示去 APP 登录，禁止进入小游戏。
后续接口（用户数据、排行榜、能量兑换、比赛记账）均在认证通过后使用。

flowchart TD
    A[羊多多APP] -->|启动小游戏| B[小游戏启动]
    A -->|POST /game/auth 传递用户+服务端信息| B
    B --> C{已在APP登录?}
    C -- 是 --> D[加载配置/资源]            C -- 否 --> G[弹窗提示前往APP登录 终止进入小游戏]
    D --> E[GET /user/{id} 拉取用户数据]
    E --> F[进入首页/待机]
    F --> H[GET /game/rank 排行榜]
    F --> I[POST /game/energy/exchange 能量兑换]
    F --> J[POST /game/match/start|end 记账]

总体约定

响应包统一结构
- code 整型，0 表示成功，非 0 表示失败
- errMsg 字符串，错误说明
- data 字典类型，成功时的业务数据
分页约定
- page 从 1 开始的页码
- row 每页记录数，默认 10，最大 100，服务端可做限制
时间戳
- 统一使用秒（Unix Timestamp, int64）
用户标识
- 使用 userId 作为 UDID（客户端已生成并持久化）

GET /client/info （APP提供接口）

H5 小游戏主动向 APP 客户端请求用户与服务端配置信息，用于后续调用 /game/auth 完成认证并访问服务端接口。

Auth: None
Response
- code int 成功为 0
- errMsg string 错误说明
- data object
  - userId string 用户唯一标识（UDID）
  - appToken string 可选；APP 侧登录态令牌，用于服务端校验
  - serverConfig object 服务端配置信息
    - root_url string 服务端根地址
    - cdn_url string CDN 根地址
    - config_url string 配置文件相对路径，如 config.json

示例

GET /client/info HTTP/1.1

{
  "code": 0,
  "errMsg": "",
  "data": {
    "userId": "u_9d2b3f1a",
    "appToken": "app-token-xxx",
    "serverConfig": {
      "root_url": "https://api.example.com",
      "cdn_url": "https://cdn.example.com/1.2.4/",
      "config_url": "config.json"
    }
  }
}

认证与用户数据

POST /game/auth （服务端提供接口）

用于小游戏认证，核实用户是否已在羊多多APP登录，同时下发服务端配置信息。

Auth: None
Body (application/json)
- userId string 必填；APP生成并传递的用户唯一ID（UDID）
- appToken string 可选；APP侧登录态令牌，用于服务端校验
Response
- code int 成功为 0；未登录返回 1001
- errMsg string 失败信息或未登录说明
- data object
  - authorized boolean 是否已在 APP 登录
  - userId string 确认后的用户唯一标识
  - cdn_url string CDN 根地址
  - config_url string 配置文件相对路径，如 config.json
  - token string 可选；服务端签发的访问令牌，用于后续接口 Authorization

示例

POST /game/auth HTTP/1.1
Content-Type: application/json

{
  "userId": "u_9d2b3f1a",
  "appToken": "app-token-xxx"
}

{
  "code": 0,
  "errMsg": "",
  "data": {
    "authorized": true,
    "userId": "u_9d2b3f1a",
    "token": "eyJhbGciOi...",
    "serverConfig": {
      "root_url": "https://api.example.com",
      "cdn_url": "https://cdn.example.com/1.2.4/",
      "config_url": "config.json",
    }
  }
}

未登录示例

{ "code": 1001, "errMsg": "未在APP登录，请前往APP登录后重试", "data": { "authorized": false } }

GET /user/{id} （服务端提供接口）

拉取用户资料与游戏进度数据。

Auth: Bearer
Path
- id string 用户ID（UDID）
Response
- code int
- errMsg string
- data object
  - userId string 用户ID
  - nickName string 昵称
  - avatarUrl string 头像 URL
  - gender number 可选；性别，0 未知，1 男，2 女
  - profile object 游戏进度与资产
    - gold int 金币
    - highScore int 最高分
    - exp int 经验值
    - level int 段位等级
    - skills object 技能等级映射，键为技能ID，值为等级
    - cars object 车辆解锁映射，键为车ID，值 1 表示已解锁
    - carsLv object 每辆车的属性等级
    - carsSkin object 每辆车当前皮肤ID
    - carskinUnlock object 皮肤解锁状态，键为皮肤ID, 值 1 表示已解锁
    - energy int 体力/能量当前值（新增）
    - maxEnergy int 体力最大值（新增）
    - energyRemainSec int 距离下一个体力点恢复的剩余秒数（新增）
    - starBank int 累计星星储备（新增，用于权益兑换）
    - lastExitTime int64 最后退出游戏时间戳（秒）
    - playNum int 当日对局次数

示例

GET /user/u_9d2b3f1a HTTP/1.1
Authorization: Bearer eyJhbGciOi...

{
  "code": 0,
  "errMsg": "",
  "data": {
    "userId": "u_9d2b3f1a",
    "nickName": "羊乐乐",
    "avatarUrl": "https://cdn/avatar/xxx.png",
    "gender": 1,
    "profile": {
      "gold": 280,
      "highScore": 5230,
      "exp": 180,
      "level": 7,
      "skills": { "101": 3, "102": 1 },
      "cars": { "0": 1, "3": 1 },
      "carsLv": { "0": 5 },
      "carsSkin": { "0": 12 },
      "carskinUnlock": { "12": 1, "200": 1 },
      "energy": 8,
      "maxEnergy": 20,
      "energyRemainSec": 45,
      "starBank": 36,
      "lastExitTime": 1731540000,
      "playNum": 5
    }
  }
}

PUT /user/{id} （服务端提供接口）

同步/更新指定用户的统一数据。用于双向打通，将客户端新增字段合并入服务端存储。

Auth: Bearer
Path
- id string 用户ID
Body (application/json)
- profile JSON；自定义键值内容（有数值变化的字段）
  - gold int 金币
  - highScore int 最高分
  - exp int 经验值
  - level int 段位等级
  - skills object 技能等级映射，键为技能ID，值为等级
  - cars object 车辆解锁映射，键为车ID，值 1 表示已解锁
  - carsLv object 每辆车的属性等级
  - carsSkin object 每辆车当前皮肤ID
  - carskinUnlock object 皮肤解锁状态，键为皮肤ID, 值 1 表示已解锁
  - energy int 体力/能量当前值（新增）
  - maxEnergy int 体力最大值（新增）
  - energyRemainSec int 距离下一个体力点恢复的剩余秒数（新增）
  - starBank int 累计星星储备（新增，用于权益兑换）
  - lastExitTime int64 最后退出游戏时间戳（秒）
Response
- code int
- errMsg string
- data object 返回更新后的数据（可选）

示例

PUT /user/u_9d2b3f1a HTTP/1.1
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json

{
  "userId": "u_9d2b3f1a",
  "profile": {
    "gold": 300,
    "highScore": 5230,
    "level": 7,
    "energy": 7,
    "maxEnergy": 20,
    "energyRemainSec": 300,
    "starBank": 40
  }
}

{ "code": 0, "errMsg": "", "data": { "updated": true } }

排行榜

GET /game/rank （服务端提供接口）

获取排行榜列表；默认按段位与最高分排序。

Auth: Bearer
Query
- orderBy string 可选；默认 level_desc,highScore_desc
- page int 页码，默认 1
- row int 页大小，默认 10
Response
- code int
- errMsg string
- data object
  - list array
    - userId string 用户ID
    - nickName string 昵称
    - avatarUrl string 头像 URL
    - gender number 可选；0/1/2
    - highScore int 最高分
    - level int 段位
  - page int 当前页
  - row int 页大小
  - total int 总记录数

示例

GET /game/rank?page=1&row=10 HTTP/1.1
Authorization: Bearer eyJhbGciOi...

{
  "code": 0,
  "errMsg": "",
  "data": {
    "list": [
      { "userId": "u_a1", "nickName": "玩家A", "avatarUrl": "", "gender": 0, "highScore": 8860, "level": 9 },
      { "userId": "u_b2", "nickName": "", "avatarUrl": "", "gender": 0, "highScore": 7310, "level": 8 }
    ],
    "page": 1,
    "row": 10,
    "total": 245
  }
}

能量体系

POST /game/energy/exchange （服务端提供接口）

使用羊多多APP金币兑换游戏能量；兑换比例由后台配置。

Auth: Bearer
Body (application/json)
- userId string 用户ID
- coins int 请求兑换的APP金币数量
- requestId string 可选；幂等请求ID，防重放
Response
- code int
- errMsg string
- data object
  - energyDelta int 增加的能量值
  - energyAfter int 兑换后的能量
  - maxEnergy int 最大能量
  - rate string 实际生效的兑换比例，如 "10_coins:1_energy"
  - requestId string 幂等ID回显

示例

POST /game/energy/exchange HTTP/1.1
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json

{
  "userId": "u_9d2b3f1a",
  "coins": 100,
  "requestId": "req_20251114_0001"
}

{
  "code": 0,
  "errMsg": "",
  "data": { "energyDelta": 10, "energyAfter": 18, "maxEnergy": 20, "rate": "10_coins:1_energy", "requestId": "req_20251114_0001" }
}

比赛记账

POST /game/match/start （服务端提供接口）

开局扣能量并返回本局凭证。

Auth: Bearer
Body (application/json)
- userId string 用户ID
- mode string 可选；游戏模式/场景
- energyCost int 本局消耗能量（由服务端确定，客户端传建议值）
Response
- code int
- errMsg string
- data object
  - matchId string 本局唯一凭证
  - energyAfter int 扣减后的能量
  - maxEnergy int 最大能量

POST /game/match/end （服务端提供接口）

结算上报本局结果；服务端计算并落库，同时按最高分与段位更新排行榜。

Auth: Bearer
Body (application/json)
- userId string 用户ID
- matchId string 与开局返回一致
- score int 本局分数
- level int 本局结束时段位
- starsEarned int 本局收集星星数
- durationSec int 对局时长（秒）
- killCount int 击败敌人数（如有）
- carLevel int 本局车等级（如有）
Response
- code int
- errMsg string
- data object
  - highScore int 更新后的最高分
  - level int 更新后的段位
  - starBankAfter int 累计星星，变动后的数值

错误码

0 成功
1001 未认证或令牌失效
1002 权限不足
2001 参数错误
3001 用户不存在
4001 排行榜服务不可用
5001 钱包扣减失败
5002 重复操作（重复兑换/结算）
9000 服务器内部错误

业务规则说明

排序规则：默认 level DESC, highScore DESC；客户端允许传 orderBy，但服务端可限制允许列表
能量恢复：服务端持久化 energy 与恢复节奏；客户端可显示 energyRemainSec 倒计时（离线恢复算法参考），以服务端数据为准
星星权益：starBank 为累计星星余额；每局 starsEarned 入账；兑换（道具/权益）由服务端扣减并返回最新余额
幂等性：兑换与结算支持 requestId/matchId 防重复；服务端需判重处理
头像与昵称：为空时客户端在排行榜用 userId 兜底展示

安全与性能

Header
- Authorization: Bearer <token> 必填（除登录验证）
- Content-Type: application/json 必填（POST/PUT）
超时
- 客户端请求默认超时 2.5–8 秒（视端内模块），建议服务端接口 2 秒内响应
速率限制
- 登录、兑换、结算建议限流；分页最大 row=100

字段字典

userId string 用户唯一标识（UDID）
nickName string 用户昵称
avatarUrl string 用户头像URL
gold int 金币余额
highScore int 最高分
exp int 经验值
level int 段位等级
skills object 技能等级映射（键：技能ID，值：等级）
cars object 车辆解锁映射（键：车ID，值：1表示已解锁）
carsLv object 车辆属性等级（键：车ID，值：等级）
carsSkin object 当前车皮肤（键：车ID，值：皮肤ID）
carskinUnlock object 皮肤解锁状态（键：皮肤ID，值：1表示已解锁）
energy int 当前能量（体力）
maxEnergy int 最大能量
energyRemainSec int 距离恢复下一个能量点的剩余秒数
starBank int 累计星星余额（用于权益兑换）
lastExitTime int64 最近一次退出时间（秒）
play_num int 当日对局次数
matchId string 对局唯一凭证（扩展）
requestId string 幂等请求ID（兑换/结算）

如需我根据后端实际实现调整字段命名或增加更多示例，请告知。

羊多多APP · 激流勇往直前 对接API文档