polaris

README

Polaris Go

English | 简体中文

README：

• Introduction
• How to use
• Examples
• Frameworks

Introduction

Polaris-go is golang SDK for Polaris. Polaris is an operation centre that supports multiple programming languages, with high compatibility to different application framework.

Polaris-go provide features listed as below:

• Service instance registration, and health check

  Provides API on/offline registration instance information, with regular report to inform caller server's healthy status.

• Service discovery

  Provides multiple API, for users to get a full list of server instance, or get one server instance after route rule filtering and loadbalancing, which can be applied to srevice invocation soon.

• Service circuitbreaking

  Provide API to report the invocation result, and conduct circuit breaker instance/group insolation based on collected data, eventually recover when the system allows.

• Service ratelimiting

  Provides API for applications to conduct quota check and deduction, supports rate limit policies that are based on server level and port.

How to use

polaris-go can be referenced by go mod, user can add dependency to go.mod file

go get -u github.com/polarismesh/polaris-go

API quick start guide，can reference：QuickStart

Examples

A polaris-examples module is included in our project for you to get started with polaris-go quickly. It contains an example, and you can refer to the readme file in the example project for a quick walkthrough.

• quick start
• router example
• circuit breaker example
• rate limiter example
• config center example

Frameworks

Developers usually use HTTP or RPC frameworks to develop distributed service. Polaris SDK is already integrated into some development frameworks. If using these frameworks, you can enable Polaris Service Governance functions without using Polaris SDK directly.

• dubbo-go
  • registry and discovery
  • routing
  • circuit breaker and rate limiter
  • examples
• grpc-go

Documentation

Overview

Package polaris api defines the interfaces for the external APIs.

Index

• func NewSDKContext() (api.SDKContext, error)
• func NewSDKContextByAddress(address ...string) (api.SDKContext, error)
• func NewSDKContextByConfig(cfg config.Configuration) (api.SDKContext, error)
• type CircuitBreakerAPI
  • func NewCircuitBreakerAPI() (CircuitBreakerAPI, error)
  • func NewCircuitBreakerAPIByConfig(cfg config.Configuration) (CircuitBreakerAPI, error)
  • func NewCircuitBreakerAPIByContext(context api.SDKContext) CircuitBreakerAPI
  • func NewCircuitBreakerAPIByFile(path string) (CircuitBreakerAPI, error)
• type ConfigAPI
  • func NewConfigAPI() (ConfigAPI, error)
  • func NewConfigAPIByConfig(cfg config.Configuration) (ConfigAPI, error)
  • func NewConfigAPIByContext(context api.SDKContext) ConfigAPI
  • func NewConfigAPIByFile(path string) (ConfigAPI, error)
• type ConfigFile
• type ConfigGroupAPI
  • func NewConfigGroupAPI() (ConfigGroupAPI, error)
  • func NewConfigGroupAPIByConfig(cfg config.Configuration) (ConfigGroupAPI, error)
  • func NewConfigGroupAPIByContext(context api.SDKContext) ConfigGroupAPI
  • func NewConfigGroupAPIByFile(path string) (ConfigGroupAPI, error)
• type ConsumerAPI
  • func NewConsumerAPI() (ConsumerAPI, error)
  • func NewConsumerAPIByAddress(address ...string) (ConsumerAPI, error)
  • func NewConsumerAPIByConfig(cfg config.Configuration) (ConsumerAPI, error)
  • func NewConsumerAPIByContext(context api.SDKContext) ConsumerAPI
  • func NewConsumerAPIByFile(path string) (ConsumerAPI, error)
• type GetAllInstancesRequest
• type GetConfigFileRequest
• type GetConfigGroupRequest
• type GetInstancesRequest
• type GetOneInstanceRequest
• type GetServiceRuleRequest
• type GetServicesRequest
• type InitCalleeServiceRequest
• type InstanceDeRegisterRequest
• type InstanceHeartbeatRequest
• type InstanceRegisterRequest
• type LimitAPI
  • func NewLimitAPI() (LimitAPI, error)
  • func NewLimitAPIByAddress(address ...string) (LimitAPI, error)
  • func NewLimitAPIByConfig(cfg config.Configuration) (LimitAPI, error)
  • func NewLimitAPIByContext(context api.SDKContext) LimitAPI
  • func NewLimitAPIByFile(path string) (LimitAPI, error)
