跳到主要内容

概述

Pub Version

CloudBase Flutter SDK 让您可以在 Flutter 应用中使用云开发的能力，包括身份认证、文档型数据库、数据模型、MySQL 数据库、云函数、云托管、APIs、云存储等功能。当前版本为 1.2.2，支持 Android、iOS、Web、macOS、Linux、Windows。使用方式请参考 CloudBase Flutter SDK，也可以参考示例代码。

提示

CloudBase Flutter SDK 已与 HTTP API 全面对齐

安装​

在 pubspec.yaml 中添加依赖：

dependencies:
  cloudbase_flutter: ^1.2.2

然后执行：

flutter pub get

SDK 按照功能用途分为以下类别：

  • 认证登录：用户注册和登录相关的 API 方法，支持多种登录方式。
  • 会话管理：管理用户会话状态和令牌的 API 方法。
  • 用户管理：获取、更新和管理用户信息的 API 方法。
  • 身份源管理：管理第三方身份源绑定和解绑的 API 方法。
  • 密码管理：密码重置和修改相关的 API 方法。
  • 验证管理：验证码发送、验证和重发、图形验证码创建、验证和管理相关的 API 方法。
  • 文档型数据库：NoSQL 文档型数据库的集合、文档、查询、更新、删除、聚合、事务等操作。
  • 数据模型：数据模型 CRUD 操作。
  • 数据源查询：查询数据源聚合列表、详情、Schema 和表名。
  • MySQL 数据库：MySQL RESTful 数据库操作。
  • 云函数：调用云函数和函数型云托管。
  • 云托管：调用云托管容器服务。
  • APIs：调用 APIs 接口。
  • 云存储：文件上传、下载、删除、复制、移动等操作。

基础使用示例​

accessKey 可前往 云开发平台/API Key 配置 中生成

import 'package:cloudbase_flutter/cloudbase_flutter.dart';

// 初始化（异步）
final app = await CloudBase.init(
  env: 'your-env-id',       // 替换为您的环境 ID（必填）
  region: 'ap-shanghai',     // 地域，默认 ap-shanghai，可选 ap-guangzhou、ap-singapore
  lang: 'zh-CN',             // 语言，默认 zh-CN，可选 en-US
  accessKey: 'your-key',     // 填入生成的 Publishable Key
  authConfig: AuthConfig(
    detectSessionInUrl: true, // 可选：自动检测 URL 中的 OAuth 参数
  ),
);

final auth = app.auth;

CloudBase.init 参数：

参数类型必填说明
envString是云开发环境 ID
regionString否地域，默认 ap-shanghai，可选 ap-guangzhou、ap-singapore
langString否语言，默认 zh-CN，可选 en-US
accessKeyString否Publishable Key，用于匿名访问公开资源
authConfigAuthConfig否认证配置，如 detectSessionInUrl

认证登录​

signUp​

Future<SignUpRes> auth.signUp(SignUpReq params)

注册新用户账户，采用智能注册并登录流程。

  • 创建一个新的用户账户
  • 采用智能注册并登录流程：发送验证码 → 等待用户输入 → 智能判断用户存在性 → 自动登录或注册并登录
  • 如果用户已存在则直接登录，如果用户不存在则注册新用户并自动登录

参数

params
SignUpReq

返回

Future
SignUpRes

示例

final result = await auth.signUp(SignUpReq(
  email: 'user@example.com',
  password: 'securePassword123',
  nickname: '新用户',
));

if (result.error != null) {
  print('注册失败: ${result.error!.message}');
  return;
}

// 验证码验证
final verifyResult = await result.data!.verifyOtp!(
  VerifyOtpParams(token: '123456'),
);

if (verifyResult.isSuccess) {
  print('注册成功: ${verifyResult.data?.user?.id}');
}

signInAnonymously​

Future<SignInRes> auth.signInAnonymously({String? providerToken})

匿名登录，创建一个临时匿名用户账户。

  • 创建一个临时匿名用户账户
  • 无需提供任何身份验证信息
  • 适合需要临时访问权限的场景

参数

providerToken
String?

第三方平台令牌，用于关联第三方平台身份

返回

Future
SignInRes

示例

final result = await auth.signInAnonymously();

if (result.isSuccess) {
  print('匿名登录成功');
  print('用户ID: ${result.data?.user?.id}');
  print('是否匿名: ${result.data?.user?.isAnonymous}');
} else {
  print('匿名登录失败: ${result.error!.message}');
}

signInWithPassword​

Future<SignInRes> auth.signInWithPassword(SignInWithPasswordReq params)

使用密码登录。支持通过用户名、邮箱或手机号进行登录。

参数

params
SignInWithPasswordReq

返回

Future
SignInRes

示例

final result = await auth.signInWithPassword(
  SignInWithPasswordReq(
    email: 'user@example.com',
    password: 'securePassword123',
  ),
);

if (result.isSuccess) {
  print('登录成功: ${result.data?.user?.id}');
} else {
  print('登录失败: ${result.error!.message}');
}

signInWithUsername​

Future<SignInRes> auth.signInWithUsername({
  required VerificationInfo verificationInfo,
  required String verificationCode,
  required String username,
  String? loginType,
  dynamic bindInfo,
})

使用用户名/邮箱/手机号和验证码登录。通常先调用 getVerification 发送验证码，再将返回的验证信息与用户输入的验证码传入本方法完成登录。

  • 若 verificationInfo.isUser 为 true，则走登录流程
  • 若用户不存在，则自动注册并登录
  • 可通过 bindInfo 在登录或注册时绑定第三方身份源

参数

verificationInfo
VerificationInfo

验证信息，通常来自 getVerification 的返回值

verificationCode
String

用户输入的验证码

username
String

用户名、邮箱或手机号

loginType
String?

登录类型：email 或 phone。为 email 时按邮箱处理，否则按手机号处理（自动补全 +86 前缀）

bindInfo
dynamic

绑定第三方身份源信息，如 {'providerToken': '...'} 或 {'providerId': '...'}

返回

Future
SignInRes

示例

final verification = await auth.getVerification(email: 'user@example.com');

if (verification.error != null) {
  print('发送验证码失败: ${verification.error!.message}');
  return;
}

final result = await auth.signInWithUsername(
  verificationInfo: VerificationInfo(
    verificationId: verification.data!.verificationId,
    isUser: verification.data!.isUser,
  ),
  verificationCode: '123456',
  username: 'user@example.com',
  loginType: 'email',
);

if (result.isSuccess) {
  print('登录成功: ${result.data?.user?.id}');
} else {
  print('登录失败: ${result.error!.message}');
}

signInWithOtp​

Future<SignInWithOtpRes> auth.signInWithOtp(SignInWithOtpReq params)

使用 OTP（一次性验证码）登录。调用后发送验证码，需通过返回的 verifyOtp 回调完成验证。

  • 如果用户不存在，会默认注册用户，可以通过 shouldCreateUser参数控制是否自动创建用户，默认为 true

参数

params
SignInWithOtpReq

返回

Future
SignInWithOtpRes

示例

final result = await auth.signInWithOtp(
  SignInWithOtpReq(email: 'user@example.com'),
);

if (result.error != null) {
  print('发送验证码失败: ${result.error!.message}');
  return;
}

// 用户输入验证码后调用
final loginResult = await result.data!.verifyOtp!(
  VerifyOtpParams(token: '123456'),
);

if (loginResult.isSuccess) {
  print('OTP 登录成功: ${loginResult.data?.user?.id}');
}

signInWithOAuth​

Future<SignInOAuthRes> auth.signInWithOAuth(SignInWithOAuthReq params)

使用 OAuth 第三方平台登录。返回授权 URL，需引导用户跳转至该 URL 完成授权。

参数

params
SignInWithOAuthReq

返回

Future
SignInOAuthRes

示例

final result = await auth.signInWithOAuth(
  SignInWithOAuthReq(provider: 'wechat'),
);

if (result.isSuccess) {
  final authUrl = result.data!.url!;
  print('请跳转到授权页面: $authUrl');
  // 引导用户打开 authUrl 进行授权
}

signInWithIdToken​

Future<SignInRes> auth.signInWithIdToken(SignInWithIdTokenReq params)

使用第三方平台的身份令牌（IdToken）登录，适用于已获取微信、Google 等平台令牌的场景。SDK 会将 provider 作为 provider_id、将 token 作为 provider_id_token 发送给登录接口。

参数

params
SignInWithIdTokenReq

返回

Future
SignInRes

示例

final result = await auth.signInWithIdToken(
  SignInWithIdTokenReq(
    token: 'provider-id-token',
    provider: 'wechat',
  ),
);

