sdk

package
v1.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 25, 2026 License: MIT Imports: 28 Imported by: 3

Documentation

Index

Constants

View Source 
const (
	DefaultWsRoute = "/ws" // 默认WebSocket路由路径
)

WebSocket客户端常量

Variables

This section is empty.

Functions

func BuildRequestObject added in v1.0.146 

func BuildRequestObject(path string, requestObj interface{}, secret string, encrypted ...bool) ([]byte, error)

BuildRequestObject 构建标准的API请求数据 用于生成符合FreeGo协议的请求JSON数据

协议格式: 

{
  "d": "数据(Base64或AES加密)",
  "t": 时间戳,
  "n": Nonce随机数,
  "p": Plan模式(0=Base64, 1=AES),
  "s": HMAC-SHA256签名
}

构建流程: 1. JSON序列化请求对象 2. 根据encrypted参数选择编码方式 3. 生成时间戳和Nonce 4. 计算HMAC-SHA256签名 5. 构建完整的请求JSON

参数:

  • path: API路径，用于签名计算
  • requestObj: 请求数据对象，会被JSON序列化
  • secret: HMAC签名密钥
  • encrypted: 可选参数，是否使用AES加密 (默认false)

返回值:

  • []byte: 构建好的请求JSON字节数组
  • error: 构建失败时的错误信息

兼容性: - 这是早期版本的构建函数 - 新代码推荐使用PostByAuth或PostByECC方法 - 主要用于向后兼容和简单场景

注意: - 不支持ECDSA签名 - 使用固定的AES-CBC加密 (非GCM模式) - HMAC签名算法略有不同

Types

type AuthToken added in v1.0.98 

type AuthToken struct {
	Token   string `json:"token"`   // JWT认证令牌
	Secret  string `json:"secret"`  // 动态生成的AES密钥(Base64编码)
	Expired int64  `json:"expired"` // 令牌过期时间戳(Unix秒)
}

AuthToken 认证令牌结构体 包含JWT token、动态secret和过期时间

type HttpSDK 

type HttpSDK struct {
	Domain     string // API域名 (如: https://api.example.com)
	AuthDomain string // 认证域名 (可选，用于/key和/login接口)
	KeyPath    string // 公钥获取路径 (默认: /key)
	LoginPath  string // 登录路径 (默认: /login)

	ClientNo int64 // 客户端编号
	// contains filtered or unexported fields
}

HttpSDK FreeGo HTTP客户端SDK 支持ECC+AES-GCM加密传输、强制双向ECDSA签名验证、JWT认证等

安全特性: - AES-256-GCM 认证加密 - HMAC-SHA256 完整性验证 - 强制双向ECDSA签名验证 (必须配置) - 动态密钥协商 (ECDH) - 防重放攻击 (时间戳+Nonce)

使用模式: - PostByECC: 匿名访问，使用ECC密钥协商 (必须配置ECDSA) - PostByAuth: 登录后访问，使用JWT令牌 (必须配置ECDSA)

func NewHttpSDK added in v1.1.0 

func NewHttpSDK() *HttpSDK

NewHttpSDK 创建新的HttpSDK实例并设置默认值 提供便捷的构造函数，避免手动初始化所有字段

默认值: - KeyPath: "/key" - LoginPath: "/login" - timeout: 120秒 - language: "zh-CN"

返回值:

  • *HttpSDK: 初始化的HttpSDK实例

使用示例: 

sdk := NewHttpSDK()
sdk.Domain = "https://api.example.com"
sdk.ClientNo = 12345

func (*HttpSDK) AuthObject added in v1.0.98 

func (s *HttpSDK) AuthObject(object func() (interface{}, error))

AuthObject 设置登录认证对象 用于存储用户名、密码等登录凭据 自动登录时会使用此对象调用登录接口

参数:

  • object: 认证对象，包含用户名密码等信息

注意: 请使用指针对象以避免数据拷贝

func (*HttpSDK) AuthToken added in v1.0.98 

func (s *HttpSDK) AuthToken(object AuthToken)

AuthToken 设置JWT认证令牌 设置登录成功后获得的令牌，用于后续API调用的身份认证

参数:

  • object: AuthToken结构体，包含token、secret、expired字段

安全特性: - Token: JWT令牌，用于身份验证 - Secret: 动态生成的AES密钥，用于数据加密 - Expired: 令牌过期时间

注意: 此方法会覆盖之前设置的令牌

func (*HttpSDK) GetPublicKey 

func (s *HttpSDK) GetPublicKey() (*crypto.EcdhObject, *node.PublicKey, crypto.Cipher, error)

