Go SDK

go-flashduty 是 Flashduty 官方开源的 Go SDK，与 Open API 严格 1:1 的类型化封装，覆盖全部 253 个接口、27 个服务。

​

概述

---

go-flashduty 是 Flashduty 官方开源的 Go 客户端，覆盖 Flashduty Open API 的每一个 REST 接口。它采用与 go-github 一致的设计风格——服务分组、类型化请求与响应、可组合传输层——并与 OpenAPI 规范保持严格 1:1：每个方法对应且仅对应一次 HTTP 调用，返回 (*T, *Response, error)，不做任何跨接口的隐式聚合或增强。

SDK 当前覆盖 253 个接口、27 个服务,全部由 Flashduty OpenAPI 规范生成,经单元测试覆盖,并针对线上 API 做过端到端验证。

SDK 故意保持”薄”。诸如短 ID 解析、跨接口编排等消费侧逻辑应放在调用方（CLI / MCP）中，而不是塞进 SDK 或滥用某个接口。这样 SDK 始终与 API 一一对应,可预测、可生成、可校验。

模块路径为 github.com/flashcatcloud/go-flashduty,包名为 flashduty,源码遵循 Apache-2.0 协议开源在 flashcatcloud/go-flashduty。

Open API 参考

全部接口的请求参数与响应字段说明。

命令行工具

在终端中直接操作 Flashduty 的 CLI。

​

安装

---

1. 要求 Go 1.24+

   请确认本地 Go 工具链版本不低于 1.24。

2. 获取依赖

   go get github.com/flashcatcloud/go-flashduty
   
3. 导入包

   import flashduty "github.com/flashcatcloud/go-flashduty"
   

​

快速开始

---

以下是一个最小可运行示例：构造客户端、列出处于”已触发”状态的故障，并处理返回的三元组 (数据, *Response, error)。

package main

import (
	"context"
	"fmt"
	"log"

	flashduty "github.com/flashcatcloud/go-flashduty"
)

func main() {
	client, err := flashduty.NewClient("YOUR_APP_KEY")
	if err != nil {
		log.Fatal(err)
	}

	list, resp, err := client.Incidents.List(context.Background(), &flashduty.ListIncidentsRequest{
		Progress:    "Triggered",
		ListOptions: flashduty.ListOptions{Limit: 20},
	})
	if err != nil {
		log.Fatal(err)
	}

	fmt.Printf("request_id=%s total=%d has_next=%t\n", resp.RequestID, resp.Total, resp.HasNextPage)
	for _, inc := range list.Items {
		fmt.Printf("[%s] %s\n", inc.IncidentSeverity, inc.Title)
	}
}

每次调用都返回三个值：

返回值	类型	说明
数据	*T	接口对应的类型化响应体（如 *ListIncidentsResponse）；调用失败时为 nil
*Response	*flashduty.Response	包裹 *http.Response,并附带 RequestID、分页等信封元信息
error	error	失败时为 *ErrorResponse,429 时为 *RateLimitError

app_key 用于鉴权,SDK 会自动将其作为查询参数注入每个请求。请在 Flashduty 控制台的”推送集成”或团队配置中获取对应的 app_key。

​

创建客户端

---

NewClient 接收 app_key 与零到多个 Option。app_key 为空会直接返回错误。默认 Base URL 为 https://api.flashcat.cloud,默认 HTTP 超时为 30 秒,默认 User-Agent 为 go-flashduty。

client, err := flashduty.NewClient("YOUR_APP_KEY",
	flashduty.WithBaseURL("https://api.flashcat.cloud"),
	flashduty.WithTimeout(10*time.Second),
	flashduty.WithUserAgent("my-app/1.0"),
	flashduty.WithHTTPClient(customHTTPClient),
	flashduty.WithTransport(customRoundTripper),
	flashduty.WithLogger(myLogger),
	flashduty.WithRequestHeaders(staticHeaders),
	flashduty.WithRequestHook(func(req *http.Request) { /* 例如注入 traceparent */ }),
)

Option	说明
WithBaseURL(raw string)	覆盖 API 基础地址（默认 https://api.flashcat.cloud）。私有化部署用它指向自有网关；非法 URL 会在 NewClient 阶段报错
WithTimeout(d time.Duration)	设置底层 HTTP 客户端的整体超时
WithUserAgent(ua string)	设置每个请求携带的 User-Agent 头
WithHTTPClient(hc *http.Client)	替换底层 *http.Client;传入 nil 时忽略
WithTransport(rt http.RoundTripper)	设置自定义 http.RoundTripper,是接入重试、缓存、链路追踪、限流等中间件的惯用切入点;传入 nil 时忽略
WithLogger(l Logger)	设置自定义日志器;传入 nil 时忽略
WithRequestHeaders(h http.Header)	设置追加到每个请求的静态头,在 SDK 自身的头（Content-Type、Accept、User-Agent）之后应用
WithRequestHook(hook func(*http.Request))	注册回调,在每个请求发出前调用,用于注入逐请求的头（如 W3C traceparent）

