Go SDK [community]

社群 SDK

此 SDK 完全由社群維護。

Remnawave Go SDK 是一個用於方便地與 RestAPI 互動的函式庫。

✨ 主要特色

• 使用 ogen v1.19.0 生成: 高吞吐量的零反射 JSON 解碼器
• 類型安全: 針對 OpenAPI 3.0 規範的編譯時驗證
• 基於控制器的設計: 用於簡潔 API 存取的有序子客戶端
• 簡化簽章: 簡單操作無需冗長的 Params 結構體
• Context 支援: 一流的 context.Context 支援
• OpenTelemetry: 內建追蹤插樁
• 請求選項: 透過 ...RequestOption 進行每請求自訂
• 編輯器: 請求/回應中介軟體支援

安裝

go get github.com/Jolymmiles/remnawave-api-go/v2@latest

注意

請務必選擇並固定正確版本的 SDK，以符合 Remnawave 後端的版本。

SDK 版本	Remnawave 面板版本
v2.6.1	2.6.1
v2.5.3	2.5.3
v2.3.0-6	2.3.0
v2.2.6-3	2.2.6

使用方法

基本範例

package main

import (
    "context"
    "fmt"
    "log"

    remapi "github.com/Jolymmiles/remnawave-api-go/v2/api"
)

func main() {
    ctx := context.Background()

    // Create base client
    baseClient, err := remapi.NewClient(
        "https://your-panel.example.com",
        remapi.StaticToken{Token: "YOUR_API_TOKEN"},
    )
    if err != nil {
        log.Fatal(err)
    }

    // Wrap with organized sub-clients
    client := remapi.NewClientExt(baseClient)

    // Get user by UUID - simplified signature
    resp, err := client.Users().GetUserByUuid(ctx, "user-uuid-here")
    if err != nil {
        log.Fatal(err)
    }

    switch r := resp.(type) {
    case *remapi.UserResponse:
        fmt.Printf("User: %s\n", r.Response.Username)
    case *remapi.NotFoundError:
        fmt.Println("User not found")
    case *remapi.BadRequestError:
        fmt.Printf("Validation error: %v\n", r.Errors)
    }
}

建立和管理使用者

package main

import (
    "context"
    "fmt"
    "log"

    remapi "github.com/Jolymmiles/remnawave-api-go/v2/api"
)

func main() {
    ctx := context.Background()

    baseClient, _ := remapi.NewClient(
        "https://your-panel.example.com",
        remapi.StaticToken{Token: "YOUR_API_TOKEN"},
    )
    client := remapi.NewClientExt(baseClient)

    // Create user
    createResp, err := client.Users().CreateUser(ctx, &remapi.CreateUserRequest{
        Username: "john_doe",
    })
    if err != nil {
        log.Fatal(err)
    }

    user := createResp.(*remapi.UserResponse).Response
    fmt.Printf("Created user: %s (UUID: %s)\n", user.Username, user.UUID)

    // Disable user
    _, err = client.Users().DisableUser(ctx, user.UUID.String())
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("User disabled")

    // Enable user
    _, err = client.Users().EnableUser(ctx, user.UUID.String())
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("User enabled")

    // Delete user
    _, err = client.Users().DeleteUser(ctx, user.UUID.String())
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println("User deleted")
}

節點管理

package main

import (
    "context"
    "fmt"
    "log"

    remapi "github.com/Jolymmiles/remnawave-api-go/v2/api"
)

func main() {
    ctx := context.Background()

    baseClient, _ := remapi.NewClient(
        "https://your-panel.example.com",
        remapi.StaticToken{Token: "YOUR_API_TOKEN"},
    )
    client := remapi.NewClientExt(baseClient)

    // Get all nodes
    nodesResp, err := client.Nodes().GetAllNodes(ctx)
    if err != nil {
        log.Fatal(err)
    }

    nodes := nodesResp.(*remapi.NodesResponse).Response
    fmt.Printf("Total nodes: %d\n", len(nodes))

    for _, node := range nodes {
        fmt.Printf("  - %s (%s): connected=%v\n",
            node.Name, node.Address, node.IsConnected)
    }

    // Get single node
    if len(nodes) > 0 {
        nodeResp, _ := client.Nodes().GetOneNode(ctx, nodes[0].UUID.String())
        node := nodeResp.(*remapi.NodeResponse).Response
        fmt.Printf("\nNode details: %s\n", node.Name)
    }
}

