RESTful API service for surmon.me blog, powered by
nestjs
, requiredmongoDB
&Redis
.
适用于 surmon.me 的 RESTful API 服务端应用;基于
nestjs
(nodejs),需安装mongoDB
和Redis
方可完整运行。
🔥 其他相关项目:
- SSR Blog: surmon.me powered by Vue (3)
- Blog admin: veact-admin powered by React & Veact
- Blog native app: surmon.me.native powered by react-native
更新记录:CHANGELOG.md
接口文档:API_DOC.md
-
HTTP 状态码(详见 errors )
400
请求的业务被拒绝401
鉴权失败403
权限不足/请求参数需要更高的权限404
资源不存在405
无此方法500
服务器挂了200
正常201
POST 正常
-
数据特征码(详见 http.interface.ts )
status
:success
:正常error
:异常
message
:永远返回(由 http.decorator 装饰)error
:一般会返回错误发生节点的 error;在status
为error
的时候必须返回,方便调试debug
:开发模式下为发生错误的堆栈,生产模式不返回result
:在status
为success
的时候必须返回- 列表数据:一般返回
{ pagination: {...}, data: {..} }
- 具体数据:例如文章,则包含直接数据如
{ title: '', content: ... }
- 列表数据:一般返回
-
通用
extend
为通用扩展(模型在此)- 文章、分类、Tag 表都包含 extend 字段,用于在后台管理中自定义扩展,类似于 Wordpress 中的自定义字段功能,目前用来实现前台 icon 图标的 class 或者其他功能
-
各表重要字段
_id
:mongodb 生成的 id,一般用于后台执行 CRUD 操作id
:插件生成的自增数字 id,类似 mysql 中的 id,具有唯一性,用于前台获取数据pid
:父级 id,用于建立数据表关系,与 id 字段映射
-
数据组成的几种可能
- 数据库真实存在数据
- 业务计算出的数据,非存储数据,如:统计数据
- Mongoose 支持的 virtual 虚拟数据
-
入口
main.ts
:引入配置,启动主程序,引入各种全局服务app.module.ts
:主程序根模块,负责各业务模块的聚合app.controller.ts
:主程序根控制器app.config.ts
:主程序配置,数据库、程序、第三方,一切可配置项app.environment.ts:
全局环境变量
-
请求处理流程
request
:收到请求middleware
:中间件过滤(跨域、来源校验等处理)guard
:守卫过滤(鉴权)interceptor:before
:数据流拦截器(本应用为空,即:无处理)pipe
:参数提取(校验)器controller
:业务控制器service
:业务服务interceptor:after
:数据流拦截器(格式化数据、错误)filter
:捕获以上所有流程中出现的异常,如果任何一个环节抛出异常,则返回错误
-
鉴权处理流程
guard
:守卫 分析请求guard.canActivate
:继承处理JwtStrategy.validate
:调用 鉴权服务guard.handleRequest
:根据鉴权服务返回的结果作判断处理,通行或拦截
-
鉴权级别
- 任何高级操作(CUD)都会校验必须的 Token(代码见 auth.guard.ts )
- 涉及表数据读取的 GET 请求会智能校验 Token,无 Token 或 Token 验证生效则通行,否则不通行(代码见 humanized-auth.guard.ts )
-
参数校验逻辑(代码见 query-params.decorator.ts )
- 普通用户使用高级查询参数将被视为无权限,返回 403
- 任何用户的请求参数不合法,将被校验器拦截,返回 400
-
错误过滤器(代码见 error.filter.ts )
-
拦截器 interceptors
-
装饰器扩展 decorators
-
守卫 guards
- 默认所有非 GET 请求会使用 Auth 守卫鉴权
- 所有涉及到多角色请求的 GET 接口会使用 HumanizedJwtAuthGuard 进行鉴权
-
中间件 middlewares
- Cors 中间件,用于处理跨域访问
- Origin 中间件,用于拦截各路不明请求
-
管道 pipes
- validation.pipe 用于验证所有基于 class-validate 的验证类
-
业务模块 modules
- 公告
- 文章
- 分类
- 标签
- 评论
- 配置
- 鉴权/登陆:全局鉴权业务和 Token 业务
- 点赞:点赞评论、文章、主站
- 聚合供稿:负责聚和信息的输出和写入,如 Sitemap、RSSXML
- 扩展模块
- 统计:业务数据统计业务
- 备份:数据库备份业务(定时、手动)
- 其他:其他第三方 token 等服务
-
核心辅助模块 processors
- 数据库
- 连接数据库和异常自动重试
- 缓存 / Redis
- 基本的缓存数据 Set、Get
- 扩展的 Promise 工作模式(双向同步/被动更新)
- 扩展的 Interval 工作模式(超时更新/定时更新)
- 辅助 / Helper
- 搜索引擎实时更新服务:根据入参主动提交搜索引擎收录,支持百度、Google 服务;分别会在动态数据 进行 CUD 的时候调用对应方法
- 评论过滤服务:使用 akismet 过滤 spam;暴露三个方法:校验 spam、提交 spam、提交 ham
- 邮件服务:根据入参发送邮件;程序启动时会自动校验客户端有效性,校验成功则根据入参发送邮件
- IP 地理查询服务:根据入参查询 IP 物理位置;控制器内优先使用阿里云 IP 查询服务,当服务无效,
使用本地 GEO 库查询,使用 ip.cn 等备用方案 - 第三方云存储服务:生成云存储上传 Token(目前服务为 Aliyun OSS),后期可以添加 SDK 的更多支持,比如管理文件
- Google 证书(鉴权)服务:用于生成各 Google 应用的服务端证书
- 数据库
- OAuth 2.0 客户端 ID、服务帐号密钥 都是 OAuth 授权类型
- Auth 申请及管理页面
# 安装
$ yarn
# 开发
$ yarn start:dev
# 测试
$ yarn lint
$ yarn test
$ yarn test:e2e
$ yarn test:cov
$ yarn test:watch
# 构建
$ yarn build
# 生产环境运行
$ yarn start:prod
# 更新 GEO IP 库数据
$ yarn update-geo-db
Rule:
any PR open
→CI:Build test
new tag v*
→CI:Create Release
release create
→CI:Deploy
→CI:Execute server script