私有化部署：用 WithBaseURL 将客户端指向您自有的 Flashduty 网关地址即可,其余调用方式完全不变。

​

服务与方法

---

接口按服务分组挂在客户端上：调用约定统一为 client.<Service>.<Method>(ctx, req),返回 (*T, *Response, error)。例如 client.Incidents.List(ctx, req)、client.Sessions.Info(ctx, req)。

服务字段	说明
client.Incidents	故障
client.Alerts	告警
client.Channels	协作空间
client.Schedules	排班
client.Calendars	日历
client.StatusPages	状态页
client.Members	成员
client.Teams	团队
client.RolesPermissions	角色与权限
client.Account	账户
client.AuditLogs	审计日志
client.AlertRules	告警规则
client.RuleSets	规则集
client.AlertEnrichment	告警字段加工
client.DataSources	数据源
client.Integrations	集成
client.ImIntegrations	IM 集成
client.NotificationTemplates	通知模板
client.Changes	变更
client.Diagnostics	诊断
client.Analytics	分析
client.A2aAgents	A2A Agents
client.McpServers	MCP Servers
client.Sessions	AI SRE 会话
client.Skills	Skills
client.Applications	RUM 应用
client.Issues	RUM 问题
client.Sourcemaps	RUM Sourcemap

所有标识符、服务字段名与方法名均与生成代码保持一致。具体每个服务有哪些方法、请求与响应类型,请以 services_gen.go 与各服务文件,以及 Open API 参考 为准。

​

响应时间戳

---

响应中的时间字段不再是裸整数,而是自描述的 Timestamp（Unix 秒）或 TimestampMilli（毫秒）类型。它们序列化为本地时区的 RFC3339 字符串,因此 JSON、日志以及面向 LLM 的输出都直接可读;原始 epoch 仍只需一次方法调用即可取到。

• 序列化（出站）：非零值序列化为带引号的 RFC3339 字符串（TimestampMilli 用 RFC3339Nano 以保留毫秒精度）。零值序列化为裸整数 0——一个”未设置”哨兵,而非 1970 年的日期,并被 json:",omitempty" 丢弃。
• 反序列化（入站）：既兼容数字 epoch（线上原始形态),也兼容 RFC3339 字符串(使序列化后的值可无损往返),还接受 null（→ 0）。

inc := list.Items[0]

fmt.Println(inc.StartTime)            // 2026-05-30T14:37:11+08:00  （String / fmt / TOON）
b, _ := json.Marshal(inc.StartTime)   // "2026-05-30T14:37:11+08:00"
epoch := inc.StartTime.Unix()         // 1779514631  （原始 wire 值）
t := inc.StartTime.Time()             // time.Time
zero := inc.StartTime.IsZero()        // 是否为未设置哨兵

方法	返回	说明
.Time()	time.Time	取为标准时间值
.Unix()	int64	取原始 wire 值（Timestamp 为秒,TimestampMilli 为毫秒）
.IsZero()	bool	是否为未设置哨兵（0）
.String()	string	本地时区 RFC3339,未设置时为 "0"

请求侧时间字段仍为 int64,API 在 wire 上要求数字 epoch。注意:多数接口取秒,但 RUM 与 webhook 历史相关接口取毫秒。

​

分页

---

所有列表接口共享 ListOptions,将其内嵌在请求结构体中即可。零值会被省略,不会覆盖服务端默认值（后端默认 p=1、limit=20）。

字段	类型	wire 字段	说明
Page	int	p	从 1 开始的页码
Limit	int	limit	每页返回条数上限
SearchAfterCtx	string	search_after_ctx	上一页回显的不透明游标,用于深分页;回传它即可取下一页

响应侧,*Response 携带 Total、HasNextPage 与 SearchAfterCtx。推荐用 search-after 游标逐页遍历：

req := &flashduty.ListIncidentsRequest{
	ListOptions: flashduty.ListOptions{Limit: 50},
}

// 设上限,避免游标异常时无限循环。
for page := 0; page < 100; page++ {
	list, resp, err := client.Incidents.List(ctx, req)
	if err != nil {
		log.Fatal(err)
	}

	for _, inc := range list.Items {
		fmt.Printf("%s: %s\n", inc.IncidentID, inc.Title)
	}

	if !resp.HasNextPage {
		break
	}
	// 推进游标,取下一页。
	req.ListOptions.SearchAfterCtx = list.SearchAfterCtx
}

​

错误处理

---

任何未成功的调用——无论是信封中携带了错误,还是 HTTP 状态非 2xx——都会返回 *ErrorResponse。它带有 Code、Message 与 RequestID 字段,排障时把 RequestID 提供给支持团队即可定位。

当 API 返回 429 时,错误被提升为 *RateLimitError：它内嵌 *ErrorResponse（所以 errors.As 取 *ErrorResponse 仍然成立),并额外带上 RetryAfter 提示。

