# point - TapDB事件上报SDK / TapDB Event Reporting SDK [中文](#中文) | [English](#english) --- ## 中文 ### 📖 简介 `point` 是专为TapDB设计的线程安全事件上报SDK,提供简洁的API接口和并发安全机制。采用单例模式设计,内置HTTP连接池和自动重试策略,适用于高并发场景下的数据上报。 GitHub地址: [gitea.weitiangame.com/sdk/wt-game/point](https://gitea.weitiangame.com/sdk/wt-game/point) ### 📦 安装 ```bash go get gitea.weitiangame.com/sdk/wt-game/point ``` ### 🚀 快速开始 #### 初始化上报器 ```go 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) } ``` #### 基础事件上报 ```go 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"))) } } ``` ### 🔧 高级用法 #### 启用调试模式 ```go 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客户端 ```go 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. 上报数据量较大时建议批量处理 ### 🤝 参与贡献 [贡献指南](CONTRIBUTING.md) | [提交Issue](https://gitea.weitiangame.com/sdk/wt-game/point/issues) --- ## 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](https://gitea.weitiangame.com/sdk/wt-game/point) ### 📦 Installation ```bash go get gitea.weitiangame.com/sdk/wt-game/point ``` ### 🚀 Quick Start #### Initialize Reporter ```go 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 ```go 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 ```go 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 ```go 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](CONTRIBUTING.md) | [Open an Issue](https://gitea.weitiangame.com/sdk/wt-game/point/issues) [⬆ Back to Top](#中文)