|
|
@ -0,0 +1,229 @@
|
|
|
|
|
|
|
|
# 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](#中文)
|