_, _, err := client.Incidents.Info(ctx, &flashduty.IncidentInfoRequest{
	IncidentID: "does-not-exist",
})

var rl *flashduty.RateLimitError
if errors.As(err, &rl) {
	// 按服务端要求退避后再重试。
	time.Sleep(rl.RetryAfter)
	return
}

var apiErr *flashduty.ErrorResponse
if errors.As(err, &apiErr) {
	fmt.Printf("api error code=%s request_id=%s\n", apiErr.Code, apiErr.RequestID)
	return
}

类型化判定函数能省去字符串比较,并能穿透被包裹的错误（内部用 errors.As）：

辅助函数	说明
IsNotFound(err)	是否为资源不存在
IsRateLimited(err)	是否为请求过于频繁（429）
IsUnauthorized(err)	是否为未授权
IsAccessDenied(err)	是否为访问被拒
IsInvalidParameter(err)	是否为参数非法
ErrorCodeOf(err)	提取错误码,返回 ErrorCode 常量(如 ErrorCodeAccessDenied、ErrorCodeUnauthorized)

switch flashduty.ErrorCodeOf(err) {
case flashduty.ErrorCodeAccessDenied, flashduty.ErrorCodeUnauthorized:
	// 处理鉴权失败
}

​

重试

---

核心客户端不内置自动重试。请通过传输层组合可选的 retry 子包——一个安全默认的重试型 http.RoundTripper。

github.com/flashcatcloud/go-flashduty/retry 的特性：

• 重试条件：HTTP 429、任意 5xx（状态码 ≥ 500),以及传输错误。其他 4xx 与所有 2xx/3xx 立即返回。
• 退避策略：确定性指数退避（MinWait * 2^attempt,每次上限为 MaxWait);无随机抖动。存在合法的整数 Retry-After 头时,以其为准（同样不超过 MaxWait）。
• 安全回放：仅当请求体可回放（req.Body 为 nil 或 req.GetBody 非空）时才重试,每次重试都在请求的克隆上重建请求体,绝不修改调用方的原始 *http.Request。SDK 构造的所有请求都设置了 GetBody,因此 POST 请求体都可安全回放。
• 尊重取消：等待退避期间若请求 context 被取消,立即返回 context 错误。

import "github.com/flashcatcloud/go-flashduty/retry"

client, err := flashduty.NewClient("YOUR_APP_KEY",
	flashduty.WithTransport(retry.New(
		retry.WithMaxRetries(3),
	)),
)

配置项	默认值	说明
retry.WithMaxRetries(n int)	3	首次尝试之后的最大重试次数;负数表示禁用重试
retry.WithMinWait(d time.Duration)	500ms	基础退避时长（首次重试前的等待）
retry.WithMaxWait(d time.Duration)	30s	单次退避等待的上限
retry.WithBase(base http.RoundTripper)	http.DefaultTransport	底层实际执行请求的 RoundTripper

retry 子包是纯 net/http 实现,刻意不导入父级 flashduty 包,因此永远不会引入循环依赖。retry.New() 与 &retry.Transport{}（零值）都开箱即用。

​

流式导出

---

client.Sessions.Export 用于导出一个 AI SRE 会话的完整事件转录,返回的是 io.ReadCloser（NDJSON 流,application/x-ndjson),而非 JSON 信封。首行始终是一条 session_meta 信封,其后每行是一个会话事件;当 req.IncludeSubagents 为 true 时,每条 subagent_dispatch 行后会跟随子会话自身的完整事件流。

由于响应体可能很大,应当逐行读取并直接写入文件,不要把整段转录缓冲进内存。返回的 io.ReadCloser 是活动 HTTP 响应体,由调用方持有并必须 Close(defer 关闭即正确)。配合 NewExportScanner 可按行扫描,DecodeExportLine 可将一行解码为 ExportLine：

rc, _, err := client.Sessions.Export(ctx, &flashduty.SessionExportRequest{
	SessionID:        "your-session-id",
	IncludeSubagents: true,
})
if err != nil {
	return err
}
defer rc.Close()

sc := flashduty.NewExportScanner(rc)
for sc.Scan() {
	line, err := flashduty.DecodeExportLine(sc.Bytes())
	if err != nil {
		return err
	}
	// 用 line.Type 区分：session_meta、user_message、llm_call、
	// tool_call、subagent_dispatch、final_answer、agent_text、error
	_ = line
	// 也可以把 sc.Bytes() 原样写入文件。
}
return sc.Err()

NewExportScanner 配置的单行缓冲区足以容纳转录中较宽的事件行（如 tool 输出、LLM 调用),不受默认 64KB token 上限限制。任何非 2xx 状态下,响应体仍是常规 JSON 错误信封——Export 会读取并关闭它,返回类型化错误（*ErrorResponse,429 时为 *RateLimitError),此时 io.ReadCloser 为 nil,与其他生成接口行为一致。