Google Analytics报告功能封装库实现

下面我将为你展示如何使用Go语言封装Google Analytics(GA)的报告API功能，创建一个简单的插件库。

1. 基础封装实现

首先我们需要创建一个基础结构体来封装GA API的交互：

package googleanalytics

import (
	"context"
	"encoding/json"
	"fmt"
	"log"
	"time"

	"golang.org/x/oauth2"
	"golang.org/x/oauth2/google"
	"google.golang.org/api/analyticsreporting/v4"
)

// GAClient 封装Google Analytics客户端
type GAClient struct {
	service *analyticsreporting.Service
	viewID  string
}

// NewGAClient 创建新的GA客户端
func NewGAClient(credentialsJSON []byte, viewID string) (*GAClient, error) {
	// 创建JWT配置
	config, err := google.JWTConfigFromJSON(
		credentialsJSON,
		analyticsreporting.AnalyticsReadonlyScope,
	)
	if err != nil {
		return nil, fmt.Errorf("无法解析服务账号JSON: %v", err)
	}

	// 创建HTTP客户端
	ctx := context.Background()
	client := config.Client(ctx)

	// 创建GA服务
	service, err := analyticsreporting.New(client)
	if err != nil {
		return nil, fmt.Errorf("无法创建GA服务: %v", err)
	}

	return &GAClient{
		service: service,
		viewID:  viewID,
	}, nil
}

2. 报告查询功能

添加获取报告的核心功能：

// ReportRequest 定义报告请求参数
type ReportRequest struct {
	StartDate      string
	EndDate        string
	Metrics        []string
	Dimensions     []string
	OrderBys       []string
	Filters        string
	PageSize       int64
	IncludeEmpty   bool
	UseSampling   bool
}

// GetReport 获取GA报告数据
func (ga *GAClient) GetReport(req *ReportRequest) (*analyticsreporting.GetReportsResponse, error) {
	// 构建指标
	var metrics []*analyticsreporting.Metric
	for _, m := range req.Metrics {
		metrics = append(metrics, &analyticsreporting.Metric{
			Expression: m,
		})
	}

	// 构建维度
	var dimensions []*analyticsreporting.Dimension
	for _, d := range req.Dimensions {
		dimensions = append(dimensions, &analyticsreporting.Dimension{
			Name: d,
		})
	}

	// 构建排序
	var orderBys []*analyticsreporting.OrderBy
	for _, o := range req.OrderBys {
		orderBys = append(orderBys, &analyticsreporting.OrderBy{
			FieldName: o,
			SortOrder: "DESCENDING",
		})
	}

	// 创建报告请求
	reportRequest := &analyticsreporting.ReportRequest{
		ViewId:         ga.viewID,
		DateRanges: []*analyticsreporting.DateRange{
			{StartDate: req.StartDate, EndDate: req.EndDate},
		},
		Metrics:        metrics,
		Dimensions:     dimensions,
		OrderBys:       orderBys,
		PageSize:       req.PageSize,
		IncludeEmptyRows: req.IncludeEmpty,
		SamplingLevel:  "LARGE",
	}

	if req.Filters != "" {
		reportRequest.FiltersExpression = req.Filters
	}

	// 发送请求
	return ga.service.Reports.BatchGet(
		&analyticsreporting.GetReportsRequest{
			ReportRequests: []*analyticsreporting.ReportRequest{reportRequest},
		},
	).Do()
}

3. 简化使用示例

添加一些简化使用的方法：

// GetSimpleReport 获取简化报告
func (ga *GAClient) GetSimpleReport(metrics, dimensions []string, days int) ([]map[string]string, error) {
	// 设置日期范围
	endDate := time.Now().Format("2006-01-02")
	startDate := time.Now().AddDate(0, 0, -days).Format("2006-01-02")

	// 构建请求
	req := &ReportRequest{
		StartDate:    startDate,
		EndDate:      endDate,
		Metrics:      metrics,
		Dimensions:   dimensions,
		PageSize:     1000,
		IncludeEmpty: false,
	}

	// 获取报告
	res, err := ga.GetReport(req)
	if err != nil {
		return nil, err
	}

	// 处理报告数据
	var results []map[string]string
	for _, report := range res.Reports {
		for _, row := range report.Data.Rows {
			rowData := make(map[string]string)
			
			// 添加维度
			for i, dim := range row.Dimensions {
				if i < len(req.Dimensions) {
					rowData[req.Dimensions[i]] = dim
				}
			}
			
			// 添加指标
			for i, metric := range row.Metrics[0].Values {
				if i < len(req.Metrics) {
					rowData[req.Metrics[i]] = metric
				}
			}
			
			results = append(results, rowData)
		}
	}

	return results, nil
}

