Documentation

Index

Constants

const (
	// ParseError Parse error
	// Invalid JSON was received by the server.
	ParseError = -32600
)

Variables

This section is empty.

Functions

func Params

func Params(params ...interface{}) interface{}

Params is a helper function that uses the same parameter syntax as Call(). But you should consider to always use NewRequest() instead.

e.g. to manually create an RPCRequest object: request := &RPCRequest{

Method: "myMethod",
Params: Params("Alex", 35, true),

}

same with new request: request := NewRequest("myMethod", "Alex", 35, true)

If you know what you are doing you can omit the Params() call but potentially create incorrect rpc requests: request := &RPCRequest{

Method: "myMethod",
Params: 2, <-- invalid since a single primitive value must be wrapped in an array --> no magic without Params()

}

correct: request := &RPCRequest{

Method: "myMethod",
Params: []int{2}, <-- valid since a single primitive value must be wrapped in an array

}

Types

type Ctx

type Ctx interface {
	// Req 返回当前请求的Request
	Req() *http.Request
	// Header 获取头部参数
	Header(string) string
	// Bind 获取当前请求的URL参数
	Bind(interface{}) error
	// Base 获取一些请求的基础信息
	Base() map[string]string
	// Success 成功返回
	Success(interface{}) error
	// Error 错误返回
	Error(int, string, interface{}) error
	Logger() Logger
}

Ctx 接口,用于向Handler传递Web上下文数据,并提供简化操作完成请求处理

type HTTPError

type HTTPError struct {
	Code int
	// contains filtered or unexported fields
}

HTTPError represents a error that occurred on HTTP level.

An error of type HTTPError is returned when a HTTP error occurred (status code) and the body could not be parsed to a valid RPCResponse object that holds a RPCError.

Otherwise a RPCResponse object is returned with a RPCError field that is not nil.

func (*HTTPError) Error

func (e *HTTPError) Error() string

Error function is provided to be used as error object.

type Logger

type Logger interface {
	SetBase(base map[string]string)
	Debug(msg string, fields ...interface{})
	Info(msg string, fields ...interface{})
	Warn(msg string, fields ...interface{})
	Error(msg string, fields ...interface{})
}

Logger 定义日志接口

type RPCClient

type RPCClient interface {
	// Call 用于发送JSON-RPC请求到服务端.
	//
	// 规则说明, 参数只能是数组或map,不能是基础数据类型.
	// 所以有几个简单的规则要注意:
	//
	// 1. 无参数: Call("getinfo")
	//
	// 2. 单个基础数据参数: 参数值被封装在数组里面. 例如. Call("getByID", 1423)
	//
	// 3. 单个数组或map参数: 例如. Call("storePerson", &Person{Name: "Alex"})
	//
	// 4. 多个参数: 封装成数组. 例如. Call("setDetails", "Alex, 35, "Germany", true)
	//
	// 示例:
	//   Call("getinfo") -> {"method": "getinfo"}
	//   Call("getPersonId", 123) -> {"method": "getPersonId", "params": [123]}
	//   Call("setName", "Alex") -> {"method": "setName", "params": ["Alex"]}
	//   Call("setMale", true) -> {"method": "setMale", "params": [true]}
	//   Call("setNumbers", []int{1, 2, 3}) -> {"method": "setNumbers", "params": [1, 2, 3]}
	//   Call("setNumbers", 1, 2, 3) -> {"method": "setNumbers", "params": [1, 2, 3]}
	//   Call("savePerson", &Person{Name: "Alex", Age: 35}) -> {"method": "savePerson", "params": {"name": "Alex", "age": 35}}
	//   Call("setPersonDetails", "Alex", 35, "Germany") -> {"method": "setPersonDetails", "params": ["Alex", 35, "Germany"}}
	//
	Call(method string, params ...interface{}) (*RPCResponse, error)

	// CallRaw 和Call类似,但是没有处理requests.Params字段.
	// RPCRequest对象按提供的数据原样发送.
	// 查看: NewRequest, RPCRequest, Params()
	//
	// 建议优先考虑Call和CallFor
	CallRaw(request *RPCRequest) (*RPCResponse, error)

	// method和params: 和 Call() 方法的一样
	//
	// 如果请求不成功 (网络或http错误)或rpc响应返回一个错误,
	// error将得到一个错误类型的值. 如果它是JSON-RPC错误类型,那它可以通过*RPCError解析.
	//
	CallFor(out interface{}, method string, params ...interface{}) error

	// CallBatch 在一个请求中调用多个方法.
	//
	// 最直观的使用方式如下:
	// CallBatch(RPCRequests{
	//   NewRequest("myMethod1", 1, 2, 3),
	//   NewRequest("myMethod2", "Test"),
	// })
	//
	// 可以自己创建[]*RPCRequest数组,但不建议这样做,且应该注意以下几点:
	// - field Params is sent as provided, so Params: 2 forms an invalid json (correct would be Params: []int{2})
	// - you can use the helper function Params(1, 2, 3) to use the same format as in Call()
	// - `JSONRPC`字段值会被覆盖为"2.0"
	// - `ID`字段会被覆盖为一个映射到数组下标的值 (例如. requests[5].ID == 5)
	//
	// - 返回的RPCResponses是[]*RPCResponse
	// - 注意RPCResponses的值是无序的, 这样就可能发生: responses[i] != responses[i].ID
	// - RPCPersponses有一些有用的函数, 例如: responses.HasError(), 如果其中某一个请求响应是RPCError则返回true
	CallBatch(requests RPCRequests) (RPCResponses, error)

	// CallBatchRaw  在一个请求中调用多个RPCRequests.
	// It sends the RPCRequests parameter is it passed (no magic, no id autoincrement).
	//
	// 建议优先考虑CallBatch.
	//
	// CallBatchRaw(RPCRequests{
	//   &RPCRequest{
	//     ID: 123,            // 在CallBatchRaw里面,该值不会变
	//     JSONRPC: "wrong",   // 在CallBatchRaw里面,该值不会变
	//     Method: "myMethod1",
	//     Params: []int{1},   // 没有处理, 所以必须确保是array或map
	//   },
	//   &RPCRequest{
	//     ID: 612,
	//     JSONRPC: "2.0",
	//     Method: "myMethod2",
	//     Params: Params("Alex", 35, true), // Params()方法可以处理参数
	//   },
	// })
	//
	// - 返回的RPCResponses是[]*RPCResponse
	// - 注意RPCResponses的值是无序的
	// - 必须将id映射到您提供的id
	// - RPCPersponses有一些有用的函数, 例如: responses.HasError(), 如果其中某一个请求响应是RPCError则返回true
	CallBatchRaw(requests RPCRequests) (RPCResponses, error)
}

