███╗ ███╗ ██████╗ ██████╗ ████████╗ ██╗ ███████╗ ███████╗ ████╗ ████║ ██╔═══██╗ ██╔══██╗ ╚══██╔══╝ ██║ ██╔════╝ ██╔════╝ ██╔████╔██║ ██║ ██║ ██████╔╝ ██║ ██║ ███████╗ █████╗ ██║╚██╔╝██║ ██║ ██║ ██╔══██╗ ██║ ██║ ╚════██║ ██╔══╝ ██║ ╚═╝ ██║ ╚██████╔╝ ██║ ██║ ██║ ██║ ███████║ ███████╗ ╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═╝ ╚═╝ ╚═╝ ╚══════╝ ╚══════╝
现代化企业级后台管理脚手架
Mortise 是一款现代化、模块化的企业级后台管理脚手架项目，基于 Spring Boot 3.5.7 构建。采用多模块单体架构设计，集成了完整的认证授权、监控、缓存等企业级功能，开箱即用。
- 🏗️ 模块化设计 - 25 个模块、6 层依赖矩阵、12 组 SPI 可扩展接口
- 🚀 开箱即用 - Docker Compose 一键启动完整环境
- 🔒 安全可靠 - Spring Security 6 + JWT + OAuth2 多平台 + SMS 验证码 + 扫码登录
- 📊 可观测性 - 集成 Prometheus + Grafana 监控体系、自定义 DB/Redis 指标
- ⚡ 高性能 - MyBatis-Flex + Redis + JDK 21 虚拟线程
- 🛡️ 生产就绪 - Resilience4j
@RateLimit限流、Jasypt 加密、Flyway 数据库迁移 - 💬 微信集成 - 多账号公众号管理、消息路由、扫码登录、模板消息
- 📁 文件管理 - x-file-storage 统一存储、阿里云 OSS 适配、分片上传
💡 提示: 截图即将上线，敬请期待...
| 指标 | 数值 | 说明 |
|---|---|---|
| 🚀 启动时间 | < 10s | 应用冷启动到就绪 |
| 📦 内存占用 | ~300MB | 空闲状态 JVM 内存 |
| 🔥 QPS | 1000+ | 单机并发处理能力 |
| ⚡ 响应时间 | < 50ms | 平均 API 响应时间 |
| 💾 数据库连接池 | 10-20 | HikariCP 默认配置 |
| 🔴 Redis 命中率 | > 90% | 缓存命中率 |
📝 注: 以上数据基于 4C8G 服务器，实际性能因环境而异。
后端核心
- Spring Boot 3.5.7 - 主框架
- Spring Security 6 - 安全认证框架
- JWT (JJWT 0.12.5) - 无状态 Token 认证
- OAuth2 Client - GitHub / Google / Logto / 微信多平台登录
- MyBatis-Flex 1.11.0 - 轻量级 ORM 框架
- Redis 6.0+ - 缓存与会话存储
- PostgreSQL 17 - 主数据库（推荐）/ MySQL 8.0+
- Flyway - 数据库版本化迁移
微信生态
- WxJava - 微信公众号 / 开放平台 SDK
- 多账号管理 - 动态服务实例、配置热加载
文件存储
- x-file-storage - 统一文件管理框架
- 阿里云 OSS - 对象存储适配
监控与运维
- Spring Boot Actuator - 应用健康监控
- Prometheus + Micrometer - 时序指标收集
- Grafana - 可视化监控面板
- HikariCP - 高性能数据库连接池
安全与限流
- Resilience4j 2.2.0 -
@RateLimit注解限流（IP / 用户 / 方法 / SpEL） - Jasypt 3.0.5 - 配置文件加密
- Apache Commons - 工具库集合（Lang3, IO, Codec, Text, Collections4）
开发工具
- JDK 21 虚拟线程 - 异步任务默认执行器
- SpringDoc OpenAPI 2.8 - API 文档自动生成（Swagger UI）
- Lombok - 简化 Java 代码
- ULID Creator - 分布式唯一 ID 生成器
核心业务模块
- 用户管理 - 用户注册、登录、个人信息管理、密码修改
- 会员管理 - 会员注册、登录、个人资料、OAuth2 绑定、手机验证码登录
- 角色管理 - 角色定义、权限分配、角色层级
- 菜单管理 - 动态菜单加载、多级菜单支持、权限控制
- 权限管理 - 基于角色的访问控制（RBAC）、细粒度权限控制
- 字典管理 - 系统字典配置、字典缓存优化、
@DictFormat自动翻译
安全与认证
- JWT 认证 - 无状态 Token 认证、自动续期、Token 刷新
- Spring Security 集成 - 统一认证授权、方法级权限控制
- OAuth2 多平台登录 - 支持 GitHub、Google、Logto、微信等多平台，Strategy 模式可扩展
- 短信验证码登录 - 手机号 + 验证码认证，Redis 存储验证码
- 扫码登录 - 二维码生成、扫码确认、Spring Event 事件驱动
- 多用户表认证 - 系统用户 / 会员用户分表管理，
CustomUserDetailsServiceSPI 扩展 - 配置加密 - Jasypt 敏感配置加密存储
操作日志与审计
- 操作日志 -
@OperationLogAOP 注解、模块/操作类型/参数记录、异步写入 - API 日志 -
@ApiLog注解、请求/响应体/头信息记录、耗时统计 - 日志存储 SPI - 支持数据库存储、文件存储，可扩展自定义实现
- 客户端类型识别 - 责任链模式自动识别客户端类型
文件管理
- 文件上传下载 - 基于 x-file-storage 的统一文件管理
- 分片上传 - 大文件分片上传支持
- 文件元数据 - 文件详情数据库持久化、删除事件监听
- 对象存储适配 - 支持阿里云 OSS 等多种存储后端
通知系统
- 统一通知抽象 -
NotificationSenderSPI，支持多渠道扩展 - 邮件通知 - Spring Mail + Thymeleaf 模板引擎
- 微信模板消息 - 微信公众号模板消息推送
- 异步批量发送 - 支持异步发送和批量发送
微信集成
- 公众号管理 - 多账号管理、动态服务实例、配置热加载
- 消息路由 - 关注/取关/扫码/菜单/文本消息等事件路由
- 微信扫码登录 - 公众号扫码 + 微信开放平台扫码登录
- 模板消息 - 微信模板消息发送与管理
- 微信开放平台 - 第三方平台接入支持
缓存与性能
- 多级缓存 - 统一缓存抽象、Redis 实现、缓存过期策略
- SPI 架构 -
CacheConfigurer模块化缓存 TTL 注册、CacheExpirationHandler过期事件处理 - 缓存预热 - 应用启动时自动加载热点数据
- 键过期监听 - Redis Keyspace Notification 自动处理过期事件
API 文档
- SpringDoc OpenAPI 3 - 自动生成 API 文档
- 接口分组 - Admin / API 分组展示
- Swagger UI - 内置交互式 API 调试界面
监控与运维
- Actuator 集成 - 健康检查、应用指标、端点管理
- Prometheus 集成 - 指标导出、自定义指标、公共标签
- Grafana 可视化 - 实时监控面板、告警配置
- 数据库监控 - HikariCP 连接池监控、自定义数据库健康指标
- Redis 健康检查 - 自定义 Redis 连接健康指标
- 启动性能监控 - 应用启动耗时统计
限流与保护
- Resilience4j 限流 -
@RateLimit注解、多维限流策略（IP / 方法 / 用户 / SpEL） - 限流健康指标 - Resilience4j 限流器健康状态上报
数据持久化
- PostgreSQL 深度适配 - JSONB / Duration / StringList 自定义类型处理器
- Flyway 数据库迁移 - 版本化 SQL 迁移脚本
- MyBatis-Flex - 轻量级 ORM、FlexId 生成器
开发体验
- 模块化架构 - 清晰的 15+ 模块划分，6 层依赖矩阵
- SPI 可扩展 - 12 组 SPI 接口，支持模块化热插拔
- JDK 21 虚拟线程 - 异步任务默认使用虚拟线程
- 详细文档 - 50+ 技术文档、最佳实践指南
- Docker 支持 - 一键启动开发环境
- 工作流引擎 - Flowable 集成
- 多租户支持 - 租户隔离、数据隔离
- 支付集成 - 微信支付 / 支付宝（依赖已引入）
- 定时任务 - 定时任务调度
- 分布式事务 - Seata 集成
- 消息队列 - RocketMQ/Kafka 集成
- 全文搜索 - Elasticsearch 集成
- 微服务化 - Spring Cloud 改造方案
| 组件 | 版本要求 | 推荐版本 |
|---|---|---|
| Java | 21+ | Eclipse Temurin 21 |
| Maven | 3.6.0+ | 3.9.x |
| 数据库 | PostgreSQL 12+ / MySQL 8.0+ | PostgreSQL 17 |
| Redis | 6.0+ | 7.x |
| IDE | - | IntelliJ IDEA 2023+ |
| Git | 2.0+ | 最新版本 |
| 组件 | 版本要求 |
|---|---|
| Docker | 20.10+ |
| Docker Compose | 2.0+ |
最低配置
- CPU: 2 核心
- 内存: 4 GB
- 磁盘: 10 GB 可用空间
推荐配置
- CPU: 4 核心以上
- 内存: 8 GB 以上
- 磁盘: 20 GB 可用空间（包含 Docker 镜像）
- ✅ Windows 10/11
- ✅ macOS 11+
- ✅ Linux (Ubuntu 20.04+, CentOS 7+, Debian 10+)
适合快速体验和开发环境，一键启动包含数据库、Redis、Nginx 等完整服务。
# HTTPS
git clone https://github.com/rymcu/mortise.git
cd mortise
# SSH
git clone [email protected]:rymcu/mortise.git
cd mortise# Windows (以管理员身份运行 PowerShell)
.\update_hosts.bat
# macOS/Linux
sudo ./update_hosts.sh添加的域名映射：
127.0.0.1 rymcu.local
127.0.0.1 npm.rymcu.local
127.0.0.1 auth.rymcu.local
127.0.0.1 logto.rymcu.local
# 启动服务（首次启动会下载镜像，需要几分钟）
docker-compose up -d
# 查看启动日志
docker-compose logs -f
# 检查服务状态
docker-compose ps| 服务 | 地址 | 说明 |
|---|---|---|
| 🌐 应用主页 | http://localhost:9999 | 主应用服务 |
| 📊 Actuator | http://localhost:9999/mortise/actuator | 监控端点 |
| 🗄️ PostgreSQL | localhost:5432 | 数据库（用户: mortise, 密码: mortise） |
| 🔴 Redis | localhost:6379 | 缓存服务 |
| 🌐 Nginx | http://localhost:80 | 反向代理 |
# 停止服务
docker-compose stop
# 停止并删除容器
docker-compose down
# 停止并删除容器、网络、卷
docker-compose down -v适合日常开发调试，需要手动配置环境。
# 检查 Java 版本（需要 21+）
java -version
# 检查 Maven 版本（需要 3.6+）
mvn -version
# 检查 PostgreSQL（需要安装并启动）
psql --version
# 检查 Redis（需要安装并启动）
redis-cli --version-- 连接 PostgreSQL
psql -U postgres
-- 创建数据库
CREATE DATABASE mortise;
-- 创建用户
CREATE USER mortise WITH PASSWORD 'your_password';
-- 授权
GRANT ALL PRIVILEGES ON DATABASE mortise TO mortise;
-- 退出
\q# Windows (需要先安装 Redis)
redis-server
# macOS
brew services start redis
# Linux
sudo systemctl start redis
# 或
redis-server编辑配置文件 mortise-app/src/main/resources/application-dev.yml：
spring:
datasource:
url: jdbc:postgresql://localhost:5432/mortise
username: mortise
password: your_password
data:
redis:
host: localhost
port: 6379
# password: your_redis_password # 如有密码# 清理并编译
mvn clean install -DskipTests
# 或只编译
mvn clean package -DskipTests# 方式 1: 使用 Maven 启动
cd mortise-app
mvn spring-boot:run
# 方式 2: 使用 jar 包启动
java -jar mortise-app/target/mortise-app-0.2.0.jar
# 方式 3: 指定配置文件启动
java -jar mortise-app/target/mortise-app-0.2.0.jar --spring.profiles.active=dev# 健康检查（需要先登录获取 Token）
curl http://localhost:9999/mortise/actuator/health
# 或在浏览器访问
http://localhost:9999/mortise/actuator在 IDE 中启动：
- 导入项目到 IntelliJ IDEA
- 找到
MortiseApplication.java - 右键 → Run 'MortiseApplication'
- 开启 IDEA 的 Build Project Automatically 实现热重载
适合生产环境部署。
# 生产环境打包
mvn clean package -Pprod -DskipTests
# 生成的 jar 包位置
ls -lh mortise-app/target/mortise-app-0.2.0.jar# 构建镜像
docker build -t mortise:latest .
# 运行容器
docker run -d \
--name mortise-app \
-p 9999:9999 \
-e SPRING_PROFILES_ACTIVE=prod \
-e SPRING_DATASOURCE_URL=jdbc:postgresql://db-host:5432/mortise \
-e SPRING_DATASOURCE_USERNAME=mortise \
-e SPRING_DATASOURCE_PASSWORD=your_password \
-e SPRING_DATA_REDIS_HOST=redis-host \
mortise:latest
# 查看日志
docker logs -f mortise-app创建服务文件 /etc/systemd/system/mortise.service：
[Unit]
Description=Mortise Application
After=network.target
[Service]
Type=simple
User=mortise
WorkingDirectory=/opt/mortise
ExecStart=/usr/bin/java -jar /opt/mortise/mortise-app.jar
Restart=on-failure
RestartSec=10
[Install]
WantedBy=multi-user.target启动服务：
# 重载配置
sudo systemctl daemon-reload
# 启动服务
sudo systemctl start mortise
# 开机自启
sudo systemctl enable mortise
# 查看状态
sudo systemctl status mortise启动失败：数据库连接错误
问题: Connection refused 或 Authentication failed
解决:
- 检查数据库是否启动：
psql -U postgres - 检查用户名密码是否正确
- 检查数据库是否已创建：
\l查看数据库列表 - 检查防火墙是否开放 5432 端口
启动失败：Redis 连接错误
问题: Could not connect to Redis
解决:
- 检查 Redis 是否启动：
redis-cli ping（应返回 PONG） - 检查配置文件中的 Redis 地址和端口
- 如果有密码，确保配置了正确的密码
Docker 启动慢
问题: docker-compose up 长时间无响应
解决:
- 首次启动需要下载镜像，耐心等待
- 使用国内镜像加速器
- 查看具体日志：
docker-compose logs -f
端口被占用
问题: Port 9999 is already in use
解决:
- 修改
application.yml中的端口号 - 或停止占用端口的进程：
- Windows:
netstat -ano | findstr 9999 - Linux/Mac:
lsof -i :9999
- Windows:
应用启动后，可通过以下方式访问监控端点：
# PowerShell
$response = Invoke-RestMethod -Uri "http://localhost:9999/mortise/api/v1/auth/login" `
-Method Post `
-ContentType "application/json" `
-Body '{"account":"your_account","password":"your_password"}'
$token = $response.data.token
# Bash/cURL
curl -X POST http://localhost:9999/mortise/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{"account":"your_account","password":"your_password"}'# PowerShell
Invoke-RestMethod -Uri "http://localhost:9999/mortise/actuator/health" `
-Headers @{ Authorization = "Bearer $token" }
# Bash/cURL
curl -H "Authorization: Bearer <token>" \
http://localhost:9999/mortise/actuator/health| 端点 | 描述 | URL | 认证 |
|---|---|---|---|
| 🏥 健康检查 | 应用整体健康状态、组件状态 | /mortise/actuator/health |
✅ |
| ℹ️ 应用信息 | 版本、环境、构建信息 | /mortise/actuator/info |
✅ |
| 📈 性能指标 | JVM、系统、应用指标 | /mortise/actuator/metrics |
✅ |
| 📊 Prometheus | Prometheus 格式指标导出 | /mortise/actuator/prometheus |
✅ |
| 📝 端点列表 | 所有可用 Actuator 端点 | /mortise/actuator |
✅ |
| 🗃️ 数据库 | 数据库连接池状态 | /mortise/actuator/metrics/hikaricp.* |
✅ |
| 🔧 配置属性 | 应用配置信息 | /mortise/actuator/configprops |
✅ |
| 🌿 环境变量 | 系统环境和配置 | /mortise/actuator/env |
✅ |
💡 提示: 所有端点都需要 JWT Token 认证
# prometheus.yml
global:
scrape_interval: 15s
evaluation_interval: 15s
scrape_configs:
- job_name: 'mortise-application'
metrics_path: '/mortise/actuator/prometheus'
static_configs:
- targets: ['localhost:9999']
# JWT 认证配置
bearer_token: 'your_jwt_token'
# 或使用文件
# bearer_token_file: '/path/to/token.txt'JVM 指标
jvm_memory_used_bytes{area="heap"} # 堆内存使用量
jvm_memory_max_bytes{area="heap"} # 堆内存最大值
jvm_gc_pause_seconds_sum # GC 总耗时
jvm_threads_live_threads # 活跃线程数
数据库连接池
hikaricp_connections_active # 活跃连接数
hikaricp_connections_idle # 空闲连接数
hikaricp_connections_pending # 等待连接数
hikaricp_connections_timeout_total # 连接超时次数
HTTP 请求
http_server_requests_seconds_count # 请求总数
http_server_requests_seconds_sum # 请求总耗时
http_server_requests_seconds_max # 最大响应时间
系统指标
system_cpu_usage # 系统 CPU 使用率
process_cpu_usage # 进程 CPU 使用率
system_load_average_1m # 系统负载
- Spring Boot 2.1 Statistics (Dashboard ID: 6756)
- JVM (Micrometer) (Dashboard ID: 4701)
- Spring Boot APM Dashboard (Dashboard ID: 12900)
导入方式：Grafana → Dashboards → Import → 输入 Dashboard ID
# 清理编译
mvn clean install
# 跳过测试编译
mvn clean install -DskipTests
# 运行测试
mvn test
# 打包应用
mvn package
# 运行应用
mvn spring-boot:run
# 查看依赖树
mvn dependency:tree
# 更新依赖
mvn versions:display-dependency-updates# 启动所有服务
docker-compose up -d
# 查看日志
docker-compose logs -f [service_name]
# 停止服务
docker-compose stop
# 重启服务
docker-compose restart [service_name]
# 删除容器和网络
docker-compose down
# 删除容器、网络和卷
docker-compose down -v
# 重新构建镜像
docker-compose build --no-cache
# 查看服务状态
docker-compose ps# 克隆项目
git clone https://github.com/rymcu/mortise.git
# 创建功能分支
git checkout -b feature/your-feature
# 提交更改
git add .
git commit -m "feat: your feature description"
# 推送到远程
git push origin feature/your-feature
# 同步上游
git fetch upstream
git rebase upstream/master# 连接 Redis
redis-cli
# 查看所有键
KEYS *
# 查看键值
GET key_name
# 删除键
DEL key_name
# 清空数据库
FLUSHDB
# 查看内存使用
INFO memory# 连接数据库
psql -U mortise -d mortise
# 查看所有表
\dt
# 查看表结构
\d table_name
# 执行 SQL 文件
\i path/to/file.sql
# 导出数据库
pg_dump -U mortise mortise > backup.sql
# 导入数据库
psql -U mortise mortise < backup.sql项目包含 50+ 份详细技术文档，位于 docs/ 目录。
- 架构说明 - 分层与模块职责
- 项目架构优化 - 整体架构设计
- 模块依赖与 SPI 架构 - 模块化设计原则
- 架构重构计划 - 重构路线图
查看完整文档列表：docs/migration/MIGRATION_INDEX.md
mortise/ # 父 POM，版本管理与模块聚合
├── mortise-common/ # L1 公共模块 - 通用工具类（ULID/BeanCopier）、异常体系、枚举常量
├── mortise-core/ # L1 核心模块 - 统一返回 GlobalResult、CurrentUser SPI、JDK21 虚拟线程、Jasypt 加密
├── mortise-log/ # L2 日志模块 - @OperationLog/@ApiLog AOP 注解、LogStorage SPI、ClientTypeResolver 责任链
├── mortise-cache/ # L2 缓存模块 - CacheService 统一抽象、Redis 实现、CacheConfigurer/CacheExpirationHandler SPI
├── mortise-notification/ # L2 通知模块 - NotificationSender SPI、邮件/微信模板消息、异步批量发送
├── mortise-persistence/ # L2 持久化模块 - MyBatis-Flex 配置、PostgreSQL JSONB/Duration 类型处理器、数据库日志存储
├── mortise-auth/ # L3 认证模块 - JWT、Spring Security 6、OAuth2 多平台、短信/扫码登录、多用户表
├── mortise-web-support/ # L3 Web 支撑 - @AdminController/@ApiController、GlobalExceptionHandler、@RateLimit、OpenAPI
├── mortise-monitor/ # L3 监控模块 - Actuator 端点安全、Prometheus 指标、DB/Redis 健康检查
├── mortise-file/ # L3 文件模块 - x-file-storage 集成、阿里云 OSS、分片上传、文件元数据管理
├── mortise-wechat/ # L3 微信模块 - 多账号公众号管理、消息路由、扫码登录、模板消息、开放平台接入
├── mortise-test-support/ # 测试支撑 - 共享测试配置与工具
├── mortise-system/ # 系统域聚合（DDD 分层）
│ ├── mortise-system-domain/ # L4 领域层 - User/Role/Menu/Dict/DictType 实体、@DictFormat 注解
│ ├── mortise-system-infra/ # L4 基础设施层 - Mapper 接口、SystemCacheConfigurer、日志存储实现
│ ├── mortise-system-application/ # L4 应用层 - UserService/AuthService/RoleService 等、事件驱动（登录/注册/重置密码）
│ ├── mortise-system-admin/ # L5 管理端 API - 系统管理 REST 接口、DictSerializer 字典翻译、SecurityConfigurer
│ └── mortise-system-api/ # L5 公共 API（预留扩展）
├── mortise-member/ # 会员域聚合（DDD 分层）
│ ├── mortise-member-domain/ # L4 领域层 - Member/MemberOAuth2Binding 实体
│ ├── mortise-member-infra/ # L4 基础设施层 - Mapper 接口
│ ├── mortise-member-application/ # L4 应用层 - MemberService、OAuth2 绑定服务
│ ├── mortise-member-admin/ # L5 管理端 API - 会员管理 REST 接口
│ └── mortise-member-api/ # L5 公共 API - 会员注册/登录/OAuth2/文件上传接口、MemberDetailsService
└── mortise-app/ # L6 应用装配 - Spring Boot 启动入口、Flyway 迁移、多环境配置
flowchart TB
subgraph L6[L6 应用层]
app[mortise-app<br/><i>Spring Boot 启动 · Flyway</i>]
end
subgraph L5[L5 业务域 API]
sysAdmin[mortise-system-admin]
sysApi[mortise-system-api]
memAdmin[mortise-member-admin]
memApi[mortise-member-api]
end
subgraph L4[L4 业务域应用与基础设施]
sysApp[mortise-system-application]
sysInfra[mortise-system-infra]
memApp[mortise-member-application]
memInfra[mortise-member-infra]
sysDomain[mortise-system-domain]
memDomain[mortise-member-domain]
end
subgraph L3[L3 应用基础层]
auth[mortise-auth<br/><i>JWT · OAuth2 · SMS · QR</i>]
webSupport[mortise-web-support<br/><i>@RateLimit · OpenAPI</i>]
monitor[mortise-monitor<br/><i>Actuator · Prometheus</i>]
file[mortise-file<br/><i>x-file-storage · OSS</i>]
wechat[mortise-wechat<br/><i>公众号 · 开放平台</i>]
end
subgraph L2[L2 基础设施层]
log[mortise-log<br/><i>@OperationLog · @ApiLog</i>]
cache[mortise-cache<br/><i>Redis · SPI</i>]
notify[mortise-notification<br/><i>邮件 · 微信</i>]
persistence[mortise-persistence<br/><i>MyBatis-Flex · JSONB</i>]
end
subgraph L1[L1 核心层]
common[mortise-common<br/><i>工具 · 异常 · 枚举</i>]
core[mortise-core<br/><i>GlobalResult · 虚拟线程</i>]
end
app --> sysAdmin & sysApi & memAdmin & memApi
app --> auth & webSupport & monitor & file & wechat
sysAdmin --> sysApp
sysApi --> sysApp
memAdmin --> memApp
memApi --> memApp
sysApp --> sysDomain & sysInfra
memApp --> memDomain & memInfra
sysInfra --> persistence & log & cache
memInfra --> persistence
wechat --> auth & cache & notify & webSupport
file --> auth
auth --> core & cache & persistence
webSupport --> core & log & auth
monitor --> common
log --> core
cache --> common
notify --> common
persistence --> log
core --> common
| 层级 | 允许依赖 |
|---|---|
| L6 应用层 | L1-L5 全部模块 |
| L5 业务域 API | L3-L4 与本域 domain/application/infra |
| L4 业务域应用与基础设施 | L1-L3 与本域 domain |
| L3 应用基础层 | L1-L2 |
| L2 基础设施层 | L1 |
| L1 核心层 | 无 |
🎯 SPI 架构设计（12 组 SPI 接口）
项目全面采用 SPI（Service Provider Interface）机制，实现模块间松耦合与热插拔扩展：
| SPI 接口 | 所属模块 | 用途 | 已有实现 |
|---|---|---|---|
LogStorage |
mortise-log | 日志存储策略 | DatabaseLogStorage、SystemLogStorage |
ClientTypeResolver |
mortise-log | 客户端类型识别 | DefaultClientTypeResolver |
CacheConfigurer |
mortise-cache | 模块缓存 TTL 注册 | SystemCacheConfigurer、AuthCacheConfigurer |
CacheExpirationHandler |
mortise-cache | 缓存过期事件处理 | UserOnlineStatusExpirationHandler |
SecurityConfigurer |
mortise-auth | 模块安全规则注册 | System/App/Web/Monitor/File/WeChat 共 6 个实现 |
CustomUserDetailsService |
mortise-auth | 多用户表认证 | UserDetailsServiceImpl、MemberDetailsServiceImpl |
UserTypeResolver |
mortise-auth | 用户类型识别 | DefaultUserTypeResolver |
OAuth2ProviderStrategy |
mortise-auth | OAuth2 平台适配 | GitHub/Google/WeChat/Logto 共 4 个实现 |
OAuth2LoginSuccessHandlerProvider |
mortise-auth | OAuth2 登录成功处理 | System/Api 共 2 个实现 |
NotificationSender |
mortise-notification | 通知渠道扩展 | EmailNotificationSender、WeChatNotificationSender |
JacksonConfigurer |
mortise-web-support | Jackson 序列化扩展 | DictJacksonConfigurer |
CurrentUser |
mortise-core | 当前用户抽象 | UserDetailInfo、MemberDetailInfo |
🔄 缓存过期策略
- 统一过期时间管理（
CacheConfigurerSPI 每模块独立注册） - Redis Keyspace Notification 监听键过期
CacheExpirationHandlerSPI 自动分发过期事件
📊 可观测性
- Spring Boot Actuator 端点 + JWT 安全保护
- Prometheus 指标导出 + 公共标签
- HikariCP 连接池 / Redis / DB 自定义健康指标
- 应用启动耗时监控
🛡️ 安全保障
- JWT Token 认证 + Token 刷新
- OAuth2 多平台登录（GitHub / Google / Logto / 微信）
- SMS 验证码登录 + 扫码登录
- Spring Security 方法级权限控制
- Jasypt 配置加密
- Resilience4j
@RateLimit注解限流（IP / 用户 / 方法 / SpEL）
⚡ 高性能设计
- JDK 21 虚拟线程作为默认异步执行器
- MyBatis-Flex 轻量级 ORM + PostgreSQL JSONB 原生支持
- Redis 缓存 + 键过期自动处理
- Flyway 版本化数据库迁移
我们欢迎并感谢任何形式的贡献！
- 在 GitHub Issues 创建 Issue
- 清晰描述问题、重现步骤、期望行为
- 提供错误日志、截图等相关信息
- 在 GitHub Discussions 发起讨论
- 说明功能的使用场景和价值
- 提供参考实现或设计思路
-
Fork 项目
# Fork 后克隆到本地 git clone https://github.com/YOUR_USERNAME/mortise.git cd mortise
-
创建功能分支
git checkout -b feature/amazing-feature # 或修复分支 git checkout -b fix/bug-description -
编写代码
- 遵循项目代码规范
- 添加必要的注释和文档
- 编写单元测试
-
提交变更
git add . git commit -m 'feat: add amazing feature' # 使用 Conventional Commits 规范
-
同步上游代码
git remote add upstream https://github.com/rymcu/mortise.git git fetch upstream git rebase upstream/master
-
推送到 GitHub
git push origin feature/amazing-feature
-
创建 Pull Request
- 访问 GitHub 仓库页面
- 点击 "New Pull Request"
- 填写 PR 描述、关联 Issue
- 等待代码审查
代码风格
- 遵循 阿里巴巴 Java 开发手册
- 使用 IDE 格式化工具（提供配置文件）
- 类、方法添加 Javadoc 注释
提交信息规范
使用 Conventional Commits 格式：
<type>(<scope>): <subject>
<body>
<footer>
Type 类型：
feat: 新功能fix: Bug 修复docs: 文档变更style: 代码格式（不影响功能）refactor: 重构（不增加功能不修复 Bug）perf: 性能优化test: 测试相关chore: 构建工具、依赖管理
示例：
feat(auth): add password encryption support
- Implement BCrypt password encoder
- Add password strength validation
- Update user registration flow
Closes #123测试要求
- 新功能必须包含单元测试
- 测试覆盖率不低于 70%
- 确保所有测试通过
文档要求
- 新功能需要更新相关文档
- API 变更需要更新接口文档
- 重要变更需要在 CHANGELOG.md 记录
所有 Pull Request 都需要经过代码审查：
- 至少 1 位维护者审批
- 通过所有 CI 检查
- 解决所有审查意见
- 保持提交历史清晰
| 渠道 | 用途 | 响应时间 |
|---|---|---|
| 📖 技术文档 | 查阅详细文档 | 即时 |
| 🐛 GitHub Issues | Bug 报告、问题追踪 | 1-3 天 |
| 💡 GitHub Discussions | 功能建议、技术讨论 | 3-7 天 |
| 商务合作、私密问题 | 7 天内 |
- 官方网站: https://rymcu.com
- 在线演示: 即将上线
- API 文档: 开发中
- 视频教程: 计划中
Q: 支持哪些数据库？
A: 目前支持 PostgreSQL（推荐）和 MySQL。推荐使用 PostgreSQL 17，性能和功能更完善。
Q: 可以用于商业项目吗？
A: 可以。本项目基于 MIT 协议，可免费用于商业项目。
Q: 如何升级 Spring Boot 版本？
A: 修改 pom.xml 中的 spring-boot-starter-parent 版本，然后执行 mvn clean install 测试兼容性。
Q: 监控端点需要认证吗？
A: 是的。所有 Actuator 端点都需要 JWT Token 认证，确保生产环境安全。
Q: 如何自定义缓存实现？
A: 实现 CacheConfigurer 接口注册模块缓存 TTL，或实现 CacheExpirationHandler 处理过期事件。参考 缓存过期 SPI 指南。
| 版本 | 发布日期 | 主要更新 |
|---|---|---|
| v0.0.1 | 2024-09-24 | 🎉 首次发布：核心功能、基础架构 |
| v0.2.0 | 2025-12 | 🚀 全面功能完善：OAuth2 多平台、微信集成、文件管理、日志审计、通知系统、SPI 架构 |
v0.0.1 (✅ 已完成)
├─ 用户、角色、菜单管理
├─ JWT 认证授权
├─ Redis 缓存集成
├─ Actuator 监控
└─ 基础文档
v0.2.0 (✅ 已完成)
├─ 操作日志 (@OperationLog/@ApiLog AOP + SPI 存储)
├─ 文件上传管理 (x-file-storage + 阿里云 OSS)
├─ SpringDoc OpenAPI 3 API 文档
├─ 通知系统 (邮件 + 微信模板消息 SPI)
├─ OAuth2 多平台登录 (GitHub/Google/Logto/微信)
├─ 短信验证码 / 扫码登录
├─ 微信公众号 & 开放平台集成
├─ 会员模块 (DDD 分层)
├─ Resilience4j @RateLimit 注解限流
├─ 12 组 SPI 接口完整实现
├─ JDK 21 虚拟线程 & 性能优化
├─ Prometheus + Grafana 监控体系
└─ PostgreSQL JSONB / Flyway 数据库迁移
v0.3.0 (📋 计划中 - 预计 Q2 2026)
├─ 支付集成 (微信支付 / 支付宝)
├─ 工作流引擎 (Flowable)
├─ 多租户支持
├─ 前端管理界面
└─ 单元测试覆盖提升
v1.0.0 (🎯 目标 - 预计 Q4 2026)
├─ 生产就绪认证
├─ 完整测试覆盖
├─ 性能基准测试
├─ 安全加固
└─ 详尽使用手册
v2.0.0 (💡 展望)
├─ 微服务架构 (Spring Cloud)
├─ 消息队列 (RocketMQ/Kafka)
├─ 分布式事务 (Seata)
├─ 全文搜索 (Elasticsearch)
└─ 大数据分析
本项目基于 MIT License 开源协议。
MIT License
Copyright (c) 2024 RYMCU
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction...
✅ 商业使用
✅ 修改
✅ 分发
✅ 私人使用
感谢所有为本项目做出贡献的开发者：
本项目基于以下优秀的开源项目构建：
- Spring Boot - 应用框架
- Spring Security - 安全框架
- MyBatis-Flex - ORM 框架
- Redis - 缓存数据库
- PostgreSQL - 关系型数据库
- Resilience4j - 容错库
- Prometheus - 监控系统
- Grafana - 可视化平台
- 感谢 JetBrains 提供的开源许可证
- 感谢所有提供反馈和建议的用户
| 资源 | 链接 | 描述 |
|---|---|---|
| 🏠 项目主页 | GitHub | 源代码仓库 |
| 📖 文档中心 | Docs | 完整技术文档 |
| 🐛 问题追踪 | Issues | Bug 报告与功能请求 |
| 💬 讨论区 | Discussions | 技术讨论与交流 |
| 📝 变更日志 | Releases | 版本发布记录 |
| 👥 贡献者 | Contributors | 项目贡献者列表 |
| 📊 代码统计 | Insights | 项目活跃度统计 |