Lix.li Go SDK — Go URL 缩短 API 官方客户端

功能

Go URL 缩短 API 集成所需的一切

仅用标准库构建，零外部依赖。为惯用的 Go，具有结构体、错误和可选指针类型。

链接管理

创建、获取、更新、删除和列出短链接。具有定型结构体的完整 CRUD。用于可空字段的可选指针类型。

分组管理

将链接组织成组。创建旋转分组进行网页 A/B 测试。具有结构体响应的完整 CRUD。

账户和使用量 API

检索帐户个人资料、计划详情和实时使用限制。

零依赖

仅标准库。没有外部依赖。小尺寸、零供应链风险。

定型错误

6 个专用错误类型包裹基本的 LixError。使用 errors.As() 进行精确的错误匹配并附有验证数据。

自定义 HTTPClient

通过 HTTPClient 接口注入任何与 net/http 兼容的客户端。设置超时、代理或模拟测试。

快速开始

30 秒就能上手

纯 Go，没有外部依赖。与从 Go 1.22+ 的标准库一起使用。

Go 1.22+ MIT License Stdlib Only

1

安装包

使用 go get 将 SDK 添加到您的 Go 模块。

 go get github.com/lix-url/go-sdk/lix

2

实例化客户端

传入您的 API 密钥。可选注入自定义 HTTPClient 以进行超时、代理或测试。

import "github.com/lix-url/go-sdk/lix"

client := lix.NewClient("lix_live_xxx")

// With custom HTTPClient
httpClient := &http.Client{Timeout: 10 * time.Second}
client := lix.NewClient("lix_live_xxx", httpClient)

3

创建您的第一个链接

缩短 URL 并获取带有短链接和使用信息的定型 LinkShortenResult。

链接 API

Go 中完整的链接生命周期

使用自定义别名、UTM 参数、跟踪像素、密码保护和过期日期创建短链接。每次操作都返回定型的结构体。

// Create a basic link
result, err := client.Links().Create("https://example.com", nil)
fmt.Println(result.Link.ShortURL)

// With custom alias and UTM
opts := lix.NewCreateLinkOptions()
opts.Alias = strPtr("my-link")
opts.Title = strPtr("My Page Title")
opts.Tags = []string{"sale", "promo"}
opts.UTM = map[string]string{
    "utm_source":  "google",
    "utm_medium":  "email",
    "utm_campaign": "summer",
}
opts.TrackingPixelIDs = []int{1001, 1002}
opts.IsPublic = true

result, err := client.Links().Create("https://example.com", opts)

// Password protection + expiration
opts := lix.NewCreateLinkOptions()
opts.Password = strPtr("secret123")
opts.ActiveBeforeDatetime = strPtr("2026-12-31T23:59:59+00:00")
result, err := client.Links().Create("https://example.com", opts)

func strPtr(s string) *string { return &s }

Create(url, opts) 使用可选的 CreateLinkOptions 创建短链接：别名、UTM、标签、密码、过期、跟踪像素。
Get(id) 按 ID 检索带有完整元数据、组、标签和状态的链接。
Update(id, opts) 通过 UpdateLinkOptions 更新链接的任何字段：URL、标题、组、标签、UTM、密码、可见性。
Delete(id) 按 ID 软删除链接。失败时返回错误。
List(limit, fromID) 使用 *int 指针进行分页。返回带有 ResponseMeta 的 LinksResult。

分页示例： client.Links().List(&limit, &fromID) 返回下一批结果带有 ResponseMeta，其中包含总数和下一个 URL。对于 API 默认值传递 nil。

分组 API

组织和旋转链接

分组有助于按营销活动、团队或项目对链接进行分类。旋转组通过在多个链接之间分配流量来实现 A/B 测试。

Create(name, desc, rotate) 使用名称、可选描述指针和旋转模式创建组。
Get(id) 检索具有所有元数据的组。
Update(id, name, desc, rotate) 更名、更新描述或切换旋转模式。
Delete(id) 按 ID 删除组。
List(limit, fromID) 使用定型的 GroupsResult 和 ResponseMeta 进行分页。

