txcloud-sdk

类似微信小程序云开发的云环境 SDK，提供数据库、文件存储、云函数等 BaaS 服务。

快速开始

1. 注册账号并创建环境

访问管理后台：https://pay.silkspinner.cn/

1. 注册/登录：使用邮箱或用户名注册账号
2. 创建环境：登录后在「环境管理」页面创建云环境（开发环境或生产环境）
3. 获取环境 ID：创建成功后会得到一个 env_id，用于 SDK 初始化
4. 创建集合：在「数据库」页面创建数据集合（相当于数据库表）

2. 创建数据集合

在管理后台的「数据库」页面，可以创建集合并定义字段：

支持的字段类型：

• String：字符串类型
• Number：数字类型
• Boolean：布尔类型
• Date：日期类型
• Object：对象类型
• Array：数组类型
• GeoPoint：地理位置类型

字段配置：

• 字段名：字段的唯一标识（如 username、age）
• 字段类型：选择上述类型之一
• 是否必填：设置该字段是否为必填项
• 默认值：可选，设置字段的默认值
• 索引：可为字段创建索引以提高查询性能

示例：创建 users 集合

字段名      类型      必填    默认值
username   String    是      -
email      String    是      -
age        Number    否      0
avatar     String    否      -
created_at Date      是      当前时间

3. 安装 SDK

npm install txcloud-sdk
# 或
pnpm add txcloud-sdk
# 或
yarn add txcloud-sdk

使用示例

初始化

import tx from 'txcloud-sdk';

// 使用默认 API 地址（https://pay.silkspinner.cn/api）
tx.init({
  env: 'your-env-id'
});

// 或者自定义 API 地址
tx.init({
  env: 'your-env-id',
  apiUrl: 'https://your-custom-api.com/api'
});

数据库操作

const db = tx.database;

// 查询数据
const res = await db.collection('users')
  .where({ age: db.command().gt(18) })
  .limit(10)
  .get();

// 添加数据
await db.collection('users').add({
  name: '张三',
  age: 20
});

// 更新数据
await db.collection('users')
  .where({ name: '张三' })
  .update({ age: 21 });

// 删除数据
await db.collection('users')
  .where({ name: '张三' })
  .remove();

// 通过 ID 操作
await db.collection('users').doc('xxx').get();
await db.collection('users').doc('xxx').update({ age: 22 });
await db.collection('users').doc('xxx').remove();

文件存储

const storage = tx.storage;

// 上传文件
const file = document.querySelector('input[type="file"]').files[0];
const result = await storage.uploadFile(file, 'images/avatar.png');
console.log('文件ID:', result.fileID);
console.log('访问链接:', result.url);
console.log('内部路径:', result.internalPath); // 用于删除和下载

// 删除文件（使用 internalPath）
await storage.deleteFile(result.internalPath);

// 获取临时链接（使用 internalPath）
const { url } = await storage.getTempFileURL(result.internalPath);
console.log('临时链接:', url);

// 直接访问文件（使用返回的 url）
window.open(result.url, '_blank');

云函数（待实现）

⚠️ 注意：云函数功能目前正在开发中。

云函数允许你在云端运行自定义的 JavaScript 代码，无需管理服务器。

使用方式：

// 调用云函数
const result = await tx.functions.callFunction('login', {
  username: 'admin',
  password: '123456'
});
console.log('函数返回:', result);

云函数示例代码：

// 函数名: login
// 这段代码会在云端执行
exports.main = async (event, context) => {
  const { username, password } = event;
  
  // 在云函数中可以访问数据库
  const db = context.database;
  const user = await db.collection('users')
    .where({ username, password })
    .getOne();
  
  if (user) {
    return {
      success: true,
      message: '登录成功',
      user: {
        id: user._id,
        username: user.username
      }
    };
  } else {
    return {
      success: false,
      message: '用户名或密码错误'
    };
  }
};

云函数功能规划：

• 📤 上传函数代码到云端
• 📝 在线编辑函数代码
• 🚀 调用云函数并传递参数
• 📊 查看函数执行日志
• ⚡ 函数内访问数据库和存储

管理后台功能

访问 https://pay.silkspinner.cn/ 进入管理后台

主要功能模块

1. 环境管理

• 创建开发环境（dev）和生产环境（prod）
• 每个环境拥有独立的数据库和存储空间
• 查看环境 ID（env_id）用于 SDK 初始化

2. 数据库管理

• 创建集合：定义数据表结构，配置字段类型和约束
• 数据查看：浏览集合中的所有数据记录
• 数据编辑：直接在后台增删改查数据
• 索引管理：为字段创建索引，优化查询性能

3. 文件存储

• 上传文件到云存储
• 管理已上传的文件
• 获取文件访问链接

4. 云函数（开发中）

• 部署和管理云函数
• 查看函数调用日志

5. 用户管理

• 查看注册用户列表
• 管理用户权限

数据库查询指令

SDK 提供了丰富的查询指令：

const db = tx.database;
const _ = db.command();

// 比较运算符
db.collection('users').where({ age: _.gt(18) }).get();      // 大于
db.collection('users').where({ age: _.gte(18) }).get();     // 大于等于
db.collection('users').where({ age: _.lt(60) }).get();      // 小于
db.collection('users').where({ age: _.lte(60) }).get();     // 小于等于
db.collection('users').where({ age: _.eq(25) }).get();      // 等于
db.collection('users').where({ age: _.neq(25) }).get();     // 不等于

// 逻辑运算符
db.collection('users').where({
  age: _.and(_.gte(18), _.lte(60))  // 且
}).get();

db.collection('users').where(
  _.or([
    { age: _.lt(18) },
    { age: _.gt(60) }
  ])
).get();

// 数组运算符
db.collection('users').where({ 
  tags: _.in(['developer', 'designer'])  // 在数组中
}).get();

db.collection('users').where({ 
  tags: _.nin(['admin'])  // 不在数组中
}).get();

完整示例

import tx from 'txcloud-sdk';

// 1. 初始化（使用你在后台创建的环境 ID）
tx.init({
  env: 'prod-xxx'  // 替换为你的环境 ID
});

const db = tx.database;

// 2. 添加数据
async function addUser() {
  const result = await db.collection('users').add({
    username: 'zhangsan',
    email: '[email protected]',
    age: 25,
    avatar: 'https://example.com/avatar.jpg',
    created_at: new Date()
  });
  console.log('添加成功，ID:', result._id);
}

// 3. 查询数据
async function getUsers() {
  const result = await db.collection('users')
    .where({ age: db.command().gte(18) })
    .orderBy('created_at', 'desc')
    .limit(10)
    .get();
  console.log('查询结果:', result.data);
}

// 4. 更新数据
async function updateUser(userId) {
  await db.collection('users').doc(userId).update({
    age: 26,
    updated_at: new Date()
  });
  console.log('更新成功');
}

// 5. 删除数据
async function deleteUser(userId) {
  await db.collection('users').doc(userId).remove();
  console.log('删除成功');
}

注意事项

1. 环境隔离：开发环境和生产环境的数据完全隔离，建议在开发时使用开发环境
2. 字段类型：添加数据时请确保字段类型与集合定义一致
3. 必填字段：添加数据时必须包含所有必填字段
4. 索引优化：对于经常查询的字段，建议在后台创建索引
5. 数据安全：生产环境数据请谨慎操作，建议定期备份

技术支持

• 管理后台：https://pay.silkspinner.cn/
• 问题反馈：请在管理后台提交工单或联系技术支持

License

MIT