Help us shape the future of Go! Take the 2026 Go Developer Survey

polaris

package module
v1.7.2 Latest Latest
Warning

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

 Go to latest Published: Oct 14, 2026 License: Apache-2.0, BSD-2-Clause, BSD-3-Clause, + 3 more Imports: 3 Imported by: 73

README

Polaris Go

codecov Go goproxy Go Reference GitHub release (latest by date)

English | 简体中文

README：

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.

Documentation

Overview

Package polaris api defines the interfaces for the external APIs.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewSDKContext added in v1.2.0 

func NewSDKContext() (api.SDKContext, error)

NewSDKContext 创建SDK上下文

func NewSDKContextByAddress added in v1.2.0 

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

NewSDKContextByAddress 根据address创建SDK上下文

func NewSDKContextByConfig added in v1.2.0 

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

NewSDKContextByConfig 根据配置创建SDK上下文

Types

type AuthAPI added in v1.7.1 

type AuthAPI interface {
	api.SDKOwner
	// Authenticate 执行鉴权，按 provider.auth.chain 顺序调用各鉴权插件
	Authenticate(request *AuthenticateRequest) (*model.AuthenticateResponse, error)
	// Destroy 销毁 API，销毁后无法再进行调用
	Destroy()
}

AuthAPI 服务鉴权相关的 API 接口.

func NewAuthAPI added in v1.7.1 

func NewAuthAPI() (AuthAPI, error)

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

func NewAuthAPIByAddress added in v1.7.1 

func NewAuthAPIByAddress(address ...string) (AuthAPI, error)

NewAuthAPIByAddress 通过地址创建 SDK AuthAPI 对象

func NewAuthAPIByConfig added in v1.7.1 

func NewAuthAPIByConfig(cfg config.Configuration) (AuthAPI, error)

NewAuthAPIByConfig 通过配置对象创建 SDK AuthAPI 对象

func NewAuthAPIByContext added in v1.7.1 

func NewAuthAPIByContext(context api.SDKContext) AuthAPI

NewAuthAPIByContext 通过上下文创建 SDK AuthAPI 对象

func NewAuthAPIByFile added in v1.7.1 

func NewAuthAPIByFile(path string) (AuthAPI, error)

NewAuthAPIByFile 通过配置文件创建 SDK AuthAPI 对象

type AuthenticateRequest added in v1.7.1 

type AuthenticateRequest api.AuthenticateRequest

AuthenticateRequest 鉴权请求.

func NewAuthenticateRequest added in v1.7.1 

func NewAuthenticateRequest() *AuthenticateRequest

NewAuthenticateRequest 创建鉴权请求

type CircuitBreakerAPI added in v1.6.0 

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 added in v1.6.0 

func NewCircuitBreakerAPI() (CircuitBreakerAPI, error)

NewCircuitBreakerAPI 获取 CircuitBreakerAPI

func NewCircuitBreakerAPIByConfig added in v1.6.0 

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

NewCircuitBreakerAPIByConfig 通过配置对象获取 CircuitBreakerAPI

func NewCircuitBreakerAPIByContext added in v1.6.0 

func NewCircuitBreakerAPIByContext(context api.SDKContext) CircuitBreakerAPI

NewCircuitBreakerAPIByContext 通过上下文对象获取 CircuitBreakerAPI

