Golang实现Oracle Coherence缓存API的gRPC网络传输插件库coherence-go-client的使用

Coherence Go Client简介

Coherence Go Client允许Go应用程序作为缓存客户端连接到Coherence集群，使用gRPC作为网络传输协议。

Coherence是一个可扩展、容错、云就绪的分布式平台，用于构建基于网格的应用程序和可靠存储数据。该产品广泛应用于关键金融交易系统、高性能电信产品和电子商务应用等领域。

主要特性

• 提供类似Map的接口操作缓存条目，包括：
  • Put, PutWithExpiry, PutIfAbsent, PutAll, Get, GetAll, Remove, Clear, GetOrDefault, Replace, ReplaceMapping, Size, IsEmpty, ContainsKey, ContainsValue, ContainsEntry等操作
• 支持集群端查询、聚合和过滤Map条目
• 支持使用EntryProcessors在集群端操作Map条目
• 支持注册监听器以接收以下通知：
  • Map的插入、更新和删除等变更事件
  • Map生命周期事件，如截断、释放或销毁
  • 会话生命周期事件，如连接、断开、重新连接和关闭
• 支持将Go结构体存储为JSON，并能够序列化为Java对象以便其他Coherence语言API访问
• 支持近缓存(Near Cache)，在Go客户端缓存频繁访问的数据以避免跨网络请求
• 在Coherence Community Edition 25.03+和商业版14.1.2.0+中支持简单和双端队列
• 所有Coherence API全面支持Go泛型

系统要求

• Coherence CE 22.06.4+, 25.03+ 或 Coherence 14.1.1.2206.4+ 商业版，并配置了gRPCProxy
• Go 1.23+

注意：如果要使用最新版本中的队列API，必须使用CE 24.09或商业版14.1.2.0.x。

注意：如果使用Go版本<1.23，可以使用客户端的v2.0.0版本。

启动支持gRPC的Coherence集群

在测试Go客户端之前，必须确保有可用的Coherence集群。对于本地开发，推荐使用Coherence CE Docker镜像，它包含了客户端正常运行所需的一切。

docker run -d -p 1408:1408 -p 30000:30000 ghcr.io/oracle/coherence-ce:25.03.1

安装

go get github.com/oracle/coherence-go-client/v2@latest

使用示例

以下示例连接到运行在默认端口1408上的gRPC Proxy的Coherence集群，创建一个键为int、值为string的新NamedMap，并执行Put()、Get()和Size()操作。

注意：键和值也可以是Go结构体。

package main

import (
    "context"
    "fmt"
    "github.com/oracle/coherence-go-client/v2/coherence"
)

func main() {
    var (
        value *string
        ctx   = context.Background()
    )

    // 创建一个新的Session，连接到默认gRPC端口1408
    session, err := coherence.NewSession(ctx, coherence.WithPlainText())
    if err != nil {
        panic(err)
    }
    defer session.Close()

    // 获取一个键为int、值为string的NamedMap
    namedMap, err := coherence.GetNamedMap[int, string](session, "my-map")
    if err != nil {
        panic(err)
    }

    // 放入一个新的键/值对
    if _, err = namedMap.Put(ctx, 1, "one"); err != nil {
        panic(err)
    }
    
    // 获取键1的值
    if value, err = namedMap.Get(ctx, 1); err != nil {
       panic(err)
    }
    fmt.Println("Value for key 1 is", *value)

    // 更新键1的值
    if _, err = namedMap.Put(ctx, 1, "ONE"); err != nil {
        panic(err)
    }

    // 获取更新后的值
    if value, err = namedMap.Get(ctx, 1); err != nil {
        panic(err)
    }
    fmt.Println("Updated value is", *value)

    // 移除该条目
    if _, err = namedMap.Remove(ctx, 1); err != nil {
        panic(err)
    }
}

更复杂的示例（使用结构体）

package main