if (result.isSuccess) {
  print('IdToken 登录成功: ${result.data?.user?.id}');
} else {
  print('登录失败: ${result.error!.message}');
}

signInWithCustomTicket​

Future<SignInRes> auth.signInWithCustomTicket(Future<String> Function() getTicketFn)

使用自定义票据登录。通过传入获取票据的异步函数，由服务端生成票据并完成登录。

参数

getTicketFn
Future<String> Function()

获取自定义登录票据的异步函数

返回

Future
SignInRes

示例

final result = await auth.signInWithCustomTicket(() async {
  // 从您的服务端获取自定义票据
  final ticket = await fetchTicketFromServer();
  return ticket;
});

if (result.isSuccess) {
  print('自定义票据登录成功: ${result.data?.user?.id}');
} else {
  print('登录失败: ${result.error!.message}');
}

会话管理​

getSession​

Future<SignInRes> auth.getSession()

获取当前会话。如果 Token 已过期会自动刷新。

参数

无参数

返回

Future
SignInRes

示例

final result = await auth.getSession();

if (result.isSuccess) {
  final session = result.data?.session;
  print('Access Token: ${session?.accessToken}');
  print('用户: ${result.data?.user?.id}');
} else {
  print('获取会话失败: ${result.error!.message}');
}

refreshSession​

Future<SignInRes> auth.refreshSession([String? refreshToken])

刷新会话。使用 Refresh Token 获取新的 Access Token。

参数

refreshToken
String?

刷新令牌（可选，默认使用当前会话的 refreshToken）

返回

Future
SignInRes

示例

final result = await auth.refreshSession();

if (result.isSuccess) {
  print('会话已刷新');
  print('新 Access Token: ${result.data?.session?.accessToken}');
} else {
  print('刷新失败: ${result.error!.message}');
}

setSession​

Future<SignInRes> auth.setSession(SetSessionReq params)

设置会话。通过 Refresh Token 恢复会话状态。

参数

params
SetSessionReq

返回

Future
SignInRes

示例

final result = await auth.setSession(
  SetSessionReq(refreshToken: 'your-refresh-token'),
);

if (result.isSuccess) {
  print('会话设置成功: ${result.data?.user?.id}');
}

signOut​

Future<SignOutRes> auth.signOut([SignOutReq? params])

退出登录。清除本地会话并通知服务端吊销令牌。

参数

params
SignOutReq?

登出配置选项（可选）

返回

Future
SignOutRes

示例

await auth.signOut();
print("已退出登录");

onAuthStateChange​

OnAuthStateChangeResult auth.onAuthStateChange(OnAuthStateChangeCallback callback)

监听认证状态变化。支持监听登录、登出、Token 刷新和用户更新等事件。

参数

callback
void Function(AuthStateChangeEvent, Session?, AuthStateChangeInfo?)

状态变化回调函数

返回

OnAuthStateChangeResult
OnAuthStateChangeResult

示例

final result = auth.onAuthStateChange((event, session, info) {
  print('认证状态变化: ${event.value}');
  if (session != null) {
    print('用户: ${session.user?.id}');
  }
});

// 取消监听
result.data?.subscription.unsubscribe();

getClaims​

Future<GetClaimsRes> auth.getClaims()

获取当前 Access Token 的 JWT Claims（令牌声明）。

参数

无参数

返回

Future
GetClaimsRes

示例

final result = await auth.getClaims();

if (result.isSuccess) {
  final claims = result.data?.claims;
  print('用户ID: ${claims?.sub}');
  print('邮箱: ${claims?.email}');
  print('用户组: ${claims?.groups}');
  print('过期时间: ${claims?.exp}');
}

用户管理​

getUser​

Future<GetUserRes> auth.getUser()

获取当前登录用户信息。

参数

无参数

返回

Future
GetUserRes

示例

final result = await auth.getUser();

if (result.isSuccess) {
  final user = result.data?.user;
  print('用户ID: ${user?.id}');
  print('邮箱: ${user?.id}');
  print('昵称: ${user?.userMetadata?.nickName}');
} else {
  print('获取用户信息失败: ${result.error!.message}');
}

refreshUser​

Future<SignInRes> auth.refreshUser()

刷新用户信息。重新从服务端获取最新的用户数据并更新本地会话。

参数

无参数

返回

Future
SignInRes

示例

final result = await auth.refreshUser();

if (result.isSuccess) {
  print('用户信息已刷新: ${result.data?.user?.id}');
}

updateUser​

Future<UpdateUserRes> auth.updateUser(UpdateUserReq params)

更新用户信息。如果更新邮箱或手机号，需要通过验证码验证。

参数

params
UpdateUserReq

返回

Future
UpdateUserRes

示例

final result = await auth.updateUser(
  UpdateUserReq(nickname: '新昵称', avatarUrl: 'https://example.com/avatar.png'),
);

if (result.isSuccess) {
  print('用户信息已更新: ${result.data?.user?.userMetadata?.nickName}');
}

deleteUser​

Future<CloudBaseResponse<void>> auth.deleteUser(DeleteUserReq params)

删除当前用户。需要提供密码进行安全验证。

参数

params
DeleteUserReq

返回

Future
CloudBaseResponse<void>

示例

final result = await auth.deleteUser(
  DeleteUserReq(password: 'currentPassword'),
);

if (result.isSuccess) {
  print('用户已删除');
} else {
  print('删除失败: ${result.error!.message}');
}

身份源管理​

getUserIdentities​

Future<GetUserIdentitiesRes> auth.getUserIdentities()

获取当前用户已绑定的身份源列表。

参数

无参数

返回

Future
GetUserIdentitiesRes

示例

final result = await auth.getUserIdentities();

if (result.isSuccess) {
  for (final identity in result.data?.identities ?? []) {
    print('身份源: ${identity.name} (${identity.provider})');
  }
}

linkIdentity​

Future<LinkIdentityRes> auth.linkIdentity(LinkIdentityReq params)

绑定第三方身份源。会跳转到第三方授权页面完成绑定。

参数

params
LinkIdentityReq

返回

Future
LinkIdentityRes

示例

final result = await auth.linkIdentity(
  LinkIdentityReq(provider: 'wechat'),
);

if (result.isSuccess) {
  print('身份源绑定成功: ${result.data?.provider}');
}

unlinkIdentity​

Future<CloudBaseResponse<void>> auth.unlinkIdentity(UnlinkIdentityReq params)

解绑第三方身份源。

参数

params
UnlinkIdentityReq

返回

Future
CloudBaseResponse<void>

示例

final result = await auth.unlinkIdentity(
  UnlinkIdentityReq(provider: 'wechat'),
);

if (result.isSuccess) {
  print('身份源已解绑');
}

密码管理​

resetPasswordForEmail​

Future<ResetPasswordForEmailRes> auth.resetPasswordForEmail(String emailOrPhone, {String? redirectTo})

通过邮箱或手机号重置密码。调用后发送验证码，需通过返回的 updateUser 回调完成密码重置。

参数

emailOrPhone
String

邮箱或手机号

redirectTo
String?

重定向地址

返回

Future
ResetPasswordForEmailRes

示例

final result = await auth.resetPasswordForEmail('user@example.com');

if (result.error != null) {
  print('发送验证码失败: ${result.error!.message}');
  return;
}

// 用户收到验证码后
final resetResult = await result.data!.updateUser!(
  UpdateUserAttributes(nonce: '123456', password: 'newPassword123'),
);

if (resetResult.isSuccess) {
  print('密码重置成功，已自动登录');
}

resetPasswordForOld​

Future<SignInRes> auth.resetPasswordForOld(ResetPasswordForOldReq params)

通过旧密码重置密码。

参数

params
ResetPasswordForOldReq

返回

Future
SignInRes

示例

final result = await auth.resetPasswordForOld(
  ResetPasswordForOldReq(
    oldPassword: 'oldPassword123',
    newPassword: 'newPassword456',
  ),
);

if (result.isSuccess) {
  print('密码修改成功');
} else {
  print('密码修改失败: ${result.error!.message}');
}

reauthenticate​

Future<ReauthenticateRes> auth.reauthenticate()

重新认证。发送验证码到用户邮箱或手机号，验证后可进行敏感操作（如设置新密码）。

参数

无参数

返回

Future
ReauthenticateRes

示例

final result = await auth.reauthenticate();

if (result.error != null) {
  print('发送验证码失败: ${result.error!.message}');
  return;
}

