Golang 实现 JSON-RPC 2.0 HTTP 客户端通信插件库 jsonrpc 的使用

简介

这是一个基于 JSON-RPC 2.0 规范的 Golang 实现，通过 HTTP 协议进行 RPC 通信的客户端库。

安装

go get -u github.com/ybbus/jsonrpc/v3

快速开始

以下是一个简单的示例，展示如何获取和更新人员信息：

package main

import (
	"context"
	"github.com/ybbus/jsonrpc/v3"
)

type Person struct {
	ID   int    `json:"id"`
	Name string `json:"name"`
	Age  int    `json:"age"`
}

func main() {
	rpcClient := jsonrpc.NewClient("http://my-rpc-service:8080/rpc")

	var person *Person
	rpcClient.CallFor(context.Background(), &person, "getPersonById", 4711)

	person.Age = 33
	rpcClient.Call(context.Background(), "updatePerson", person)
}

详细使用

生成 JSON-RPC 请求

简单调用：

func main() {
    rpcClient := jsonrpc.NewClient("http://my-rpc-service:8080/rpc")
    rpcClient.Call(ctx, "getDate")
    // 生成请求体: {"method":"getDate","id":0,"jsonrpc":"2.0"}
}

带参数的调用：

func main() {
    rpcClient := jsonrpc.NewClient("http://my-rpc-service:8080/rpc")
    rpcClient.Call(ctx, "addNumbers", 1, 2)
    // 生成请求体: {"method":"addNumbers","params":[1,2],"id":0,"jsonrpc":"2.0"}
}

处理 JSON-RPC 响应

基本错误处理：

func main() {
    rpcClient := jsonrpc.NewClient("http://my-rpc-service:8080/rpc")
    response, err := rpcClient.Call(ctx, "addNumbers", 1, 2)
    if err != nil {
        // 处理网络/HTTP错误
    }

    if response.Error != nil {
        // 处理RPC错误
        // 检查 response.Error.Code, response.Error.Message 和可选的 response.Error.Data
    }
}

获取响应结果：

func main() {
    rpcClient := jsonrpc.NewClient("http://my-rpc-service:8080/rpc")
    response, _ := rpcClient.Call(ctx, "addNumbers", 1, 2)

    result, err := response.GetInt()
    if err != nil {
        // 结果无法解析为整数
    }

    // 其他基本类型获取方法:
    response.GetFloat()
    response.GetString()
    response.GetBool()
}

使用 CallFor() 便捷方法

type Person struct {
    Id   int    `json:"id"`
    Name string `json:"name"`
    Age  int    `json:"age"`
}

func main() {
    rpcClient := jsonrpc.NewClient("http://my-rpc-service:8080/rpc")

    var person *Person
    err := rpcClient.CallFor(ctx, &person, "getPersonById", 123)

    if err != nil || person == nil {
        // 处理错误
    }

    fmt.Println(person.Name)
}

使用批量请求

func main() {
    rpcClient := jsonrpc.NewClient("http://my-rpc-service:8080/rpc")

    response, _ := rpcClient.CallBatch(ctx, RPCRequests{
      NewRequest("myMethod1", 1, 2, 3),
      NewRequest("anotherMethod", "Alex", 35, true),
      NewRequest("myMethod2", &Person{
        Name: "Emmy",
        Age: 4,
      }),
    })
}

自定义 HTTP 客户端

func main() {
	proxyURL, _ := url.Parse("http://proxy:8080")
	transport := &http.Transport{Proxy: http.ProxyURL(proxyURL)}

	httpClient := &http.Client{
		Transport: transport,
	}

	rpcClient := jsonrpc.NewClientWithOpts("http://my-rpc-service:8080/rpc", &jsonrpc.RPCClientOpts{
		HTTPClient: httpClient,
	})

	// 请求现在会使用代理
}

基本认证

func main() {
    rpcClient := jsonrpc.NewClientWithOpts("http://my-rpc-service:8080/rpc", &jsonrpc.RPCClientOpts{
		CustomHeaders: map[string]string{
			"Authorization": "Basic " + base64.StdEncoding.EncodeToString([]byte("myUser"+":"+"mySecret")),
		},
	})
    response, _ := rpcClient.Call(ctx, "addNumbers", 1, 2) // 发送带 Authorization 头的请求
}

OAuth 认证

func main() {
		credentials := clientcredentials.Config{
    		ClientID:     "myID",
    		ClientSecret: "mySecret",
    		TokenURL:     "http://mytokenurl",
    	}

    	rpcClient := jsonrpc.NewClientWithOpts("http://my-rpc-service:8080/rpc", &jsonrpc.RPCClientOpts{
    		HTTPClient: credentials.Client(context.Background()),
    	})

	// 请求现在会获取并使用 OAuth token
}

高级配置

允许响应中的未知字段

func main() {
	rpcClient := jsonrpc.NewClientWithOpts("http://my-rpc-service:8080/rpc", &jsonrpc.RPCClientOpts{
        AllowUnknownFields: true,
	})

	// 现在响应中允许未知字段
}

修改默认请求 ID

func main() {
    rpcClient := jsonrpc.NewClientWithOpts("http://my-rpc-service:8080/rpc", &jsonrpc.RPCClientOpts{
        DefaultRequestID: 1,
    })

    // 请求现在默认 ID 为 1
}

以上是 jsonrpc 库的基本使用方法和示例代码。这个库提供了灵活的配置选项，可以满足各种 JSON-RPC 2.0 客户端通信需求。