wt-game/point/README.md

point - TapDB事件上报SDK / TapDB Event Reporting SDK

中文 | English

---

中文

📖 简介

point 是专为TapDB设计的线程安全事件上报SDK，提供简洁的API接口和并发安全机制。采用单例模式设计，内置HTTP连接池和自动重试策略，适用于高并发场景下的数据上报。

GitHub地址: gitea.weitiangame.com/sdk/wt-game/point

📦 安装

go get gitea.weitiangame.com/sdk/wt-game/point

🚀 快速开始

初始化上报器

package main

import (
    "gitea.weitiangame.com/sdk/wt-game/point"
    "go.uber.org/zap"
)

func main() {
    logger, _ := zap.NewProduction()
    
    // 创建单例上报实例（自动注入client_id）
    reporter := point.New("your_client_id", logger)
}

基础事件上报

func main() {
    reporter := point.New("game_123", zap.NewExample())
    
    eventData := map[string]interface{}{
        "event":       "player_login",
        "distinct_id": "user_888",
        "properties": map[string]interface{}{
            "level":  5,
            "region": "cn",
        },
    }

    if resp, err := reporter.Event(eventData); err != nil {
        logger.Error("上报失败", zap.Error(err))
    } else {
        logger.Info("上报成功", 
            zap.Int("status", resp.StatusCode()),
            zap.String("trace_id", resp.Header().Get("X-Trace-Id")))
    }
}

🔧 高级用法

启用调试模式

func main() {
    // 初始化时启用调试和CURL输出
    reporter := point.New("client_123", logger).
        Debug().  // 显示请求详情
        Curl()    // 生成CURL命令
    
    reporter.Event(map[string]interface{}{
        "event": "ad_click",
        "properties": map[string]interface{}{
            "ad_id": "banner_001",
        },
    })
}

自定义HTTP客户端

func main() {
    customClient := ahttp.New(&ahttp.Config{
        Timeout:   10 * time.Second,
        Retries:   3,
    }).Client()

    point.New("game_123", logger).
        SetClient(customClient).  // 注入自定义客户端
        Event(eventData)
}

✨ 核心特性

特性	描述
单例模式	全局唯一实例，避免重复创建资源
线程安全	基于互斥锁保护配置变更，内置线程安全HTTP客户端
调试支持	支持请求详情输出和CURL命令生成
自动重试	依赖底层HTTP客户端的重试策略（默认3次）
数据隔离	自动复制传入数据，防止并发修改

⚠️ 注意事项

1. New() 方法为单例模式，首次调用后配置不可变更
2. Debug() 和 Curl() 建议仅在开发环境使用
3. 事件数据需包含 event 字段，建议包含 distinct_id 字段
4. HTTP响应状态码非2xx时需要检查请求参数
5. 上报数据量较大时建议批量处理

🤝 参与贡献

贡献指南 | 提交Issue

---

English

📖 Introduction

point is a thread-safe event reporting SDK designed for TapDB, featuring a clean API and concurrency-safe mechanisms. Built with singleton pattern and HTTP connection pooling, ideal for high-concurrency data reporting scenarios.

GitHub URL: gitea.weitiangame.com/sdk/wt-game/point

📦 Installation

go get gitea.weitiangame.com/sdk/wt-game/point

🚀 Quick Start

Initialize Reporter

package main

import (
    "gitea.weitiangame.com/sdk/wt-game/point"
    "go.uber.org/zap"
)

func main() {
    logger, _ := zap.NewProduction()
    
    // Create singleton instance (auto-injects client_id)
    reporter := point.New("your_client_id", logger)
}

Basic Event Reporting

func main() {
    reporter := point.New("game_123", zap.NewExample())
    
    eventData := map[string]interface{}{
        "event":       "player_login",
        "distinct_id": "user_888",
        "properties": map[string]interface{}{
            "level":  5,
            "region": "cn",
        },
    }

    if resp, err := reporter.Event(eventData); err != nil {
        logger.Error("Report failed", zap.Error(err))
    } else {
        logger.Info("Report succeeded", 
            zap.Int("status", resp.StatusCode()),
            zap.String("trace_id", resp.Header().Get("X-Trace-Id")))
    }
}

🔧 Advanced Usage

Enable Debug Mode

func main() {
    // Enable debug features during initialization
    reporter := point.New("client_123", logger).
        Debug().  // Show request details
        Curl()    // Generate CURL commands
    
    reporter.Event(map[string]interface{}{
        "event": "ad_click",
        "properties": map[string]interface{}{
            "ad_id": "banner_001",
        },
    })
}

Custom HTTP Client

func main() {
    customClient := ahttp.New(&ahttp.Config{
        Timeout:   10 * time.Second,
        Retries:   3,
    }).Client()

    point.New("game_123", logger).
        SetClient(customClient).  // Inject custom client
        Event(eventData)
}

✨ Key Features

Feature	Description
Singleton	Global single instance prevents resource duplication
Thread-Safe	Mutex-protected configuration with built-in safe HTTP client
Debug Support	Request diagnostics and CURL command generation
Auto Retry	Built-in retry policy (default 3 attempts)
Data Isolation	Automatic data copying prevents concurrent modification

⚠️ Important Notes

1. New() uses singleton pattern, configurations are immutable after first call
2. Use Debug() and Curl() only in development environments
3. Event data must contain event field, distinct_id is recommended
4. Check request parameters for non-2xx HTTP responses
5. Implement batch processing for large-scale data reporting

🤝 Contributing

Contribution Guide | Open an Issue

⬆ Back to Top