final authResult = await result.data!.updateUser!(
  UpdateUserAttributes(nonce: '123456', password: 'newSecurePassword'),
);

if (authResult.isSuccess) {
  print('重新认证成功');
}

验证管理​

getVerification​

Future<CloudBaseResponse<GetVerificationResData>> auth.getVerification({String? email, String? phoneNumber})

发送验证码到邮箱或手机号。

参数

email
String?

邮箱（与 phoneNumber 二选一）

phoneNumber
String?

手机号（与 email 二选一）

返回

Future
CloudBaseResponse<GetVerificationResData>

示例

final result = await auth.getVerification(email: 'user@example.com');

if (result.isSuccess) {
  print('验证码已发送，验证ID: ${result.data?.verificationId}');
  print('是否已注册用户: ${result.data?.isUser}');
}

verify​

Future<CloudBaseResponse<VerifyCodeResData>> auth.verify({required String verificationId, required String verificationCode})

验证验证码。

参数

verificationId
String

验证 ID

verificationCode
String

验证码

返回

Future
CloudBaseResponse<VerifyCodeResData>

示例

final result = await auth.verify(
  verificationId: 'verification-id',
  verificationCode: '123456',
);

if (result.isSuccess) {
  print('验证成功，令牌: ${result.data?.verificationToken}');
}

verifyOAuth​

Future<VerifyOAuthRes> auth.verifyOAuth([VerifyOAuthReq? params])

验证 OAuth 回调，完成第三方登录或绑定身份。如果未传入参数，会自动从当前页面 URL 中提取 code 和 state。

参数

params
VerifyOAuthReq?

OAuth 回调参数（可选，不传时自动从 URL 中获取）

返回

Future
VerifyOAuthRes

示例

// 自动从 URL 获取 code 和 state
final result = await auth.verifyOAuth();

if (result.isSuccess) {
  print('OAuth 验证成功: ${result.data?.user?.id}');
}

// 手动传入参数
final result2 = await auth.verifyOAuth(VerifyOAuthReq(
  code: 'authorization-code',
  state: 'state-value',
  provider: 'google',
  redirectUri: 'https://example.com/callback',
));

verifyOtp​

Future<SignInRes> auth.verifyOtp(VerifyOtpReq params)

验证 OTP 并登录。

参数

params
VerifyOtpReq

返回

Future
SignInRes

示例

final result = await auth.verifyOtp(VerifyOtpReq(
  email: 'user@example.com',
  token: '123456',
  messageId: 'message-id',
));

if (result.isSuccess) {
  print('验证并登录成功: ${result.data?.user?.id}');
}

resend​

Future<ResendRes> auth.resend(ResendReq params)

重发验证码。

参数

params
ResendReq

返回

Future
ResendRes

示例

final result = await auth.resend(
  ResendReq(email: 'user@example.com', type: ResendType.signup),
);

if (result.isSuccess) {
  print('验证码已重发，消息ID: ${result.data?.messageId}');
}

getCaptchaToken​

Future<String?> app.captcha.getCaptchaToken({bool forceNew, required String state})

获取有效的验证码 Token，在多次出现密码输入错误或频繁发送验证码时会要求提供验证码 Token。优先从缓存获取，若无缓存则自动创建验证码并弹出验证界面。支持自定义验证码处理器或使用内置弹窗。

参数

forceNew
bool

是否强制创建新验证码（默认 false）

state
String

状态标识

返回

Future
String?

验证码 Token，失败时为 null

示例

// 初始化时配置 navigatorKey
final navigatorKey = GlobalKey<NavigatorState>();

final app = await CloudBase.init(
  env: 'your-env-id',
  captchaConfig: CaptchaConfig(navigatorKey: navigatorKey),
);

// 获取验证码 Token（自动弹出验证码弹窗）
final token = await app.captcha.getCaptchaToken(state: 'login');
print('Captcha Token: $token');

createCaptchaData​

Future<CreateCaptchaDataRes> app.captcha.createCaptchaData({required String state})

创建验证码数据。返回验证码图片数据和 Token。

参数

state
String

状态标识

返回

Future
CreateCaptchaDataRes

示例

final captchaData = await app.captcha.createCaptchaData(state: 'login');
print('验证码图片: ${captchaData.data}');
print('Token: ${captchaData.token}');

verifyCaptchaData​

Future<VerifyCaptchaRes> app.captcha.verifyCaptchaData({required String token, required String key})

验证用户输入的验证码。

参数

token
String

验证码 Token

key
String

用户输入的验证码

返回

Future
VerifyCaptchaRes

示例

final result = await app.captcha.verifyCaptchaData(
  token: captchaData.token,
  key: '用户输入的验证码',
);
print('验证码 Token: ${result.captchaToken}');

clearCaptchaToken​

Future<void> app.captcha.clearCaptchaToken()

清除本地缓存的验证码 Token。

参数

无参数

返回

Future
void

无返回值

示例

await app.captcha.clearCaptchaToken();
print("验证码 Token 已清除");

文档型数据库​

文档型数据库（NoSQL）提供 JS SDK 风格的链式调用，通过 app.database() 获取实例。支持集合与文档的增删改查、复杂条件查询、聚合、事务等能力，并已与 HTTP API 全面对齐。

final app = await CloudBase.init(env: 'your-env-id');
final db = app.database();

// 单条新增
final addRes = await db.collection('todos').add({
  'title': '学习 CloudBase',
  'completed': false,
  'createdAt': DateTime.now(),
});
print('新增文档 ID: ${addRes.id}');

database​

CloudBaseDatabase app.database({String? instance, String? database})

获取文档型数据库实例。可选参数 instance（实例 ID）与 database（数据库名称）用于指定要访问的数据库，两者均可省略，省略时默认使用 (default)（即默认实例的默认数据库）。仅当需要访问非默认的实例或数据库时才需显式传入。

参数

instance
String?

实例 ID，默认为 (default)

database
String?

数据库名称，默认为 (default)

返回

CloudBaseDatabase
CloudBaseDatabase

数据库实例，提供 collection、command、Geo、startTransaction 等能力

示例

final db = app.database();

createCollection​

Future<DbCreateCollectionResult> db.createCollection(String collName)

创建集合。

参数

collName
String

集合名称

返回

Future
DbCreateCollectionResult

示例

final result = await db.createCollection('todos');
if (result.isSuccess) {
  print('集合创建成功');
}

collection​

CollectionReference db.collection(String collName)

获取集合引用，可在其上链式调用 where、orderBy、limit、skip、field 等查询方法，或调用 doc、add、get、count、aggregate。

参数

collName
String

集合名称

返回

CollectionReference
CollectionReference

集合引用

示例

final collection = db.collection('todos');

add​

Future<DbAddResult> collection.add(dynamic data)

向集合中添加记录，支持单条（Map）和批量（List）新增。

参数

data
dynamic

文档数据，传入 Map 为单条新增，传入 List 为批量新增

返回

Future
DbAddResult

示例

final res = await db.collection('todos').add({
  'title': '学习 CloudBase',
  'completed': false,
  'createdAt': DateTime.now(),
});
print('新增文档 ID: ${res.id}');

doc​

DocumentReference collection.doc(dynamic docId)

获取文档引用，可在其上调用 get、update、set、remove、field。

参数

docId
dynamic

文档 ID

返回

DocumentReference
DocumentReference

文档引用

示例

final docRef = db.collection('todos').doc('doc-id');
final res = await docRef.get();
print(res.data);

where​

Query collection.where(Map<String, dynamic> condition)

设置查询条件，支持等值匹配以及通过 db.command 指令进行复杂条件筛选。

参数

condition
Map<String, dynamic>

查询条件对象，支持等值匹配、操作符匹配、嵌套字段匹配等

返回

Query
Query

查询对象，可链式调用 orderBy、limit、skip、field、get、count、update、remove 等方法

示例

final res = await db
    .collection('todos')
    .where({'completed': false, 'priority': 'high'})
    .get();

print('查询结果: ${res.data}');

orderBy​

Query collection.orderBy(String field, OrderDirection direction)

设置排序规则，direction 取值为 OrderDirection.asc 或 OrderDirection.desc。可多次调用组合多字段排序。

参数

field
String

排序字段

direction
OrderDirection

排序方向：OrderDirection.asc（升序）或 OrderDirection.desc（降序）

返回

Query
Query

查询对象，可继续链式调用

示例

final res = await db
    .collection('todos')
    .orderBy('createdAt', OrderDirection.desc)
    .get();

limit​

Query collection.limit(int max)

设置返回数量上限。

参数

max
int

返回记录数量上限

返回

Query
Query

