数据存储开发指南 · JavaScript
数据存储是云服务提供的核心功能之一,可用于存放和查询应用数据。下面的代码展示了如何创建一个对象并将其存入云端:
// 声明 class
const Todo = AV.Object.extend("Todo");
// 构建对象
const todo = new Todo();
// 为属性赋值
todo.set("title", "工程师周会");
todo.set("content", "周二两点,全体成员");
// 将对象保存到云端
todo.save().then(
(todo) => {
// 成功保存之后,执行其他逻辑
console.log(`保存成功。objectId:${todo.id}`);
},
(error) => {
// 异常处理
}
);
我们为各个平台或者语言开发的 SDK 在底层都是通过 HTTPS 协议调用统一的 REST API,提供完整的接口对数据进行各类操作。
SDK 安装与初始化
请阅读 数据存储、即时通讯 JavaScript SDK 配置指南。
对象
AV.Object
AV.Object
是云服务对复杂对象的封装,每个 AV.Object
包含若干与 JSON 格式兼容的属性值对(也称键值对,key-value pairs)。这个数据是无模式化的(schema free),意味着你不需要提前标注每个 AV.Object
上有哪些 key,你只需要随意设置键值对就可以,云端会保存它。
比如说,一个保存着单个 Todo 的 AV.Object
可能包含如下数据:
title: "给小林发邮件确认会议时间",
isComplete: false,
priority: 2,
tags: ["工作", "销售"]
数据类型
AV.Object
支持的数据类型包括 String
、Number
、Boolean
、Object
、Array
、Date
等等。你可以通过嵌套的方式在 Object
或 Array
里面存储更加结构化的数据。
AV.Object
还支持两种特殊的数据类型 Pointer
和 File
,可以分别用来存储指向其他 AV.Object
的指针以及二进制数据。
AV.Object
同时支持 GeoPoint
,可以用来存储地理位置信息。参见 GeoPoint。
以下是一些示例:
// 基本类型
const bool = true;
const number = 2018;
const string = `${number} 流行音乐榜单`;
const date = new Date();
const array = [string, number];
const object = {
number: number,
string: string,
};
// 构建对象
const TestObject = AV.Object.extend("TestObject");
const testObject = new TestObject();
testObject.set("testNumber", number);
testObject.set("testString", string);
testObject.set("testDate", date);
testObject.set("testArray", array);
testObject.set("testObject", object);
testObject.save();
我们不推荐在 AV.Object
里面存储图片、文档等大型二进制数据。每个 AV.Object
的大小不应超过 128 KB。如需存储大型文件,可创建 AV.File
实例并将其关联到 AV.Object
的某个属性上。参见 文件。
注意:时间类型在云端将会以 UTC 时间格式存储,但是客户端在读取之后会转化成本地时间。
开发者中心 > 你的游戏 > 游戏服务 > 云服务 > 数据存储 > 结构化数据 中展示的日期数据也会依据操作系统的时区进行转换。一个例外是当你通过 REST API 获得数据时,这些数据将以 UTC 呈现。你可以手动对它们进行转换。
若想了解云服务是如何保护应用数据的,请阅读数据和安全。
构建对象
下面的代码构建了一个 class 为 Todo
的 AV.Object
:
// 为 AV.Object 创建子类
const Todo = AV.Object.extend("Todo");
// 为该类创建一个新实例
const todo = new Todo();
// 你还可以直接使用 AV.Object 的构造器
const todo = new AV.Object("Todo");
在构建对象时,为了使云端知道对象属于哪个 class,需要将 class 的名字作为参数传入。你可以将云服务里面的 class 比作关系型数据库里面的表。一个 class 的名字必须以字母开头,且只能包含数字、字母和下划线。
如果你使用的是 ES6,还可以通过 extends
关键字来创建 AV.Object
的子类,然而 SDK 无法自动识别你创建的子类。你需要通过这种方式手动注册一下:
class Todo extends AV.Object {
// 自定义属性和方法
}
// 注册子类
AV.Object.register(Todo);
这样你就能在 AV.Object
的子类中添加额外的方法和属性了。
保存对象
下面的代码将一个 class 为 Todo
的对象存入云端:
// 声明 class
const Todo = AV.Object.extend("Todo");
// 构建对象
const todo = new Todo();
// 为属性赋值
todo.set("title", "马拉松报名");
todo.set("priority", 2);
// 将对象保存到云端
todo.save().then(
(todo) => {
// 成功保存之后,执行其他逻辑
console.log(`保存成功。objectId:${todo.id}`);
},
(error) => {
// 异常处理
}
);
为了确认对象已经保存成功,我们可以到 开发者中心 > 你的游戏 > 游戏服务 > 云服务 > 数据存储 > 结构化数据 > Todo
里面看一下,应该会有一行新的数据产生。点一下这个数据的 objectId
,应该能看到类似这样的内容:
{
"title": "马拉松报名",
"priority": 2,
"ACL": {
"*": {
"read": true,
"write": true
}
},
"objectId": "582570f38ac247004f39c24b",
"createdAt": "2017-11-11T07:19:15.549Z",
"updatedAt": "2017-11-11T07:19:15.549Z"
}
注意,无需在 开发者中心 > 你的游戏 > 游戏服务 > 云服务 > 数据存储 > 结构化数据 里面创建新的 Todo
class 即可运行前面的代码。如果 class 不存在,它将自动创建。
以下是一些对象的内置属性,会在对象保存时自动创建,无需手动指定:
内置属性 | 类型 | 描述 |
---|---|---|
objectId | String | 该对象唯一的 ID 标识。 |
ACL | AV.ACL | 该对象的权限控制,实际上是一个 JSON 对象,控制台做了展现优化。 |
createdAt | Date | 该对象被创建的时间。 |
updatedAt | Date | 该对象最后一次被修改的时间。 |
这些属性的值会在对象被存入云端时自动填入,代码中尚未保存的 AV.Object
不存在这些属性。
属性名(keys)只能包含字母、数字和下划线。自定义属性不得以双下划线(__
)开头或与任何系统保留字段和内置属性(ACL
、className
、createdAt
、objectId
和 updatedAt
)重名,无论大小写。
属性值(values)可以是字符串、数字、布尔值、数组或字典(任何能以 JSON 编码的数据)。参见 数据类型。
我们推荐使用驼峰式命名法(CamelCase)为类和属性来取名。类,采用大驼峰法,如 CustomData
。属性,采用小驼峰法,如 imageUrl
。
获取对象
对于已经保存到云端的 AV.Object
,可以通过它的 objectId
将其取回:
const query = new AV.Query("Todo");
query.get("582570f38ac247004f39c24b").then((todo) => {
// todo 就是 objectId 为 582570f38ac247004f39c24b 的 Todo 实例
const title = todo.get("title");
const priority = todo.get("priority");
// 获取内置属性
const objectId = todo.id;
const updatedAt = todo.updatedAt;
const createdAt = todo.createdAt;
});
如果你试图获取一个不存在的属性,SDK 不会报错,而是会返回 undefined
。
如果需要一次性获取返回对象的所有属性(比如进行数据绑定)而非显式地调用 get
,可以利用 AV.Object
实例的 toJSON
方法:
const query = new AV.Query("Todo");
query.get("582570f38ac247004f39c24b").then((todo) => {
console.log(todo.toJSON());
// {
// createdAt: "2017-03-08T11:25:07.804Z",
// objectId: "582570f38ac247004f39c24b",
// priority: 2,
// title: "工程师周会",
// updatedAt: "2017-03-08T11:25:07.804Z"
// }
});
同步对象
当云端数据发生更改时,你可以调用 fetch
方法来刷新对象,使之与云端数据同步:
const todo = AV.Object.createWithoutData("Todo", "582570f38ac247004f39c24b");
todo.fetch().then((todo) => {
// todo 已刷新
});
刷新操作会强行使用云端的属性值覆盖本地的属性。因此如果本地有属性修改,fetch
操作会丢弃这些修改。为避免这种情况,你可以在刷新时指定 需要刷新的属性,这样只有指定的属性会被刷新(包括内置属性 objectId
、createdAt
和 updatedAt
),其他属性不受影响。
const todo = AV.Object.createWithoutData("Todo", "582570f38ac247004f39c24b");
todo
.fetch({
keys: "priority, location",
})
.then((todo) => {
// 只有 priority 和 location 会被获取和刷新
});
更新对象
要更新一个对象,只需指定需要更新的属性名和属性值,然后调用 save
方法。例如:
const todo = AV.Object.createWithoutData("Todo", "582570f38ac247004f39c24b");
todo.set("content", "这周周会改到周三下午三点。");
todo.save();
云服务会自动识别需要更新的属性并将对应的数据发往云端,未更新的属性会保持原样。
如果想要查看哪些属性有尚未保存的修改,可以调用 dirtyKeys
方法:
todo.dirtyKeys(); // ['content']
如果希望撤销尚未保存的修改,可以调用 revert
方法。直接调用 revert()
将撤销所有尚未保存的修改。还可以额外传入 keys
数组作为参数,指定需要撤销的属性,例如:
todo.revert(["content"]);
有条件更新对象
通过传入 query
选项,可以按照指定条件去更新对象——当条件满足时,执行更新;条件不满足时,不执行更新并返回 305
错误。
例如,用户的账户表 Account
有一个余额字段 balance
,同时有多个请求要修改该字段值。为避免余额出现负值,只有当金额小于或等于余额的时候才能接受请求:
const account = AV.Object.createWithoutData(
"Account",
"5745557f71cfe40068c6abe0"
);
// 对 balance 原子减少 100
const amount = -100;
account.increment("balance", amount);
account
.save(null, {
// 设置条件
query: new AV.Query("Account").greaterThanOrEqualTo("balance", -amount),
// 操作结束后,返回最新数据。
// 如果是新对象,则所有属性都会被返回,
// 否则只有更新的属性会被返回。
fetchWhenSave: true,
})
.then(
(account) => {
console.log(`当前余额为:${account.get("balance")}`);
},
(error) => {
if (error.code === 305) {
console.error("余额不足,操作失败!");
}
}
);
query
选项只对已存在的对象有效,不适用于尚未存入云端的对象。
query
选项在有多个客户端需要更新同一属性的时候非常有用。相比于通过 AV.Query
查询 AV.Object
再对其进行更新的方法,这样做更加简洁,并且能够避免出现差错。
更新计数器
设想我们正在开发一个微博,需要统计一条微博有多少个赞和多少次转发。由于赞和转发的操作可能由多个客户端同时进行,直接在本地更新数字并保存到云端的做法极有可能导致差错。为保证计数的准确性,可以通过 原子操作 来增加或减少一个属性内保存的数字:
post.increment("likes", 1);
可以指定需要增加或减少的值。若未指定,则默认使用 1
。
注意,虽然原子增减支持浮点数,但因为底层数据库的浮点数存储格式限制,会有舍入误差。
因此,需要原子增减的字段建议使用整数以避免误差,例如 3.14
可以存储为 314
,然后在客户端进行相应的转换。
否则,以比较大小为条件查询对象的时候,需要特殊处理,
< a
需改查 < a + e
,> a
需改查 > a - e
,== a
需改查 > a - e
且 < a + e
,其中 e
为误差范围,据所需精度取值,比如 0.0001
。
更新数组
更新数组也是原子操作。使用以下方法可以方便地维护数组类型的数据:
AV.Object.add('arrayKey', value)
将指定对象附加到数组末尾。AV.Object.addUnique('arrayKey', value)
如果数组中不包含指定对象,则将该对象加入数组。对象的插入位置是随机的。AV.Object.remove('arrayKey', value)
从数组字段中删除指定对象的所有实例。
例如,Todo
用一个 alarms
属性保存所有闹钟的时间。下面的代码将多个时间加入这个属性:
const alarm1 = new Date("2018-04-30T07:10:00");
const alarm2 = new Date("2018-04-30T07:20:00");
const alarm3 = new Date("2018-04-30T07:30:00");
const alarms = [alarm1, alarm2, alarm3];
const todo = new AV.Object("Todo");
todo.addUnique("alarms", alarms);
todo.save();
删除对象
下面的代码从云端删除一个 Todo
对象:
const todo = AV.Object.createWithoutData("Todo", "582570f38ac247004f39c24b");
todo.destroy();
如果只需删除对象的一个属性,可以用 unset
:
const todo = AV.Object.createWithoutData("Todo", "582570f38ac247004f39c24b");
// priority 属性会被删除
todo.unset("priority");
// 保存对象
todo.save();
注意,删除对象是一个较为敏感的操作,我们建议你阅读ACL 权限管理开发指南 来了解潜在的风险。熟悉 class 级别、对象级别和字段级别的权限可以帮助你有效阻止未经授权的操作。
批量操作
// 创建一个保存所有 AV.Object 的数组
const object1 = new AV.Object("Todo");
object1.set("content", "更新文档");
const object2 = new AV.Object("Todo");
object2.set("content", "回复论坛帖子");
const objects = [object1, object2];
// 批量构建和更新
AV.Object.saveAll(objects).then(
function (savedObjects) {
// 成功保存所有对象时进入此 resolve 函数,savedObjects 是包含所有 AV.Object 的数组
},
function (error) {
// 只要有一个对象保存错误就会进入此 reject 函数
}
);
// 批量删除
AV.Object.destroyAll(objects).then(
function (deletedObjects) {
// 成功删除所有对象时进入此 resolve 函数,deletedObjects 是包含所有的 AV.Object 的数组
},
function (error) {
// 只要有一个对象删除错误就会进入此 reject 函数
}
);
// 批量同步
AV.Object.fetchAll(objects).then(
function (fetchedObjects) {
// 成功同步所有对象时进入此 resolve 函数,fetchedObjects 是包含所有的 AV.Object 的数组
},
function (error) {
// 只要有一个对象同步错误就会进入此 reject 函数
}
);
下面的代码将所有 Todo
的 isComplete
设为 true
:
const query = new AV.Query("Todo");
query.find().then((todos) => {
// 获取需要更新的 todo
todos.forEach((todo) => {
// 更新属性值
todo.set("isComplete", true);
});
// 批量更新
AV.Object.saveAll(todos);
});
虽然上述方法可以在一次请求中包含多个操作,每一个分别的保存或同步操作在计费时依然会被算作一次请求,而所有的删除操作则会被合并为一次请求。
数据模型
对象之间可以产生关联。拿一个博客应用来说,一个 Post
对象可以与许多个 Comment
对象产生关联。云服务支持三种关系:一对一、一对多、多对多。
一对一、一对多关系
一对一、一对多关系可以通过将 AV.Object
保存为另一个对象的属性值的方式产生。比如说,让博客应用中的一个 Comment
指向一个 Post
。
下面的代码会创建一个含有单个 Comment
的 Post
:
// 创建 post
const post = new AV.Object("Post");
post.set("title", "饿了……");
post.set("content", "中午去哪吃呢?");
// 创建 comment
const comment = new AV.Object("Comment");
comment.set("content", "当然是肯德基啦!");
// 将 post 设为 comment 的一个属性值
comment.set("parent", post);
// 保存 comment 会同时保存 post
comment.save();
云端存储时,会将被指向的对象用 Pointer
的形式存起来。你也可以用 objectId
来指向一个对象:
const post = AV.Object.createWithoutData("Post", "57328ca079bc44005c2472d0");
comment.set("post", post);
请参阅 关系查询 来了解如何获取关联的对象。
多对多关系
想要建立多对多关系,最简单的办法就是使用 数组。在大多数情况下,使用数组可以有效减少查询的次数,提升程序的运行效率。但如果有额外的属性需要附着于两个 class 之间的关联,那么使用 中间表 可能是更好的方式。注意这里说到的额外的属性是用来描述 class 之间的关系的,而不是任何单一的 class 的。
我们建议你在任何一个 class 的对象数量超出 100 的时候考虑使用中间表。
序列化和反序列化
在实际的开发中,把 AV.Object
当作参数传递的时候,会涉及到复杂对象的拷贝的问题,因此 AV.Object
也提供了序列化和反序列化的方法。
序列化:
const todo = new AV.Object("Todo"); // 构建对象
todo.set("title", "马拉松报名"); // 设置名称
todo.set("priority", 2); // 设置优先级
todo.set("owner", AV.User.current()); // 这里就是一个 Pointer 类型,指向当前登录的用户
// 将 AV.Object 对象序列化成 JSON 对象
const json = todo.toFullJSON();
// 将 JSON 对象序列化为字符串
const serializedString = JSON.stringify(json);
AV.Object
还提供了另一个方法 toJSON()
。它们的区别是 toJSON()
得到的对象仅包含对象的 payload,一般用于展示,而 toFullJSON()
得到的对象包含了元数据,一般用于传输。在使用时请注意区分。
反序列化:
// 将字符串反序列化为 JSON 对象
const json = JSON.parse(serializedString);
// 将 JSON 对象反序列化成 AV.Object 对象
const todo = AV.parseJSON(json);
查询
我们已经了解到如何从云端获取单个 AV.Object
,但你可能还会有一次性获取多个符合特定条件的 AV.Object
的需求,这时候就需要用到 AV.Query
了。