分頁

package main

import (
    "context"
    "fmt"
    "log"

    remapi "github.com/Jolymmiles/remnawave-api-go/v2/api"
)

func main() {
    ctx := context.Background()

    baseClient, _ := remapi.NewClient(
        "https://your-panel.example.com",
        remapi.StaticToken{Token: "YOUR_API_TOKEN"},
    )
    client := remapi.NewClientExt(baseClient)

    // Use PaginationHelper for iterating through pages
    pager := remapi.NewPaginationHelper(50) // 50 items per page

    for pager.HasMore {
        resp, err := client.Users().GetAllUsers(ctx,
            pager.Limit,  // size
            pager.Offset, // start
        )
        if err != nil {
            log.Fatal(err)
        }

        users := resp.(*remapi.GetAllUsersResponse)
        for _, user := range users.Response.Users {
            fmt.Printf("User: %s (UUID: %s)\n", user.Username, user.UUID)
        }

        // Advance to next page
        pager.SetTotal(int(users.Response.Total))
        pager.NextPage()
    }

    fmt.Printf("Total users: %d\n", *pager.Total)
}

錯誤處理

package main

import (
    "context"
    "fmt"
    "log"

    remapi "github.com/Jolymmiles/remnawave-api-go/v2/api"
)

func main() {
    ctx := context.Background()

    baseClient, _ := remapi.NewClient(
        "https://your-panel.example.com",
        remapi.StaticToken{Token: "YOUR_API_TOKEN"},
    )
    client := remapi.NewClientExt(baseClient)

    resp, err := client.Users().GetUserByUuid(ctx, "invalid-uuid")
    if err != nil {
        log.Fatal("Network error:", err)
    }

    // Available error types depend on the endpoint — check the generated
    // Res interface (e.g. UsersGetUserByUuidRes) for the full list.
    switch e := resp.(type) {
    case *remapi.UserResponse:
        fmt.Printf("User found: %s\n", e.Response.Username)
    case *remapi.BadRequestError:
        fmt.Println("Validation errors:")
        for _, ve := range e.Errors {
            fmt.Printf("  - %s: %s (path: %v)\n",
                ve.Code, ve.Message, ve.Path)
        }
    case *remapi.NotFoundError:
        fmt.Println("Resource not found")
    case *remapi.InternalServerError:
        fmt.Printf("Server error: %s\n", e.Message.Value)
    }
}

可用控制器

控制器	描述
client.ApiTokens()	API 令牌管理
client.Auth()	身份驗證
client.BandwidthStatsNodes()	節點頻寬統計
client.BandwidthStatsUsers()	使用者頻寬統計
client.ConfigProfile()	設定檔
client.ExternalSquad()	外部小隊
client.Hosts()	主機管理
client.HostsBulkActions()	主機批量操作
client.HwidUserDevices()	HWID 裝置
client.InfraBilling()	基礎設施計費
client.InternalSquad()	內部小隊
client.Keygen()	金鑰生成
client.Nodes()	節點管理
client.NodesUsageHistory()	節點使用歷史
client.Passkey()	密鑰認證
client.RemnawaveSettings()	面板設定
client.Snippets()	程式碼片段
client.Subscription()	訂閱管理
client.SubscriptionPageConfig()	訂閱頁面設定
client.SubscriptionSettings()	訂閱設定
client.SubscriptionTemplate()	訂閱範本
client.Subscriptions()	多訂閱
client.System()	系統資訊
client.UserSubscriptionRequestHistory()	請求歷史
client.Users()	使用者管理
client.UsersBulkActions()	使用者批量操作

錯誤類型

類型	HTTP 狀態	描述
BadRequestError	400	帶詳情的驗證錯誤
UnauthorizedError	401	需要身份驗證
ForbiddenError	403	存取被拒絕
NotFoundError	404	資源未找到
InternalServerError	500	伺服器錯誤

🛠️ 專案連結

• GitHub 儲存庫: remnawave-api-go on GitHub
• 作者: Jolymmiles