russ3ll-franz / nodepress

😎 A RESTful api server application for Blog/CMS using @nestjs

   

NodePress

v3.0.0 使用 Nest 进行重构。 之前的 nodejs 版本在 此分支。

RESTful API server application for my blog.

• Maintained by me
• Online site: https://surmon.me
• SRE service: sre.surmon.me
• Web client for user: surmon.me By Nuxt.js(Vue)
• Web client for admin: angular-admin powered by Angular + Bootstrap4
• Native app client: surmon.me.native powered by React native

所有依赖：在这里

更新记录：在这里

v3.0.0 架构说明

接口概述

• 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 的时候必须返回
    • 列表数据：一般返回{ pagenation: {...}, data: {..} }
    • 具体数据：例如文章，则包含直接数据如{ title: '', content: ... }

数据结构

• 通用

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

• 各表重要字段

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

• 数据组成的几种可能

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

应用结构

• 入口

  • 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

  • 缓存拦截器：自定义这个拦截器是是要弥补框架不支持 ttl 参数的缺陷
  • 数据流转换拦截器：当控制器所需的 Promise service 成功响应时，将在此被转换为标准的数据结构
  • 数据流异常拦截器：当控制器所需的 Promise service 发生错误时，错误将在此被捕获
  • 日志拦截器：代替默认的全局日志

• 装饰器 decorators

  • 缓存装饰器：用于配置 cache key / cache ttl
  • 控制器响应装饰器：用于输出规范化的信息，如 message 和 翻页参数数据
  • 请求参数提取器：用户自动校验和格式化请求参数，包括 query/params/辅助信息

• 守卫 guards

  • 默认所有非 GET 请求会使用 Auth 守卫鉴权
  • 所有涉及到多角色请求的 GET 接口会使用 HumanizedJwtAuthGuard 进行鉴权

• 中间件 middlewares

  • Cors 中间件，用于处理跨域访问
  • Origin 中间件，用于拦截各路不明请求

• 管道 pipes

  • 用于验证所有基于 class-validate 的验证类

• 业务模块 modules

  • 公告
  • 文章
  • 分类
  • 标签
  • 评论
  • 配置
  • bilibili：Vlog 业务的请求
  • 鉴权/登陆：全局鉴权业务和 Token 业务
  • 点赞：点赞评论、文章、主站
  • 音乐：播放器音乐数据业务
  • 网站地图：负责网站地图 xml 生成，抽象出的对象。包含 Tag、Article、Category 及一些死数据（页面）的集合，生成 xml 并写入本地
  • 壁纸：主站每日壁纸模块业务
  • 扩展模块
    • Github：Github 项目列表业务
    • 统计：简单的统计业务
    • 七牛：生成七牛上传 Token

• 核心辅助模块 processors

  • 数据库
    • 连接数据库和异常自动重试
  • 缓存 / Redis
    • 基本的缓存数据 Set、Get
    • 扩展的 Promise 工作模式（双向同步/被动更新）
    • 扩展的 Interval 工作模式（超时更新/定时更新）
  • 辅助 / Helper
    • 百度实时更新服务：根据入参主动提交搜索引擎收录；目前只有百度；分别会在文章、分类、标签、进行 CUD 的时候调用对应方法
    • 评论过滤服务：使用 akismet 过滤 spam；暴露三个方法：校验 spam、提交 spam、提交 ham
    • 邮件服务：根据入参发送邮件；程序启动时会自动校验客户端有效性，校验成功则根据入参发送邮件
    • IP 地理查询服务：根据入参查询 IP 物理位置；控制器内优先使用阿里云 IP 查询服务，当服务无效，使用本地 GEO 库查询

开发命令

Installation

$ npm install

Running the app

# 开发
$ npm run start:dev

# 构建
$ npm run build

# 更新 GEO IP 库数据
$ npm run updategeodb

# 生产环境运行
$ npm run start:prod

Test

# 语法检查
$ npm run lint

# 测试
$ npm run test
$ npm run test:e2e
$ npm run test:cov
$ npm run test:watch