core/

蓝鲸云 API 客户端(Golang)

蓝鲸 API 网关 SDK 提供了一种基于配置构建 SDK 的方案，本项目基于 gentleman 为该方案提供了底层实现。

指引

安装

一般情况下，本项目应该作为某个 SDK 的依赖被间接引入，如需直接引用，可以执行：

go get -u github.com/TencentBlueKing/bk-apigateway-sdks/core@latest

命名约定：

在 bkapi 包中，作以下命名约定：

快速使用

以下基于 demo 包中的示例：

import (
	"fmt"
	"github.com/TencentBlueKing/bk-apigateway-sdks/core/bkapi"
	"github.com/TencentBlueKing/bk-apigateway-sdks/demo"
)

// 创建客户端，并声明所有结果都使用 Json 格式
client, _ := demo.New(bkapi.ClientConfig{
	Endpoint: "https://httpbin.org/",
}, bkapi.OptJsonResultProvider())

// 创建结果变量
var result demo.AnythingResponse

// 调用接口
_, _ = client.Anything().
	SetResult(&result).
	Request()

// 结果将自动填充到 result 中
fmt.Printf("%#v", result)

进阶用法

启用日志

可通过 bkapi.ClientConfig 的 Logger 属性来传入日志实现，来捕获相关的流水日志和报错信息，辅助排查问题。 当该属性为空时，默认获取名为 github.com/TencentBlueKing/bk-apigateway-sdks/core/bkapi 的日志实现。 日志输出会带上请求对应的 Context，可以结合 OTLP 完善链路可观测性。 详见：github.com/TencentBlueKing/gopkg/logging。

配置中心

可以使用 ClientConfigRegistry 简化每次初始化客户端时都需要传递网关地址，认证信息等重复性工作，ClientConfigRegistry 本身已实现成 ClientConfigProvider，可直接替代 ClientConfig 来使用：

// 获取默认的配置中心
registry := bkapi.GetGlobalClientConfigRegistry()

// 注册默认的配置（不区分网关）
registry.RegisterDefaultConfig(bkapi.ClientConfig{
	BkApiUrlTmpl: "http://{api_name}.example.com/",
	Stage:        "prod",
})

// 注册指定网关配置
registry.RegisterDefaultConfig("my-gateway", bkapi.ClientConfig{
	Endpoint:      "http://special-api.example.com/",
	ClientOptions: []define.BkApiClientOption{bkapi.OptJsonResultProvider()},  // 声明这个网关的所有响应都是 JSON
})

// 可直接使用配置中心来初始化客户端
client, _ := New(registry)

Prometheus 指标

github.com/prometheus/client_golang/prometheus 模块实现了 Prometheus 插件，启用后可以统计请求过程中的指标：

// 启用指标插件，可设置指标前缀
prometheus.Enable(prometheus.PrometheusOptions{
	Namespace: "project",
	Subsystem: "module",
})

指标一览：

定义说明

资源封装

Operation 表示一个网关资源封装，方法定义：

客户端封装

BkApiClient 表示一个网关封装，方法定义：

客户端配置

客户端配置通过 bkapi.ClientConfig 类型来传入，部分参数会自动填充：

注意，Endpoint 和 BkApiUrlTmpl/Stage 选择一种配置方式即可，推荐使用后者。