查询对象，可继续链式调用

示例

final res = await db.collection('todos').limit(10).get();

skip​

Query collection.skip(int offset)

设置跳过的记录数量，常用于分页。

参数

offset
int

跳过的记录数量（偏移量）

返回

Query
Query

查询对象，可继续链式调用

示例

const pageSize = 10;
const pageNum = 2;

final res = await db
    .collection('todos')
    .orderBy('createdAt', OrderDirection.desc)
    .skip((pageNum - 1) * pageSize)
    .limit(pageSize)
    .get();

print('第 $pageNum 页数据: ${res.data}');
print('偏移量: ${res.offset}, 每页数量: ${res.limit}');

field​

Query collection.field(Map<String, dynamic> projection)

指定查询返回的字段，true 表示返回，false 表示不返回。文档引用 doc 也支持 field 方法。

参数

projection
Map<String, dynamic>

字段投影，如 {'title': true, 'content': false}

返回

Query
Query

查询对象，可继续链式调用

示例

final res = await db
    .collection('todos')
    .where({'completed': false})
    .field({'title': true, 'completed': true, 'content': false})
    .get();

get​

Future<DbGetResult> collection.get()
Future<DbGetResult> query.get()
Future<DbGetResult> doc.get()

获取查询结果。在集合引用上调用为无条件查询，在 Query 上调用返回匹配文档列表，在文档引用上调用返回单个文档（文档不存在时 data 为空列表）。

参数

无参数

返回

Future
DbGetResult

示例

final res = await db.collection('todos').get();
print('共 ${res.data.length} 条记录');

count​

Future<DbCountResult> collection.count()
Future<DbCountResult> query.count()

统计匹配条件的文档数量。

参数

无参数

返回

Future
DbCountResult

示例

final res = await db
    .collection('todos')
    .where({'completed': false})
    .count();
print('未完成任务数量: ${res.total}');

update​

Future<DbUpdateResult> query.update(Map<String, dynamic> data)
Future<DbUpdateResult> doc.update(Map<String, dynamic> data, {bool returnDoc = false})

更新文档。在 Query 上调用为批量更新匹配条件的文档；在文档引用上调用为合并更新单个文档，returnDoc 为 true 时返回更新后的文档。

参数

data
Map<String, dynamic>

更新数据，可使用 db.command 更新指令（如 _.inc、_.set、_.push 等）

returnDoc
bool

仅文档引用 update 支持，为 true 时返回更新后的文档，默认 false

返回

Future
DbUpdateResult

示例

final _ = db.command;

final res = await db
    .collection('todos')
    .doc('doc-id')
    .update({'count': _.inc(1), 'completed': true}, returnDoc: true);
print('更新后的文档: ${res.doc}');

set​

Future<DbUpdateResult> doc.set(Map<String, dynamic> data)

设置文档数据（完全替换，文档不存在则创建）。

参数

data
Map<String, dynamic>

文档完整数据，将完全替换原文档

返回

Future
DbUpdateResult

示例

final res = await db.collection('todos').doc('doc-id').set({
  'title': '重置后的任务',
  'completed': false,
});

remove​

Future<DbRemoveResult> query.remove()
Future<DbRemoveResult> doc.remove()

删除文档。在 Query 上调用为批量删除匹配条件的文档；在文档引用上调用为删除单个文档。

参数

无参数

返回

Future
DbRemoveResult

示例

final res = await db.collection('todos').doc('doc-id').remove();
print('删除了 ${res.deleted} 条记录');

command​

DbCommand get db.command

获取查询/更新指令（对应 JS SDK 的 db.command，通常简写为 _）。支持比较、逻辑、字段/数组、更新、地理位置等操作符。

参数

无参数

返回

DbCommand
DbCommand

指令对象，用于构建查询条件与更新操作

示例

final _ = db.command;

// eq / neq / gt / gte / lt / lte / inList / nin
await db.collection('todos').where({'age': _.gte(18)}).get();

// and / or / not / nor
await db.collection('todos').where({
  'priority': _.or([_.eq('high'), _.eq('medium')]),
}).get();

aggregate​

Aggregate collection.aggregate()

获取聚合操作对象，链式添加聚合阶段后调用 end() 执行。支持 match、group、sort、project、limit、skip、unwind、lookup、addFields、count、sample、bucket、bucketAuto、geoNear、replaceRoot、sortByCount 以及自定义 stage。

参数

无参数

返回

Aggregate
Aggregate

聚合操作对象，链式添加阶段后调用 end() 执行

示例

final res = await db
    .collection('todos')
    .aggregate()
    .match({'completed': true})
    .group({
      '_id': '\$priority',
      'total': {'\$sum': 1},
    })
    .sort({'total': -1})
    .end();

print('聚合结果: ${res.data}');

startTransaction​

Future<Transaction> db.startTransaction()

开启事务，返回事务对象。通过事务对象的 collection 获取事务内的集合引用进行操作，最后调用 commit 提交或 rollback 回滚。

参数

无参数

返回

Future
Transaction

示例

final _ = db.command;

final transaction = await db.startTransaction();
try {
  await transaction.collection('accounts').doc('a').update({'balance': _.inc(-100)});
  await transaction.collection('accounts').doc('b').update({'balance': _.inc(100)});
  await transaction.commit();
} catch (e) {
  await transaction.rollback();
}

runCommands​

Future<DbRunCommandsResult> db.runCommands({required List<Map<String, dynamic>> commands, String? transactionId})

执行 MongoDB 风格数据库命令（批量），仅管理员可调用。

参数

commands
List<Map<String, dynamic>>

命令对象数组

transactionId
String?

事务 ID（可选，在事务中执行所有命令）

返回

Future
DbRunCommandsResult

示例

final res = await db.runCommands(commands: [
  {'find': 'todos', 'filter': {'completed': true}},
]);
print('执行结果: ${res.list}');

Geo​

GeoNamespace get db.Geo
DbRegExp db.RegExp({required String regexp, String? options})
DbServerDate db.serverDate({int offset = 0})

数据库辅助类型：地理位置命名空间 Geo、正则表达式 RegExp、服务端时间 serverDate。

  • Geo 支持 point、lineString、polygon、multiPoint、multiLineString、multiPolygon，配合指令 geoNear、geoWithin、geoIntersects 使用。
  • RegExp 用于模糊查询，options 如 i 表示忽略大小写。
  • serverDate 生成服务端时间，offset 为毫秒偏移量。

参数

无参数

返回

GeoNamespace
GeoNamespace

地理位置命名空间

示例

final _ = db.command;

// 查询距离指定坐标 5000 米内的记录
final res = await db.collection('places').where({
  'location': _.geoNear(
    geometry: db.Geo.point(116.397, 39.908),
    maxDistance: 5000,
  ),
}).get();

数据模型​

getById​

Future<ModelFindResponse> app.models.getById({required String modelName, required String recordId})

根据 ID 获取单条数据。

参数

modelName
String

数据模型标识

recordId
String

数据 ID

返回

Future
ModelFindResponse

示例

final result = await app.models.getById(
  modelName: 'user',
  recordId: '123',
);

if (result.isSuccess) {
  print('记录: ${result.record}');
} else {
  print('查询失败: ${result.message}');
}

get​

Future<ModelFindResponse> app.models.get({required String modelName, Map<String, dynamic>? filter, Map<String, dynamic>? select})

根据条件获取单条数据。

参数

modelName
String

数据模型标识

filter
Map<String, dynamic>?

筛选条件，格式：{'where': {'_id': {'\$eq': 'foobar'}}}

select
Map<String, dynamic>?

字段筛选，格式：{'\$master': true} 或 {'field': true}

返回

Future
ModelFindResponse

示例

final result = await app.models.get(
  modelName: 'user',
  filter: {'where': {'_id': {'\$eq': '123'}}},
  select: {'\$master': true},
);

if (result.isSuccess) {
  print('记录: ${result.record}');
} else {
  print('查询失败: ${result.message}');
}

list​

Future<ModelFindManyResponse> app.models.list({
  required String modelName,
  Map<String, dynamic>? filter,
  Map<String, dynamic>? select,
  int? pageSize,
  int? pageNumber,
  bool? getCount,
  List<Map<String, String>>? orderBy,
})

查询多条数据。支持筛选条件、字段筛选、分页和排序。

参数

modelName
String

数据模型标识

filter
Map<String, dynamic>?

筛选条件，格式：{'where': {'field': {'\$eq': 'value'}}}

select
Map<String, dynamic>?

字段筛选，格式：{'\$master': true} 或 {'field': true}

pageSize
int?