• type ProcessLoadBalanceRequest
• type ProcessRoutersRequest
• type ProviderAPI
  • func NewProviderAPI() (ProviderAPI, error)
  • func NewProviderAPIByAddress(address ...string) (ProviderAPI, error)
  • func NewProviderAPIByConfig(cfg config.Configuration) (ProviderAPI, error)
  • func NewProviderAPIByContext(context api.SDKContext) ProviderAPI
  • func NewProviderAPIByFile(path string) (ProviderAPI, error)
• type QuotaFuture
• type QuotaRequest
  • func NewQuotaRequest() QuotaRequest
• type RouterAPI
  • func NewRouterAPI() (RouterAPI, error)
  • func NewRouterAPIByAddress(address ...string) (RouterAPI, error)
  • func NewRouterAPIByConfig(cfg config.Configuration) (RouterAPI, error)
  • func NewRouterAPIByContext(context api.SDKContext) RouterAPI
  • func NewRouterAPIByFile(path string) (RouterAPI, error)
• type ServiceCallResult
• type WatchAllInstancesRequest
• type WatchAllServicesRequest
• type WatchServiceRequest

Functions

func NewSDKContext

func NewSDKContext() (api.SDKContext, error)

NewSDKContext 创建SDK上下文

func NewSDKContextByAddress

func NewSDKContextByAddress(address ...string) (api.SDKContext, error)

NewSDKContextByAddress 根据address创建SDK上下文

func NewSDKContextByConfig

func NewSDKContextByConfig(cfg config.Configuration) (api.SDKContext, error)

NewSDKContextByConfig 根据配置创建SDK上下文

Types

type CircuitBreakerAPI

type CircuitBreakerAPI interface {
	api.SDKOwner
	// Check
	Check(model.Resource) (*model.CheckResult, error)
	// Report
	Report(*model.ResourceStat) error
	// MakeFunctionDecorator
	MakeFunctionDecorator(model.CustomerFunction, *api.RequestContext) model.DecoratorFunction
	// MakeInvokeHandler
	MakeInvokeHandler(*api.RequestContext) model.InvokeHandler
	// Destroy the api is destroyed and cannot be called again
	Destroy()
}

func NewCircuitBreakerAPI

func NewCircuitBreakerAPI() (CircuitBreakerAPI, error)

NewCircuitBreakerAPI 获取 CircuitBreakerAPI

func NewCircuitBreakerAPIByConfig

func NewCircuitBreakerAPIByConfig(cfg config.Configuration) (CircuitBreakerAPI, error)

NewCircuitBreakerAPIByConfig 通过配置对象获取 CircuitBreakerAPI

func NewCircuitBreakerAPIByContext

func NewCircuitBreakerAPIByContext(context api.SDKContext) CircuitBreakerAPI

NewCircuitBreakerAPIByContext 通过上下文对象获取 CircuitBreakerAPI

func NewCircuitBreakerAPIByFile

func NewCircuitBreakerAPIByFile(path string) (CircuitBreakerAPI, error)

NewCircuitBreakerAPIByFile 通过配置文件获取 CircuitBreakerAPI

type ConfigAPI

type ConfigAPI interface {
	api.SDKOwner
	// Deprecated: please use FetchConfigFile
	// GetConfigFile 获取配置文件
	GetConfigFile(namespace, fileGroup, fileName string) (model.ConfigFile, error)
	// FetchConfigFile 获取配置文件
	FetchConfigFile(*GetConfigFileRequest) (model.ConfigFile, error)
	// CreateConfigFile create configuration file
	CreateConfigFile(namespace, fileGroup, fileName, content string) error
	// UpdateConfigFile update configuration file
	UpdateConfigFile(namespace, fileGroup, fileName, content string) error
	// PublishConfigFile publish configuration file
	PublishConfigFile(namespace, fileGroup, fileName string) error
}