// Create a regular group
group, err := client.Groups().Create("Marketing", nil, false)
fmt.Println(group.Name, group.URL)

// Create a rotating group for A/B testing
group, err := client.Groups().Create(
    "Landing Pages",
    strPtr("Rotating pages"),
    true,
)

// Update group
group, err := client.Groups().Update(
    10, nil,
    strPtr("Updated description"),
    false,
)

// List with pagination
limit := 10
page, err := client.Groups().List(&limit, nil)
for _, g := range page.Groups {
    fmt.Println(g.Name, g.URL)
}
fmt.Println(page.Meta.Total)

账户和使用量 API

账户和使用详情

检索您的个人资料、计划和实时使用限制 — 一切都返回为嵌套结构体并具有完整的 JSON 标签映射。

profile, err := client.Profile().Me()
if err != nil {
    log.Fatal(err)
}

// Account info
fmt.Println(profile.Client.Name, profile.Client.Email)
fmt.Println(profile.User.Email)

// Plan details
fmt.Println(profile.Plan.Name, profile.Plan.EndDatetime)

// Usage limits
if profile.Usages.Links.Remaining != nil {
    fmt.Println(*profile.Usages.Links.Remaining)
}
fmt.Println(profile.Usages.APILinks.Used)
fmt.Println(profile.Usages.MassLinks.Limit)

ClientInfo

ID、名称、电子邮件、created_datetime

User

名称、电子邮件、created_datetime

Plan

ID、名称、start_datetime、end_datetime

Usage

链接、API、大批量 — 每个具有 Limit (*int)、Used (int)、Remaining (*int)

错误处理

6 个定型错误用于惯用的 Go

使用 errors.As() 精确捕获您所需的内容。所有错误都包裹 LixError。ValidationError 将完整的字段级验证错误数据包含在 Data 中。

import "errors"

result, err := client.Links().Create("invalid-url", nil)
if err != nil {
    var ve *lix.ValidationError
    var notFound *lix.NotFoundException
    var unauth *lix.UnauthorizedError
    var rateLimit *lix.RateLimitError
    var server *lix.ServerError

    switch {
    case errors.As(err, &ve):
        // Field-level validation errors
        fmt.Println("Validation:", ve.Data)
    case errors.As(err, &notFound):
        fmt.Println("Not found")
    case errors.As(err, &unauth):
        // Invalid API key
    case errors.As(err, &rateLimit):
        // Too many requests
    case errors.As(err, &server):
        // 5xx server error
    default:
        // Generic Lix or network error
        log.Fatal(err)
    }
}

ValidationException

400 — 无效输入。访问 Data 以获取字段错误。

UnauthorizedException

401 — 无效的 API 密钥或缺少授权。

NotFoundException

404 — 未找到链接或组。

RateLimitException

429 — 超出速率限制。

ServerException

500 — 意外的服务器错误。

HttpClientException

网络 / 传输故障。

所有错误都包裹 LixError，其实现了 error。使用 errors.As() 进行类型安全匹配。捕获基本 LixError 以处理任何 SDK 错误，或定位特定类型进行精细处理。

生态系统

流行技术栈的官方 SDK

从 PHP、JavaScript、Python 或 Go 使用相同的 Lix.li API，配备为每个生态系统量身定制的 SDK。

Python SDK

用于短链接、分组、分析和自动化的定型 Python 客户端。为现代 Python 应用和工作流构建。

GitHub 文档

PHP SDK

具有定型 DTO、只读模型、专用异常和通过 Composer 优先安装的现代 PHP SDK。

GitHub 文档

JS SDK

基于 Promise 的 JavaScript SDK，适用于 Node.js 和浏览器环境。使用干净的开发体验创建和管理短链接。

GitHub 文档

准备好在 Go 中缩短链接了吗？

安装 SDK，获取 API 密钥，并在一分钟内开始创建短链接。

GitHub Repository 创建 API 密钥