4. 使用示例

下面是如何使用这个封装库的示例：

package main

import (
	"encoding/json"
	"fmt"
	"io/ioutil"
	"log"

	"github.com/yourusername/googleanalytics"
)

func main() {
	// 1. 读取服务账号凭据
	credentials, err := ioutil.ReadFile("service-account.json")
	if err != nil {
		log.Fatalf("无法读取凭据文件: %v", err)
	}

	// 2. 创建GA客户端
	ga, err := googleanalytics.NewGAClient(credentials, "YOUR_VIEW_ID")
	if err != nil {
		log.Fatalf("创建GA客户端失败: %v", err)
	}

	// 3. 获取简单报告
	metrics := []string{"ga:sessions", "ga:pageviews"}
	dimensions := []string{"ga:date", "ga:country"}
	
	data, err := ga.GetSimpleReport(metrics, dimensions, 7)
	if err != nil {
		log.Fatalf("获取报告失败: %v", err)
	}

	// 4. 输出结果
	jsonData, _ := json.MarshalIndent(data, "", "  ")
	fmt.Println(string(jsonData))
}

5. 高级功能扩展

你还可以添加更多高级功能：

// GetRealtimeData 获取实时数据
func (ga *GAClient) GetRealtimeData(metrics, dimensions []string) (*analyticsreporting.GetReportsResponse, error) {
	req := &ReportRequest{
		StartDate:  "today",
		EndDate:    "today",
		Metrics:    metrics,
		Dimensions: dimensions,
	}
	return ga.GetReport(req)
}

// GetUserActivity 获取用户活动数据
func (ga *GAClient) GetUserActivity(userID string, days int) (*analyticsreporting.GetReportsResponse, error) {
	req := &ReportRequest{
		StartDate:  time.Now().AddDate(0, 0, -days).Format("2006-01-02"),
		EndDate:    time.Now().Format("2006-01-02"),
		Metrics:    []string{"ga:totalEvents", "ga:sessionDuration"},
		Dimensions: []string{"ga:date", "ga:eventCategory", "ga:eventAction"},
		Filters:    fmt.Sprintf("ga:dimension1==%s", userID), // 假设dimension1是用户ID
		PageSize:   1000,
	}
	return ga.GetReport(req)
}

6. 错误处理和日志

添加更好的错误处理和日志记录：

// withRetry 带重试的请求执行
func (ga *GAClient) withRetry(fn func() (*analyticsreporting.GetReportsResponse, error), retries int) (*analyticsreporting.GetReportsResponse, error) {
	var lastErr error
	for i := 0; i < retries; i++ {
		res, err := fn()
		if err == nil {
			return res, nil
		}
		lastErr = err
		time.Sleep(time.Duration(i+1) * time.Second) // 指数退避
	}
	return nil, fmt.Errorf("重试%d次后失败: %v", retries, lastErr)
}

// GetReportWithRetry 带重试的报告获取
func (ga *GAClient) GetReportWithRetry(req *ReportRequest, retries int) (*analyticsreporting.GetReportsResponse, error) {
	fn := func() (*analyticsreporting.GetReportsResponse, error) {
		return ga.GetReport(req)
	}
	return ga.withRetry(fn, retries)
}

这个封装库提供了Google Analytics报告API的基本功能，包括：

1. 认证和客户端初始化
2. 报告请求构建
3. 简化数据获取
4. 错误处理和重试机制
5. 实时数据和用户活动等扩展功能

你可以根据需要进一步扩展这个库，添加缓存、并发请求、数据转换等功能。