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
Source Files