GetPublicKey 获取服务端ECC公钥并建立安全通信信道 这是ECC模式的核心初始化函数，实现密钥协商和强制身份验证

执行流程: 1. 生成客户端临时ECDH密钥对 (一次性使用) 2. 构造公钥交换请求 (包含客户端公钥) 3. 请求服务端/key接口获取服务端公钥 4. 验证服务端ECDSA签名 (强制要求) 5. 返回协商结果用于后续加密通信

安全特性: - ECDH密钥协商: 前向保密性 (PFS) - 临时密钥: 每次请求使用新的密钥对 - 强制ECDSA验证: 验证服务端身份真实性

返回值:

  • *crypto.EcdhObject: 客户端ECDH对象 (包含私钥)
  • *node.PublicKey: 服务端公钥信息
  • crypto.Cipher: ECDSA验证对象 (必须配置)
  • error: 执行失败时的错误信息

注意: - 必须预先配置ECDSA对象，否则会抛出异常 - ECDH对象包含敏感的私钥信息，使用后应立即清除 - 此方法会在每次PostByECC调用时执行

func (*HttpSDK) PostByAuth 

func (s *HttpSDK) PostByAuth(path string, requestObj, responseObj interface{}, encrypted bool) error

PostByAuth 通过JWT认证+强制ECDSA模式发送POST请求 适用于登录后的业务API调用，使用令牌进行身份认证

安全协议栈: 1. TLS 1.2+ (网络层加密) 2. JWT令牌认证 (身份验证) 3. AES-GCM或Base64 (数据加密，可选) 4. HMAC-SHA256 (数据完整性) 5. 强制双向ECDSA签名验证 (必须配置)

执行流程: 1. 检查认证状态，自动登录 (如果需要) 2. 获取认证令牌 (Token + Secret) 3. 根据encrypted参数选择加密方式 4. 生成HMAC-SHA256签名 5. 添加ECDSA签名 (如果配置) 6. 发送HTTP请求 (Authorization头) 7. 验证响应HMAC签名 8. 验证响应ECDSA签名 (如果配置) 9. 解密响应数据

参数:

  • path: API路径，如"/user/info"
  • requestObj: 请求数据对象
  • responseObj: 响应数据对象指针
  • encrypted: 是否使用AES-GCM加密 (true=Plan1, false=Plan0)

返回值:

  • error: 请求失败时的错误信息

安全特性: - JWT令牌认证: 身份验证和授权 - 动态Secret: 每次登录生成新的AES密钥 - 可选加密: 支持明文(Base64)和加密传输 - 双向签名: 可配置ECDSA提供金融级安全

使用场景: - 用户登录后的业务API调用 - 需要身份认证的接口 - 中等安全要求的场景

性能特点: - 比ECC模式更快 (复用令牌，无需密钥协商) - 支持高并发 (令牌复用) - 适合高频API调用

注意: - 需要预先登录或设置有效的authToken - 会自动处理令牌过期和续期

func (*HttpSDK) PostByECC 

func (s *HttpSDK) PostByECC(path string, requestObj, responseObj interface{}) error

PostByECC 通过ECC+AES-GCM+强制ECDSA模式发送POST请求 实现最高安全级别的API调用，支持匿名访问

安全协议栈 (从下到上): 1. TLS 1.2+ (网络层加密) 2. ECDH + AES-256-GCM (密钥协商 + 对称加密) 3. HMAC-SHA256 (数据完整性) 4. 强制双向ECDSA签名验证 (必须配置)

执行流程: 1. 获取服务端ECC公钥 (GetPublicKey) 2. 生成客户端ECDH密钥对 3. 计算共享密钥 (ECDH协商) 4. PBKDF2密钥派生 5. AES-GCM加密请求数据 6. 生成HMAC-SHA256签名 7. 添加ECDSA签名 (强制要求) 8. 发送HTTP请求 9. 验证响应HMAC签名 10. 验证响应ECDSA签名 (强制要求) 11. AES-GCM解密响应数据

参数:

  • path: API路径，如"/user/info"
  • requestObj: 请求数据对象 (会自动JSON序列化)
  • responseObj: 响应数据对象指针 (会自动JSON反序列化)

返回值:

  • error: 请求失败时的错误信息

安全特性: - 前向保密性 (PFS): 每次请求使用新密钥 - 完美前向保密: ECDH协商的密钥不依赖长期密钥 - 双向认证: 客户端和服务端相互验证身份 - 防重放攻击: 时间戳 + Nonce机制