分页大小，默认 10

pageNumber
int?

分页页码，默认 1

getCount
bool?

是否返回总数

orderBy
List<Map<String, String>>?

排序，最多 3 个字段，格式：[{'field': 'desc'}]

返回

Future
ModelFindManyResponse

示例

final result = await app.models.list(
  modelName: 'user',
  pageSize: 10,
  pageNumber: 1,
  getCount: true,
  orderBy: [{'createdAt': 'desc'}],
  filter: {'where': {'age': {'\$gt': 18}}},
);

if (result.isSuccess) {
  print('总数: ${result.total}');
  for (final record in result.records) {
    print('记录: $record');
  }
}

listSimple​

Future<ModelFindManyResponse> app.models.listSimple({required String modelName, int? pageSize, int? pageNumber, bool? getCount})

简单查询多条数据（GET 请求，仅支持分页参数）。

参数

modelName
String

数据模型标识

pageSize
int?

分页大小

pageNumber
int?

分页页码，默认 1

getCount
bool?

是否返回总数，默认 false

返回

Future
ModelFindManyResponse

示例

final result = await app.models.listSimple(
  modelName: 'user',
  pageSize: 10,
  pageNumber: 1,
  getCount: true,
);

if (result.isSuccess) {
  print('总数: ${result.total}');
  for (final record in result.records) {
    print('记录: $record');
  }
}

create​

Future<ModelCreateResponse> app.models.create({required String modelName, required Map<String, dynamic> data})

创建单条数据。

参数

modelName
String

数据模型标识

data
Map<String, dynamic>

数据内容

返回

Future
ModelCreateResponse

示例

final result = await app.models.create(
  modelName: 'user',
  data: {'name': '张三', 'age': 25, 'email': 'test@example.com'},
);

if (result.isSuccess) {
  print('创建成功，ID: ${result.id}');
} else {
  print('创建失败: ${result.message}');
}

createMany​

Future<ModelCreateManyResponse> app.models.createMany({required String modelName, required List<Map<String, dynamic>> data})

批量创建数据。

参数

modelName
String

数据模型标识

data
List<Map<String, dynamic>>

批量数据列表

返回

Future
ModelCreateManyResponse

示例

final result = await app.models.createMany(
  modelName: 'user',
  data: [
    {'name': '张三', 'age': 25},
    {'name': '李四', 'age': 30},
  ],
);

if (result.isSuccess) {
  print('批量创建成功，ID 列表: ${result.idList}');
}

update​

Future<ModelUpdateDeleteResponse> app.models.update({required String modelName, required Map<String, dynamic> filter, required Map<String, dynamic> data})

更新单条数据。

参数

modelName
String

数据模型标识

filter
Map<String, dynamic>

筛选条件

data
Map<String, dynamic>

更新数据

返回

Future
ModelUpdateDeleteResponse

示例

final result = await app.models.update(
  modelName: 'user',
  filter: {'where': {'_id': {'\$eq': '123'}}},
  data: {'age': 26},
);

if (result.isSuccess) {
  print('更新成功，变更 ${result.count} 条');
}

updateMany​

Future<ModelUpdateDeleteManyResponse> app.models.updateMany({required String modelName, required Map<String, dynamic> filter, required Map<String, dynamic> data})

批量更新数据。

参数

modelName
String

数据模型标识

filter
Map<String, dynamic>

筛选条件

data
Map<String, dynamic>

更新数据

返回

Future
ModelUpdateDeleteManyResponse

示例

final result = await app.models.updateMany(
  modelName: 'user',
  filter: {'where': {'age': {'\$lt': 18}}},
  data: {'status': 'minor'},
);

if (result.isSuccess) {
  print('批量更新成功，变更 ${result.count} 条');
}

upsert​

Future<ModelUpsertResponse> app.models.upsert({required String modelName, required Map<String, dynamic> filter, Map<String, dynamic>? create, Map<String, dynamic>? update})

创建或更新单条数据（Upsert）。如果匹配到已有记录则更新，否则创建新记录。

参数

modelName
String

数据模型标识

filter
Map<String, dynamic>

筛选条件

create
Map<String, dynamic>?

不存在时创建的数据内容

update
Map<String, dynamic>?

已存在时更新的数据内容

返回

Future
ModelUpsertResponse

示例

final result = await app.models.upsert(
  modelName: 'user',
  filter: {'where': {'email': {'\$eq': 'test@example.com'}}},
  create: {'name': '张三', 'email': 'test@example.com', 'age': 25},
  update: {'age': 26},
);

if (result.isSuccess) {
  print('Upsert 成功，变更 ${result.count} 条');
  if (result.id != null) {
    print('新创建记录 ID: ${result.id}');
  }
}

deleteById​

Future<ModelUpdateDeleteResponse> app.models.deleteById({required String modelName, required String recordId})

根据 ID 删除单条数据。

参数

modelName
String

数据模型标识

recordId
String

数据 ID

返回

Future
ModelUpdateDeleteResponse

示例

final result = await app.models.deleteById(
  modelName: 'user',
  recordId: '123',
);

if (result.isSuccess) {
  print('删除成功，变更 ${result.count} 条');
}

deleteRecord​

Future<ModelUpdateDeleteResponse> app.models.deleteRecord({required String modelName, required Map<String, dynamic> filter})

根据条件删除单条数据。

参数

modelName
String

数据模型标识

filter
Map<String, dynamic>

筛选条件

返回

Future
ModelUpdateDeleteResponse

示例

final result = await app.models.deleteRecord(
  modelName: 'user',
  filter: {'where': {'_id': {'\$eq': '123'}}},
);

if (result.isSuccess) {
  print('删除成功，变更 ${result.count} 条');
}

deleteMany​

Future<ModelUpdateDeleteManyResponse> app.models.deleteMany({required String modelName, required Map<String, dynamic> filter})

批量删除数据。

参数

modelName
String

数据模型标识

filter
Map<String, dynamic>

筛选条件

返回

Future
ModelUpdateDeleteManyResponse

示例

final result = await app.models.deleteMany(
  modelName: 'user',
  filter: {'where': {'status': {'\$eq': 'inactive'}}},
);

if (result.isSuccess) {
  print('批量删除成功，变更 ${result.count} 条');
}

mysqlCommand​

Future<ModelMysqlCommandResponse> app.models.mysqlCommand({required String sqlTemplate, List<ModelMysqlParameter>? parameter, ModelMysqlConfig? config})

执行 MySQL 命令。支持参数化查询。

参数

sqlTemplate
String

SQL 语句，支持参数占位符 {{ var }}

parameter
List<ModelMysqlParameter>?

SQL 参数列表

config
ModelMysqlConfig?

执行配置（timeout、preparedStatements、dbLinkName）

返回

Future
ModelMysqlCommandResponse

示例

final result = await app.models.mysqlCommand(
  sqlTemplate: 'select * from `users` where _id = {{ _id }}',
  parameter: [
    ModelMysqlParameter(key: '_id', type: 'STRING', value: '123'),
  ],
);

if (result.isSuccess) {
  print('执行结果: ${result.executeResultList}');
}

数据源查询​

getAggregateDataSourceList​

Future<AggregateDataSourceListResponse> app.models.getAggregateDataSourceList({
  required int pageSize,
  String? envId,
  int? pageIndex,
  int? queryAll,
  List<String>? dataSourceIds,
  List<String>? dataSourceNames,
  String? dataSourceType,
  List<String>? viewIds,
  List<String>? appIds,
  int? appLinkStatus,
  int? queryBindToApp,
  int? queryConnector,
  List<String>? channelList,
  bool? queryDataSourceRelationList,
  String? dbInstanceType,
  List<String>? databaseTableNames,
  bool? querySystemModel,
})

根据条件查询数据源聚合列表。envId 可选，默认使用初始化时的环境 ID。

参数

pageSize
int

每页条数

envId
String?

环境 ID（可选，默认使用初始化时的 env）

pageIndex
int?

页码

queryAll
int?

是否查询全部（0 或 1）

dataSourceIds
List<String>?

数据源 ID 列表

dataSourceNames
List<String>?

数据源名称列表

dataSourceType
String?

数据源类型

queryBindToApp
int?

是否查询绑定到应用的数据源（0 或 1）

queryConnector
int?

是否查询连接器（0 或 1）

querySystemModel
bool?

是否查询系统模型

返回

Future
AggregateDataSourceListResponse

示例

final result = await app.models.getAggregateDataSourceList(
  pageSize: 10,
  pageIndex: 0,
);