RPCClient 用于向提供JSON-RPC的后台发送基于HTTP协议的JSON-RPC请求.

func NewClient

func NewClient(endpoint string) RPCClient

NewClient 返回一个默认配置的RPCClient

endpoint: 发送JSON-RPC请求的JSON-RPC服务端URL

func NewClientWithOpts

func NewClientWithOpts(endpoint string, opts *RPCClientOpts) RPCClient

NewClientWithOpts 返回一个包含自定义配置的RPCClient实例

endpoint: 发送JSON-RPC请求的JSON-RPC服务端URL opts: 自定义RPCClientOpts

type RPCClientOpts

type RPCClientOpts struct {
	HTTPClient    *http.Client
	CustomHeaders map[string]string
}

RPCClientOpts 用于给NewClientWithOpts()以更改RPCClient的配置.

HTTPClient: 用于自定义http.Client (例如. 设置proxy,或 tls) CustomHeaders: 用于自定义headers, 例如. 设置 BasicAuth

type RPCError

type RPCError struct {
	Code    int         `json:"code"`
	Message string      `json:"message"`
	Data    interface{} `json:"data,omitempty"`
}

RPCError 表示JSON-RPC出错时错误对象

Code: 错误码 Message: 简短的错误信息 Data: 额外的错误数据, 值可以是nil

func InternalError

func InternalError() RPCError

InternalError JSON解析错误

func InvalidParams

func InvalidParams() RPCError

InvalidParams JSON解析错误

func InvalidRequest

func InvalidRequest() RPCError

InvalidRequest JSON解析错误

func MethodNotFound

func MethodNotFound() RPCError

MethodNotFound JSON解析错误

func ServerError

func ServerError() RPCError

ServerError JSON解析错误

func SetError

func SetError(code int, message string, data interface{}) RPCError

SetError 按格式设置rpc错误

func (RPCError) Error

func (e RPCError) Error() string

Error function is provided to be used as error object.

func (RPCError) SetData

func (e RPCError) SetData(data interface{}) RPCError

SetData 给RPCError的Data赋值

type RPCRequest

type RPCRequest struct {
	Method  string      `json:"method"`
	Params  interface{} `json:"params,omitempty"`
	ID      int         `json:"id"`
	JSONRPC string      `json:"jsonrpc"`
}

