基于Midwayjs的管理系统-快速了解

J_TsMask
852 阅读5分钟

基于Midwayjs的管理系统-快速了解

本文用于快速了解本项目的定位、技术栈、开发与部署方式，帮助你尽快上手并进入业务开发。

项目简介

本项目是基于 RuoYi-Vue 后端体系重构的管理系统 API 服务。
当前主版本为 v0.7.x，核心目标是保持中后台系统的常见能力（权限、日志、监控、调度、数据权限等）的同时，采用 Node.js + TypeScript 进行工程化实现。

当前技术栈

  • 运行时：Node.js >= 24.0.0
  • 后端框架：MidwayJS 4.x（@midwayjs/* 4.1.0）
  • 类型与构建：TypeScript 6.0.3，构建工具 mwtsc
  • 数据库：MySQL 8+，ORM 使用 TypeORM 0.3.x
  • 缓存与队列：Redis 6+，任务队列 BullMQ
  • 接口协议：RESTful HTTP，权限与安全能力通过 MidwayJS 注解和中间件实现

项目能力概览

系统内置以下典型后台能力：

  1. 用户管理
  2. 部门管理
  3. 岗位管理
  4. 菜单与按钮权限管理
  5. 角色管理与数据权限
  6. 字典管理
  7. 参数管理
  8. 通知公告
  9. 操作日志与异常日志
  10. 登录日志
  11. 在线用户监控
  12. 调度任务管理
  13. 服务监控
  14. 缓存监控

这些能力主要用于中后台系统的账号、权限、监控和运营配置场景。

环境变量与配置说明

项目当前采用 .env 方式管理运行时环境变量，并已拆分为以下文件：

  • .env.example：可提交到 Git 的示例模板，用于说明变量结构
  • .env.development：本地开发配置（含真实本地账号信息，不提交）
  • .env.production：生产环境配置（含生产账号信息，不提交）

典型变量包括：

  • 服务端口：PORT
  • JWT 配置：JWT_SECRET、JWT_EXPIRES_IN、JWT_REFRESH_EXPIRES_IN
  • MySQL 配置：DB_HOST、DB_PORT、DB_USERNAME、DB_PASSWORD、DB_DATABASE
  • Redis 配置：REDIS_HOST、REDIS_PORT、REDIS_PASSWORD、REDIS_DB

应用层业务配置统一放在 src/config 目录：

  • config.default.ts：公共默认配置
  • config.local.ts：本地开发差异配置
  • config.unittest.ts：测试环境差异配置

说明：.env 主要承载数据库、Redis、JWT 等外部运行依赖信息，便于不同环境独立维护。

快速开始

1. 安装依赖

npm install

2. 准备环境配置

复制示例文件并生成本地开发配置：

cp .env.example .env.development

随后填写本地 MySQL、Redis、JWT 等真实参数。

3. 初始化数据库

数据库初始化脚本位于 script 目录，可使用：

  • script/db_init.sql
  • script/db_init_demo.sql

请根据实际业务需要选择执行。

4. 本地开发启动

npm run dev

默认端口通常为 6275，启动成功后可访问本地接口服务进行联调。

构建与生产部署

构建

npm run build

当前项目已完成 TypeScript 构建问题修复， pm run build 应处于可用状态。

生产启动

npm run start

若使用 PM2：

npm run start:pm2

生产环境请提前准备好 .env.production，并确保数据库与 Redis 已就绪。

常用命令

# 本地开发
npm run dev

# 构建
npm run build

# 单元测试
npm run test

# 测试覆盖率
npm run cov

# 代码检查
npm run lint

# 自动修复格式问题
npm run lint:fix

目录结构简要说明

项目主目录结构如下：

src
├── config          应用与业务配置
├── framework       核心框架能力（中间件、异常处理、工具、Token等）
├── modules         业务模块（system / monitor / auth / common / demo）
├── typings         通用类型定义
├── configuration.ts 程序启动与中间件注册入口
└── interface.ts    公共接口声明
script              初始化脚本与运维脚本
docs                项目文档
test                测试代码
dist                构建产物

modules 下一般按功能域拆分，每个模块内部通常包含：

  • controller：接口层
  • service：业务逻辑层
  • model：实体/数据结构定义

epository：数据访问层

前后端协作说明

前端仓库通常包括：

  • Vue3 + Element 版本前端
  • Vue3 + Ant Design 版本前端

本仓库为后端 API 服务，主要职责：

  • 提供 REST 接口
  • 处理鉴权与权限控制
  • 管理系统基础数据
  • 承接日志、监控、调度等后台能力

学习建议

如果你是第一次接触本项目，建议按以下顺序了解：

  1. 先看 .env.example 与 src/config，理解配置来源
  2. 再看 src/configuration.ts，理解应用启动与中间件链
  3. 再进入 src/modules/system，理解业务分层
  4. 最后结合 script 与部署文档完成环境搭建

这样可以快速建立“配置 -> 启动 -> 业务 -> 部署”的完整认知路径。

常见问题

为什么使用 .env 拆分而不是单文件？

为了将敏感信息（数据库、Redis、JWT Secret）从代码仓库中隔离出去。
.env.example 用于模板说明，.env.development 与 .env.production 用于实际环境运行。

为什么部分文档与 README 细节可能不完全一致？

项目经历了版本升级与结构调整，当前以代码实际状态为准。
若文档与代码冲突，优先以源码、package.json、 sconfig.json 和实际可运行命令为准。

建议的排查顺序是什么？

  1. 先确认 Node 版本是否满足 >= 24.0.0
  2. 再确认 .env.development 是否完整
  3. 然后执行 pm run build
  4. 最后执行 pm run dev

若构建通过但启动失败，通常为数据库、Redis 连接或 JWT 配置问题。

结语

本文档目标是帮助你用最短时间理解项目全貌并跑通本地开发。
如果你需要进一步了解部署、目录手册或接口设计，可继续阅读项目中的对应专题文档。

avatar
文章
阅读
粉丝