if (result.isSuccess) {
  print('总数: ${result.count}');
  for (final ds in result.rows) {
    print('${ds.name}: ${ds.title} (type: ${ds.type})');
  }
}

getDataSourceAggregateDetail​

Future<DataSourceAggregateDetailResponse> app.models.getDataSourceAggregateDetail({
  String? datasourceId,
  String? dataSourceName,
  String? viewId,
  int? queryPublish,
  bool? queryModelRelation,
  String? dbInstanceType,
  String? databaseTableName,
})

根据条件查询数据源聚合详情。datasourceId 和 dataSourceName 不能都为空。

参数

datasourceId
String?

数据源 ID（与 dataSourceName 不能都为空）

dataSourceName
String?

数据源名称（与 datasourceId 不能都为空）

viewId
String?

视图 ID

queryPublish
int?

查询发布数据源（0 体验, 1 发布）

queryModelRelation
bool?

是否查询关联关系

dbInstanceType
String?

实例 DB 类型

databaseTableName
String?

数据库表名

返回

Future
DataSourceAggregateDetailResponse

示例

final result = await app.models.getDataSourceAggregateDetail(
  dataSourceName: 'user',
);

if (result.isSuccess) {
  print('Schema: ${result.dataSource?.schema}');
  print('名称: ${result.dataSource?.title}');
}

getDataSourceByTableName​

Future<DataSourceByTableNameResponse> app.models.getDataSourceByTableName({required List<String> tableNames})

根据数据库表名称查询数据源 Schema 定义。

参数

tableNames
List<String>

数据表名称列表

返回

Future
DataSourceByTableNameResponse

示例

final result = await app.models.getDataSourceByTableName(
  tableNames: ['user_table', 'order_table'],
);

if (result.isSuccess) {
  for (final info in result.dataSourceTableInfos) {
    print('表: ${info.tableName}, 数据源: ${info.name}');
  }
}

getBasicDataSourceList​

Future<BasicDataSourceListResponse> app.models.getBasicDataSourceList({
  List<String>? idList,
  List<String>? nameList,
  int? pageNum,
  int? pageSize,
  bool? queryAll,
  List<DataSourceQueryFilter>? queryFilterList,
  bool? onlyFlexDb,
})

根据条件查询基础数据源信息列表（POST 请求，支持过滤条件）。

参数

idList
List<String>?

数据源 ID 列表

nameList
List<String>?

数据源标识列表

pageNum
int?

页码，默认 1

pageSize
int?

每页条数，默认 10

queryAll
bool?

是否查询全部

queryFilterList
List<DataSourceQueryFilter>?

查询过滤条件列表

onlyFlexDb
bool?

是否仅查询 flexdb 类型

返回

Future
BasicDataSourceListResponse

示例

final result = await app.models.getBasicDataSourceList(
  pageSize: 10,
  pageNum: 1,
  queryFilterList: [
    DataSourceQueryFilter(name: 'Type', values: ['database']),
  ],
);

if (result.isSuccess) {
  print('总数: ${result.total}');
  for (final ds in result.dataSourceList) {
    print('${ds.name}: ${ds.title}');
  }
}

getBasicDataSource​

Future<BasicDataSourceResponse> app.models.getBasicDataSource({
  String? datasourceId,
  String? dataSourceName,
  String? viewId,
  int? queryPublish,
  bool? queryModelRelation,
  String? dbInstanceType,
  String? databaseTableName,
})

根据条件查询基础数据源信息。datasourceId 和 dataSourceName 不能都为空。

参数

datasourceId
String?

数据源 ID（与 dataSourceName 不能都为空）

dataSourceName
String?

数据源名称（与 datasourceId 不能都为空）

viewId
String?

视图 ID

queryPublish
int?

查询发布数据源（0 体验, 1 发布）

queryModelRelation
bool?

是否查询关联关系

dbInstanceType
String?

实例 DB 类型

databaseTableName
String?

数据库表名

返回

Future
BasicDataSourceResponse

示例

final result = await app.models.getBasicDataSource(
  dataSourceName: 'user',
);

if (result.isSuccess) {
  print('数据源: ${result.dataSource?.name}');
  print('类型: ${result.dataSource?.type}');
}

getSchemaList​

Future<DataSourceSchemaListResponse> app.models.getSchemaList({List<String>? dataSourceNameList})

查询环境下所有数据源 Schema。不传参数则查询全部。

参数

dataSourceNameList
List<String>?

数据源名称列表（可选，不传则查询全部）

返回

Future
DataSourceSchemaListResponse

示例

final result = await app.models.getSchemaList(
  dataSourceNameList: ['user', 'order'],
);

if (result.isSuccess) {
  for (final rel in result.dataSourceRelationInfoList) {
    print('${rel.name}: ${rel.title}');
  }
}

getTableName​

Future<DataSourceTableNameResponse> app.models.getTableName({String? dataSourceName})

根据数据源名称查询对应的数据库表名称。

参数

dataSourceName
String?

数据源名称

返回

Future
DataSourceTableNameResponse

示例

final result = await app.models.getTableName(
  dataSourceName: 'user',
);

if (result.isSuccess) {
  print('表名: ${result.tableName}');
  print('数据库类型: ${result.dbType}');
}

MySQL 数据库​

query​

Future<MySqlResponse> app.mysql.query({required String table, String? schema, String? instance, MySqlQueryOptions? options})

查询 MySQL 数据。支持字段筛选、分页、排序和条件过滤。

支持的过滤运算符：eq（等于）、neq（不等于）、gt（大于）、gte（大于等于）、lt（小于）、lte（小于等于）、like（模糊匹配）、in（在列表中）、is（判断 null）

参数

table
String

表名

schema
String?

数据库名

instance
String?

数据库实例标识（需搭配 schema）

options
MySqlQueryOptions?

查询选项

返回

Future
MySqlResponse

示例

final result = await app.mysql.query(
  table: 'users',
  options: MySqlQueryOptions(
    select: '*',
    limit: 10,
    offset: 0,
    order: 'id.asc',
    withCount: true,
  ),
);

if (result.isSuccess) {
  print('总数: ${result.total}');
  for (final row in result.data) {
    print('记录: $row');
  }
}

insert​

Future<MySqlWriteResponse> app.mysql.insert({required String table, required dynamic data, String? schema, String? instance, bool upsert, String? onConflict})

插入数据。支持单条和批量插入，以及 Upsert 模式。

参数

table
String

表名

data
dynamic

插入数据，单条 Map 或批量 List<Map>

schema
String?

数据库名

instance
String?

数据库实例标识（需搭配 schema）

upsert
bool

是否开启 Upsert 模式（默认 false）

onConflict
String?

Upsert 冲突字段

返回

Future
MySqlWriteResponse

示例

final result = await app.mysql.insert(
  table: 'users',
  data: {'name': '张三', 'age': 25},
);

if (result.isSuccess) {
  print('插入成功');
}

update (MySQL)​

Future<MySqlWriteResponse> app.mysql.update({required String table, required Map<String, dynamic> data, required Map<String, String> filters, String? schema, String? instance})

更新 MySQL 数据。必须提供 WHERE 条件。

参数

table
String

表名

data
Map<String, dynamic>

要更新的数据

filters
Map<String, String>

WHERE 条件（不能为空）

返回

Future
MySqlWriteResponse

示例

final result = await app.mysql.update(
  table: 'users',
  data: {'age': 26},
  filters: {'name': 'eq.张三'},
);

if (result.isSuccess) {
  print('更新成功');
} else {
  print('更新失败: ${result.message}');
}

delete (MySQL)​

Future<MySqlWriteResponse> app.mysql.delete({required String table, required Map<String, String> filters, String? schema, String? instance})

删除 MySQL 数据。必须提供 WHERE 条件。

参数

table
String

表名

filters
Map<String, String>

WHERE 条件（不能为空）

返回

Future
MySqlWriteResponse

示例

final result = await app.mysql.delete(
  table: 'users',
  filters: {'name': 'eq.张三'},
);

if (result.isSuccess) {
  print('删除成功');
}

count​

Future<MySqlCountResponse> app.mysql.count({required String table, Map<String, String>? filters, String? schema, String? instance})

统计 MySQL 数据数量。

参数

table
String

表名

filters
Map<String, String>?

筛选条件

返回

Future
MySqlCountResponse

示例

final result = await app.mysql.count(
  table: 'users',
  filters: {'age': 'gt.18'},
);

if (result.isSuccess) {
  print('符合条件的数据量: ${result.count}');
} else {
  print('统计失败: ${result.message}');
}

云函数​

callFunction​

