YuanXuan.TrackingSystem.SDK 1.0.2

<div align="center"> <H1><a href="./README_API.md" style="margin-left: 5px">点我跳转项目架构说明文档</a></H1> </div>

📦 TrackingSystem.SDK 使用文档

版本：v1.0.2
框架：netstandard2.1
作者：胡船辉
说明：TrackingSystem.SDK 是用于埋点日志与 API 日志自动收集、缓存、批量推送的客户端 SDK。

🚀 一、安装与配置

1. 安装方式

✅ NuGet 安装

dotnet add package TrackingSystem.SDK

✅ 或者手动引用

将 TrackingSystem.SDK.dll 引入你的 WebAPI / 控制台项目。

⚙️ 二、快速开始

1. 初始化客户端

using TrackingSystem.SDK;

var client = new TrackingSystemClient("SystemA", batchSize: 50);

TrackingSystemClient 会自动从系统中心同步系统信息，并初始化日志推送通道。

🧩 三、功能说明

1. 获取系统信息

var sysInfo = await client.GetDimSystem();

返回系统注册信息，用于验证接入合法性。初始化客户端会自动获取一次，后续调用会返回缓存数据。

2. 获取系统事件类型

var types = await client.GetDimEventTypes();

• 若缓存存在，默认返回缓存；
• 传入 IsRefresh: true 强制调用 API 刷新。

3. 获取系统自定义标签

var tags = await client.GetDimCustomTags();

与事件类型逻辑相同，用于埋点分类。

4. 检查服务健康状态

bool isAlive = await client.GetHealthStatus();

若返回 false，表示系统未注册或服务不可用。

5. 推送埋点日志

await client.PushEventLogAsync(new EventlogAddDto
{
    System_code = "SystemA",
    EventType = "Click",
    UserId = "U10001",
    EventTime = DateTime.Now
});

SDK 会自动缓存、批量推送，支持：

• 达到阈值自动推送；
• 超过时间间隔自动推送；
• 程序退出前自动落盘与恢复。 💡 v1.0.2 更新内容
  • System_code 会自动从初始化参数中获取，无需手动设置。

6. 推送 API 日志

如果初始化时 IsMQDirectPush 为 true，则会直接将日志推送到 MQ。

await client.PushApiLogAsync(new ApiLogAddDto
{
    Endpoint = "/api/test",
    Method = "POST",
    ResponseInfo = new ApiLog_ResponseInfo { StatusCode = 200 }
});

支持自动附加系统编码与推送策略，与埋点逻辑独立。 💡 v1.0.2 更新内容

• RequestId 默认会自动生成，无需手动设置。
• System_code 会自动从初始化参数中获取，无需手动设置。

7. 推送自定义日志

💡 v1.0.2 新增

如果初始化时 IsMQDirectPush 为 true，则会直接将日志推送到 MQ。

await client.PushCustomLogAsync(new CustomLogAddDto()
{
  CustomLogTypeCode = "mqlogs",
  Timestamp = DateTime.Now,
  Fields=new Dictionary<string, object>
  {
    {"数据下标",tagid},
  }
});

• CustomLogTypeCode 自定义日志类型编码:warning:必填。
• Timestamp 日志时间，不传默认当前时间
• Fields 自定义字段，键值对格式，可选。

8. 上传文件

var file = await client.UploadFile(new UploadFileDto
{
    FileName = "report.log",
    FileStream = Stream流
});

返回 ApiLog_FileInfo：

{
  "FileId": "650a1b2c...",//文件id
  "FileName": "report.log",//文件名称
  "FileExt":".log", //文件后缀
  "FileLength":15320,//文件大小 单位KB
  "BucketName": "TrackingSystem.Apiapi_log" //存储桶名称
}

🧠 四、生命周期与资源释放

TrackingSystemClient 实现了 IAsyncDisposable：

await using var client = new TrackingSystemClient("SystemA");

或手动调用：

await client.DisposeAsync();

SDK 会在释放时自动推送缓存中未发送的日志，并释放内部资源。

🧾 五、异常与重试机制

📚 六、最佳实践

✅ 建议 静态化实例 ：

static readonly TrackingSystemClient Client = new("SystemA");

✅ 不建议频繁创建销毁客户端对象。
✅ 可在 WebAPI 全局过滤器或中间件中统一封装日志调用。

📄 七、命名空间

using TrackingSystem.SDK;
using TrackingSystem.SDK.Dto;

🧩 八、更新记录