ConfigAPI api for configuration files.

func NewConfigAPI

func NewConfigAPI() (ConfigAPI, error)

NewConfigAPI 获取配置中心 API

func NewConfigAPIByConfig

func NewConfigAPIByConfig(cfg config.Configuration) (ConfigAPI, error)

NewConfigAPIByConfig 通过配置对象获取配置中心 API

func NewConfigAPIByContext

func NewConfigAPIByContext(context api.SDKContext) ConfigAPI

NewConfigAPIByContext 通过上下文对象获取配置中心 API

func NewConfigAPIByFile

func NewConfigAPIByFile(path string) (ConfigAPI, error)

NewConfigAPIByFile 通过配置文件获取配置中心 API

type ConfigFile

type ConfigFile model.ConfigFile

ConfigFile config

type ConfigGroupAPI

type ConfigGroupAPI interface {
	api.SDKOwner
	// GetConfigGroup .
	GetConfigGroup(namesapce, group string) (model.ConfigFileGroup, error)

	// FetchConfigGroup 获取配置分组
	FetchConfigGroup(*GetConfigGroupRequest) (model.ConfigFileGroup, error)
}

ConfigGroupAPI .

func NewConfigGroupAPI

func NewConfigGroupAPI() (ConfigGroupAPI, error)

NewConfigGroupAPI 获取配置中心 API

func NewConfigGroupAPIByConfig

func NewConfigGroupAPIByConfig(cfg config.Configuration) (ConfigGroupAPI, error)

NewConfigAPIByConfig 通过配置对象获取配置中心 API

func NewConfigGroupAPIByContext

func NewConfigGroupAPIByContext(context api.SDKContext) ConfigGroupAPI

NewConfigAPIByContext 通过上下文对象获取配置中心 API

func NewConfigGroupAPIByFile

func NewConfigGroupAPIByFile(path string) (ConfigGroupAPI, error)

NewConfigAPIByFile 通过配置文件获取配置中心 API

type ConsumerAPI

type ConsumerAPI interface {
	api.SDKOwner
	// GetOneInstance 同步获取单个服务
	GetOneInstance(req *GetOneInstanceRequest) (*model.OneInstanceResponse, error)
	// GetInstances 同步获取可用的服务列表
	GetInstances(req *GetInstancesRequest) (*model.InstancesResponse, error)
	// GetAllInstances 同步获取完整的服务列表
	GetAllInstances(req *GetAllInstancesRequest) (*model.InstancesResponse, error)
	// GetRouteRule 同步获取服务路由规则
	GetRouteRule(req *GetServiceRuleRequest) (*model.ServiceRuleResponse, error)
	// UpdateServiceCallResult 上报服务调用结果
	UpdateServiceCallResult(req *ServiceCallResult) error
	// WatchService 订阅服务消息
	WatchService(req *WatchServiceRequest) (*model.WatchServiceResponse, error)
	// GetServices 根据业务同步获取批量服务
	GetServices(req *GetServicesRequest) (*model.ServicesResponse, error)
	// InitCalleeService 初始化服务运行中需要的被调服务
	InitCalleeService(req *InitCalleeServiceRequest) error
	// WatchAllInstances 监听服务实例变更事件
	WatchAllInstances(req *WatchAllInstancesRequest) (*model.WatchAllInstancesResponse, error)
	// WatchAllServices 监听服务列表变更事件
	WatchAllServices(req *WatchAllServicesRequest) (*model.WatchAllServicesResponse, error)
	// Destroy 销毁API，销毁后无法再进行调用
	Destroy()
}

ConsumerAPI 主调端API方法.

func NewConsumerAPI

func NewConsumerAPI() (ConsumerAPI, error)

NewConsumerAPI 创建调用者API

func NewConsumerAPIByAddress

