纯 Go 标准库实现的 CSB(云服务总线)HTTP 服务调用客户端:按 CSB 规范自动完成 HMAC-SHA1 签名,无第三方依赖,要求 Go 1.27+。
go get github.com/gomodb/csbgoclient := 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() 从模板派生。
| 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) 表示恢复默认值。
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 传入会报错。
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。