T1YOS.Sdk

特性

• 安全认证 — HMAC-SHA256 请求签名，带时间窗口验证
• 云数据库 — 完整的 CRUD 操作，支持 MongoDB 风格的查询（单文档、批量、分页、聚合）
• Schema 管理 — 通过 API 创建、清空和删除集合
• 云函数 — 调用服务端 .jsc 函数，自动解析扩展名
• 安全模式 — AES-256-GCM 负载加密，端到端安全保障
• 特殊类型 — ObjectID、Date、Timestamp、类型化数值等标记字符串
• 时间同步 — 通过服务端时间同步自动校正时钟偏差
• 元数据 — 获取服务端元数据（版本、状态、集合列表）
• 多目标框架 — 支持 .NET Framework 4.8、.NET Core 2.0+、.NET 5–8+、Unity 和 Xamarin

支持的平台

安装

NuGet 包管理器

dotnet add package T1YOS.Sdk

包管理器控制台

Install-Package T1YOS.Sdk

快速开始

using T1YOS.Sdk;
using T1YOS.Sdk.Client;
using T1YOS.Sdk.SpecialTypes;

// 1. 创建客户端
var client = new T1YOS(new T1YOSConfig
{
    AppId = 1001,                                    // 您的应用 ID
    ApiKey = "your-32-character-api-key-here",       // 您的 API 密钥
    SecretKey = "your-32-character-secret-key-here", // 您的密钥
    BaseUrl = "https://myapp.t1y.net"                // 可选（默认值）
});

// 2. 初始化（同步服务器时间和安全模式）
await client.InitAsync();

// 3. 开始使用数据库
var users = client.Db.Collection("users");

// 插入文档
var insertResult = await users.InsertOneAsync(new Dictionary<string, object?>
{
    { "name", "张三" },
    { "age", 30 },
    { "email", "zhangsan@example.com" },
    { "createdAt", SpecialTypes.TimeNow }  // 服务端时间戳
});
Console.WriteLine($"已插入: {insertResult.Data?.ObjectId}");

// 通过 ID 查找
var findResult = await users.FindByIdAsync(insertResult.Data!.ObjectId!);
Console.WriteLine($"已找到: {findResult.Data?.Result?["name"]}");

配置

数据库操作

单文档操作

// 插入
var result = await users.InsertOneAsync(new Dictionary<string, object?>
{
    { "name", "李四" },
    { "score", 95 }
});

// 通过 ObjectID 查找
var doc = await users.FindByIdAsync("507f1f77bcf86cd799439011");

// 通过 ObjectID 更新
await users.UpdateByIdAsync("507f1f77bcf86cd799439011", new Dictionary<string, object?>
{
    { "$set", new Dictionary<string, object?> { { "score", 100 } } }
});

// 通过 ObjectID 删除
await users.DeleteByIdAsync("507f1f77bcf86cd799439011");

条件查询操作

// 条件查找
var doc = await users.FindOneAsync(new Dictionary<string, object?>
{
    { "name", "张三" }
});

// 条件更新
await users.UpdateOneAsync(
    new Dictionary<string, object?> { { "name", "李四" } },
    new Dictionary<string, object?>
    {
        { "$inc", new Dictionary<string, object?> { { "score", 5 } } }
    });

// 条件删除
await users.DeleteOneAsync(new Dictionary<string, object?>
{
    { "status", "inactive" }
});

批量操作

// 批量插入
var result = await users.InsertManyAsync(new[]
{
    new Dictionary<string, object?> { { "name", "张三" } },
    new Dictionary<string, object?> { { "name", "李四" } },
    new Dictionary<string, object?> { { "name", "王五" } }
});
Console.WriteLine($"已插入 {result.Data?.InsertedCount} 条文档");

// 批量更新
await users.UpdateManyAsync(
    new Dictionary<string, object?> { { "status", "pending" } },
    new Dictionary<string, object?>
    {
        { "$set", new Dictionary<string, object?> { { "status", "active" } } }
    });

// 批量删除
await users.DeleteManyAsync(new Dictionary<string, object?>
{
    { "archived", true }
});

高级查询