import (
    "context"
    "fmt"
    "github.com/oracle/coherence-go-client/v2/coherence"
)

// 定义一个Person结构体
type Person struct {
    ID        int    `json:"id"`
    Name      string `json:"name"`
    Age       int    `json:"age"`
    Email     string `json:"email"`
}

func main() {
    ctx := context.Background()

    // 创建Session
    session, err := coherence.NewSession(ctx, coherence.WithPlainText())
    if err != nil {
        panic(err)
    }
    defer session.Close()

    // 获取一个键为string、值为Person的NamedMap
    namedMap, err := coherence.GetNamedMap[string, Person](session, "people")
    if err != nil {
        panic(err)
    }

    // 创建一个Person实例
    person := Person{
        ID:    1,
        Name:  "John Doe",
        Age:   30,
        Email: "john.doe@example.com",
    }

    // 将Person存入缓存
    if _, err = namedMap.Put(ctx, person.Email, person); err != nil {
        panic(err)
    }

    // 从缓存中获取Person
    value, err := namedMap.Get(ctx, person.Email)
    if err != nil {
        panic(err)
    }
    
    if value != nil {
        fmt.Printf("Retrieved person: %+v\n", *value)
    }

    // 使用PutIfAbsent方法
    newPerson := Person{
        ID:    2,
        Name:  "Jane Smith",
        Age:   28,
        Email: "jane.smith@example.com",
    }

    if previous, err := namedMap.PutIfAbsent(ctx, newPerson.Email, newPerson); err != nil {
        panic(err)
    } else if previous != nil {
        fmt.Println("Entry already existed")
    } else {
        fmt.Println("New entry added")
    }

    // 获取Map大小
    size, err := namedMap.Size(ctx)
    if err != nil {
        panic(err)
    }
    fmt.Printf("Map size: %d\n", size)
}

监听器示例

package main

import (
    "context"
    "fmt"
    "github.com/oracle/coherence-go-client/v2/coherence"
)

func main() {
    ctx := context.Background()

    // 创建Session
    session, err := coherence.NewSession(ctx, coherence.WithPlainText())
    if err != nil {
        panic(err)
    }
    defer session.Close()

    // 获取NamedMap
    namedMap, err := coherence.GetNamedMap[string, string](session, "events")
    if err != nil {
        panic(err)
    }

    // 创建监听器
    listener := coherence.MapListener[string, string]{
        OnInserted: func(e coherence.MapEvent[string, string]) {
            fmt.Printf("Entry inserted - key: %v, value: %v\n", e.Key(), e.NewValue())
        },
        OnUpdated: func(e coherence.MapEvent[string, string]) {
            fmt.Printf("Entry updated - key: %v, old value: %v, new value: %v\n", 
                e.Key(), e.OldValue(), e.NewValue())
        },
        OnDeleted: func(e coherence.MapEvent[string, string]) {
            fmt.Printf("Entry deleted - key: %v, old value: %v\n", e.Key(), e.OldValue())
        },
    }

    // 添加监听器
    if err = namedMap.AddListener(ctx, listener); err != nil {
        panic(err)
    }

    // 执行一些操作触发事件
    if _, err = namedMap.Put(ctx, "key1", "value1"); err != nil {
        panic(err)
    }

    if _, err = namedMap.Put(ctx, "key1", "value2"); err != nil {
        panic(err)
    }

    if _, err = namedMap.Remove(ctx, "key1"); err != nil {
        panic(err)
    }

    // 移除监听器
    if err = namedMap.RemoveListener(ctx, listener); err != nil {
        panic(err)
    }
}

注意事项

1. 确保Coherence集群已正确配置gRPC Proxy
2. 对于生产环境，应考虑使用安全连接而非明文连接
3. 合理处理错误和资源释放（如使用defer关闭session）
4. 根据实际需求选择合适的缓存策略和数据结构

以上示例展示了coherence-go-client的基本用法，更多高级功能可以参考官方文档和示例代码。