Bmob database flutter

Bmob Database — Flutter / Dart SDK

官方 Flutter 插件 bmob_plugin（源码 bmob-flutter-sdk/data_plugin）。数据模型 继承 BmobObject + JSON 序列化（与 Android 类似），查询用泛型 BmobQuery<T>，异步返回 Future + .then / .catchError。

完整 API 以 BmobDocs Flutter 文档 为准；agent 可直接 WebFetch metadata.docs_raw。

核心原则

1. 安装与引用

flutter pub add bmob_plugin

import 'package:bmob_plugin/bmob_plugin.dart';

2. 初始化 — 控制台 → 设置 → 应用密钥 → Secret Key、API 安全码；不要在客户端填 masterKey（第三个可选参数仅服务端场景）。

// main() 或 App 启动最早处
Bmob.initialize(secretKey, apiSafe);
// 不推荐：Bmob.initialize(secretKey, apiSafe, masterKey);

3. 上线换备案域名 — resetDomain 必须在 initialize 之前（开发期内置测试域名有请求次数限制）：

Bmob.resetDomain("http://api.yourdomain.com");
Bmob.initialize(secretKey, apiSafe);

4. 自定义表模型 — 每张业务表一个 Dart 类 extends BmobObject，并实现 fromJson / toJson（见 references/model-and-init.md）。表名默认与类名一致（如 Blog → 表 Blog）。

5. 错误处理 — 统一用 BmobError.convert(e) 取 code / error：

}).catchError((e) {
  final err = BmobError.convert(e);
  print('${err.code}: ${err.error}');
});

6. 保留字段 — objectId、createdAt、updatedAt、ACL 由 SDK / 服务端维护；业务代码在更新 / 删除时必须设置 objectId。

安全清单

• 客户端不要传 Master Key 给 Bmob.initialize 第三参数。
• Secret Key / API 安全码 用 --dart-define、.env + flutter_dotenv 或 CI 注入，不要 commit 进 git。
• release 前 resetDomain 为备案域名，且顺序在 initialize 之前。
• 写入的表必须配 ACL（blog.setAcl(bmobAcl)），否则任意用户可改任意行。
• Android 文件上传 / 下载 需先适配存储权限（见官方文档「文件操作」）。
• 实时监听 RealTimeDataManager 回调里 data.data 是 Map，不要直接当 Blog 用。

常见问题

跨平台 Q&A：shared/faq.md（含 Flutter 路由说明）。

反模式

见 shared/anti-patterns.md。本端重点：客户端勿传 masterKey；实时回调勿直接把 Map 当 model。

单条 CRUD（以 Blog 为例）

class Blog extends BmobObject {
  String? title;
  String? content;
  int? like;
  BmobUser? author;

  Blog();

  Blog.fromJson(Map<String, dynamic> json) {
    objectId = json['objectId'];
    title = json['title'];
    content = json['content'];
    like = json['like'];
    if (json['author'] != null) {
      author = BmobUser()..objectId = json['author']['objectId'];
    }
  }

  Map<String, dynamic> toJson() => {
        'title': title,
        'content': content,
        'like': like,
        if (author != null) 'author': author,
      };
}

新增

final blog = Blog()
  ..title = '博客标题'
  ..content = '博客内容'
  ..like = 77;

blog.save().then((BmobSaved saved) {
  print(saved.objectId);
}).catchError((e) => print(BmobError.convert(e).error));

查询单条（含 Pointer include）

final q = BmobQuery<Blog>();
q.setInclude('author');
q.queryObject(objectId).then((data) {
  final blog = Blog.fromJson(data);
  print(blog.title);
}).catchError((e) => print(BmobError.convert(e).error));

更新

final blog = Blog()
  ..objectId = objectId
  ..title = '修改标题';
blog.update().then((BmobUpdated u) => print(u.updatedAt));

删除

Blog()..objectId = objectId
  ..delete()
  .then((BmobHandled h) => print(h.msg));

删除某字段值

Blog()..objectId = objectId
  ..deleteFieldValue('content')
  .then((BmobUpdated u) => print(u.updatedAt));

条件查询与分页

final q = BmobQuery<Blog>();
q.addWhereEqualTo('title', '博客标题');
q.addWhereGreaterThan('like', 70);
q.setOrder('-createdAt'); // 逆序：字段前加 -
q.setLimit(10);
q.setSkip(0);
q.queryObjects().then((List<dynamic> data) {
  final blogs = data.map((i) => Blog.fromJson(i)).toList();
});

比较	方法
等于	addWhereEqualTo
不等于	addWhereNotEqualTo
小于	addWhereLessThan
小于等于	addWhereLessThanOrEqualTo
大于	addWhereGreaterThan
大于等于	addWhereGreaterThanOrEqualTo
条数	queryCount() → Future<int>

OR / AND 复合查询见 references/query.md。

Pointer / 关联

final blog = Blog()..title = '带作者';
final user = BmobUser()..objectId = '已有用户的objectId';
blog.author = user;
blog.save();
// 查询：q.setInclude('author');
// 解除关联：blog.deleteFieldValue('author')

详见 references/pointer-and-relation.md。

用户 / 短信 / 文件（skill 内简表，P1 将有专用 auth/storage）

场景	入口
注册	BmobUser()..username=.. ..password=.. → .register()
用户名密码登录	.login()
短信登录	BmobSms.sendSms() → loginBySms(code)
上传文件	BmobFileManager.upload(file) → 写入表的 BmobFile 字段

完整片段见 Flutter 文档「用户操作」「文件操作」。

与 MCP 联动

如已配置 Bmob MCP，写 Flutter 代码前先 get_project_tables，避免 schemaless 下字段名拼错、Pointer 格式错误。

排错速查

跨平台现象先查 shared/faq.md。

现象	排查
初始化后请求失败	Secret Key / API 安全码是否与控制台一致；是否忘记 release 的 resetDomain
更新 / 删无效	未设 objectId
include 后 author 为空	setInclude 字段名与表字段一致；Pointer 目标 objectId 存在
BmobError code 不明	bmob-error-codes + REST/Android 表对照
实时监听类型错	onDataChanged 里用 Map，勿直接 Blog.fromJson 整包

进阶能力（按需读 references/）

主题	路径
端到端场景	shared/recipes/
BmobDocs 同步代码片段	references/snippets/
模型继承 + JSON 序列化	references/model-and-init.md
条件 / OR·AND / 统计 / 个数查询	references/query.md
Pointer / Relation / ACL / 角色	references/pointer-and-relation.md

参考

• 完整 API：mds/data/flutter/index.md
• Raw（agent fetch）：metadata.docs_raw
• 插件源码：https://github.com/bmob/bmob-flutter-sdk/tree/master/data_plugin
• 示例工程：https://github.com/bmob/bmob-flutter-sdk/tree/master/data_demo
• 操作路由：shared/operation-routing.md
• 错误码：bmob-error-codes
• MCP：bmob-mcp