RPCRequest 表示JSON-RPC请求对象.

Method: 调用方法

Params: 调用参数,可以是nil. 否则只能是object或map

ID: 单个请求中值是1. 批量请求中每个请求的id值必须是唯一的.

JSONRPC: JSON-RPC 2.0版本的值总是 "2.0"

大多数时候你不应该自己创建RPCRequest对象.而是使用 Call(), CallFor(), NewRequest()

如果要自己创建(例如CallRaw()), 组装参数考虑使用Params()函数.

例如,手动创建如下RPCRequest: request := &RPCRequest{

Method: "myMethod",
Params: Params("Alex", 35, true),

}

如果知道自己在做什么,可以不用Params()以避免使用反射影响性能,但可能会创建不正确的rpc请求: request := &RPCRequest{

Method: "myMethod",
Params: 2, <-- 无效,因为单个基础数据类型的值必须包装在数组中 --> 没有使用Params()时

}

正确方式: request := &RPCRequest{

Method: "myMethod",
Params: []int{2},

}

func NewRequest

func NewRequest(method string, params ...interface{}) *RPCRequest

NewRequest 像使用Call()一样方便的返回一个RPCRequest

e.g. NewRequest("myMethod", "Alex", 35, true)

type RPCRequests

type RPCRequests []*RPCRequest

RPCRequests 定义[]*RPCRequest的类型

type RPCResponse

type RPCResponse struct {
	JSONRPC string      `json:"jsonrpc"`
	Result  interface{} `json:"result,omitempty"`
	Error   *RPCError   `json:"error,omitempty"`
	ID      interface{} `json:"id"`
}

RPCResponse 表示JSON-RPC响应对象

Result: 如果没有发生错误,则保存rpc调用的结果,否则为nil。当然,成功的值也可能是nil。 Error: 如果发生错误,则结果为RPCError对象, 成功则是nil。 ID: 单个请求时的值是0. 批量请求中每个请求的id值必须是唯一的. JSONRPC: JSON-RPC 2.0版本的值总是 "2.0"

func (*RPCResponse) GetBool

func (RPCResponse *RPCResponse) GetBool() (bool, error)

GetBool 将rpc响应转换为一个bool

func (*RPCResponse) GetFloat

func (RPCResponse *RPCResponse) GetFloat() (float64, error)

GetFloat 将rpc响应转换为一个float64

func (*RPCResponse) GetInt

func (RPCResponse *RPCResponse) GetInt() (int64, error)

GetInt 将rpc响应转换为一个int64

func (*RPCResponse) GetObject

func (RPCResponse *RPCResponse) GetObject(toType interface{}) error

GetObject 将rpc响应转换为任意类型(结果即json.Unmarshal()中所接收的值)

func (*RPCResponse) GetString

func (RPCResponse *RPCResponse) GetString() (string, error)

GetString 将rpc响应转换为一个string

type RPCResponses

type RPCResponses []*RPCResponse

RPCResponses 定义[]*RPCResponse的类型. 该类型实现了一些常用的处理列表值的方法

func (RPCResponses) AsMap

func (res RPCResponses) AsMap() map[int]*RPCResponse

AsMap RPCResponses改为id作key的map.id无效的会被抛弃,慎用!

func (RPCResponses) GetByID

func (res RPCResponses) GetByID(id int) *RPCResponse

GetByID 根据给定的id获取RPCResponses的一个RPCResponse, 如果该id不存在则返回nil

func (RPCResponses) HasError

func (res RPCResponses) HasError() bool

HasError RPCResponses的任一RPCResponse错误则返回true

type ServeMux

type ServeMux struct {
	// contains filtered or unexported fields
}

ServeMux method过滤器

func NewServer

func NewServer(addr string) *ServeMux

NewServer 启动rpc服务

func (*ServeMux) AddLogger

func (m *ServeMux) AddLogger(l Logger) *ServeMux

AddLogger 增加日志类

func (*ServeMux) Register

func (m *ServeMux) Register(pattern string, handler func(Ctx) error)

Register register functions to be called for specific rpc calls

func (*ServeMux) Run

func (m *ServeMux) Run() error

Run 启用服务

func (*ServeMux) ServeHTTP

func (m *ServeMux) ServeHTTP(w http.ResponseWriter, r *http.Request)

func (*ServeMux) SetDefaultFunc

func (m *ServeMux) SetDefaultFunc(def func(http.ResponseWriter, *http.Request))

SetDefaultFunc a function to be called if the request is not a HTTP JSON RPC call