func NewConsumerAPIByAddress(address ...string) (ConsumerAPI, error)

NewConsumerAPIByAddress 创建调用者API

func NewConsumerAPIByConfig

func NewConsumerAPIByConfig(cfg config.Configuration) (ConsumerAPI, error)

NewConsumerAPIByConfig 创建调用者API

func NewConsumerAPIByContext

func NewConsumerAPIByContext(context api.SDKContext) ConsumerAPI

NewConsumerAPIByContext 创建调用者API

func NewConsumerAPIByFile

func NewConsumerAPIByFile(path string) (ConsumerAPI, error)

NewConsumerAPIByFile 创建调用者API

type GetAllInstancesRequest

type GetAllInstancesRequest api.GetAllInstancesRequest

GetAllInstancesRequest is the request struct for GetAllInstances.

type GetConfigFileRequest

type GetConfigFileRequest api.GetConfigFileRequest

type GetConfigGroupRequest

type GetConfigGroupRequest api.GetConfigGroupRequest

type GetInstancesRequest

type GetInstancesRequest api.GetInstancesRequest

GetInstancesRequest is the request struct for GetInstances.

type GetOneInstanceRequest

type GetOneInstanceRequest api.GetOneInstanceRequest

GetOneInstanceRequest is the request struct for GetOneInstance.

type GetServiceRuleRequest

type GetServiceRuleRequest api.GetServiceRuleRequest

GetServiceRuleRequest is the request struct for GetServiceRule.

type GetServicesRequest

type GetServicesRequest api.GetServicesRequest

GetServicesRequest is the request struct for GetServices.

type InitCalleeServiceRequest

type InitCalleeServiceRequest api.InitCalleeServiceRequest

InitCalleeServiceRequest is the request struct for InitCalleeService.

type InstanceDeRegisterRequest

type InstanceDeRegisterRequest api.InstanceDeRegisterRequest

InstanceDeRegisterRequest 实例注销请求.

type InstanceHeartbeatRequest

type InstanceHeartbeatRequest api.InstanceHeartbeatRequest

InstanceHeartbeatRequest 实例心跳请求.

type InstanceRegisterRequest

type InstanceRegisterRequest api.InstanceRegisterRequest

InstanceRegisterRequest 实例注册请求.

type LimitAPI

type LimitAPI interface {
	api.SDKOwner
	// GetQuota the interface obtains only one quota at a time
	GetQuota(request QuotaRequest) (QuotaFuture, error)
	// Destroy the api is destroyed and cannot be called again
	Destroy()
}

LimitAPI 限流相关的API相关接口.

func NewLimitAPI

func NewLimitAPI() (LimitAPI, error)

NewLimitAPI 通过以默认域名为埋点server的默认配置创建LimitAPI

func NewLimitAPIByAddress

func NewLimitAPIByAddress(address ...string) (LimitAPI, error)

NewLimitAPIByAddress 通过地址创建SDK LimitAPI对象

func NewLimitAPIByConfig

func NewLimitAPIByConfig(cfg config.Configuration) (LimitAPI, error)

NewLimitAPIByConfig 通过配置对象创建SDK LimitAPI对象

func NewLimitAPIByContext

func NewLimitAPIByContext(context api.SDKContext) LimitAPI

NewLimitAPIByContext 通过上下文创建SDK LimitAPI对象

func NewLimitAPIByFile

func NewLimitAPIByFile(path string) (LimitAPI, error)

NewLimitAPIByFile 通过配置文件创建SDK LimitAPI对象

type ProcessLoadBalanceRequest

type ProcessLoadBalanceRequest struct {
	model.ProcessLoadBalanceRequest
}

ProcessLoadBalanceRequest process load balancer to get the target instances

type ProcessRoutersRequest

type ProcessRoutersRequest struct {
	model.ProcessRoutersRequest
}

ProcessRoutersRequest process routers to filter instances

type ProviderAPI

