小游戏服务平台 - 接口详细设计（入参/出参）
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）
5 代码实践：Go DTO 与统一响应封装
本节将 API 文档中的 JSON 格式转化为 Go struct DTO 与 Gin 路由 + 中间件，可直接用于前后端联调。
2.1 请求/响应 DTO
package dto
import "time"
type LoginRequest struct {
LoginType string `json:"login_type"`
Username string `json:"username"`
Password string `json:"password"`
OAuthProvider string `json:"oauth_provider"`
OAuthToken string `json:"oauth_token"`
}
type LoginResponse struct {
Code int `json:"code"`
Message string `json:"message"`
Data struct {
UserID uint64 `json:"user_id"`
AccessToken string `json:"access_token"`
RefreshToken string `json:"refresh_token"`
ExpiresIn int `json:"expires_in"`
} `json:"data"`
TraceID string `json:"trace_id"`
}
type GameDetailResponse struct {
Code int `json:"code"`
Message string `json:"message"`
Data struct {
GameID uint64 `json:"game_id"`
Name string `json:"name"`
Description string `json:"description"`
Version string `json:"version"`
Status string `json:"status"`
CDNURL string `json:"cdn_url"`
Tags []string `json:"tags"`
CreatedAt time.Time `json:"created_at"`
} `json:"data"`
}
type AdRequest struct {
SlotID int `form:"slot_id"`
UserID uint64 `form:"user_id"`
}
2.2 统一响应与错误封装
package response
import (
"github.com/gin-gonic/gin"
"net/http"
)
type APIResponse struct {
Code int `json:"code"`
Message string `json:"message"`
Data interface{} `json:"data,omitempty"`
TraceID string `json:"trace_id"`
}
func Success(c *gin.Context, data interface{}) {
c.JSON(http.StatusOK, APIResponse{Code: 0, Message: "success", Data: data, TraceID: c.GetString("trace_id")})
}
func Error(c *gin.Context, code int, message string) {
c.JSON(http.StatusOK, APIResponse{Code: code, Message: message, TraceID: c.GetString("trace_id")})
}
2.3 路由注册示例
package routes
import (
"github.com/gin-gonic/gin"
"playnow/handler"
"playnow/middleware"
)
func Register(r *gin.Engine) {
api := r.Group("/api/v1")
{
api.POST("/auth/login", handler.Login)
api.POST("/auth/refresh", handler.RefreshToken)
authorized := api.Group("", middleware.JWT(), middleware.VerifySig())
{
authorized.GET("/users/:id", handler.GetUser)
authorized.GET("/games/:id", handler.GetGame)
authorized.GET("/ads/request", handler.RequestAd)
authorized.POST("/payments", handler.CreatePayment)
}
}
}
本章小结
详细设计了用户服务、游戏服务、支付服务、广告服务等全模块的 RESTful API 入参/出参与数据结构，为前后端联调提供统一契约。
延伸阅读
相关专题
📂 本文属于 「小游戏服务平台」完整知识体系。
如果你正在构建一个 SaaS 小游戏平台，可参考 后端架构白皮书 了解多租户、缓存、高可用等通用架构模式。
继续阅读
探索更多技术文章
浏览归档，发现更多关于系统设计、工具链和工程实践的内容。