注册发现

引入依赖

go get github.com/polarismesh/polaris-go@latest

初始化 polaris.yaml

你需要在项目的根路径下创建一个 polaris.yaml 文件用于初始化 polaris-go SDK。polaris.yaml配置详细

服务注册

SDK实例构建

当初始化好 polaris.yaml 文件之后，你可以直接使用在 package github.com/polarismesh/polaris-go 下的 NewProviderAPI 方法进行构造一个 ProviderAPI SDK 实例

import (
    ...
	"github.com/polarismesh/polaris-go"
)


func main() {
    provider, err := polaris.NewProviderAPI()
}

注册请求体

// InstanceRegisterRequest 注册服务请求
type InstanceRegisterRequest struct {
	// 必选，服务名
	Service string
	// 必选，命名空间
	Namespace string
	// 必选，服务监听host，支持IPv6地址
	Host string
	// 必选，服务实例监听port
	Port int
	// 可选，资源访问Token，即用户/用户组访问凭据，仅当服务端开启客户端鉴权时才需配置
	ServiceToken string
	// 以下字段可选，默认nil表示客户端不配置，使用服务端配置
	// 服务协议
	Protocol *string
	// 服务权重，默认100，范围0-10000
	Weight *int
	// 实例提供服务版本号
	Version *string
	// 用户自定义metadata信息
	Metadata map[string]string
	// 该服务实例是否健康，默认健康
	Healthy *bool
	// 该服务实例是否隔离，默认不隔离
	Isolate *bool
    // 设置心跳健康检查ttl，单位为s，不填默认为5s，TTL的取值范围为 (0s, 60s]
    // 开启了心跳健康检查，客户端必须以TTL间隔上报心跳
    // 健康检查服务器3个TTL未受到心跳则将实例置为不健康
	TTL *int
    // Location 当前注册实例的地理位置信息，主要用于就近路由
	Location *Location
	// 可选，单次查询超时时间，默认直接获取全局的超时配置
	// 用户总最大超时时间为(1+RetryCount) * Timeout
	Timeout *time.Duration
	// 可选，重试次数，默认直接获取全局的超时配置
	RetryCount *int
}

说明： 鉴权文档可参考权限控制。

发起注册请求

你在初始化完 InstanceRegisterRequest 结构体后，只需要调用 ProviderAPI.RegisterInstance 方法即可完成实例注册，并且 RegisterInstance 方法内部会自动维护实例的心跳上报。

resp, err := provider.RegisterInstance(registerRequest)

服务发现

SDK实例构建

consumer, err := polaris.NewConsumerAPI()

发现服务实例

GetAllInstances

直接返回目标服务下的所有实例，包括不健康、隔离、权重为0、被熔断的实例，也会在返回的实例列表中。

// GetAllInstancesRequest 获取所有实例的请求
type GetAllInstancesRequest struct {
	// 必选，服务名
	Service string
	// 必选，命名空间
	Namespace string
	// 可选，单次查询超时时间，默认直接获取全局的超时配置
	// 用户总最大超时时间为(1+RetryCount) * Timeout
	Timeout *time.Duration
	// 可选，重试次数，默认直接获取全局的超时配置
	RetryCount *int
}

// 调用该方法执行请求
consumer.GetAllInstances()

GetInstances

每次获取一批可用服务提供者实例，该方法会执行路由流程。

该方法默认会过滤掉不健康、隔离、权重为0、被熔断的实例。

说明：

执行路由流程的条件

配置了 GetInstancesRequest.SourceService.Metadata 属性，会触发自定义路由流程
设置了 GetInstancesRequest.Metadata 属性，会触发元数据路由流程

// GetInstancesRequest 批量服务实例查询请求
type GetInstancesRequest struct {
	// 必选，服务名
	Service string
	// 必选，命名空间
	Namespace string
	// 可选，元数据信息，仅用于dstMetadata路由插件的过滤
	Metadata map[string]string
	// 主调方服务信息，只用于路由规则匹配
	SourceService *ServiceInfo
	// 可选，是否跳过服务路由筛选，默认false
	SkipRouteFilter bool
	// 可选，单次查询超时时间，默认直接获取全局的超时配置
	// 用户总最大超时时间为(1+RetryCount) * Timeout
	Timeout *time.Duration
	// 可选，重试次数，默认直接获取全局的超时配置
	RetryCount *int
}

// 调用该方法执行请求
consumer.GetInstances()

GetOneInstances

每次仅获取一个可用服务提供者实例，该方法会依次执行路由、负载均衡流程。

该方法默认会过滤掉不健康、隔离、权重为0、被熔断的实例。

说明：

执行路由流程的条件

配置了 GetOneInstanceRequest.SourceService.Metadata 属性，会触发自定义路由流程
设置了 GetOneInstanceRequest.Metadata 属性，会触发元数据路由流程

// GetOneInstanceRequest 单个服务实例查询请求
type GetOneInstanceRequest struct {
	// 必选，服务名
	Service string
	// 必选，命名空间
	Namespace string
	// 可选，元数据信息，仅用于dstMetadata路由插件的过滤
	Metadata map[string]string
	// 是否开启元数据匹配不到时启用自定义匹配规则，仅用于dstMetadata路由插件
	EnableFailOverDefaultMeta bool
	// 自定义匹配规则，仅当EnableFailOverDefaultMeta为true时生效
	FailOverDefaultMeta FailOverDefaultMetaConfig
	// 用户计算hash值的key
	HashKey []byte
	// 主调方服务信息
	SourceService *ServiceInfo
	// 可选，单次查询超时时间，默认直接获取全局的超时配置
	// 用户总最大超时时间为(1+RetryCount) * Timeout
	Timeout *time.Duration
	// 可选，重试次数，默认直接获取全局的超时配置
	RetryCount *int
	// 可选，备份节点数
	// 对于一致性hash等有状态的负载均衡方式
	ReplicateCount int
	// 可选，负载均衡算法
	LbPolicy string
}

// 调用该方法执行请求
consumer.GetOneInstance()

如何基于 polaris-go 客户端完成一个服务发现的程序

示例工程项目