Bark Golang SDK

一个简单、轻量、零依赖的 Bark 推送通知服务 Golang SDK。

🤖 AI Coding 项目：本项目完全由 AI 辅助编程完成。如果你想了解或复刻此项目的开发过程，请参考 TASKS.md 文件，其中包含了完整的实现任务清单。

什么是 Bark？

Bark 是一款免费、简单、安全的 iOS 推送通知工具。它利用 Apple Push Notification service (APNs) 将通知推送到你的 iPhone。你可以使用官方服务器，也可以自建服务器。

功能特性

• 🚀 极简 API - 一行代码发送通知
• 🔗 链式调用 - 流畅的消息构建体验
• 🔒 加密推送 - 支持 AES-128/192/256-CBC 加密
• 📦 零依赖 - 仅使用 Go 标准库，无第三方依赖
• ⚡ 批量推送 - 一次请求推送到多个设备
• 🎨 功能完整 - 支持 Bark 所有 API 功能（包括 Markdown）
• 🛡️ 类型安全 - 完整的类型定义，编译时检查
• 📝 完善文档 - 详细的 GoDoc 文档和示例

安装

go get github.com/Mia0a-hi/bark-golang-sdk

要求 Go 1.18 或更高版本。

快速开始

最简单的用法

package main

import "github.com/Mia0a-hi/bark-golang-sdk"

func main() {
    // 一行代码发送通知
    err := bark.Push("你的设备Key", "Hello from Go!")
    if err != nil {
        panic(err)
    }
}

带标题的通知

err := bark.PushWithTitle("设备Key", "服务器告警", "CPU 使用率超过 90%")

点击跳转 URL

err := bark.PushURL("设备Key", "点击查看详情", "https://example.com")

分组通知

err := bark.PushGroup("设备Key", "新订单 #12345", "orders")

进阶用法

使用 Client 实例

client := bark.NewClient("你的设备Key",
    bark.WithServer("https://your-bark-server.com"),
    bark.WithTimeout(10*time.Second),
)

msg := bark.NewMessage("服务器告警").
    SetTitle("紧急").
    SetSound("alarm").
    SetLevel(bark.LevelCritical).
    SetGroup("alerts")

resp, err := client.Send(context.Background(), msg)

Markdown 格式支持

Bark 支持 Markdown 格式渲染消息内容：

// 方式一：使用便捷函数
err := bark.PushMarkdown("设备Key", "hello **markdown** !")

// 方式二：带标题
err := bark.PushMarkdownWithTitle("设备Key", "通知", "hello **markdown** !")

// 方式三：使用 NewMarkdownMessage
msg := bark.NewMarkdownMessage("**重要通知**\n\n请点击[这里](https://example.com)查看详情").
    SetTitle("Markdown 示例")
err := bark.PushWithOptions("设备Key", msg)

// 方式四：使用 SetMarkdown
msg := bark.NewMessage("").
    SetTitle("通知").
    SetMarkdown("hello **markdown** !")

支持的 Markdown 语法：

• **粗体** 或 __粗体__
• *斜体* 或 _斜体_
• [链接文字](URL)
• `代码`
• 列表等

注意：需要较新版本的 Bark App 支持 Markdown 功能。

加密推送

client := bark.NewClient("设备Key",
    bark.WithEncryption("1234567890123456", "1111111111111111"),
)

msg := bark.NewMessage("这是加密的消息内容")
resp, err := client.SendEncrypted(context.Background(), msg)

批量推送

client := bark.NewClient("", bark.WithServer("https://api.day.app"))

deviceKeys := []string{"key1", "key2", "key3"}
msg := bark.NewMessage("系统公告").SetTitle("通知")

resp, err := client.SendBatch(context.Background(), deviceKeys, msg)

完整消息配置

msg := &bark.Message{
    Body:     "订单 #12345 已确认",
    Title:    "新订单",
    Subtitle: "电商平台",
    URL:      "https://example.com/orders/12345",
    Sound:    "minuet",
    Icon:     "https://example.com/icon.png",
    Group:    "orders",
    Badge:    1,
    Level:    bark.LevelTimeSensitive,
    IsArchive: "1",
}

err := bark.PushWithOptions("设备Key", msg)

API 参考

包级别函数