使用场景: - 金融交易API - 敏感数据传输 - 匿名访问但需要高安全性的接口

注意: - 每次调用都会执行完整的密钥协商流程 - 适合低频但高安全要求的API调用

func (*HttpSDK) ResetAuth added in v1.1.0 

func (s *HttpSDK) ResetAuth() error

func (*HttpSDK) SetClientNo added in v1.1.0 

func (s *HttpSDK) SetClientNo(usr int64)

func (*HttpSDK) SetECDHObject added in v1.1.0 

func (s *HttpSDK) SetECDHObject(object *crypto.EcdhObject) error

SetECDHObject 设置预生成的ECDH密钥协商对象 用于复用ECDH密钥对，避免重复生成

参数:

  • object: ECDH密钥协商对象指针

返回值:

  • error: 设置失败时的错误信息

高级用法: 在连接池或长连接场景下可以复用ECDH对象

func (*HttpSDK) SetECDSAObject added in v1.1.0 

func (s *HttpSDK) SetECDSAObject(usr int64, prkB64, pubB64 string) error

SetECDSAObject 设置ECDSA签名验证对象 用于强制双向ECDSA签名验证，提供金融级身份认证

安全特性: - 强制双向ECDSA签名验证 (必须配置) - 支持多个备用ECDSA密钥对 - 客户端签名，服务端验证 - 服务端签名，客户端验证 - 防止中间人攻击和身份伪造

参数:

  • prkB64: ECDSA私钥(Base64编码)，用于客户端签名
  • pubB64: ECDSA公钥(Base64编码)，用于服务端验证

返回值:

  • error: 创建失败时的错误信息

注意: - 必须配置ECDSA对象，否则所有请求都会失败 - 可以多次调用添加多个备用密钥对 - 验证时会尝试所有配置的密钥对 - 私钥仅用于签名，公钥用于验证

func (*HttpSDK) SetLanguage added in v1.0.107 

func (s *HttpSDK) SetLanguage(language string)

SetLanguage 设置HTTP请求语言头 用于服务端国际化支持

参数:

  • language: 语言代码，如"zh-CN"、"en-US"等

HTTP头: 设置为"Language: {language}"

func (*HttpSDK) SetTimeout added in v1.0.101 

func (s *HttpSDK) SetTimeout(timeout int64)

SetTimeout 设置HTTP请求超时时间 控制单个API请求的最大等待时间

参数:

  • timeout: 超时时间(秒)，0表示使用默认120秒

默认值: 120秒 建议值: 根据网络状况设置，如30-300秒

type MessageHandler added in v1.1.0 

type MessageHandler interface {
	HandleMessage(message *node.JsonResp) error
}

MessageHandler 消息处理器接口

type RPC added in v1.1.0 

type RPC struct {
	Address string // gRPC服务地址 (如: localhost:9090)
	SSL     bool   // 是否启用SSL/TLS
	// contains filtered or unexported fields
}

RPC FreeGo gRPC客户端SDK 支持ECC+AES-GCM加密传输、强制双向ECDSA签名验证

安全特性: - AES-256-GCM 认证加密 - HMAC-SHA256 完整性验证 - 强制双向ECDSA签名验证 - 动态密钥协商 (ECDH) - 防重放攻击 (时间戳+Nonce)

func NewRPC added in v1.1.0 

func NewRPC(address string) *RPC

NewRPC 创建gRPC客户端SDK实例，初始化默认配置 address: gRPC服务地址，格式如 "localhost:9090" 返回: 配置了默认参数的RPC客户端实例

func (*RPC) AddCipher added in v1.1.0 

func (r *RPC) AddCipher(usr int64, cipher crypto.Cipher) *RPC

AddCipher 添加ECDSA密钥对用于双向签名验证 cipher: ECDSA加密器实例，包含公钥和私钥 返回: RPC实例，支持链式调用

func (*RPC) AddLocalCache added in v1.1.0 

func (r *RPC) AddLocalCache(c cache.Cache) *RPC

AddLocalCache 设置本地缓存实例，用于存储共享密钥等临时数据 c: 缓存接口实现，通常使用本地缓存实例 返回: RPC实例，支持链式调用

func (*RPC) Call added in v1.1.0 

func (r *RPC) Call(router string, requestObj, responseObj proto.Message, encrypted bool) error

Call 发送gRPC业务请求，使用默认超时时间 router: 业务路由标识符，用于服务端路由分发 requestObj: 请求数据对象，实现proto.Message接口 responseObj: 响应数据对象，实现proto.Message接口，用于接收服务端返回数据 encrypted: 是否启用AES-GCM加密传输 返回: 请求成功返回nil，否则返回错误信息