// 分页查询
var page = await users.FindAsync(
    page: 1,
    size: 20,
    sort: new Dictionary<string, object?> { { "createdAt", -1 } },
    filter: new Dictionary<string, object?>
    {
        { "age", new Dictionary<string, object?> { { "$gte", 18 } } }
    });
Console.WriteLine($"第 {page.Data?.Page} 页，共 {page.Data?.Pagination?.TotalPages} 页");

// 聚合管道
var aggregateResult = await users.AggregateAsync(new[]
{
    new Dictionary<string, object?> { { "$match", new Dictionary<string, object?> { { "score", new Dictionary<string, object?> { { "$gt", 60 } } } } } },
    new Dictionary<string, object?> { { "$group", new Dictionary<string, object?> { { "_id", "$name" }, { "total", new Dictionary<string, object?> { { "$sum", "$score" } } } } } }
});

// 统计文档数
var countResult = await users.CountAsync(new Dictionary<string, object?>
{
    { "status", "active" }
});

// 去重值
var distinctResult = await users.DistinctAsync("category");

Schema 管理

// 创建集合
await users.CreateAsync();

// 清空集合（保留 Schema）
await users.ClearAsync();

// 删除集合（同时删除 Schema 和所有文档）
await users.DropAsync();

特殊类型

t1yOS 服务端能识别 JSON 请求体中的特殊标记字符串。使用 SpecialTypes 类来创建它们：

注意： 以 _ 结尾的方法（Date_、Boolean_、Double_、Array_、Map_、DateTime_）添加了下划线后缀，以避免与 C# 内置类型冲突。

自动日期转换

SDK 会自动将请求体中的 C# DateTime 对象转换为 Date('...') 标记，将 10 位及以上的数字转换为 Timestamp('...') 标记。例如：

await users.InsertOneAsync(new Dictionary<string, object?>
{
    { "scheduledAt", DateTime.UtcNow },       // → Date('2024-01-15T...')
    { "version", 1705312200L }                 // → Timestamp('1705312200')
});

云函数

调用服务端 JavaScript（.jsc）函数：

// 使用参数调用 "hello.jsc"
var result = await client.CallFuncAsync("hello", new
{
    name = "World",
    greeting = "你好"
});

// 扩展名规则：
// "hello"     → "hello.jsc"
// "dir/"      → "dir/index.jsc"
// "script.js" → "script.jsc"
// "func.jsc"  → "func.jsc"（无变化）

元数据

// 获取所有元数据
var meta = await client.GetMetaAsync();

// 获取特定字段
var versionInfo = await client.GetMetaAsync("version");

安全性

请求签名

每个 API 请求都使用 HMAC-SHA256 进行签名：

签名    = HMAC-SHA256(secretKey, message)
message = METHOD + "\n" + PATH_AND_QUERY + "\n" + SHA256(body) + "\n" + appId + "\n" + timestamp

签名通过 X-T1Y-Safe-Sign 请求头发送，同时发送的还有：

• X-T1Y-Application-ID — 您的应用 ID
• X-T1Y-API-Key — 您的 API 密钥
• X-T1Y-Safe-Timestamp — Unix 时间戳（已根据服务端偏移量调整）

安全模式（AES-256-GCM 加密）

当启用安全模式时（通过 IsSafeMode: true 或在 InitAsync() 期间自动检测），请求和响应体将使用 AES-256-GCM 进行加密：

• 密钥：您的 32 字符密钥（UTF-8 编码 → 32 字节）
• Nonce：12 个随机字节（每条消息独立）
• Tag：128 位认证标签
• 负载格式：{"n": "<base64 nonce>", "j": "<base64 ciphertext>", "t": "<base64 tag>"}

这确保了敏感数据的端到端机密性和完整性。

错误处理

try
{
    var result = await users.InsertOneAsync(data);
}
catch (T1YError ex)
{
    Console.WriteLine($"API 错误 [{ex.Code}]: {ex.Message}");
    // ex.ErrorData 可能包含额外信息
}
catch (ValidationError ex)
{
    Console.WriteLine($"验证错误: {ex.Message}");
}

API 参考

T1YOS 客户端

T1Collection