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 // 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.
type Logger ¶ added in v1.0.1
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 NewClientWithOpts ¶
func NewClientWithOpts(endpoint string, opts *RPCClientOpts) RPCClient
NewClientWithOpts 返回一个包含自定义配置的RPCClient实例
endpoint: 发送JSON-RPC请求的JSON-RPC服务端URL opts: 自定义RPCClientOpts
type RPCClientOpts ¶
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
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 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 (*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