Skip to content
gomodbPublic

About

apsara csb sdk for go

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

csbgo

License: MIT Go Reference

纯 Go 标准库实现的 CSB(云服务总线)HTTP 服务调用客户端:按 CSB 规范自动完成 HMAC-SHA1 签名,无第三方依赖,要求 Go 1.27+。

go get github.com/gomodb/csbgo

快速开始

client := csbgo.New(
    csbgo.WithBaseURL("http://broker.example.com/CSB"), // CSB 唯一端点
    csbgo.WithAK("access-key"),
    csbgo.WithSK("secret-key"),
    csbgo.WithTimeout(10*time.Second),
)

resp, err := client.Do(ctx,
    csbgo.NewRequest(csbgo.MethodPost).
        WithAPI("MyService").
        WithVersion("v1").
        WithQuery("name", "wiseking").
        WithForm("p1", "dog"),
)
if err != nil {
    return err
}
log.Println(resp.ToString())

WithAPI / WithVersion 也可设在 Client 上作为默认值。Client 创建后不可变、并发安全,适合设为包级变量复用;Request 不是并发安全的,每次调用新建,或用 Clone() 从模板派生。

API

New(opts ...Option) *Client

Option 说明
WithBaseURL CSB 端点(必填,单个端点)
WithAK / WithSK access key / secret key(要么都给,要么都不给=匿名)
WithAPI / WithVersion 默认 API 名 / 版本
WithTimeout 总超时(默认 60s)
WithHTTPClient / WithTransport 自定义 *http.Client / http.RoundTripper(可用 RoundTripFunc 适配函数)
WithUserAgent User-Agent(默认 csbBroker)
WithDebug / WithLogger 调试日志开关与出口(接受任意 *slog.Logger)
WithStatusCheck 状态码判定:默认仅 2xx,AcceptStatus(200, 201) 指定码,AcceptAnyStatus 关闭
WithRetries 等 见「重试」

WithHTTPClient(nil) / WithLogger(nil) / WithStatusCheck(nil) 表示恢复默认值。

NewRequest(method) *Request

method 仅支持 MethodGet / MethodPost。链式方法:

  • 参数:WithQuery / WithQueryInt / WithQueries / WithQueryValues,WithForm / WithForms / WithFormValues
  • 其他:WithHeader / WithHeaders,WithBody(contentType, body) / WithJSON(v)(仅 POST)
  • URL:WithHost / WithPath / WithPathf(默认使用 Client 的 baseURL)
  • 按请求覆盖:WithAK / WithSK / WithMethod / WithStatusCheck 及整套重试选项

WithQuery / WithForm 重复设置同一 key 会覆盖;需要重复参数时用 WithQueryValues(key, v1, v2, ...)。

_api_* 是 SDK 保留字段,通过 WithQuery / WithForm / WithHeader 或 base URL query 传入会报错。

Do / DoAs

resp, err := client.Do(ctx, req)          // 原始响应
user, err := client.DoAs[User](ctx, req)  // 一步请求 + JSON 解码

默认只接受 2xx,否则返回 *StatusError。Response 提供 ToString() / ToBytes() / ToJSON(&v) / OK();需要同时拿到响应头时用 Do + resp.ToJSON(&out)。

错误处理

所有诊断信息都挂在 *Error 上,*StatusError 只是「状态码不被接受」的标记(Response() 是 Err.Response 的简写):

var ce *csbgo.Error
if errors.As(err, &ce) {
    ce.Code        // CSB 错误码(csbgo.Code)
    ce.Message     // 错误描述
    ce.RequestID   // 便于对账定位
    ce.Request     // 实际发出的请求;nil = 尚未构造(校验类失败)
    ce.Response    // 收到的响应;nil = 传输失败
}

ce.Request 含 Method、URL(最终 URL)、Header(secret key 与 signature 已脱敏)、BodyLen(不保存请求体内容)。

CSB 通过逃逸码返回失败,真实错误码写在描述里:[504] api name not found(阶段 2,CSB 处理失败)、[800][60] service not found(阶段 3,服务提供端失败)。SDK 会解析并填入 Code / ProviderCode / Message,ProviderError() 判断是否阶段 3。全部错误码见 csbgo.Code 常量,描述用 Code.String()。

非 CSB 响应体(如网关 HTML 错误页)不含错误码,此时 Code 为 0,截断后的正文作为 Message 保留。

参数发送规则

方法 Query Form 请求体
GET 追加到 URL 追加到 URL 无
POST(无显式 body) 追加到 URL — form 编码
POST + WithJSON / WithBody 追加到 URL 追加到 URL JSON / 原始字节

无论走哪条路径,query 与 form 参数(含重复参数)都会进入签名,签名参数集与线上送达参数集保持一致。

重试

默认关闭。

client := csbgo.New(
    csbgo.WithBaseURL("http://broker.example.com/CSB"),
    csbgo.WithAK("ak"), csbgo.WithSK("sk"),
    csbgo.WithRetries(3),
    csbgo.WithRetryBackoff(200*time.Millisecond), // 退避起点,逐次翻倍(默认 100ms)
    csbgo.WithMaxRetryDelay(5*time.Second),       // 单次等待上限(默认 30s)
    csbgo.WithJitter(csbgo.FullJitter),           // 默认;另有 EqualJitter / NoJitter
)
  • 触发条件:传输错误、5xx、429;context 取消或超时永不重试
  • Retry-After 响应头(秒数或 HTTP-date)优先采用,仍受 WithMaxRetryDelay 约束
  • WithRetryIf(pred) 自定义是否重试;WithRetryDelay(fn) 完全替换退避;WithOnRetry(fn) 用于日志或指标
  • 以上重试选项均可在 Request 上按请求覆盖

说明

  • JSON:使用 Go 1.27 的 encoding/json/v2。与 v1 的差异:重复键与非法 UTF-8 会直接报错。
  • 日志:WithDebug(true) 输出结构化日志(csb: http request、csb: signed request),签名已脱敏;WithLogger 可传入现有 *slog.Logger 复用同一套 handler。

License

MIT

About

apsara csb sdk for go

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages