FyLib.DuckSoft.ClientApi 1.2.0

DuckSoft.ClientApi

DuckClient API 客户端 SDK，用于对接 DuckClient SaaS 平台。提供用户认证、版本管理、会话管理、支付集成、SignalR 实时通信等完整功能，开箱即用。

✨ 功能特性

📦 安装

dotnet add package DuckSoft.ClientApi

或通过 NuGet 包管理器搜索 DuckSoft.ClientApi。

要求: .NET 10.0 或更高版本

🚀 快速开始

1. 配置并创建客户端

using ClientApi;
using ClientApi.Models;
using ClientApi.Utils;

var config = new ClientConfig
{
    ApiBaseUrl = "https://api.example.com",   // API 服务器地址
    ProjectId = 1,                             // 项目 ID
    Token = "your-project-token",              // 项目 Token
    EncryptKey = "12345678",                   // DES 加密密钥（8字节）
    EncryptSalt = "your-salt",                 // MD5 签名盐值
    Version = "1.0.0",                         // 客户端版本号
    MachineCode = CryptoHelper.GenerateMachineCode(), // 自动生成机器码
    TimeoutSeconds = 30                        // 请求超时（秒）
};

using var client = new DuckClient(config);

2. 初始化并检测版本

var init = await client.InitAsync();
if (init.Success)
{
    Console.WriteLine($"最新版本: {init.Data.LastVersion}");
    Console.WriteLine($"是否需要更新: {init.Data.NeedUpdate}");
    if (init.Data.NeedUpdate)
    {
        Console.WriteLine($"下载地址: {init.Data.Url}");
    }
}

3. 用户登录

var login = await client.LoginAsync("username", "password");
if (login.Success)
{
    Console.WriteLine($"登录成功！Token: {client.UserToken}");
    // 登录成功后 SignalR 自动连接
}

4. 心跳保活

// 建议每 30~60 秒发送一次心跳
var heartbeat = await client.HeartbeatAsync();
if (heartbeat.Success)
{
    Console.WriteLine($"会话有效，服务器时间: {heartbeat.Data.ServerTime}");
}

5. 获取用户信息

var info = await client.GetUserInfoAsync();
if (info.Success)
{
    Console.WriteLine($"用户名: {info.Data.Username}");
    Console.WriteLine($"积分: {info.Data.Score}");
    Console.WriteLine($"等级: {info.Data.Level}");
    Console.WriteLine($"到期时间: {DateTimeOffset.FromUnixTimeSeconds(info.Data.ExpireTime)}");
}

6. 用户注册

var register = await client.RegisterAsync(
    username: "newuser",
    password: "password123",
    qq: "123456789",
    email: "user@example.com",
    inviteCode: "INVITE123"
);
if (register.Success) Console.WriteLine("注册成功！");

7. 登出

await client.LogoutAsync();
// 登出后 SignalR 自动断开

📡 SignalR 实时通信

登录成功后 SignalR 自动连接。你可以监听以下事件：

// 收到服务器推送消息
client.SignalR.OnMessageReceived += (title, content) =>
{
    Console.WriteLine($"[{title}] {content}");
};

// 被强制下线
client.SignalR.OnForceLogout += reason =>
{
    Console.WriteLine($"被强制下线: {reason}");
};

// 积分变动
client.SignalR.OnScoreChanged += (change, current, reason) =>
{
    Console.WriteLine($"积分变动: {change:+#;-#;0}，当前: {current}，原因: {reason}");
};

// 到期时间变动
client.SignalR.OnTimeChanged += (expireTime, reason) =>
{
    Console.WriteLine($"到期时间更新: {DateTimeOffset.FromUnixTimeSeconds(expireTime)}，原因: {reason}");
};

// 账号状态变更
client.SignalR.OnStatusChanged += (status, reason) =>
{
    Console.WriteLine($"状态变更: {status}，原因: {reason}");
};

// 连接生命周期
client.SignalR.OnConnected += () => Console.WriteLine("SignalR 已连接");
client.SignalR.OnDisconnected += ex => Console.WriteLine("SignalR 已断开");
client.SignalR.OnReconnecting += () => Console.WriteLine("SignalR 重连中...");
client.SignalR.OnReconnected += () => Console.WriteLine("SignalR 重连成功");

📖 完整 API 列表

🔒 加密与安全

所有请求自动进行以下处理，无需手动干预：

1. 数据加密 — 请求体使用 DES (ECB/PKCS7) 加密
2. 签名校验 — 使用 MD5 对原始数据 + 盐值进行签名
3. 响应解密 — 服务端返回的数据自动 DES 解密

加密密钥 (EncryptKey) 和盐值 (EncryptSalt) 需要与服务端配置一致。

🖥️ 机器码

SDK 提供跨平台机器码生成，基于多维硬件特征（MAC 地址、系统信息、平台 UUID 等）：

// 自动生成（推荐）
var machineCode = CryptoHelper.GenerateMachineCode();

// 也可以自定义
config.MachineCode = "your-custom-machine-code";

🔁 响应格式

所有方法返回统一的 ApiResponse<T> 类型：

public class ApiResponse<T>
{
    public bool Success { get; set; }      // 是否成功
    public int Code { get; set; }          // 状态码（0=成功）
    public string Message { get; set; }    // 消息（中文）
    public T? Data { get; set; }           // 响应数据
    public long Timestamp { get; set; }    // 时间戳
    public string? TraceId { get; set; }   // 请求追踪 ID
}

错误码说明

💡 完整示例

using ClientApi;
using ClientApi.Models;
using ClientApi.Utils;

// 1. 配置
var config = new ClientConfig
{
    ApiBaseUrl = "https://api.example.com",
    ProjectId = 1,
    Token = "your-project-token",
    EncryptKey = "12345678",
    EncryptSalt = "your-salt",
    Version = "1.0.0",
    MachineCode = CryptoHelper.GenerateMachineCode()
};

using var client = new DuckClient(config);

// 2. 监听 SignalR 事件（登录前注册）
client.SignalR.OnForceLogout += reason => Console.WriteLine($"被踢下线: {reason}");
client.SignalR.OnMessageReceived += (title, msg) => Console.WriteLine($"[{title}] {msg}");

// 3. 初始化
var init = await client.InitAsync();
if (!init.Success) { Console.WriteLine($"初始化失败: {init.Message}"); return; }
Console.WriteLine($"最新版本: {init.Data.LastVersion}");

// 4. 登录
var login = await client.LoginAsync("myuser", "mypassword");
if (!login.Success) { Console.WriteLine($"登录失败: {login.Message}"); return; }
Console.WriteLine("登录成功！");

// 5. 获取用户信息
var info = await client.GetUserInfoAsync();
if (info.Success) Console.WriteLine($"欢迎 {info.Data.Username}，积分: {info.Data.Score}");

// 6. 定时心跳
using var cts = new CancellationTokenSource();
_ = Task.Run(async () =>
{
    while (!cts.Token.IsCancellationRequested)
    {
        await client.HeartbeatAsync();
        await Task.Delay(TimeSpan.FromSeconds(30), cts.Token);
    }
});

// ... 你的业务逻辑 ...

// 7. 登出
cts.Cancel();
await client.LogoutAsync();

⚠️ 注意事项

1. 线程安全 — DuckClient 实例非线程安全，建议每个线程使用独立实例
2. 资源释放 — 使用 using 语句或手动调用 Dispose() 释放资源
3. 心跳保活 — 长时间运行的应用需定期调用 HeartbeatAsync()（建议 30~60 秒）
4. 版本检测 — 建议启动时调用 InitAsync() 检查更新
5. SignalR — 登录成功后自动连接，登出后自动断开

📋 依赖项

📄 许可证

MIT License

🤝 技术支持

如有问题或建议，请通过 GitHub Issues 反馈。