已废弃，未来将会基于 midwayjs 做模板。
boilerplate-express 是一个面向中国用户的简单 express 模板，目标是帮助你快速开发中小型项目后端。当然，也希望能引导你更进一步地了解 node 后端生态。
如果想要快速开发大型项目后端，请考虑使用 boilerplate-nest。
- node
- express
- typescript
- mongoose
- statuses
- @modyqyw/utils
- dayjs
- @modyqyw/fabric
- npm-check-updates
- esno
请先阅读上面的文档，并确保对 node 和 npm 有 基本了解。
这部分说明将让你得到能在本地运行的项目副本以开始开发。有关如何部署项目，请阅读 部署部分。
你可能需要使用梯子或手机 WiFi 完成准备步骤。
对于 macOS 用户，请按照以下指引操作。
# 安装 nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# 设置镜像，加快下载速度
export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node
# 安装 node@lts
nvm install --lts
# 使用 node@lts
nvm use --lts
# 设置默认版本
nvm alias default node
# 安装 pnpm
npm i -g pnpm --registry=https://registry.npmmirror.com
# 安装 homebrew
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# 安装 git
brew install git
# 不自动转换换行符
git config --global core.autocrlf false
# 设置默认分支名为 main
git config --global init.defaultBranch main
# 安装 Xcode 命令行工具
xcode-select --install
# tap
brew tap mongodb/brew
# 安装 mongodb-community
brew install mongodb-community
# 启动服务
brew services start mongodb-community
# 重启服务
brew services restart mongodb-community
设置 ~/.huskyrc。
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
对于 Windows 用户，请按照以下指引操作。
首先安装 nvm-windows 和 Git。
然后使用 Windows Terminal 作为终端，Git Bash 作为 Shell，参考 让 Win10 的终端更好用 和 配置 Windows Terminal。
如果你正在使用 Chocolatey 或 Scoop，你也可以通过命令安装，然后配置。
# 使用 Chocolatey
choco install nvm
choco install git
choco install mongodb
# 使用 Scoop
scoop install nvm
scoop install git
scoop install mongodb
# 不自动转换换行符
git config --global core.autocrlf false
# 设置默认分支名为 main
git config --global init.defaultBranch main
# 设置镜像，加快下载速度
nvm node_mirror https://npmmirror.com/mirrors/node
nvm npm_mirror https://npmmirror.com/mirrors/npm
# 安装 node@lts
nvm install lts
# 使用 node@lts
nvm use lts
# 安装 pnpm
npm i -g pnpm --registry=https://registry.npmmirror.com
你可能需要配置 ~/.huskyrc。
其它系统请根据以上指引自行调整。
# clone 项目到本地
git clone [email protected]:MillCloud/boilerplate-express.git
# git clone [email protected]:MillCloud/boilerplate-express.git
# 进入项目
cd boilerplate-express
# 安装依赖
pnpm install
# 启动项目
pnpm run dev
.
├── .github # github 配置目录
├── .husky # husky 配置目录
├── logs # 日志目录，生产环境出现
├── src
│ ├── constants # 固定数据目录
│ ├── controllers # 控制器目录
│ ├── middlewares # 中间件目录
│ ├── models # mongoose model 目录
│ ├── routes # 路由目录
│ ├── schedules # 定时任务目录
│ ├── typings # 类型目录
│ ├── utils # 工具方法目录
│ ├── app.ts # express 实例
│ ├── db.ts # mongoose 连接
│ ├── env.ts # dotenv 读取
│ ├── index.ts # 入口
│ ├── localhost-key.pem # 创建 HTTPS 服务器所需
│ ├── localhost.pem # 创建 HTTPS 服务器所需
│ └── server.ts # 服务器实例
│ ├── static # 静态文件目录
├── .commitlintrc.cjs # commitlint 配置文件
├── .editorconfig
├── .eslintrc.cjs # eslint 配置文件
├── .gitattributes # git 配置文件
├── .gitignore # git 配置文件
├── .lintstagedrc.cjs # lint-staged 配置文件
├── .markdownlint.json # markdownlint 配置文件
├── .npmrc # npm 配置文件
├── .prettierrc.cjs # prettier 配置文件
├── .release-it.cjs # release-it 配置文件
├── package.json
├── pnpm-lock.yaml
├── README.md
├── renovate.json # renovate 配置文件
└── tsconfig.json # typescript 配置文件可参考 egg.js 目录结构 自行调整。
你可以参考 插件 和 settings.json。
nodemon 提供了开发阶段的热重载支持，默认监听 src 文件夹、模式和环境变量相关文件。
底层使用了基于 [esbuild] 的 esmo。
使用 cross-env 在命令行内处理模式和环境变量。
使用 dotenv 和 dotenv-expand 在应用内处理模式和环境变量。
支持根目录下存在多个 .env 文件，优先级由低到高和相关说明如下。
.env- 通用环境变量.env.${process.env.NODE_ENV}-${process.env.NODE_ENV}专属环境变量.env.local- 本地通用环境变量.env.${process.env.NODE_ENV}.local- 本地${process.env.NODE_ENV}专属环境变量
下面是一个 .env 内容示例。
APP_HOST=127.0.0.1
APP_PORT=3000
APP_API_ROUTER_PREFIX=/api
APP_DB_HOST=127.0.0.1
APP_DB_PORT=27017
APP_DB_NAME=app
APP_JWT_SECRET=secret
APP_JWT_EXPIRES_IN=604800000
使用 mongodb 作为数据库，使用 mongoose 作为 ODM。数据库初始化见 db.ts。
如果不喜欢 mongoose，也可以自行配置 typegoose 或 prisma 使用。
如果不喜欢 mongodb，也可以自行配置 mysql、postgresql 使用。相应地，ORM 可以使用 typeorm、prisma 或 sequelize。
固定数据 内的变量符合以下规则。
- 由模式和环境变量推导出来的变量，比如
NODE_ENV、IS_PRODUCTION、APP_MODE等。 - 与业务解耦，比如
ISO8601_FORMAT、DATE_FORMAT、DATE_TIME_FORMAT等。
项目内已经包含了较常用的社区中间件。
- compression - 基于 compression 的压缩中间件
- cors - 基于 cors 的
CORS中间件 - formidable - 基于 formidable 的
form-data解析中间件 - helmet - 基于 helmet 的 HTTP 头部中间件
- logger - 基于 winston 的日志中间件
- parser - 基于 body-parser 的
body解析中间件 - rate-limit - 基于 express-rate-limit 的频率限制中间件
- static - 基于 serve-static 的静态文件中间件
- tracer - 基于 cls-rtracer 的请求 ID 中间件
- validator - 基于 express-validator 的请求校验中间件
也包含了可能需要使用的中间件，可以根据需求调整。
- auth - 处理认证
authentication和授权authorization的中间件 Authentication vs. Authorization - error - 处理错误的中间件
和中间件相关的变量往往也会在中间件文件内导出。如果符合固定数据规则，则在固定数据内导出，比如 APP_LOGGER_LEVEL。
全局级别的中间件应用见 @/app.ts，路由级别的中间件应用见 @/routes/index.ts。
从请求到响应的全流程来说，应该是先匹配成功路由，然后通过一系列中间件的校验，最后交给控制器的方法处理请求。
但在实际开发中，如果过度分离了路由和控制器的代码，往往需要开发者在不同文件间来回横跳，同时也不利于测试，开发者体验较差。
因此，项目的路由直接根据控制器信息生成，内置有两个路由 @/src/routes/auth.ts 和 @/src/routes/home.ts。
项目也配置了 404 处理，见 @/routes/index.ts。
控制器只是一个遵循 约定格式 的对象。
项目内置了两个控制器 authController 和 homeController，分别对应内置的两个路由。
定时任务基于 agenda，需要和 mongodb 匹配使用。
如果你想要更换数据库，不妨看看其它一些相关库，比如 bullmq、bull、bree。
当前有一个每分钟运行的定时任务，见 @/schedules/index.ts。
got 应该是更好的选择，但配套（ts、jest）仍需一段时间才能完全支持 v12。未来考虑加入。
当前设计很难基于 swagger 或类似的工具自动生成文档，建议在 docs 文件夹内手写 markdown 文档。
测试基于 supertest，jest，ts-jest 和 jest-esbuild。
ts-jest 提供了 ts 支持。只使用 ts-jest，现有的 16 个测试需要跑 10 秒左右。
jest-esbuild 提供了 esbuild 支持，使用后测试时间缩短到 4.5 秒左右。
项目内置了已有的路由和控制器的测试，可以在 __tests__ 文件夹内查看。
项目使用 release-it 更新版本号并完成后续部署工作。
- 管理设计篇之“部署升级策略”
- Production best practices: performance and reliability
- Express 部署最佳实践-安全篇
- 使用 pm2 实现自动化的多服务器部署--express application
WIP