Future<FunctionResponse> app.callFunction({
  required String name,
  FunctionType type,
  Map<String, dynamic>? data,
  HttpMethod method,
  String path,
  Map<String, String>? header,
  bool parse,
})

调用云函数。支持基础云函数和函数型云托管两种类型的统一调用。

参数

name
String

函数/服务名称

type
FunctionType

调用类型：FunctionType.function（默认）/ FunctionType.cloudrun

data
Map<String, dynamic>?

请求数据

method
HttpMethod

HTTP 方法（仅 cloudrun 类型有效，默认 POST）

path
String

HTTP 路径（仅 cloudrun 类型有效，默认 /）

header
Map<String, String>?

HTTP 请求头（仅 cloudrun 类型有效）

parse
bool

是否解析返回对象（仅 function 类型有效，默认 true）

返回

Future
FunctionResponse

示例

final result = await app.callFunction(
  name: 'myFunction',
  data: {'action': 'getUserList', 'pageSize': 10},
);

if (result.isSuccess) {
  print('执行结果: ${result.result}');
} else {
  print('执行失败: ${result.message}');
}

云托管​

callContainer​

Future<CloudRunResponse> app.callContainer({
  required String name,
  HttpMethod method,
  String path,
  Map<String, String>? header,
  Map<String, dynamic>? data,
})

调用云托管容器服务。支持自定义 HTTP 方法、路径和请求头。

参数

name
String

云托管服务名

method
HttpMethod

HTTP 请求方法（默认 GET）

path
String

HTTP 请求路径（默认 /）

header
Map<String, String>?

HTTP 请求头

data
Map<String, dynamic>?

HTTP 请求体

返回

Future
CloudRunResponse

示例

final result = await app.callContainer(
  name: 'my-service',
  method: HttpMethod.post,
  path: '/api/data',
  data: {'key': 'value'},
  header: {'X-Custom': 'header'},
);

if (result.isSuccess) {
  print('响应数据: ${result.result}');
} else {
  print('请求失败: ${result.message}');
}

APIs​

apis[name]​

ApiMethodProxy app.apis[String apiName]

调用 API 网关接口。支持通过下标运算符获取 API 代理对象，进行链式调用。支持 GET、POST、PUT、DELETE、HEAD、OPTIONS、PATCH 方法。

参数

apiName
String

API 名称

返回

ApiMethodProxy
ApiMethodProxy

API 方法代理对象，支持链式调用

ApiResponse
ApiResponse

API 响应

示例

// POST 请求
final result = await app.apis['myApi'].post(
  path: '/users',
  body: {'name': '张三', 'age': 25},
);

if (result.isSuccess) {
  print('响应数据: ${result.data}');
}

// GET 请求
final getResult = await app.apis['myApi'].get(path: '/users/123');

// PUT 请求
final putResult = await app.apis['myApi'].put(
  path: '/users/123',
  body: {'name': '李四'},
);

// DELETE 请求
final deleteResult = await app.apis['myApi'].delete(path: '/users/123');

云存储​

云存储模块提供文件上传、下载、删除、复制、移动等操作。

初始化​

final app = await CloudBase.init(
  env: 'your-env-id',
  accessKey: 'your-access-key',
);

final storage = app.storage.from();

upload​

Future<StorageResponse<StorageUploadResult>> storage.upload(
  String path,
  List<int> fileData, {
  StorageUploadOptions? options,
})

上传文件到云存储。该方法会先获取上传信息，再上传文件到 COS，最后返回 fileID。

参数

path
String

云存储相对路径，如 `images/photo.jpg`。

fileData
List<int>

文件字节数据。

options
StorageUploadOptions

上传选项。

返回

data
Object

返回数据

error
StorageError?

错误信息。

示例

import 'package:cloudbase_flutter/cloudbase_flutter.dart';
import 'package:image_picker/image_picker.dart';

final app = await CloudBase.init(
  env: 'your-env-id',
  accessKey: 'your-access-key',
);

final storage = app.storage.from();

// 选择图片并上传
Future<void> uploadImage() async {
  final picker = ImagePicker();
  final XFile? image = await picker.pickImage(source: ImageSource.gallery);

  if (image == null) return;

  final fileBytes = await image.readAsBytes();

  final result = await storage.upload(
    'images/${image.name}',
    fileBytes,
    options: StorageUploadOptions(
      contentType: 'image/jpeg',
      cacheControl: 'max-age=3600',
    ),
  );

  if (result.isSuccess) {
    print('上传成功: ${result.data?.id}');
    print('文件路径: ${result.data?.path}');
  } else {
    print('上传失败: ${result.error?.message}');
  }
}

getUploadInfo​

Future<StorageResponse<List<StorageUploadInfo>>> storage.getUploadInfo(
  List<String> paths,
)

获取文件上传信息。返回上传 URL 等信息，用于客户端直接上传文件到 COS。

参数

paths
List<String>

文件路径列表（云存储相对路径）。

返回

data
List<StorageUploadInfo>?

上传信息列表。

error
StorageError?

错误信息。

示例

final result = await storage.getUploadInfo([
  'images/photo.jpg',
  'documents/report.pdf',
]);

if (result.isSuccess) {
  for (final info in result.data!) {
    print('路径: ${info.path}');
    print('上传链接: ${info.uploadUrl}');
    print('文件ID: ${info.fileId}');
  }
}

getDownloadUrls​

Future<StorageResponse<List<StorageDownloadInfo>>> storage.getDownloadUrls(
  List<String> fileIds, {
  int? expiresIn,
})

获取文件下载链接。

参数

fileIds
List<String>

文件 ID 列表（完整 cloudObjectId，如 `cloud://envId.xxx/path/file.jpg`）。

expiresIn
int?

预留参数，当前 API 不支持自定义过期时间。

返回

data
List<StorageDownloadInfo>?

下载信息列表。

error
StorageError?

错误信息。

示例

final result = await storage.getDownloadUrls([
  'cloud://envId.xxx/images/photo.jpg',
  'cloud://envId.xxx/documents/report.pdf',
]);

if (result.isSuccess) {
  for (final info in result.data!) {
    if (info.isSuccess) {
      print('下载链接: ${info.downloadUrl}');
    } else {
      print('获取失败: ${info.message}');
    }
  }
}

createSignedUrl​

Future<StorageResponse<String>> storage.createSignedUrl(
  String fileId,
  int expiresIn,
)

创建签名 URL（临时访问链接）。

参数

fileId
String

完整 fileID。

expiresIn
int

有效期（秒）。

返回

data
String?

签名 URL。

error
StorageError?

错误信息。

示例

final result = await storage.createSignedUrl(
  'cloud://envId.xxx/images/photo.jpg',
  3600, // 1小时有效期
);

if (result.isSuccess) {
  print('签名 URL: ${result.data}');
}

createSignedUrls​

Future<StorageResponse<List<StorageDownloadInfo>>> storage.createSignedUrls(
  List<String> fileIds,
  int expiresIn,
)

批量创建签名 URL。

参数

fileIds
List<String>

完整 fileID 列表。

expiresIn
int

有效期（秒）。

返回

data
List<StorageDownloadInfo>?

下载信息列表。

error
StorageError?

错误信息。

示例

final result = await storage.createSignedUrls(
  [
    'cloud://envId.xxx/images/photo1.jpg',
    'cloud://envId.xxx/images/photo2.jpg',
  ],
  3600,
);

if (result.isSuccess) {
  for (final info in result.data!) {
    print('${info.fileId}: ${info.downloadUrl}');
  }
}

remove​

Future<StorageResponse<List<StorageDeleteResult>>> storage.remove(
  List<String> fileIds,
)

删除文件。

参数

fileIds
List<String>

要删除的文件 ID 列表（完整 fileID）。

返回

data
List<StorageDeleteResult>?

删除结果列表。

error
StorageError?

错误信息。

示例

final result = await storage.remove([
  'cloud://envId.xxx/images/photo.jpg',
  'cloud://envId.xxx/documents/report.pdf',
]);

if (result.isSuccess) {
  for (final item in result.data!) {
    if (item.isSuccess) {
      print('删除成功: ${item.fileId}');
    } else {
      print('删除失败: ${item.fileId} - ${item.message}');
    }
  }
}

copy​

Future<StorageResponse<StorageCopyResult>> storage.copy(
  String fromPath,
  String toPath, {
  bool overwrite = true,
})

复制文件。

参数

fromPath
String

源文件路径（相对路径）。

toPath
String

目标文件路径（相对路径）。

overwrite
bool

目标已存在时是否覆盖，默认 `true`。

返回

