/nodepress

😎 RESTful API service for Blog/CMS, powered by @nestjs

Primary LanguageTypeScriptMIT LicenseMIT

nodepress Logo

NodePress

nodepress GitHub stars GitHub issues GitHub Workflow Status GitHub license

RESTful API service for surmon.me blog, powered by nestjs, required mongoDB & Redis.

适用于 surmon.me 的 RESTful API 服务;基于 nestjs (nodejs); 需安装 mongoDBRedis 方可完整运行。

v3.x 使用 nestjs 进行重构,之前的 nodejs 版本在 此分支

其他相关项目:

更新记录:CHANGELOG.md

接口文档:API_DOC.md


v3.x 架构说明

接口概述

  • HTTP 状态码(详见 errors

    • 400 请求的业务被拒绝
    • 401 鉴权失败
    • 403 权限不足/请求参数需要更高的权限
    • 404 资源不存在
    • 405 无此方法
    • 500 服务器挂了
    • 200 正常
    • 201 POST 正常
  • 数据特征码(详见 http.interface.ts

    • status
      • success:正常
      • error:异常
    • message:永远返回(由 http.decorator 装饰)
    • error:一般会返回错误发生节点的 error;在 statuserror 的时候必须返回,方便调试
    • debug:开发模式下为发生错误的堆栈,生产模式不返回
    • result:在 statussuccess 的时候必须返回
      • 列表数据:一般返回{ pagination: {...}, data: {..} }
      • 具体数据:例如文章,则包含直接数据如{ title: '', content: ... }

数据模型

  • 通用

    • extend 为通用扩展(模型在此
    • 文章、分类、Tag 表都包含 extend 字段,用于在后台管理中自定义扩展,类似于 Wordpress 中的自定义字段功能,目前用来实现前台 icon 图标的 class 或者其他功能
  • 各表重要字段

    • _id:mongodb 生成的 id,一般用于后台执行 CRUD 操作
    • id:插件生成的自增数字 id,类似 mysql 中的 id,具有唯一性,用于前台获取数据
    • pid:父级 id,用于建立数据表关系,与 id 字段映射
  • 数据组成的几种可能

    • 数据库真实存在数据
    • 业务计算出的数据,非存储数据,如:统计数据
    • Mongoose 支持的 virtual 虚拟数据
    • 第三方模块提供数据,如:GitHub、Bilibili

应用结构

  • 入口

    • main.ts:引入配置,启动主程序,引入各种全局服务
    • app.module.ts:主程序根模块,负责各业务模块的聚合
    • app.controller.ts:主程序根控制器
    • app.config.ts:主程序配置,数据库、程序、第三方,一切可配置项
    • app.environment.ts:全局环境变量
  • 请求处理流程

    1. request:收到请求
    2. middleware:中间件过滤(跨域、来源校验等处理)
    3. guard:守卫过滤(鉴权)
    4. interceptor:before:数据流拦截器(本应用为空,即:无处理)
    5. pipe:参数提取(校验)器
    6. controller:业务控制器
    7. service:业务服务
    8. interceptor:after:数据流拦截器(格式化数据、错误)
    9. filter:捕获以上所有流程中出现的异常,如果任何一个环节抛出异常,则返回错误
  • 鉴权处理流程

    1. guard守卫 分析请求
    2. guard.canActivate:继承处理
    3. JwtStrategy.validate:调用 鉴权服务
    4. 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

  • 管道 pipes

    • validation.pipe 用于验证所有基于 class-validate 的验证类
  • 业务模块 modules

    • 公告
    • 文章
    • 分类
    • 标签
    • 评论
    • 配置
    • bilibili:Vlog 业务的请求
    • 鉴权/登陆:全局鉴权业务和 Token 业务
    • 点赞:点赞评论、文章、主站
    • 音乐:播放器音乐数据业务
    • 聚合供稿:负责聚和信息的输出和写入,如 Sitemap、RSSXML
    • 壁纸:主站每日壁纸模块业务
    • 扩展模块
      • GitHub:GitHub 项目列表业务
      • 统计:业务数据统计业务
      • 备份:数据库备份业务(定时、手动)
      • 其他:其他第三方 token 等服务
  • 核心辅助模块 processors

    • 数据库
      • 连接数据库和异常自动重试
    • 缓存 / Redis
    • 辅助 / Helper
      • 搜索引擎实时更新服务:根据入参主动提交搜索引擎收录,支持百度、Google 服务;分别会在动态数据 进行 CUD 的时候调用对应方法
      • 评论过滤服务:使用 akismet 过滤 spam;暴露三个方法:校验 spam、提交 spam、提交 ham
      • 邮件服务:根据入参发送邮件;程序启动时会自动校验客户端有效性,校验成功则根据入参发送邮件
      • IP 地理查询服务:根据入参查询 IP 物理位置;控制器内优先使用阿里云 IP 查询服务,当服务无效,使用本地 GEO 库查询,使用 ip.cn 等备用方案
      • 第三方云存储服务:生成云存储上传 Token(目前服务为 Aliyun OSS),后期可以添加 SDK 的更多支持,比如管理文件
      • Google 证书(鉴权)服务:用于生成各 Google 应用的服务端证书

Special issues

Google Indexing API

Google Auth

Google Analytics Embed API

Development Setup

# 安装
$ 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 updategeodb

Actions setup

Rule:

  • any PR open -> CI:Build test
  • master PR closed & merged -> CI:Deploy to server

Example:

  • local:develop -> remote:develop -> CI:Build test
  • remote:develop/master -> remote:master -> merged -> CI:Deploy to server