t1y-sdk-js

v5.0.5

Published

18 hours ago

t1yOS Serverless Platform JavaScript/TypeScript SDK — cloud database, metadata, and cloud functions client

0High
0Medium
0Low

wwwanghua

t1y t1yos serverless baas sdk database cloud-functions mongodb

t1yOS SDK for JavaScript/TypeScript

English

t1yOS Serverless 平台 JavaScript/TypeScript SDK — 云数据库、元数据和云函数客户端。

平台支持

| 平台 | 支持 | 传输 API | 说明 | | ------------------------ | ---- | --------------- | -------------------------- | | Web / Vue / React / HTML | ✅ | fetch | 现代浏览器 | | Node.js | ✅ | fetch (18+) | 使用原生 fetch API | | 微信小程序 | ✅ | wx.request | 自动检测 | | QQ 小程序 | ✅ | qq.request | 自动检测（微信小程序系列） | | 头条小程序 | ✅ | tt.request | 自动检测（微信小程序系列） | | 抖音小程序 | ✅ | tt.request | 自动检测（微信小程序系列） | | 支付宝小程序 | ✅ | my.request | 自动检测 | | 快应用 | ✅ | @system.fetch | 构建时模块解析 |

注意： SDK 会自动检测运行环境并使用对应的请求 API，无需手动配置——同一套代码在所有平台都能运行。

安装

npm / pnpm / yarn

npm install t1y-sdk-js
# 或
pnpm add t1y-sdk-js
# 或
yarn add t1y-sdk-js

Script 标签（浏览器）

<script src="https://unpkg.com/t1y-sdk-js/dist/umd/t1y.min.js"></script>
<script>
  const client = new T1Y.T1YOS({ appId: 1001, apiKey: '...', secretKey: '...' })
</script>

小程序

微信 / QQ / 头条 / 抖音小程序：

在小程序项目中通过 npm 安装：
```
npm install t1y-sdk-js
```
在开发者工具中构建 npm：
- 微信：工具 → 构建 npm
- QQ / 头条 / 抖音：在各自开发者工具中类似操作

引入并使用：

import { T1YOS, timeNow } from 't1y-sdk-js'

const client = new T1YOS({
  appId: 1001,
  apiKey: '32位API-Key',
  secretKey: '32位Secret-Key',
})

await client.init()
// ... 使用数据库操作

注意： 小程序需要将 baseUrl 配置到服务器域名白名单中。前往小程序管理后台 → 开发 → 服务器域名，添加你的 t1yOS 域名（例如 https://myapp.t1y.net）。

支付宝小程序：

操作同上——SDK 会自动检测支付宝环境并使用 my.request 代替 wx.request。在支付宝开发者控制台中配置域名白名单即可。

快应用

通过 npm 安装：
```
npm install t1y-sdk-js
```

在快应用项目中引入并使用：

import { T1YOS } from 't1y-sdk-js'

const client = new T1YOS({
  appId: 1001,
  apiKey: '32位API-Key',
  secretKey: '32位Secret-Key',
})

await client.init()

注意： 快应用的 hap-toolkit 会在构建时自动解析 @system.fetch 模块依赖，无需额外配置。

快速开始

import { T1YOS, timeNow } from 't1y-sdk-js'

// 1. 创建客户端
const client = new T1YOS({
  appId: 1001, // 必填：应用 ID（>= 1001）
  apiKey: '4fd7448cdc684431a62d8a0111dc69', // 必填：32 位 API Key
  secretKey: '17b784e359c946ffa65eebbf9ce29', // 必填：32 位 Secret Key
  // 以下参数可选（均有默认值）：
  // baseUrl: 'https://myapp.t1y.net',
  // version: 0,
  // isSafeMode: false,
  // timeFormat: 'YYYY-MM-DD HH:mm:ss',
  // offset: 0,
})

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

// 3. 开始使用数据库！
await client.db.collection('users').insertOne({
  name: '张三',
  age: 25,
  active: true,
  customTimeAt: timeNow.Now(),
})

数据库操作

单条操作

const db = client.db.collection('users')

// 插入一条
const { data } = await db.insertOne({ name: '张三', age: 25 })
console.log(data.objectId) // '507f1f77bcf86cd799439011'