func (*RPC) CallWithTimeout added in v1.1.0 

func (r *RPC) CallWithTimeout(router string, requestObj, responseObj proto.Message, encrypted bool, timeout int64) error

CallWithTimeout 发送gRPC业务请求，指定自定义超时时间 router: 业务路由标识符，用于服务端路由分发 requestObj: 请求数据对象，实现proto.Message接口 responseObj: 响应数据对象，实现proto.Message接口，用于接收服务端返回数据 encrypted: 是否启用AES-GCM加密传输 timeout: 请求超时时间(秒) 返回: 请求成功返回nil，否则返回错误信息

func (*RPC) Close added in v1.1.0 

func (r *RPC) Close() error

Close 安全关闭gRPC连接，确保只关闭一次以避免重复关闭错误 返回: 关闭成功返回nil，否则返回关闭过程中的错误

func (*RPC) Connect added in v1.1.0 

func (r *RPC) Connect() error

Connect 建立与gRPC服务器的安全连接，执行必要的参数验证 返回: 连接成功返回nil，否则返回错误信息

func (*RPC) SetClientNo added in v1.1.0 

func (r *RPC) SetClientNo(usr int64) *RPC

func (*RPC) SetLanguage added in v1.1.0 

func (r *RPC) SetLanguage(language string) *RPC

SetLanguage 设置客户端语言标识，用于国际化支持 language: 语言代码，如 "zh-CN"、"en-US" 返回: RPC实例，支持链式调用

func (*RPC) SetSSL added in v1.1.0 

func (r *RPC) SetSSL(ssl bool) *RPC

SetSSL 配置是否启用SSL/TLS安全连接 ssl: true启用SSL/TLS连接，false使用明文连接 返回: RPC实例，支持链式调用

func (*RPC) SetTimeout added in v1.1.0 

func (r *RPC) SetTimeout(timeout int64) *RPC

SetTimeout 设置gRPC请求的超时时间 timeout: 超时时间(秒)，必须大于0 返回: RPC实例，支持链式调用

type SocketSDK added in v1.1.0 

type SocketSDK struct {
	Domain string // API域名 (如:api.example.com)

	SSL      bool  // 是否启用https
	ClientNo int64 // 客户端ID

	HealthPing int // 健康PING间隔时间/秒
	// contains filtered or unexported fields
}

func NewSocketSDK added in v1.1.0 

func NewSocketSDK(domain string) *SocketSDK

NewSocketSDK 创建新的WebSocket SDK实例并设置默认值

domain: API域名，如"api.example.com"

默认值: - timeout: 120秒 - maxReconnectAttempts: 10 - reconnectInterval: 1秒 - maxReconnectInterval: 30秒 - HealthPing: 30秒

返回值:

  • *SocketSDK: 初始化的WebSocket SDK实例

使用示例: 

sdk := NewSocketSDK("api.example.com")
sdk.AuthToken(AuthToken{...})
sdk.ClientNo = 12345

func (*SocketSDK) AuthObject added in v1.1.0 

func (s *SocketSDK) AuthObject(object interface{})

AuthObject 设置WebSocket客户端的登录认证对象 用于存储用户名、密码等登录凭据，自动登录时会使用此对象调用登录接口 object: 认证对象，包含用户名密码等信息，请使用指针对象避免数据拷贝

func (*SocketSDK) AuthToken added in v1.1.0 

func (s *SocketSDK) AuthToken(object AuthToken)

AuthToken 设置WebSocket客户端的JWT认证令牌 设置登录成功后获得的令牌，用于后续WebSocket消息的身份认证 object: AuthToken结构体，包含token、secret、expired字段

func (*SocketSDK) Close added in v1.1.0 

func (s *SocketSDK) Close()

Close 主动关闭整个 SDK（停止所有重连和连接）

func (*SocketSDK) ConnectWebSocket added in v1.1.0 

func (s *SocketSDK) ConnectWebSocket(path string) error

ConnectWebSocket 建立WebSocket连接并启动相关服务 path: WebSocket连接路径，如"/ws" 返回: 连接成功返回nil，否则返回连接失败的错误信息

func (*SocketSDK) DisableReconnect added in v1.1.0 

func (s *SocketSDK) DisableReconnect()

DisableReconnect 禁用自动重连

func (*SocketSDK) DisconnectWebSocket added in v1.1.0 

func (s *SocketSDK) DisconnectWebSocket()

DisconnectWebSocket 断开WebSocket连接，停止所有相关服务

func (*SocketSDK) EnableReconnect added in v1.1.0 