func NewCircuitBreakerAPIByFile added in v1.6.0 

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
	// UpsertAndPublishConfigFile insert and publish configuration file
	UpsertAndPublishConfigFile(namespace, fileGroup, fileName, content 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 added in v1.5.6 

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

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

ConfigGroupAPI .

func NewConfigGroupAPI added in v1.5.6 

func NewConfigGroupAPI() (ConfigGroupAPI, error)

NewConfigGroupAPI 获取配置中心 API

func NewConfigGroupAPIByConfig added in v1.5.6 

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

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

func NewConfigGroupAPIByContext added in v1.5.6 

func NewConfigGroupAPIByContext(context api.SDKContext) ConfigGroupAPI

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

func NewConfigGroupAPIByFile added in v1.5.6 

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 added in v1.6.0 

type GetConfigFileRequest api.GetConfigFileRequest

type GetConfigGroupRequest added in v1.6.0 

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 added in v1.2.0 

type ProcessLoadBalanceRequest struct {
	model.ProcessLoadBalanceRequest
}

ProcessLoadBalanceRequest process load balancer to get the target instances

type ProcessRoutersRequest added in v1.2.0 

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)
	// LosslessRegister 无损上线注册, 会定时上报心跳
	LosslessRegister(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 added in v1.2.0 

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 added in v1.2.0 

func NewRouterAPI() (RouterAPI, error)

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

func NewRouterAPIByAddress added in v1.2.0 

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

NewRouterAPIByAddress 通过address创建RouterAPI

func NewRouterAPIByConfig added in v1.2.0 

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

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

func NewRouterAPIByContext added in v1.2.0 

func NewRouterAPIByContext(context api.SDKContext) RouterAPI

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

func NewRouterAPIByFile added in v1.2.0 

func NewRouterAPIByFile(path string) (RouterAPI, error)

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

type ServiceCallResult 

type ServiceCallResult api.ServiceCallResult

ServiceCallResult is the response struct for ServiceCall.

type WatchAllInstancesRequest added in v1.4.0 

type WatchAllInstancesRequest api.WatchAllInstancesRequest

WatchAllInstancesRequest is the request to watch instances

type WatchAllServicesRequest added in v1.4.1 

type WatchAllServicesRequest api.WatchAllServicesRequest

WatchAllServicesRequest is the request to watch services

type WatchServiceRequest 

type WatchServiceRequest api.WatchServiceRequest

WatchServiceRequest is the request struct for WatchService.

Source Files

View all Source files

Directories

Path Synopsis
Package api is the core API of polaris-go, which provides the basic functions of service discovery and.
 Package api is the core API of polaris-go, which provides the basic functions of service discovery and.
benchmark
benchmain command
benchsimple command
flags
Package flags provide convenience types and routines to accept specific types of flag values on the command line.
 Package flags provide convenience types and routines to accept specific types of flag values on the command line.
stats
Package stats tracks the statistics associated with benchmark runs.
 Package stats tracks the statistics associated with benchmark runs.
pkg
algorithm/hash
Package hash provides hash functions
 Package hash provides hash functions
algorithm/match
algorithm/rand
Package rand random digit
 Package rand random digit
algorithm/search
Package search .
 Package search .
clock
Package clock provides a global clock.
 Package clock provides a global clock.
config
Package config provides configuration definitions for polaris-go.
 Package config provides configuration definitions for polaris-go.
flow
Package flow provides core SDK flow implementations for polaris-go.
 Package flow provides core SDK flow implementations for polaris-go.
flow/configuration
Package configuration 提供配置文件和配置分组的拉取、缓存与变更监听。
 Package configuration 提供配置文件和配置分组的拉取、缓存与变更监听。
flow/data
flow/quota
flow/registerstate
flow/schedule
flow/startup
Package startup 提供 SDK 启动阶段的周期性任务回调，包括客户端状态上报、SDK 配置上报、 服务端服务同步以及客户端事件监听（WatchClientEvents）等。
 Package startup 提供 SDK 启动阶段的周期性任务回调，包括客户端状态上报、SDK 配置上报、 服务端服务同步以及客户端事件监听（WatchClientEvents）等。
log
metric
model
Package model provides data model definitions for polaris-go.
 Package model provides data model definitions for polaris-go.
model/event
Package event provides event model definitions for polaris-go.
 Package event provides event model definitions for polaris-go.
model/local
model/pb
model/pb/metric
model/pb/metric/v2
network
Package network provides network related functions.
 Package network provides network related functions.
plugin
plugin/admin
Package admin provides the admin plugin interface for polaris-go.
 Package admin provides the admin plugin interface for polaris-go.
plugin/authenticator
Package authenticator 定义服务鉴权插件接口。
 Package authenticator 定义服务鉴权插件接口。
plugin/circuitbreaker
plugin/common
plugin/configconnector
plugin/configfilter
plugin/events
plugin/healthcheck
plugin/loadbalancer
plugin/localregistry
plugin/location
plugin/lossless
Package lossless provides the lossless plugin interface for polaris-go.
 Package lossless provides the lossless plugin interface for polaris-go.
plugin/metrics
plugin/ratelimiter
plugin/register
plugin/serverconnector
plugin/servicerouter
plugin/weightadjuster
sdk
stat/loadbalance
stat/plugin
version
Package version provides version information for the polaris-go project.
 Package version provides version information for the polaris-go project.
plugin
admin/httpServer
Package httpserver provides HTTP server implementation for the admin plugin in polaris-go.
 Package httpserver provides HTTP server implementation for the admin plugin in polaris-go.
authenticator/blockallowlist
Package blockallowlist 提供基于黑白名单规则的服务鉴权插件实现
 Package blockallowlist 提供基于黑白名单规则的服务鉴权插件实现
circuitbreaker/composite
Package composite 实现块级化的熔断计数与状态机 将每条 BlockConfig 拆分为独立的 blockCounter，块级错误条件互不串扰； 资源级状态机仍由 ResourceCounters 统一维护，任一块的任一 trigger 触发即让资源进入 Open。
 Package composite 实现块级化的熔断计数与状态机 将每条 BlockConfig 拆分为独立的 blockCounter，块级错误条件互不串扰； 资源级状态机仍由 ResourceCounters 统一维护，任一块的任一 trigger 触发即让资源进入 Open。
circuitbreaker/composite/trigger
configconnector/polaris
configfilter/crypto
configfilter/crypto/aes
configfilter/crypto/rsa
events/pushgateway
healthcheck/http
healthcheck/tcp
healthcheck/udp
healthcheck/utils
loadbalancer/common
loadbalancer/hash
loadbalancer/maglev
loadbalancer/ringhash
loadbalancer/weightedrandom
Package weightedrandom provides weighted random load balancer implementation for polaris-go.
 Package weightedrandom provides weighted random load balancer implementation for polaris-go.
localregistry/common
localregistry/inmemory
location
location/local
location/remotehttp
location/remoteservice
location/remoteservice/proto
logger/zaplog
lossless/losslessController
Package losslesscontroller provides lossless controller implementation for polaris-go.
 Package losslesscontroller provides lossless controller implementation for polaris-go.
metrics/callauditlog
Package callauditlog 服务调用审计日志插件,通过 StatReporter 链逐条记录服务调用结果到独立审计文件。
 Package callauditlog 服务调用审计日志插件,通过 StatReporter 链逐条记录服务调用结果到独立审计文件。
metrics/common
metrics/prometheus
ratelimiter/common
Package common .
 Package common .
ratelimiter/reject
ratelimiter/reject_concurrency
Package rejectconcurrency 提供并发数限流插件，实现纯本地的并发计数语义。
 Package rejectconcurrency 提供并发数限流插件，实现纯本地的并发计数语义。
ratelimiter/unirate
serverconnector/common
serverconnector/grpc
Package grpc 实现基于 gRPC 的 Polaris 服务端连接器，负责与 naming/config 集群的 长连接管理、服务发现与上报等同步/异步调用，以及 WatchClientEvents 等双向流交互。
 Package grpc 实现基于 gRPC 的 Polaris 服务端连接器，负责与 naming/config 集群的 长连接管理、服务发现与上报等同步/异步调用，以及 WatchClientEvents 等双向流交互。
servicerouter/canary
servicerouter/dstmeta
servicerouter/filteronly
servicerouter/lane
Package lane 实现泳道路由（Lane Router）插件。
 Package lane 实现泳道路由（Lane Router）插件。
servicerouter/nearbybase
servicerouter/rulebase
servicerouter/setdivision
servicerouter/zeroprotect
weightadjuster/warmup
Package warmup provides warmup weight adjuster implementation for polaris-go.
 Package warmup provides warmup weight adjuster implementation for polaris-go.
test
common
discover
loadbalance
mock
ratelimit
serviceroute
Package test mock test for set division
 Package test mock test for set division
stability
subscribe
util
tools module

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.