十六、编辑器服务端基础API开发
1、技术方案设计和基本功能开发
* 引言
- 需求指导设计，设计指导开发。无设计不开发。
* 标题
- 服务端技术方案设计 & 基础功能开发
* 将收获什么
- 服务端技术方案设计的方法
- B端和编辑器基本功能API
* 主要内容
- 技术方案设计
- 基本功能开发
* 关键词
- 技术方案设计文档（架构设计、接口设计、数据库设计）
* 学习方法
- 亲自写出来，无论是代码还是文档
* 注意事项
- 业务代码不会一行一行写
- 回顾一下之前的“整体架构设计”，各个项目之间的关系，以及和数据库之间的关系。
2、技术方案设计
* 引言
- 领导技术方案设计、评审技术方案设计，这就是架构师和基层程序员的区别之一。
* 主要产出
- 《biz-editor-server端技术方案》文档
* 主要内容
- 接口设计
- 选择Restful API，不是GraphQL
- 数据库设计
- server整体设计
* 注意事项
- 正视技术方案设计，设计不会浪费时间，只会节约时间
- GraphQL不是课程主线，不要跑偏
3、接口设计
* 引言
- 把server端当做一个黑盒，它将怎样与前端通讯？
* 功能范围
- B端，用户注册，作品管理，模板
- 编辑器，单个作品的内容获取、修改、预览和发布
* 功能拆分
- 用户信息
- 作品管理
- 模板
- 编辑器（发布和渠道，可以单独设计）
- 工具类
* 用户信息
- 获取手机短信验证码
- 登录（包含注册）
- 获取用户信息
- 修改用户信息
* 模板
- 首页推荐模板列表（搜索，分页）--不需要登录校验
- 获取单个模板信息--不需要登录校验
- 我的模板列表（搜索，分页）
* 作品管理
- 创建空白作品
- 复制作品（通过模板创建）PS：模板即作品，只是有一个标志而已，数据库设计时可以看出来
- 删除作品
- 恢复作品
- 转赠作品
- 我的作品列表（搜索，分页）
- 我的回收站列表（搜索，分页）
* 编辑器
- 设计时分开，但代码中可能会和作品管理写在一起，因为都是针对作品的。
~ 查询单个作品信息
~ 保存作品
~ 预览作品
~ 发布作品
~ 发布为模板
* 渠道
- 创建渠道
- 删除渠道
- 修改渠道名称
- 获取单个作品的所有渠道
* 工具类
- 上传图片
* 统一的输出格式
########
{
errno: 0, // 错误码，无错误则返回0
data: {...}, // 或者[...]
message: 'xxx'
}
########
- 留作业，设计每个接口的输入和输出，可使用第三方工具YAPI。
* 其他
- 作品统计，会用到单独的统计服务，不在这里出数据
- 预览作品，在h5-server中
* 小结
- 功能拆分
- 详细的接口设计
- 统一输出格式
4、Restful API vs GraphQL
* 引言
- 默认所有同学都已非常熟悉Restful API。而GraphQL大家可能比较陌生，会放慢节奏。
- 而GraphQL是和Restful API完全不同的两种设计和实现方式，
两者也尽量不要混用（虽然混用也能做到无bug）
* 什么是GraphQL
- GraphQL-Graph Query Language图查询语言。意思是擅长处理“图”数据结构的查询，
即多个数据对象，各个之间还有关联关系。
- 核心概念：
~ schema - 数据规范
~ rootValue - 数据源
- 代码演示，可参考中文官网。注意，在此不要深入进去，还是沿着课程主线走。
########
var express = require('express');
var graphqlHTTP = require('express-graphql');
var { buildSchema } = require('graphql');
// 使用GraphQL Schema Language创建一个schema
var schema = buildSchema(`
type Query {
hello: String,
}
`)
// root提供所有API入口端点相应的解析器函数
var rootValue = {
hello: () => {
return 'Hello world';
},
};
var app = express();
app.use('/graphql', graphqlHTTP({
schema: schema,
rootValue: rootValue,
graphiql: true,
}));
app.listen(4000);
console.log('Running a GraphQL API server at http://localhost:4000/graphql');
########
- 另外，虽然GraphQL主要用于查询，但它也支持输入和更新，参考官网input和Mutation。
课程就不在继续扩展了。
* GraphQL的应用场景
- 数据关系比较复杂。PS：和我们正好相反，我们是作品的数据结构复杂（前段编辑器复杂），
而数据实体之间的关系比较清晰。
- 前端查询需求多变，如果用Restful API会导致频繁地修改API，不灵活。
- 有一个独立的数据提供方，对接很多使用方，不能一一定制开发
* 如何选择
- 选择使用Restful API，放弃GraphQL。
- 并不匹配它的使用场景
- 考虑它的缺点：
~ 学习使用成本高，不如Restful API普及
~ 当数据结构复杂时，效率较低
~ 维护数据源和schema也比较复杂
* 小结
- GraphQL介绍
- 应用场景
- 选择Restful API
5、数据库设计
* 需要存储的数据
- 用户
- 项目/模板（包含项目内容，组件信息）
- 渠道
* 数据之间的关系
* 数据表设计
- 注意，使用sequelize和mongoose，会自动创建id、createdAt和updatedAt，无需再自己手动创建。
* 用户
* 作品/模板
* 渠道
* 作品内容
- 未发布
- 发布
########
{
// 页面的组件列表
components: [Object],
// 页面的属性，如页面背景图片
props: Object,
// 配置信息，如微信分享配置
setting: Object,
}
########
* 代码演示
- sequelize Model以及关联关系
- mongoose Schema和Model
* 小结
- 数据表设计
- 数据表的关系
- 代码演示
| 列 |
类型 |
注释 |
| username |
varchar |
用户名，唯一 |
| password |
varchar |
密码，保留字段，暂时用不到 |
| phoneNumber |
varchar |
手机号 |
| nickName |
varchar |
昵称 |
| gender |
int |
性别（1男性，2女性，0保密） |
| picture |
varchar |
用户头像 |
| latestLoginAt |
date |
最后登录时间 |
| isFrozen |
boolean |
用户是否冻结 |
| 列 |
类型 |
注释 |
| uuid |
varchar |
uuid，h5 url中使用，隐藏真正的id，避免被爬 |
| title |
varchar |
标题 |
| desc |
varchar |
副标题 |
| contentId |
varchar |
未发布内容id，内容存储在mongodb中 |
| publishContentId |
varchar |
发布内容id，内容存储在mongodb中，未发布的为空 |
| author |
varchar |
作者username，和用户表关联 |
| coverImg |
varchar |
封面图片url |
| isTemplate |
boolean |
是否模板 |
| status |
int |
状态：0-删除，1-未发布，2-发布，3-强制下线 |
| copiedCount |
int |
模板被使用的次数 |
| lastestPublishAt |
date |
最近一次发布的时间 |
| isHot |
boolean |
hot标签，模板使用 |
| isNew |
boolean |
new标签，模板使用 |
| orderIndex |
int |
排序参数 |
| isPublic |
boolean |
模板是否公开显示 |
| 列 |
类型 |
注释 |
| name |
varchar |
渠道名称 |
| workId |
int |
作品id |
| status |
int |
状态：0-删除，1-正常 |
6、server架构设计
* 引言
- 回顾egg.js的代码结构。
* 整体架构图
* 写文档
- 在语雀中新建文档《biz-editor-server端技术方案》，目录
~ 范围（以及和其他项目的关系）
~ 技术选型
~ 整体架构设计
~ 接口设计
~ 数据库设计
* 小结
- 架构设计图
- 写文档
7、技术方案设计
* 引言
- 领导技术方案设计、评审技术方案设计，这就是架构师和基层程序员的区别之一。
* 主要产出
- 《biz-editor-server端技术方案》文档
* 主要内容
- 接口设计
- 选择Restful API，不是GraphQL
- 数据库设计
- server整体设计
* 注意事项
- 正视技术方案设计，设计不会浪费时间，只会节约时间
- GraphQL不是课程主线，不要跑偏
8、基本功能开发
* 主要产出
- 基础功能的接口，并发布到测试机
* 主要内容
- 登录功能
- 用户信息接口
- 作品接口
- 模板接口
* 注意事项
- 发布相关的接口和渠道接口，会在下一周讲解
- 发送短信功能还没有，先模拟
- 简单的代码不在从0手写
- 注意规范的研发流程，如git分支规范、commit规范、合并代码等
9、登录功能
* 引言
- 回顾JWT的登录校验过程
* 短信验证过程
* 初次获取验证码
- request - 输入手机号，请求短信验证码
- server - 生成4位随机数，缓存2min
- res
~ 发短信验证码
~ 返回给前端{ errno: 0 }
* 再次获取验证码
- request - 输入手机号，请求短信验证码
- server - 检查缓存，无则生成，并再次缓存
- res
~ 有缓存，则返回错误：不能频繁获取
~ 发送短信验证码，并返回给前端{ errno: 0 }
* 登录验证
- request - 书记好、验证码，请求登录验证
- server - 匹配缓存
- res
~ 匹配成功，则验证通过
~ 匹配失败，则验证不通过
* 重点考虑
- 费用
~ 缓存，禁止频繁发送
~ 短信服务的提示和报警（后面会讲）
- 用户体验
~ 短信发送失败，不会缓存，可以立马重新生成验证码
- 稳定性
~ 如果server缓存失败，那就允许用户重复调用。情况较少，没关系
~ 短信服务挂掉，报警（后面会讲）
- 注意事项
~ 发送短信，暂时模拟
~ 可以写个文档，虽然已经经过了技术方案设计，但有些写在开发前如果感觉复杂，
可以写个设计文档再评审一下。及时发现问题，及时沟通。
* 小结
- 短信验证过程
~ 生成验证码
~ 验证
- 重点关注
10、用户信息接口
* 研发过程
- 研发规范的细节，会在课程最后总结，先实践起来。
~ 拉新分支feature-xxx fix-xxx hotfix-xxx
~ 修改代码
~ commit，参考.cz-config.js
~ 往dev分支提交pr Pull Request（gitlal中是mr Merge Request）
~ 代码走查
~ 合并代码到dev
~ 等待发布上线
* 接口
- 获取手机短信验证码
- 登录（包含注册）
- 获取用户信息
- 修改用户信息
* 代码演示
- routes/users.js
- controller/users/
- service/users.js
- cache/users/
- __test__/apis/users.js接口测试
* 测试
- npm run test:local
- 使用postman手动测试
* 小结
- 注意研发过程
- 接口
- 代码演示
- 测试
11、作品管理接口
* 接口
- 创建空白作品
- 复制作品（通过模板创建）
- 删除作品
- 恢复作品
- 转赠作品
- 我的作品列表（搜索，分页）
- 我的回收站列表（搜索，分页）
- 查询单个作品信息
- 保存作品
* 代码演示
- routes/works.js
- controller/works/
- service/works.js
- __test__/apis/works.js
- PS：发布相关的，下周再讲解
* 测试
- npm run test:local
- 使用postman手动测试
* 小结
- 接口
- 代码演示
- 测试
12、模板接口
* 接口
- 首页推荐模板列表（搜索，分页）--不需要登录校验
- 获取单个模板信息--不需要登录校验
- 我的模板列表（搜索，分页）
* 代码演示
- routes/templates.js
- controller/works/findTemplate
- cache/works/templates
- __test__/apis/template.js
* 测试
- npm run test:local
- 使用postman手动测试
* 小结
- 接口
- 代码演示
- 测试
十七、编辑器服务端调用第三方服务
1、重要功能 & 第三方服务
* 引言
-