跳到主要内容

快速开始

在快速开始示例中,我们将使用清林云 BaaS (Backend as a Service) 云服务和各种前端语言框架创建一个简单的博客系统。

本章节要求你至少熟悉 JavaScript 语言和开发网页的基础知识,如果你是零基础,可以先前往清林云学院学习[零基础编程课程]

本章节假设你还未注册清林云,已注册的用户可以跳过第一部分。

1. 获取环境密匙

请点击右上角“控制台”按钮打开清林云控制台登录页面,扫描小程序码后注册登录。

当你在手机端完成验证后,网页端会自动跳转到控制台界面,如果你没有组织,则会创建一个“默认组织”和对应地域的一个“默认环境”。

“组织”是清林云管理环境、成员、权限的基本单位,类似于公司或团队的概念。

“环境”是使用 BaaS 的基本单位,你可以理解为一个环境就是一套独立的服务器数据库机房。就好比说微信和淘宝分别是两个环境,他们的数据互相隔离,但是天猫和淘宝可以共用一个环境。

地域决定了这个环境部署在哪个物理地区位置,不可更改。比如“cn-east-1”是中国华东地区的机房。如需开通多地域请联系客服。

第一个环境

点击该环境的右上角“查看详情”进入到该环境的详情界面。

环境详情

点击选项卡的“环境密匙”切换到环境密匙界面。

环境密匙

现在我们来创建一个,点击“新建密匙”,先不管“白名单”和“分应用权限”,直接点击“确认即可”。默认的*为允许所有来源的请求,上线产品后需要更改为你的业务域名。

ak

此时界面上会出现这个密匙的密码 secret,复制它放到备忘录或记事本保存。

环境密匙分为两部分,keyId 和 secret。keyId 是当前端请求 BaaS 时需要携带的信息,用来判定到底用哪一个密匙去解密 token 或加密 token。

注:A 密匙加密的 token 无法用 B 密匙解密,如果不是泄露了密匙需要更换,请尽量不要创建多个密匙,容易混乱。

secret 只在创建时能看到一次,请在创建密匙时妥善保存。该密文可以鉴权用户 token,也可以访问云数据库 API。

保存密匙

好的,现在我们已经有了最基础的密匙信息,拿着环境 ID 和该密匙的 keyId 前往下一步。

2. 安装简易博客应用

点击左侧栏“应用市场”前往应用中心。

在搜索栏输入“简易博客”。可以看到出现了《简易博客》应用。点击该应用查看详情。

应用详情

点击“安装”按钮就将该应用安装到了我们的组织中。现在就可以使用它的 API 了。再往下方继续浏览,查看应用的介绍和 API。

API

好的,我们现在已经安装好了“简易博客”应用,进入下一步写一个小网页来使用它吧。

3. 开发博客网页

简易示例

此处我们用 html 和 react 简单写一个小页面。

Github 仓库: https://github.com/baasapi/quickstart Gitee 仓库: https://gitee.com/baasapi/quickstart

如果你的浏览器支持,则可以看到下方的在线编辑器,点击“Run Project”:(小程序用户请到 PC 端打开)

