NodePress

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

适用于 surmon.me 的 RESTful API �?务端应用；基于 nestjs (nodejs)，需安装 mongoDB 和 Redis 方�?�完整�?行。

v3.x 使用 nestjs 进行�?构，之�?的 nodejs 版本在 此分支。

🔥 其他相关项目：

• 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

v3.x 架构说明

接�?�概述

• 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：全局环境�?��?

• 请求处�?��?程

  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

  • 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 应用的�?务端�?书

Special issues

Google Indexing API

• 完整的�?置�?程文档
• 「 统计用户的所有者角色 �?添加页�?� 在这里，而�?� 新版的

Google Auth

• OAuth 2.0 客户端 ID�?�?务�?�?�密钥 都是 OAuth 授�?�类型
• Auth 申请�?�管�?�页�?�

Google Analytics Embed API

• 完整文档
• 完整示例
• �?务端签�?� token 鉴�?�示例
• 客户端 API 文档
• 将�?务账户添加为 GA 的数�?�阅读者�?作页�?�

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 open → CI:Build test
• new tag v* → CI:Create Release
• release create → CI:Deploy → CI:Execute server script