type ProviderAPI interface {
	api.SDKOwner
	// RegisterInstance
	// minimum supported version of polaris-server is v1.10.0
	RegisterInstance(instance *InstanceRegisterRequest) (*model.InstanceRegisterResponse, error)
	// Register
	// 同步注册服务，服务注册成功后会填充instance中的InstanceID字段
	// 用户可保持该instance对象用于反注册和心跳上报
	Register(instance *InstanceRegisterRequest) (*model.InstanceRegisterResponse, error)
	// Deregister
	// 同步反注册服务
	Deregister(instance *InstanceDeRegisterRequest) error
	// Deprecated: Use RegisterInstance instead.
	// Heartbeat
	// 心跳上报
	Heartbeat(instance *InstanceHeartbeatRequest) error
	// Destroy
	// 销毁API，销毁后无法再进行调用
	Destroy()
}

ProviderAPI CL5服务端API的主接口.

func NewProviderAPI

func NewProviderAPI() (ProviderAPI, error)

NewProviderAPI 通过以默认域名为埋点server的默认配置创建ProviderAPI

func NewProviderAPIByAddress

func NewProviderAPIByAddress(address ...string) (ProviderAPI, error)

NewProviderAPIByAddress 通过address创建ProviderAPI

func NewProviderAPIByConfig

func NewProviderAPIByConfig(cfg config.Configuration) (ProviderAPI, error)

NewProviderAPIByConfig 通过配置对象创建SDK ProviderAPI对象

func NewProviderAPIByContext

func NewProviderAPIByContext(context api.SDKContext) ProviderAPI

NewProviderAPIByContext 通过上下文创建SDK ProviderAPI对象

func NewProviderAPIByFile

func NewProviderAPIByFile(path string) (ProviderAPI, error)

NewProviderAPIByFile 通过配置文件创建SDK ProviderAPI对象

type QuotaFuture

type QuotaFuture api.QuotaFuture

QuotaFuture rate limiter.

type QuotaRequest

type QuotaRequest api.QuotaRequest

QuotaRequest rate limiter.

func NewQuotaRequest

func NewQuotaRequest() QuotaRequest

NewQuotaRequest example create a quota query request.

type RouterAPI

type RouterAPI interface {
	api.SDKOwner
	// ProcessRouters process routers to filter instances
	ProcessRouters(*ProcessRoutersRequest) (*model.InstancesResponse, error)
	// ProcessLoadBalance process load balancer to get the target instances
	ProcessLoadBalance(*ProcessLoadBalanceRequest) (*model.OneInstanceResponse, error)
}

RouterAPI routing api methods

func NewRouterAPI

func NewRouterAPI() (RouterAPI, error)

NewRouterAPI 通过以默认域名为埋点server的默认配置创建RouterAPI

func NewRouterAPIByAddress

func NewRouterAPIByAddress(address ...string) (RouterAPI, error)

NewRouterAPIByAddress 通过address创建RouterAPI

func NewRouterAPIByConfig

func NewRouterAPIByConfig(cfg config.Configuration) (RouterAPI, error)

NewRouterAPIByConfig 通过配置对象创建SDK RouterAPI对象

func NewRouterAPIByContext

func NewRouterAPIByContext(context api.SDKContext) RouterAPI

NewRouterAPIByContext 通过上下文创建SDK RouterAPI对象

func NewRouterAPIByFile

func NewRouterAPIByFile(path string) (RouterAPI, error)

NewRouterAPIByFile 通过配置文件创建SDK RouterAPI对象

type ServiceCallResult

type ServiceCallResult api.ServiceCallResult

ServiceCallResult is the response struct for ServiceCall.

type WatchAllInstancesRequest

type WatchAllInstancesRequest api.WatchAllInstancesRequest

WatchAllInstancesRequest is the request to watch instances

type WatchAllServicesRequest

type WatchAllServicesRequest api.WatchAllServicesRequest

WatchAllServicesRequest is the request to watch services

type WatchServiceRequest

type WatchServiceRequest api.WatchServiceRequest

WatchServiceRequest is the request struct for WatchService.