data
StorageCopyResult?

复制结果。

error
StorageError?

错误信息。

示例

final result = await storage.copy(
  'images/photo.jpg',
  'images/backup/photo.jpg',
);

if (result.isSuccess) {
  print('复制成功: ${result.data?.cloudObjectId}');
} else {
  print('复制失败: ${result.error?.message}');
}

copyBatch​

Future<StorageResponse<List<StorageCopyResult>>> storage.copyBatch(
  List<Map<String, dynamic>> items,
)

批量复制文件。

参数

items
List<Map<String, dynamic>>

复制项列表，每项包含 `srcPath` 和 `dstPath`。

返回

data
List<StorageCopyResult>?

复制结果列表。

error
StorageError?

错误信息。

示例

final result = await storage.copyBatch([
  {'srcPath': 'images/photo1.jpg', 'dstPath': 'backup/photo1.jpg'},
  {'srcPath': 'images/photo2.jpg', 'dstPath': 'backup/photo2.jpg'},
]);

if (result.isSuccess) {
  for (final item in result.data!) {
    if (item.isSuccess) {
      print('复制成功: ${item.cloudObjectId}');
    }
  }
}

move​

Future<StorageResponse<StorageCopyResult>> storage.move(
  String fromPath,
  String toPath, {
  bool overwrite = true,
})

移动文件（通过 copy + removeOriginal 实现）。

参数

fromPath
String

源文件路径（相对路径）。

toPath
String

目标文件路径（相对路径）。

overwrite
bool

目标已存在时是否覆盖，默认 `true`。

返回

data
StorageCopyResult?

移动结果。

error
StorageError?

错误信息。

示例

final result = await storage.move(
  'images/old.jpg',
  'images/new.jpg',
);

if (result.isSuccess) {
  print('移动成功: ${result.data?.cloudObjectId}');
} else {
  print('移动失败: ${result.error?.message}');
}

存储相关类型​

StorageUploadOptions​

上传选项：

参数类型说明
cacheControlString?缓存控制，如 max-age=3600
contentTypeString?文件 MIME 类型，如 image/jpeg
metadataMap<String, dynamic>?自定义元数据
upsertbool是否覆盖已存在的文件，默认 true

StorageUploadResult​

上传结果：

参数类型说明
idString?CloudBase fileID
pathString?上传路径
fullPathString?文件完整路径

StorageUploadInfo​

上传信息：

参数类型说明
pathString?文件路径
uploadUrlString?上传链接
tokenString?上传 token
authorizationString?上传鉴权
fileIdString?文件 ID
cosFileIdString?COS 文件 ID
codeString?错误码
messageString?错误信息

StorageDownloadInfo​

下载信息：

参数类型说明
fileIdString?文件 ID
downloadUrlString?下载链接
codeString?错误码（部分失败时）
messageString?错误信息（部分失败时）

StorageDeleteResult​

删除结果：

参数类型说明
fileIdString?文件 ID
codeString?错误码（部分失败时）
messageString?错误信息（部分失败时）

StorageCopyResult​

复制结果：

参数类型说明
cloudObjectIdString?复制后对象的云端文件 ID
codeString?错误码（部分失败时）
messageString?错误信息（部分失败时）

StorageResponse<T>​

存储响应：

参数类型说明
dataT?响应数据
errorStorageError?错误信息

StorageError​

存储错误：

参数类型说明
codeString?错误码
messageString?错误信息
requestIdString?请求 ID

更新日志​

1.2.2 (2026-08-31)​

  • 修复 signInWithIdToken 向登录接口发送 provider_token 而非 provider_id / provider_id_token 的问题

1.2.1 (2026-08-18)​

  • 修复 HTTP 拦截器在未登录认证接口（刷新 Token /auth/v1/token、匿名登录 /auth/v1/signin/anonymously）上附带过期 AccessToken，导致网关拒绝刷新与重新登录的问题
  • 公开认证接口（登录/注册、OTP、OAuth 换票、图形验证码、revoke 等）不再自动附加 Authorization；受保护接口（如 /auth/v1/user/me）仍会发送会话 Token

1.2.0 (2026-07-24)​

  • 新增文档型数据库模块（CloudBaseDatabase），提供与 JS SDK 一致的链式调用 API
    • db.collection().doc() 文档引用
    • 链式查询：where / orderBy / limit / skip / field
    • 增删改查：add（单条与批量）、get、count、update、set、remove
    • 通过 db.command 使用查询/更新指令：比较（eq/gt/gte/lt/lte/neq/in/nin）、逻辑（and/or/not/nor）、更新操作符（set/inc/mul/remove/push/pull/pop/shift/unshift/addToSet/rename/max/min）
    • 通过 collection().aggregate()...end() 使用聚合管道
    • 通过 db.startTransaction() 使用事务，支持 commit / rollback
    • 地理位置类型（GeoPoint/GeoLineString/GeoPolygon/GeoMultiPoint/GeoMultiLineString/GeoMultiPolygon）及地理位置查询
    • RegExp、serverDate 辅助方法，以及自动 EJSON 编解码（如 DateTime）
    • 通过 runCommands 执行 MongoDB 风格命令

1.1.0 (2026-07-01)​

  • 新增云存储模块（CloudBaseStorage）
    • 上传文件到云存储，返回上传信息并支持直传 COS
    • 获取带签名的下载链接（单个与批量）
    • 删除文件（批量）
    • 复制文件（单个与批量）
    • 移动/重命名文件
    • 获取用于客户端直传的上传信息

1.0.9 (2026-06-30)​

  • 为所有 HTTP 请求新增 X-SDK-Version 请求头（@cloudbase/flutter-sdk/<version>），用于平台标识
  • 新增版本管理工具（tool/update_version.dart），可从 pubspec.yaml 自动同步版本号
  • 新增 CONTRIBUTING.md，补充发布流程文档
  • 优化 HTTP 客户端以支持 List 类型请求体（用于存储相关 API）

1.0.8 (2026-05-06)​

  • 修复 UserProfile.toUser() 在 email 为 null 时错误回退到 username（手机号）的问题，该问题会导致重新认证时向服务端发送格式非法的 email
  • 修复 reauthenticate() 未正确区分空字符串与合法 email 的问题，确保仅有手机号的用户使用手机号进行验证，而非非法 email

1.0.7 (2026-03-11)​

  • signInWithOtp 新增 shouldCreateUser 选项，当用户不存在时可自动注册
  • 将内部注册逻辑重构为可复用的 _signUpAndSaveSession 方法

1.0.6 (2026-03-05)​

  • 新增 MySQL 模块（CloudBaseMySQL）
    • 直接执行 SQL 查询
    • 事务支持（begin、commit、rollback）
    • 数据库/表管理操作
  • 新增 MySQL 模块的示例代码
  • 新增 MySQL 模块的单元测试

1.0.5 (2026-03-05)​

  • 新增数据模型模块（CloudBaseDataModel）
    • 支持 filter、select、orderBy、expand 的增删改查操作
    • 批量创建/更新/删除操作
    • Upsert 支持
    • 原生 MySQL 命令执行
    • 数据源查询 API（聚合列表、详情、Schema、表名）
  • 重构 HTTP 客户端，支持 token 自动刷新并完善文档
  • 新增数据模型的示例代码
  • 新增数据模型的单元测试

1.0.4 (2026-01-16)​

  • 新增示例代码

1.0.3 (2026-01-16)​

  • 更新 README 文档

1.0.2 (2026-01-15)​

  • 修复 HTTP 客户端未正确处理空 token 字符串的问题

1.0.1 (2026-01-15)​

  • 完善 README 文档，补充完整的认证 API 用法

1.0.0 (2026-01-15)​

  • 首次发布
  • 认证模块（CloudBaseAuth）
    • 邮箱/手机号注册与登录
    • 密码登录
    • OTP 验证码登录
    • OAuth 第三方登录
    • IdToken 登录
    • 自定义票据登录
    • 匿名登录
    • 会话管理（获取、刷新、设置）
    • 用户信息管理
    • 身份源绑定/解绑
    • 密码重置
  • 云函数模块（CloudBaseFunctions）
    • 基础云函数调用
    • 函数型云托管调用
  • 云托管模块（CloudBaseCloudRun）
    • 支持 HTTP 方法（GET/POST/PUT/DELETE）
    • 自定义请求头
  • API 网关模块（CloudBaseApis）
    • 链式调用
    • 支持多种 HTTP 方法
  • 验证码模块（CloudBaseCaptcha）
    • 图形验证码
    • 自定义验证码处理器
    • 内置验证码弹窗