// 通过 ObjectID 查询
const { data: findResult } = await db.findById('507f1f77bcf86cd799439011')
console.log(findResult.result) // { _id: '507f1f77...', name: '张三', ... }

// 通过 ObjectID 更新
await db.updateById('507f1f77bcf86cd799439011', { $set: { age: 26 } })

// 通过 ObjectID 删除
await db.deleteById('507f1f77bcf86cd799439011')

条件操作

// 条件查询一条
const { data } = await db.findOne({ name: '张三' })

// 条件更新一条
await db.updateOne(
  { name: '张三' }, // 查询条件
  { $set: { age: 27 } } // 更新内容
)

// 条件删除一条
await db.deleteOne({ name: '张三' })

批量操作

// 插入多条
const { data } = await db.insertMany([
  { name: '张三', age: 25 },
  { name: '李四', age: 30 },
])
console.log(data.insertedCount) // 2

// 删除多条
await db.deleteMany({ age: { $lt: 18 } })

// 更新多条
await db.updateMany({ status: 'inactive' }, { $set: { status: 'archived' } })

高级查询

// 分页查询
const { data } = await db.find(
  1, // 页码（从 1 开始）
  20, // 每页条数（最大 100）
  { createdAt: -1 }, // 排序（按创建时间倒序）
  { age: { $gte: 18 } } // 查询条件
)
console.log(data.results) // 文档数组
console.log(data.pagination) // { totalItems: 42, totalPages: 3 }

// 聚合查询
const { data } = await db.aggregate([
  { $match: { status: 'completed' } },
  { $group: { _id: '$category', total: { $sum: '$amount' } } },
  { $sort: { total: -1 } },
])

// 计数
const { data: countData } = await client.db.collection('users').count({ status: 'active' })
console.log(countData.count)

// 去重查询
const { data: distinctData } = await client.db.collection('users').distinct('city')
// 带条件过滤
const { data: filteredDistinct } = await client.db
  .collection('users')
  .distinct('city', { country: 'China' })

表管理

// 获取所有表
const { data } = await client.db.getCollections()
console.log(data.results) // ['users', 'orders', 'products']

// 创建表
await client.db.collection('posts').create()

// 清空表
const { data: clearResult } = await client.db.collection('posts').clear()
console.log(clearResult.deletedCount)

// 删除表
await client.db.collection('posts').drop()

特殊类型

SDK 提供了一系列辅助函数，用于生成服务端可识别的类型标记：

import {
  ObjectID,
  Date,
  DateTime,
  Timestamp,
  Boolean,
  Integer,
  Bigint,
  Float,
  Double,
  Array,
  Map,
  MapArray,
  Null,
  None,
  Nil,
  timeNow,
} from 't1y-sdk-js'

await db.insertOne({
  // ObjectID 引用
  userId: ObjectID('507f1f77bcf86cd799439011'),

  // 日期类型
  birthday: Date('2000-01-01T00:00:00Z'),
  eventTime: DateTime('2024-06-15T14:30:00Z'),
  loginAt: Timestamp(1705312200),

  // 数值类型
  active: Boolean(true),
  quantity: Integer(42),
  bigNumber: Bigint(9007199254740991),
  rating: Float(4.5),
  preciseValue: Double(3.141592653589793),

  // 结构化类型
  tags: Array(['javascript', 'typescript']),
  metadata: Map({ theme: 'dark', lang: 'zh' }),
  history: MapArray([{ action: 'login' }, { action: 'logout' }]),

  // 空值
  deletedAt: Null, // 服务端转为 nil
  middleName: None, // 服务端转为 nil

  // 服务端时间辅助
  customTimeAt: timeNow.Now(), // 服务端的 time.Now()
  unixCreatedAt: timeNow.NowUnix(), // 服务端的 time.Now().Unix()
})

元数据

// 获取全部元数据
const { data } = await client.getMeta()
console.log(data.results) // { version: 1, collections: [...], ... }

// 获取指定字段
const { data: versionData } = await client.getMeta('version')
console.log(versionData.result) // 1

// 检查更新
const hasUpdate = await client.checkUpdate()

云函数

// 调用 .jsc 云函数
const { data } = await client.callFunc('hello', { name: 'World' })

