跳到主要内容

快速开始

数据模型是云开发提供的一种声明式数据管理方案,通过可视化界面定义数据结构和关系,自动生成类型安全的 SDK,让您专注于业务逻辑而无需关心底层数据操作。

前置条件

在开始之前,请确保您已经:

  • 创建了云开发环境,如若还没有请参考 开通云开发环境
  • 具备基本的 JavaScript/TypeScript 开发经验

快速上手

本教程将通过一个博客应用示例,演示如何使用数据模型管理文章和评论数据。我们将学习:

  1. 如何创建和配置数据模型
  2. 如何初始化和使用 SDK
  3. 如何进行基本的数据操作

让我们开始吧!

第一步:创建数据模型

1.1 进入数据模型管理页面

访问 云开发平台/数据库,然后点击「添加模型」开始创建新的数据模型。

创建数据模型

1.2 设计数据模型

我们将创建文章数据模型来构建一个简单的博客系统:

文章模型(post)

首先创建文章模型,包含以下字段:

字段名字段类型描述是否必填
title单行文本文章标题
slug单行文本文章别名,用于 SEO 优化
body富文本文章正文内容

1.3 系统默认字段

创建数据模型时,系统会自动添加以下系统字段,并在数据操作时自动维护:

系统字段描述自动更新时机
_id数据唯一标识符创建时自动生成
createdAt创建时间戳创建时自动生成
updatedAt更新时间戳每次更新时自动更新
_openid用户标识(小程序)用户端操作时自动生成
owner数据所有者创建时自动设置
createBy创建者标识创建时自动设置
updateBy最后修改者每次更新时自动更新

💡 开发优势:开发者无需手动管理这些字段,系统自动处理数据的生命周期管理,让您专注于业务逻辑实现。

第二步:添加 SDK

2.1 下载 SDK 文件

根据您的开发平台选择对应的 SDK:

平台文档链接
小程序本教程重点介绍
Web 应用在 Web 页面中调用
云函数在云函数中调用

对于小程序开发,请下载 SDK 文件并保存到项目目录:

  1. 下载 SDK 文件:wxCloudClientSDK.umd.js
  2. 将文件保存到小程序项目的根目录(通常是 miniprogram 目录)
  3. 文件命名为:wxCloudClientSDK.umd.js

2.2 初始化 SDK

在小程序的 app.js 文件中添加初始化代码:

// 引入数据模型 SDK
const {
init
} = require("./wxCloudClientSDK.umd.js");

App({
onLaunch() {
// 初始化云开发
wx.cloud.init({
env: "your-env-id", // 替换为您的云开发环境 ID
traceUser: true,
});

// 初始化数据模型客户端
const client = init(wx.cloud);

// 将 models 挂载到全局,方便在页面中使用
this.globalData.models = client.models;

console.log("数据模型 SDK 初始化完成");
},

globalData: {
models: null, // 数据模型实例
}
});
提示

⚠️ 重要:请将 your-env-id 替换为您实际的云开发环境 ID

第三步:使用数据模型进行 CRUD 操作

3.1 在页面中获取 models 实例

在小程序页面中,首先获取 models 实例:

// pages/index/index.js
const app = getApp();

Page({
data: {
posts: [],
loading: false,
},

onLoad() {
// 获取数据模型实例
this.models = app.globalData.models;

// 加载文章列表
this.loadPosts();
},

// 其他方法...
});

3.2 创建数据(Create)

使用 create() 方法创建新文章:

// 创建新文章
async createPost() {
try {
this.setData({
loading: true
});

const {
data
} = await this.models.post.create({
data: {
title: "我的第一篇文章",
body: "这是文章的内容,支持富文本格式。\n\n可以包含多行文本。",
slug: "my-first-post",
},
});

console.log("文章创建成功:", data);
// 输出: { id: "7d8ff72c665eb6c30243b6313aa8539e" }

// 刷新文章列表
this.loadPosts();

wx.showToast({
title: "文章创建成功",
icon: "success",
});
} catch (error) {
console.error("创建文章失败:", error);
wx.showToast({
title: "创建失败",
icon: "error",
});
} finally {
this.setData({
loading: false
});
}
},

3.3 查询数据(Read)

使用 list() 方法获取文章列表:

// 加载文章列表
async loadPosts() {
try {
this.setData({
loading: true
});

const {
data
} = await this.models.post.list({
filter: {
where: {}, // 查询条件,空对象表示查询所有
},
pageSize: 10, // 每页数量
pageNumber: 1, // 页码(从 1 开始)
getCount: true, // 是否获取总数
sort: {
createdAt: -1, // 按创建时间倒序排列
},
});

console.log("查询结果:", data);

this.setData({
posts: data.records,
total: data.total,
});

} catch (error) {
console.error("加载文章失败:", error);
wx.showToast({
title: "加载失败",
icon: "error",
});
} finally {
this.setData({
loading: false
});
}
},

返回数据结构示例:

{
"records": [
{
"_id": "e2764d2d665ecbc9024b058f1d6b33a4",
"title": "我的第一篇文章",
"body": "这是文章的内容...",
"slug": "my-first-post",
"createdAt": 1717488585078,
"updatedAt": 1717490751944,
"_openid": "95fblM7nvPi01yQmYxBvBg",
"owner": "Anonymous(95fblM7nvPi01yQmYxBvBg)"
}
],
"total": 1
}

3.4 更新数据(Update)

// 更新文章
async updatePost(postId, updateData) {
try {
const {
data
} = await this.models.post.update({
filter: {
where: {
_id: postId,
},
},
data: updateData,
});

console.log("更新成功:", data);
wx.showToast({
title: "更新成功",
icon: "success",
});

// 刷新列表
this.loadPosts();
} catch (error) {
console.error("更新失败:", error);
wx.showToast({
title: "更新失败",
icon: "error",
});
}
},

3.5 删除数据(Delete)

// 删除文章
async deletePost(postId) {
try {
await this.models.post.delete({
filter: {
where: {
_id: postId,
},
},
});

wx.showToast({
title: "删除成功",
icon: "success",
});

// 刷新列表
this.loadPosts();
} catch (error) {
console.error("删除失败:", error);
wx.showToast({
title: "删除失败",
icon: "error",
});
}
},

下一步

恭喜!您已经掌握了数据模型的基本使用方法。接下来可以:

开始构建您的应用吧!🚀