# wz-opensdk-go

**Repository Path**: wz-open-platform/wz-opensdk-go

## Basic Information

- **Project Name**: wz-opensdk-go
- **Description**: 万桩开放平台 Go OpenSDK
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-09
- **Last Updated**: 2026-09-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# wz-opensdk

万桩开放平台 Go SDK。覆盖 Apifox 项目 `wz-open` 中文目录下的公开 API（设备、充电、续费、开票、回调）。`inner/*` 内部接口不在本 SDK 中。

模块路径：`gitee.com/wz-open-platform/wz-opensdk-go`。Go 1.23+。

## 安装

```bash
GOPROXY=direct GOPRIVATE=gitee.com/wz-open-platform go get gitee.com/wz-open-platform/wz-opensdk-go@v0.1.0
```

Gitee 模块需直连仓库：默认 `proxy.golang.org` / `sum.golang.org` 访问不到 Gitee，会报 checksum 404。`GOPRIVATE` 只跳过该前缀的代理与校验，不影响其它依赖。

本地开发可把本目录加到业务工程 `go.mod`：

```go
replace gitee.com/wz-open-platform/wz-opensdk-go => .
```

或与业务工程放在同一 workspace。

## 快速开始

```go
import "gitee.com/wz-open-platform/wz-opensdk-go"

client, err := wzopensdk.New(wzopensdk.Config{
    Endpoint:  os.Getenv("WZ_OPEN_ENDPOINT"),
    AppID:     os.Getenv("WZ_OPEN_APP_ID"),
    AppSecret: os.Getenv("WZ_OPEN_APP_SECRET"),
})
if err != nil {
    log.Fatal(err)
}

ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()

dev, err := client.Device.FindOne(ctx, wzopensdk.DeviceFindOneRequest{DeviceNum: "18000001"})
```

按域调用，方法不堆在 `Client` 上：

- `client.Device.*` 设备绑定、计费模式、状态、在线日志
- `client.Charge.Start` / `Stop`
- `client.Renew.*`
- `client.Invoice.*`
- `client.Callback.Log` / `RetryFinishOrder`

出站方法第一参数都是 `ctx`。`nil` context 会返回 `ErrNilContext`。不要把 context 存进 Client。

## 签名

SDK 按接入指引自动加 `app_id`、`timestamp`、`sign`（HMAC-SHA256 大写 hex）。调用方不要自己拼签，也不要传 `company_id`。金额单位为分。

契约以开放平台文档为准（OpenAPI 按 path 去重，汽车桩 `saveMode`/`getMode` 在 SDK 中拆成独立方法；`/open/device/setting/sync` 属于 inner，本 SDK 不实现）。公开能力合计 40 条出站 API。SDK 只做 client，不解析平台推送到合作方的入站回调。

## 日志

默认 stderr TextHandler、Info 级别。覆盖：

```go
wzopensdk.New(cfg, wzopensdk.WithLogger(mySlogLogger))
```

或设 `Config.Logger`。静音用 `slog.New(slog.DiscardHandler)`。SDK 不会调用 `slog.SetDefault`。

成功请求的 info 日志会带 `method`、`path`；响应头有 `X-B3-TraceId` 时再带 `traceId`。失败时同一字段出现在 error 日志里，并可从 `APIError.TraceID` 读取。

## Metric

默认关闭。打开后使用 Prometheus：

```go
reg := prometheus.NewRegistry()
cfg.Metrics.Enabled = true
cfg.Metrics.Registerer = reg // 默认 prometheus.DefaultRegisterer
```

指标：`wzopensdk_http_requests_total`、`wzopensdk_http_request_duration_seconds`、`wzopensdk_http_errors_total`。label 只有 `method` / `operation` / `code`（错误另有 `reason`）。SDK 不提供 `/metrics` HTTP。

## HTTP

`Config.HTTP` 可配 Timeout（默认 10s，作用在派生 ctx 上）、RetryCount（失败重试且每次重签）、RetryWait、UserAgent、ProxyURL、Transport、或直接传入 `http.Client`。

重试等待可被 ctx 取消打断。

## 开发

```bash
make test
make cover
make lint
```