// 为此调用单独启用安全模式
const { data: safeData } = await client.callFunc('secureFunc', params, true)

安全机制

认证请求头

每个请求都会携带以下请求头：

X-T1Y-Application-ID — 应用 ID
X-T1Y-API-Key — 32 位 API Key
X-T1Y-Safe-Timestamp — Unix 时间戳（UTC + 初始化时获取的时间偏移）
X-T1Y-Safe-Sign — HMAC-SHA256 签名（64 位十六进制）

签名算法

message = METHOD + "\n" + URL_PATH + "\n" + SHA256(body) + "\n" + appId + "\n" + timestamp
signature = HMAC-SHA256(secretKey, message)

安全模式（AES-256-GCM）

当启用安全模式时（通过 isSafeMode: true 或初始化时自动检测），请求体将使用 AES-256-GCM 加密，密钥为应用的 SecretKey，服务端响应也会自动解密。

平台检测

SDK 暴露了检测当前运行环境的工具函数：

import { getPlatformType, getMiniProgramSubType } from 't1y-sdk-js'

// 返回 'h5' | 'wx' | 'my' | 'hap' | 'nodejs' | 'unknown'
const platform = getPlatformType()

// 在 'wx' 系列中，返回 'wechat' | 'qq' | 'toutiao' | 'unknown'
const subType = getMiniProgramSubType()

console.log(platform) // 例如在微信小程序中输出 'wx'
console.log(subType) // 例如在头条小程序中输出 'toutiao'

加密可用性检测

import { isAESGCMAvailable, isWebCryptoAvailable } from 't1y-sdk-js'

// 始终返回 true——纯 JS AES-256-GCM 降级方案始终可用
console.log(isAESGCMAvailable()) // true

// 检测是否有更快的原生 Web Crypto API（硬件加速）
console.log(isWebCryptoAvailable()) // 浏览器/Node.js 中为 true，小程序中为 false

SDK 优先使用 Web Crypto API（在浏览器/Node.js 中更快、硬件加速），在没有 Web Crypto 的环境（小程序、快应用）中自动降级为纯 JavaScript AES-256-GCM 实现。这确保安全模式加密在所有平台上都能正常工作。

API 参考

T1YOS

| 方法 | 说明 | | --------------------------------------------- | ------------------------------------------- | | new T1YOS(config) | 创建客户端（校验 appId、apiKey、secretKey） | | init() | 与服务端同步时间偏移和安全模式 | | db.collection(name) | 获取集合操作实例（链式调用） | | db.toObjectID(id) | 创建 ObjectID 标记字符串 | | db.getCollections() | 获取所有表 | | getMeta(field?) | 获取应用元数据 | | checkUpdate() | 检查是否存在新版本 | | callFunc(name, params?, safeMode?) | 调用云函数 | | request(method, path, params?, encryption?) | 原始认证请求 |

T1Collection

| 方法 | HTTP | 端点 | | -------------------------------- | ------ | ----------------------------------- | | insertOne(data) | POST | /v5/classes/:name | | deleteById(objectId) | DELETE | /v5/classes/:name/:objectId | | updateById(objectId, data) | PUT | /v5/classes/:name/:objectId | | findById(objectId) | GET | /v5/classes/:name/:objectId | | deleteOne(filter) | DELETE | /v5/classes/:name/one | | updateOne(filter, body) | PUT | /v5/classes/:name/one | | findOne(filter) | POST | /v5/classes/:name/one | | insertMany(dataList) | POST | /v5/classes/:name/many | | deleteMany(filter) | DELETE | /v5/classes/:name/many | | updateMany(filter, body) | PUT | /v5/classes/:name/many | | find(page, size, sort, filter) | POST | /v5/classes/:name/find | | aggregate(pipeline) | POST | /v5/classes/:name/aggregate | | count(filter?) | POST | /v5/classes/:name/count | | distinct(fieldName, filter?) | POST | /v5/classes/:name/distinct/:field | | create() | POST | /v5/schemas/:name | | clear() | PUT | /v5/schemas/:name | | drop() | DELETE | /v5/schemas/:name |

T1YOS db 对象还提供：

| 方法 | HTTP | 端点 | | --------------------- | ---- | ------------- | | db.getCollections() | GET | /v5/schemas |

License

MIT