Golang 与 Azure Cosmos DB：REST 客户端和 gocosmos 驱动使用指南

Azure Cosmos DB 是微软提供的全球分布式多模型数据库服务。在 Golang 中，我们可以通过两种主要方式与 Cosmos DB 交互：使用 REST API 直接调用，或者使用 gocosmos 驱动库。

1. 使用 REST API 客户端

直接使用 REST API 可以让你更底层地控制与 Cosmos DB 的交互。以下是基本示例：

package main

import (
	"bytes"
	"context"
	"encoding/json"
	"fmt"
	"io/ioutil"
	"net/http"
	"time"
)

const (
	cosmosEndpoint = "https://<your-account>.documents.azure.com:443/"
	cosmosKey      = "<your-primary-key>"
	databaseName   = "testdb"
	collectionName = "testcollection"
)

func generateAuthHeader(method, resourceType, resourceLink, date string) string {
	// 实际实现中需要生成正确的授权头
	// 这里简化示例
	return "type=master&ver=1.0&sig=<signature>"
}

func cosmosRequest(ctx context.Context, method, path string, body interface{}) ([]byte, error) {
	url := cosmosEndpoint + path
	date := time.Now().UTC().Format("Mon, 02 Jan 2006 15:04:05 GMT")
	
	var reqBody []byte
	if body != nil {
		var err error
		reqBody, err = json.Marshal(body)
		if err != nil {
			return nil, err
		}
	}
	
	req, err := http.NewRequestWithContext(ctx, method, url, bytes.NewBuffer(reqBody))
	if err != nil {
		return nil, err
	}
	
	req.Header.Set("x-ms-date", date)
	req.Header.Set("x-ms-version", "2018-12-31")
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("Authorization", generateAuthHeader(method, "docs", "dbs/"+databaseName+"/colls/"+collectionName, date))
	
	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()
	
	return ioutil.ReadAll(resp.Body)
}

func main() {
	ctx := context.Background()
	
	// 创建文档示例
	doc := map[string]interface{}{
		"id":      "1",
		"name":    "John Doe",
		"email":   "john@example.com",
		"country": "USA",
	}
	
	response, err := cosmosRequest(ctx, "POST", 
		fmt.Sprintf("dbs/%s/colls/%s/docs", databaseName, collectionName), doc)
	if err != nil {
		fmt.Printf("Error: %v\n", err)
		return
	}
	
	fmt.Printf("Response: %s\n", response)
}

2. 使用 gocosmos 驱动库

gocosmos 是一个非官方的 Go 语言 Cosmos DB SDK，提供了更高级的抽象。

首先安装驱动：

go get github.com/btnguyen2k/gocosmos

基本使用示例

package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/btnguyen2k/gocosmos"
)

func main() {
	// 1. 创建客户端
	client := gocosmos.NewRestClient(nil, "<your-account>", "<your-primary-key>", "<your-database>")
	
	// 2. 检查连接
	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
	defer cancel()
	
	if _, err := client.GetDatabase(ctx, "<your-database>"); err != nil {
		log.Fatalf("Failed to connect to Cosmos DB: %v", err)
	}
	
	// 3. 创建集合（如果不存在）
	collectionSpec := gocosmos.CollectionSpec{
		DbName:           "<your-database>",
		CollectionName:   "users",
		PartitionKeyInfo: map[string]interface{}{"paths": []string{"/country"}, "kind": "Hash"},
	}
	if _, err := client.CreateCollection(ctx, collectionSpec); err != nil {
		log.Printf("Warning: collection may already exist: %v", err)
	}
	
	// 4. 插入文档
	doc := map[string]interface{}{
		"id":      "user1",
		"name":    "Alice",
		"email":   "alice@example.com",
		"country": "Canada",
	}
	
	if result, err := client.CreateDocument(ctx, "<your-database>", "users", doc); err != nil {
		log.Fatalf("Failed to create document: %v", err)
	} else {
		fmt.Printf("Created document with ID: %s\n", result.Document["id"])
	}
	
	// 5. 查询文档
	query := "SELECT * FROM users u WHERE u.country = @country"
	params := map[string]interface{}{"@country": "Canada"}
	
	if result, err := client.QueryDocuments(ctx, "<your-database>", "users", query, params); err != nil {
		log.Fatalf("Failed to query documents: %v", err)
	} else {
		fmt.Println("Query results:")
		for _, doc := range result.Documents {
			fmt.Printf("- %v\n", doc)
		}
	}
}

高级功能

批量操作

// 批量插入文档
func batchInsert(client *gocosmos.RestClient, dbName, collName string, docs []map[string]interface{}) error {
	ctx := context.Background()
	
	// 开始批量操作
	batch := client.NewBatchOperation(dbName, collName)
	
	// 添加文档到批量操作
	for _, doc := range docs {
		batch.AddDocument(doc, nil)
	}
	
	// 执行批量操作
	result, err := client.ExecuteBatch(ctx, batch)
	if err != nil {
		return err
	}
	
	fmt.Printf("Batch operation completed. Success: %d, Failed: %d\n", 
		result.NumberOfSuccessfulOperations(), result.NumberOfFailedOperations())
	
	return nil
}

存储过程

// 创建和执行存储过程
func createAndExecuteStoredProc(client *gocosmos.RestClient) error {
	ctx := context.Background()
	dbName := "testdb"
	collName := "users"
	
	// 存储过程代码
	sprocBody := `function(country) {
		var context = getContext();
		var collection = context.getCollection();
		var response = context.getResponse();
		
		var query = "SELECT * FROM users u WHERE u.country = '" + country + "'";
		var accepted = collection.queryDocuments(
			collection.getSelfLink(),
			query,
			{},
			function(err, docs, options) {
				if (err) throw err;
				response.setBody(docs);
			}
		);
		if (!accepted) throw new Error("Query not accepted");
	}`
	
	// 创建存储过程
	sproc := gocosmos.StoredProcedureSpec{
		DbName:         dbName,
		CollName:       collName,
		SprocName:      "getUsersByCountry",
		SprocBody:      sprocBody,
	}
	
	if _, err := client.CreateStoredProcedure(ctx, sproc); err != nil {
		return fmt.Errorf("failed to create stored procedure: %v", err)
	}
	
	// 执行存储过程
	params := []interface{}{"Canada"}
	result, err := client.ExecuteStoredProcedure(ctx, dbName, collName, "getUsersByCountry", params)
	if err != nil {
		return fmt.Errorf("failed to execute stored procedure: %v", err)
	}
	
	fmt.Printf("Stored procedure result: %v\n", result)
	return nil
}

选择建议

1. REST API 直接调用：

   • 适合需要精细控制请求/响应的场景
   • 当官方或第三方库不满足需求时
   • 学习 Cosmos DB 底层工作原理

2. gocosmos 驱动：

   • 提供更高级的抽象，简化开发
   • 内置连接池、重试机制等
   • 支持批量操作、存储过程等高级功能

在实际项目中，通常推荐使用 gocosmos 驱动，除非有特殊需求必须直接使用 REST API。