函数	说明
Push(deviceKey, body string) error	发送简单文本通知
PushWithTitle(deviceKey, title, body string) error	发送带标题的通知
PushWithSubtitle(deviceKey, title, subtitle, body string) error	发送带标题和副标题的通知
PushURL(deviceKey, body, url string) error	发送点击跳转的通知
PushGroup(deviceKey, body, group string) error	发送分组通知
PushMarkdown(deviceKey, markdown string) error	发送 Markdown 格式通知
PushMarkdownWithTitle(deviceKey, title, markdown string) error	发送带标题的 Markdown 通知
PushWithOptions(deviceKey string, msg *Message) error	发送自定义配置的通知
SetDefaultServer(url string)	设置默认服务器地址

Client 方法

方法	说明
NewClient(deviceKey string, opts ...Option) *Client	创建新客户端
Send(ctx context.Context, msg *Message) (*Response, error)	发送通知
SendEncrypted(ctx context.Context, msg *Message) (*Response, error)	发送加密通知
SendBatch(ctx context.Context, deviceKeys []string, msg *Message) (*Response, error)	批量发送通知

配置选项

选项	说明
WithServer(url string)	设置自定义服务器地址
WithHTTPClient(client *http.Client)	设置自定义 HTTP 客户端
WithTimeout(timeout time.Duration)	设置请求超时时间
WithEncryption(key, iv string)	启用加密推送

Message 字段

字段	类型	说明
Body	string	消息内容
Title	string	通知标题
Subtitle	string	通知副标题
URL	string	点击跳转的 URL
Copy	string	复制的内容
AutoCopy	string	自动复制（"1" 启用）
Sound	string	提示音名称
Icon	string	自定义图标 URL (iOS 15+)
Group	string	分组名称
Badge	int	角标数字
Level	Level	通知级别
Volume	int	音量 (0-10)
Call	string	重复响铃 30 秒（"1" 启用）
ID	string	通知 ID（用于更新/删除）
IsArchive	string	保存到历史（"1" 启用）
Markdown	string	Markdown 格式的消息内容

通知级别

级别	常量	说明
默认	LevelActive	默认通知级别
时效性	LevelTimeSensitive	可在专注模式下显示
被动	LevelPassive	不会点亮屏幕
紧急	LevelCritical	忽略静音和勿扰模式

提示音列表

alarm, anticipate, bell, birdsong, bloom, calypso, chime, choo, 
descent, electronic, fanfare, glass, gotosleep, healthnotification,
horn, ladder, mailsent, minuet, multiwayinvitation, newmail,
newsflash, noir, paymentsuccess, shake, sherwoodforest, silence,
spell, suspense, telegraph, tiptoes, typewriters, update

错误处理

resp, err := client.Send(ctx, msg)
if err != nil {
    var barkErr *bark.BarkError
    if errors.As(err, &barkErr) {
        fmt.Printf("Bark API 错误: code=%d, message=%s\n", barkErr.Code, barkErr.Message)
    } else {
        fmt.Printf("请求失败: %v\n", err)
    }
    return
}

预定义错误

错误	说明
ErrEmptyDeviceKey	设备 Key 为空
ErrEmptyBody	消息内容为空
ErrInvalidServer	服务器地址无效
ErrInvalidKeySize	加密密钥长度无效
ErrInvalidIVSize	IV 长度无效
ErrEmptyDeviceKeys	批量推送设备列表为空
ErrInvalidVolume	音量值无效 (0-10)
ErrInvalidLevel	通知级别无效
ErrEncryptionNotConfigured	未配置加密

自建服务器

// 方式一：设置默认服务器
bark.SetDefaultServer("https://your-bark-server.com")
bark.Push("key", "message")

// 方式二：创建客户端时指定
client := bark.NewClient("key", bark.WithServer("https://your-bark-server.com"))

AI Coding

本项目采用 AI 辅助编程方式开发，整个开发过程遵循以下流程：

1. 需求分析 - 分析 Bark API 文档，确定 SDK 功能需求
2. 设计规划 - 设计 API 接口、数据结构和架构
3. 任务拆分 - 将实现工作拆分为可执行的小任务
4. 逐步实现 - 按任务顺序实现代码和测试
5. 文档完善 - 编写详细的文档和示例

如果你想复刻此项目或了解 AI Coding 的工作方式，请参考 TASKS.md 文件。

许可证

MIT License

相关链接

• Bark iOS App
• Bark 服务端
• Bark 文档
• 实现任务清单