You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
wt-game/point/README.md

229 lines
6.6 KiB
Markdown

This file contains ambiguous Unicode characters!

This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.

# 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](#中文)