func (s *SocketSDK) EnableReconnect()

func (*SocketSDK) ForceReconnect added in v1.1.0 

func (s *SocketSDK) ForceReconnect() error

ForceReconnect 强制重新连接WebSocket，适用于连接异常恢复 返回: 重连成功返回nil，否则返回重连失败的错误信息

func (*SocketSDK) GetReconnectStatus added in v1.1.0 

func (s *SocketSDK) GetReconnectStatus() (enabled bool, attempts int, maxAttempts int, nextReconnectTime time.Time)

func (*SocketSDK) GetSubscriptions added in v1.1.0 

func (s *SocketSDK) GetSubscriptions() map[string]*Subscription

GetSubscriptions 获取所有活跃的订阅

func (*SocketSDK) IsWebSocketConnected added in v1.1.0 

func (s *SocketSDK) IsWebSocketConnected() bool

IsWebSocketConnected 检查WebSocket连接是否处于活跃状态 返回: true表示连接正常，false表示连接已断开

func (*SocketSDK) SendWebSocketMessage added in v1.1.0 

func (s *SocketSDK) SendWebSocketMessage(router string, requestObj, responseObj interface{}, waitResponse, encryptRequest bool, timeout int64) error

SendWebSocketMessage 发送WebSocket业务消息并可选等待响应 router: 业务路由标识符，用于服务端路由分发 requestObj: 请求数据对象 responseObj: 响应数据对象，用于接收服务端返回数据（当waitResponse=true时） waitResponse: 是否等待服务端响应 encryptRequest: 是否对请求数据进行加密 timeout: 等待响应的超时时间(秒) 返回: 发送成功返回nil，否则返回发送失败的错误信息

func (*SocketSDK) SetClientNo added in v1.1.0 

func (s *SocketSDK) SetClientNo(clientNo int64)

func (*SocketSDK) SetECDSAObject added in v1.1.0 

func (s *SocketSDK) SetECDSAObject(usr int64, prkB64, pubB64 string) error

SetECDSAObject 配置WebSocket客户端的ECDSA密钥对用于数字签名验证 usr: 客户端ID，服务端提供 prkB64: ECDSA私钥的Base64编码字符串 pubB64: ECDSA公钥的Base64编码字符串 返回: 配置成功返回nil，否则返回密钥解析错误

func (*SocketSDK) SetHealthPing added in v1.1.0 

func (s *SocketSDK) SetHealthPing(t int)

func (*SocketSDK) SetLanguage added in v1.1.0 

func (s *SocketSDK) SetLanguage(language string)

SetLanguage 设置WebSocket请求的语言标识 language: 语言代码，如"zh-CN"、"en-US"，用于服务端国际化支持

func (*SocketSDK) SetPushMessageCallback added in v1.1.0 

func (s *SocketSDK) SetPushMessageCallback(callback func(router string, data []byte))

SetPushMessageCallback 设置服务端主动推送消息的回调函数

func (*SocketSDK) SetReconnectConfig added in v1.1.0 

func (s *SocketSDK) SetReconnectConfig(enabled bool, maxAttempts int, initialInterval, maxInterval time.Duration)

func (*SocketSDK) SetTimeout added in v1.1.0 

func (s *SocketSDK) SetTimeout(timeout int64)

SetTimeout 设置WebSocket请求的超时时间 timeout: 超时时间(秒)，控制WebSocket消息发送和等待响应的最大时间

func (*SocketSDK) SetTokenExpiredCallback added in v1.1.0 

func (s *SocketSDK) SetTokenExpiredCallback(callback func())

func (*SocketSDK) SubscribeMessage added in v1.1.0 

func (s *SocketSDK) SubscribeMessage(router string, handler MessageHandler) (subscriptionID string, err error)

SubscribeMessage 订阅指定路由的消息 SubscribeMessage 订阅指定路由的消息推送 router: 要订阅的路由标识符 handler: 消息处理函数，当接收到对应路由的消息时会被调用 返回: 订阅ID和可能的错误信息

func (*SocketSDK) UnsubscribeMessage added in v1.1.0 

func (s *SocketSDK) UnsubscribeMessage(router string) error

UnsubscribeMessage 取消消息订阅 UnsubscribeMessage 取消订阅指定路由的消息推送 router: 要取消订阅的路由标识符 返回: 取消订阅成功返回nil，否则返回错误信息

type Subscription added in v1.1.0 

type Subscription struct {
	ID      string
	Router  string
	Handler MessageHandler
	// contains filtered or unexported fields
}

Subscription 订阅信息

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.