Skip to content
master
Go to file
Code

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
 
 
 
 
src
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.md

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 虚拟数据

应用结构

  • 入口

    • 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

    • 公告
    • 文章
    • 分类
    • 标签
    • 评论
    • 配置
    • 鉴权/登陆:全局鉴权业务和 Token 业务
    • 点赞:点赞评论、文章、主站
    • 聚合供稿:负责聚和信息的输出和写入,如 Sitemap、RSSXML
    • 扩展模块
      • 统计:业务数据统计业务
      • 备份:数据库备份业务(定时、手动)
      • 其他:其他第三方 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 update-geo-db

Actions setup

Rule:

  • any PR openCI:Build test
  • master PR closed & mergedCI:Deploy to server

Example:

  • local:developremote:developCI:Build test
  • remote:develop/masterremote:master → mergedCI:Deploy to server