该在线编辑器(不支持 Safari 和小程序端)使用了:[Web Container: https://stackblitz.com/fork/qinglin-quickstart],你也可以前往自行编辑,打开后修改环境信息即可看到效果。

React 示例:[React quickstart: https://stackblitz.com/fork/qinglin-quickstart-react]

Vue 示例:[Vue quickstart: https://stackblitz.com/fork/qinglin-quickstart-vue]

Angular 示例:[Angular quickstart: https://stackblitz.com/fork/qinglin-quickstart-angular]

如果浏览器不支持或想尝试本地编辑,则请自行创建一个index.html文件,然后复制下方代码进去后保存并用浏览器打开:

<html>
<head>
<script src="https://unpkg.com/react@latest/umd/react.development.js"></script>
<script src="https://unpkg.com/react-dom@latest/umd/react-dom.development.js"></script>
<script src="https://unpkg.com/@babel/standalone@latest/babel.js"></script>
<style>
body {
background-color: #f1f1f1;
}
.container {
display: flex;
flex-direction: column;
align-items: center;
}
.post {
background-color: #fff;
border-radius: 8px;
margin: 20px;
padding: 20px;
width: 900px;
max-width: 90%;
}
.postTitle {
font-size: 2em;
}
.postTime {
font-size: 0.8em;
color: #999;
margin: 20px auto;
}
.postContent {
color: #666;
}
.noContent {
margin: 20%;
}
</style>
</head>
<body>
<div id="root"></div>
<script type="text/babel">
function Page() {
const [posts, setPosts] = React.useState([]);

React.useEffect(() => {
fetch("https://cn-east-1.baasapi.com/", {
headers: {
envid: "yorhcDIFv2VLKyKE5YRa-", // 替换为你的环境ID
keyid: "frDo9pCfewCfBQ93otisA", // 替换为上面环境的密匙ID
},
method: "POST",
body: JSON.stringify({
appId: "qinglin-simple-blog", // 应用ID
api: "getManyPost", // 应用API
version: "latest", // API版本
args: {}, // API参数
}),
})
.then((res) => res.json())
.then((data) => {
console.log(data);
setPosts(data.posts ? data.posts.data : []);
})
.catch((e) => console.error(e));
}, []);

return (
<div className="container">
{posts.length > 0 ? (
posts.map((item, key) => (
<div className="post" key={key}>
<div className="postTitle">{item.title}</div>
<div className="postTime">
{new Date(item.createdAt).toLocaleString()}
</div>
<div className="postContent">{item.content}</div>
</div>
))
) : (
<div className="noContent">没有文章</div>
)}
</div>
);
}

ReactDOM.render(<Page />, document.getElementById("root"));
</script>
</body>
</html>

不出意外的话你已经可以看到一个空白网页了,你的环境中暂时没有文章,我们查看下一节,尝试调用createPost去创建文章。

4. 请求格式

在项目的代码中我们可以发现有地址为https://环境地域.baasapi.com的网络请求,这就是“简易博客”应用的一些相关 API。

API 的基本结构如下,以浏览器的 fetch 请求为例:

// 将以下环境地域、环境ID、环境密匙ID替换为实际信息
fetch("https://环境地域.baasapi.com/", {
headers: {
"content-type": "application/json",
envid: "你的环境ID",
keyid: "你的环境密匙ID",
},
method: "POST",
body: JSON.stringify({
appId: "qinglin-simple-blog",
api: "createPost",
version: "latest",
args: {
title: "第一篇文章",
content: "文章内容:清林云BaaS 示例",
},
}),
})
.then((res) => res.json())
.then((data) => console.log(data))
.catch((e) => console.log(e));

这是清林云的 API 约束,我们称之为 TypeAPI ,在很多场景下描述能力优于 RESTful 风格,开发者更容易理解。

所有的请求都是POST类型,URL固定为环境地域的地址,body内包括api,appId,version(api 的版本号),和args内的所有自定义数据。

返回内容都是 JSON 格式,有两种:

成功:

{
"步骤ID": "数据"
}

失败:

{
"errCode": "错误码",
"type": "错误的API",
"title": "错误原因",
"detail": "详细数据",
"instance": "请求ID和客户端数据"
}

更详细的 API 结构请查看API 格式章节。

5. 存取数据

好的,现在让我们对照“简易博客”的 API 文档测试一下请求,为了最简单,此处我们按 F12 使用浏览器开发者工具即可,当然你也可以用自己习惯的 API 调试工具,注意替换环境信息:

// 将以下环境地域、环境ID、环境密匙ID替换为实际信息
fetch("https://cn-east-1.baasapi.com/", {
"headers": {
"content-type": "application/json",
"envid": "yorhcDIFv2VLKyKE5YRa-",
"keyid": "frDo9pCfewCfBQ93otisA",
},
"method": "POST",
"body": JSON.stringify({
appId: "qinglin-simple-blog",
api: "getManyPost",
version: "latest",
args: {}
})
})
.then(res=>res.json())
.then(data=>console.log(data))
.catch(e=>console.log(e))

返回值:

{
"posts": {
"data": [],
"nextId": null
}
}

可以看到暂时没有文章数据,接下来我们将要往数据库中存一些文章数据:

// 将以下环境地域、环境ID、环境密匙ID替换为实际信息
fetch("https://cn-east-1.baasapi.com/", {
"headers": {
"content-type": "application/json",
"envid": "yorhcDIFv2VLKyKE5YRa-",
"keyid": "frDo9pCfewCfBQ93otisA",
},
"method": "POST",
"body": JSON.stringify({
appId: "qinglin-simple-blog",
api: "createPost",
version: "latest",
args: {
title: "第一篇文章",
content: "文章内容:清林云BaaS 示例",
}
})
})
.then(res=>res.json())
.then(data=>console.log(data))
.catch(e=>console.log(e))

成功返回值:

{
"post": {
"postId": 1622475599676000
}
}

好的,现在我们就成功存入了一些文章数据,回到第三步的网页应用刷新查看,发现已经有文章了:

appPost

“简易博客”应用的创建文章接口默认不需要用户名密码,只是个示例应用。

如果想要验证身份,防止任何人都可以创建文章,我们一般需要使用“用户系统”这样的专业应用去统一给用户颁发 token 验证身份。

但是在这个示例中,我们一切从简,“简易博客”应用做了一个最简单的不完全安全的防护措施用来示例。在应用中心中找到“简易博客”,然后点击“配置”前往应用配置界面,可以看到一些配置项,我们来设置该应用的密码。

set

配置完成后再执行上述请求可以看到请求失败了,没有通过验证。

// 将以下环境地域、环境ID、环境密匙ID替换为实际信息
fetch("https://cn-east-1.baasapi.com/", {
"headers": {
"content-type": "application/json",
"envid": "yorhcDIFv2VLKyKE5YRa-",
"keyid": "frDo9pCfewCfBQ93otisA",
},
"method": "POST",
"body": JSON.stringify({
appId: "qinglin-simple-blog",
api: "createPost",
version: "latest",
args: {
title: "第二篇文章",
content: "文章内容:清林云BaaS 示例",
}
})
})
.then(res=>res.json())
.then(data=>console.log(data))
.catch(e=>console.log(e))

失败返回值:

{
"errCode": 1,
"title": "密码错误",
"type": "createPost",
"detail": "xxx",
"instance": "xxx"
}

此时我们将前面配置好的密码放入请求 argspostSecret 中如下所示:

再次请求,发现成功了。

// 将以下环境地域、环境ID、环境密匙ID替换为实际信息
fetch("https://cn-east-1.baasapi.com/", {
"headers": {
"content-type": "application/json",
"envid": "yorhcDIFv2VLKyKE5YRa-",
"keyid": "frDo9pCfewCfBQ93otisA",
},
"method": "POST",
"body": JSON.stringify({
appId: "qinglin-simple-blog",
api: "createPost",
version: "latest",
args: {
title: "第二篇文章",
content: "文章内容:清林云BaaS 示例",
postSecret: "test",
}
})
})
.then(res=>res.json())
.then(data=>console.log(data))
.catch(e=>console.log(e))

成功返回值:

{
"post": {
"postId": 1622485599676000
}
}

刷新网页查看到新文章:

appPost2

这样我们就将“简易博客”的createPostAPI 简单保护了起来,其他人仅仅只能查看文章。

另外,你也可以到清林云控制台点击左侧的应用列表中的 简易博客 前往 OneTable-该应用的数据页直接查看原始数据,进行更新、删除等操作,相当于一个通用后台,并且能和组织成员协同使用。

dataPage

到此处,“简易博客”应用我们已经成功运行了,相比于传统的开发后端,直接使用 BaaS 的方便性领先一个时代,而且对于越复杂的应用效果越明显。

“简易博客”的权限只是一个简单的展示,请勿在商业产品中使用该方式保护 API。想要更完善的、和清林云同款的用户登录注册权限等应用功能和安全措施,请前往应用市场查看《用户系统 appId: user》。

如果你想知道这个“简易博客”应用是怎样被设计出来的,可以查看创建应用章节,快速入门设计自定义应用,所有人都可以设计更好更强大的应用。

6. 完成

完成产品开发后,我们将其部署,注意别忘了前往环境详情页面配置密匙白名单,减少安全隐患。如果你对部署项目不熟悉,可以前往清林云学习中心学习前端部署课程。

好的,我们已经完成了一个最基本的项目,熟悉了清林云 BaaS 的使用,能够体会到使用 BaaS 是多么的简单方便。后面你可以前往应用市场发现并安装更多的应用,用来开发你需要的产品。

如果你想了解更详细的使用方式,请查看API 格式章节。

如果你想学习如何设计自定义应用,请查看自定义应用目录。

我们在最佳实践中以 需求-功能分析-数据库结构-API-界面 的组合用描述和截图展示了一些常见应用从零到一的设计与实现,你可以通过查看实践的方式了解到完整应用的细节,能够更好的开发自定义应用并使用。

本着吃自己的狗粮原则,清林云 BaaS 控制台自身就使用了最佳实践中的用户系统组织系统