（工程基线与通用能力集合，而非通用后台系统）
这是一个在真实项目中反复使用和调整过的 Spring Boot 微服务工程脚手架， 主要用于解决新项目启动阶段工程结构混乱、基础能力重复建设的问题。
这个仓库里已经准备好了我在项目中最常用的一些工程基础，包括： 一套相对稳定的微服务目录结构和模块拆分方式 常见基础能力的工程化实现（缓存、幂等、认证等） 新建业务服务时可以直接复用的模板和约定
FrameworkJava 是我在多个项目中反复使用的一套基于 Spring Boot 3.x + Spring Cloud 2023 的 微服务工程脚手架（Scaffold）。
这个项目一开始只是我自己用来起新服务的一套工程骨架。
后来项目多了，每个项目里都会重复用到一些东西， 比如网关、认证、缓存、幂等、日志、链路追踪、服务监控等， 就干脆把这些部分慢慢拆出来，整理成现在这个结构。
⚠️ 适合人群
- ✅ 具备 Spring Boot / Spring Cloud 基础的开发者
- ✅ 希望快速落地微服务工程架构的团队
- ✅ 需要统一工程规范与公共能力沉淀的项目
⚠️ 不适合
- ❌ 完全零基础的 Java 初学者
- ❌ 仅需简单单体应用的项目
FrameworkJava 本身并不是一个可以直接上线使用的后台系统，这一点在一开始用的时候就刻意控制住了。
它更多是用来当一个工程起点，哪些业务要做、做到什么程度，还是应该由具体项目自己决定。
- ✅ 微服务工程结构与模块拆分规范
- ✅ 通用基础能力组件（缓存、幂等、认证、消息、文件抽象等）
- ✅ 新业务服务的标准模板与参考实现
- ✅ 可直接复用的工程实践与设计模式
- ❌ 统一的用户 / 组织 / 菜单 / 权限业务模型
- ❌ 固定的后台功能集合
- ❌ 面向所有公司的通用业务表结构
实际用下来，不同项目之间差异最大的往往就是这两块：
- 组织结构怎么划
- 权限到底要细到什么程度
这些东西如果在脚手架阶段就定死，后续基本都会被推翻重来。
- 工程化优先：关注项目结构、模块边界和长期可维护性，而不是单纯堆砌功能
- 能力下沉：公共能力尽量集中到基础模块，业务服务保持轻量
- 模块解耦：服务间通过清晰接口协作，减少隐式依赖
- 可裁剪性：示例业务模块仅作参考，可根据需要删除或替换
Docker Compose 一键部署所有中间件（MySQL、Redis、Nacos、RabbitMQ、SkyWalking、Prometheus、Grafana、AlertManager、XXL-JOB Admin），支持 dev/test/prd 多环境配置， 快速搭建完整开发环境，告别繁琐的环境配置
JWT 无状态认证，网关统一校验，支持 B 端 / C 端用户体系，开箱即用的安全方案
布隆过滤器 + Caffeine 本地缓存 + Redis 分布式缓存，有效防止缓存穿透，降低数据库压力 （支持 Redis/Fast/Safe 三种布隆过滤器实现，本地缓存支持自定义过期策略，非简单封装）
基于 AOP + Redis 的幂等性方案，支持 HTTP / MQ 场景，针对高并发做了专项优化，保障数据一致性 （支持防重模式/强幂等模式，Redis + Lua 脚本保证原子性，支持并发穿透控制）
基于 MyBatis 拦截器的数据权限方案，支持本人/本部门/本部门及子部门/全部/自定义五种权限类型，自动过滤 SQL，零侵入实现数据隔离 （支持多租户隔离、自定义字段、表别名，适用于 SaaS 系统和企业内部系统）
无侵入式链路追踪，自动追踪微服务间的调用链路，支持性能分析、慢查询定位、服务拓扑图、日志关联 TraceId （基于 Java Agent，零代码侵入，支持 HTTP、RPC、数据库、缓存、消息队列全链路追踪）
基于 XXL-JOB 的分布式调度体系，zmbdp-common-xxljob 提供执行器自动配置，引入依赖即注册，无需重复编写初始化代码。
内置布隆过滤器每日重置 Handler（ResetBloomFilterJobHandler），使用 Redisson 分布式锁保证多实例安全，并提供 Spring Scheduled 降级兜底方案。
zmbdp-mstemplate 提供简单任务和分片广播任务两种完整示例，新业务接入只需添加 @XxlJob 注解。
实时监控 JVM、接口、数据库、缓存、系统资源，Grafana 可视化大盘，多级别智能告警（邮件/钉钉/短信） （30+ 监控指标，10+ 告警规则，开箱即用的监控大盘，支持自定义扩展）
API / Service 分离，公共能力集中到基础模块， 新业务模块接入时只需关注自身领域逻辑。
FrameworkJava 集成了 20 多个常用工具类，涵盖复杂泛型BeanCopy、加密、JSON、Excel、邮件、分页、流处理等功能。 同时提供 三套策略模式实现，支持登录流程、验证码发送、账号校验等场景。
基础业务能力也已工程化实现，包括用户管理、配置管理、文件处理、消息处理等模块。 这些工具和能力都是从真实项目中沉淀出来的，开箱即用， 能够在新业务开发中直接复用，避免重复造轮子，帮助团队快速启动并保持工程规范。
frameworkjava
├── zmbdp-gateway # 网关服务（工程必选）
├── zmbdp-common # 公共基础能力模块（工程必选）
├── zmbdp-admin # 业务示例：管理端参考实现
├── zmbdp-portal # 业务示例：门户参考实现
├── zmbdp-file # 业务示例：文件服务参考实现
└── zmbdp-mstemplate # 微服务模板（规范示例）
说明 admin / portal / file 等模块主要用于演示：
- 脚手架在实际业务中的落地方式
- 业务分层、接口设计、领域拆分的参考实现
它们不是脚手架的必选部分，可以根据实际项目自由裁剪或替换。
完整结构说明：见 docs/PROJECT_STRUCTURE.md
- JDK 17+
- Maven 3.6+
- Docker & Docker Compose
git clone https://github.com/zmbdp/frameworkjava.git
cd frameworkjavacd deploy/dev/app
docker compose -p frameworkjava -f docker-compose-mid.yml up -d等待 30-60 秒后，访问以下地址验证：
- Nacos 控制台：http://localhost:8848/nacos
- RabbitMQ 管理界面：http://localhost:15672
- SkyWalking UI 界面：http://localhost:8080
- Prometheus 界面：http://localhost:9090
- Grafana 界面：http://localhost:3000
- AlertManager 界面：http://localhost:9093
# 编译项目
mvn clean install -DskipTests
# 启动网关服务
cd zmbdp-gateway
mvn spring-boot:run
# 启动管理服务（新开终端）
cd zmbdp-admin/zmbdp-admin-service
mvn spring-boot:run提示：首次启动会自动初始化数据库和配置，请耐心等待。详细配置说明见 配置中心文档
- 统一认证：通过网关访问登录接口，体验 JWT 无状态认证
- 配置管理：在 Nacos 控制台查看完整的配置结构和管理方式
- 缓存体验：测试三级缓存（布隆过滤器 + Caffeine + Redis）的命中与降级效果
- 链路追踪：访问 SkyWalking UI，查看服务调用链路和性能分析
- 服务监控：访问 Grafana，查看 JVM、接口、系统资源监控大盘
- 告警测试：访问 Prometheus，查看告警规则和触发状态
- 定时任务：在 XXL-JOB 管控台查看执行器注册状态，手动触发布隆过滤器重置任务
- 快速开发：使用
zmbdp-mstemplate模块作为模板，快速新建一个业务微服务 - 能力验证：体验幂等性控制、限流防刷、消息发送等核心能力
完整的使用手册请访问：📘 使用手册
| 文档 | 说明 |
|---|---|
| 项目结构说明 | 详细的模块划分和职责说明 |
| 工具类使用指南 | 20 多个工具类完整说明与使用示例 |
| 配置中心与环境配置 | Nacos 配置、多环境切换指南 |
| 三级缓存架构 | 布隆过滤器 + Caffeine + Redis 缓存设计 |
| 分布式幂等性设计 | 幂等性控制原理与使用指南 |
| 数据权限控制 | 数据权限控制原理与使用指南 |
| 频控 / 防刷 | 限流组件说明与使用指南 |
| 操作日志 | 操作日志组件说明与使用指南 |
| 链路追踪 | SkyWalking 链路追踪使用指南 |
| 服务监控与告警 | Prometheus + Grafana 监控告警指南 |
| 分布式定时任务（XXL-JOB） | XXL-JOB 执行器配置、Handler 编写、降级兜底方案 |
| 新增业务模块指南 | 快速创建新微服务模块 |
| 性能与并发设计 | 性能优化策略与并发设计 |
| 常见问题 | 开发中常见问题解答 |
SDK 开发文档位于项目 javapro/javadoc 目录下，基于 JavaDoc 自动生成。
访问方式：在项目根目录找到 javapro/javadoc/index.html，使用浏览器打开即可浏览完整 SDK 文档。
欢迎任何形式的贡献，让这个项目变得更好。 无论是功能改进，还是非常细微的优化，都非常欢迎：
- 提交 Issue：Bug、异常行为、设计建议等
- 文档与注释：错别字、标点符号、说明补充、示例完善
- 代码优化：性能改进、结构调整、最佳实践
- 新增能力：通用组件、公共能力、工程规范
- Star 支持：如果这个项目对你有帮助，欢迎 Star 鼓励
- 分支规范：从
main分支创建feature/xxx或fix/xxx分支 - 提交规范：使用清晰的提交信息，格式：
type: description（如：feat: 新增限流组件） - 代码规范：遵循现有项目代码风格，参考
zmbdp-mstemplate模块 - 文档完善：如有新增功能，请同步更新相关文档
即使只是一个标点符号的修改，也同样值得一次 Pull Request。
- 快速搭建企业级微服务项目
- 学习 Spring Cloud 微服务架构
- 作为项目脚手架，快速启动新业务
- 参考工程化实践和最佳实践
- 👤 作者: 稚名不带撇
- 📧 邮箱: JavaFH@163.com
- 🐙 GitHub: @zmbdp
- 📚 项目地址: https://github.com/zmbdp/frameworkjava
本项目基于 MIT License 开源。
功能概述
|
系统架构
|
使用手册
|
API文档
|
SDK文档
|
管理端登录页
|
管理端管理页
|
字典管理页
|
如果这个项目对你有帮助，请给一个 ⭐ Star FrameworkJava只负责打基础，真正的业务复杂度，还是应该由你自己的项目来承载。