# gradle-springcloud

**Repository Path**: gitlicl/gradle-springcloud

## Basic Information

- **Project Name**: gradle-springcloud
- **Description**: 此项目是自学项目
基于Spring cloud 构建一个套完整的架构，但不包含任何业务，仅是框架搭建，业务可以自行开发的项目
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2024-12-02
- **Last Updated**: 2026-04-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Spring Cloud 微服务框架

> 🌱 基于 Spring Cloud 构建的一套完整的微服务架构，不包含业务逻辑，仅为框架搭建，可作为业务开发的脚手架项目

[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-3.5.8-brightgreen.svg)](https://spring.io/projects/spring-boot)
[![Spring Cloud](https://img.shields.io/badge/Spring%20Cloud-2025.0.0-brightgreen.svg)](https://spring.io/projects/spring-cloud)
[![Java](https://img.shields.io/badge/Java-17-orange.svg)](https://openjdk.java.net/)
[![Gradle](https://img.shields.io/badge/Gradle-8.14.1-blue.svg)](https://gradle.org/)

## 📋 目录

- [项目概述](#项目概述)
- [架构设计](#架构设计)
- [技术栈](#技术栈)
- [模块说明](#模块说明)
- [快速开始](#快速开始)
- [分支学习路径](#分支学习路径)
- [配置说明](#配置说明)
- [常见问题](#常见问题)

## 项目概述

本项目是一个完整的微服务架构示例，基于 Spring Cloud 技术栈构建。项目不包含具体业务逻辑，专注于框架搭建和技术整合，可作为企业级微服务项目的起始模板。

项目遵循领域驱动设计（DDD）思想，采用前后端分离架构，支持多环境部署，内置了监控、链路追踪、日志收集等运维支撑体系。

<div align="center">
  <img src="/doc/架构图.png" alt="系统架构图" width="70%">
</div>

## 架构设计

### 微服务组件对比

| 功能 | Spring Cloud 组件 | Spring Cloud Alibaba 对应组件 | 区别与说明 |
|------|-------------------|------------------------------|------------|
| 🏛️ 注册中心 | Eureka / Consul / Zookeeper | 🟢 Nacos | Alibaba 集成配置+注册一体化，动态刷新方便 |
| 📁 配置中心 | Spring Cloud Config | 🟢 Nacos Config | 内置配置刷新、灰度、命名空间，易用性更高 |
| 🔄 服务调用 | OpenFeign / RestTemplate | ✅ 同样支持 Feign | 完全兼容 |
| 🚪 服务网关 | Spring Cloud Gateway / Zuul | ✅ 同样可用 Gateway | 一般共用官方 Gateway |
| ⚖️ 负载均衡 | Ribbon / Spring Cloud LoadBalancer | ✅ 同样可用 | Alibaba 不额外扩展 |
| 🛡️ 熔断限流 | Resilience4j（早期 Hystrix） | 🟢 Sentinel | Sentinel 更强大：限流、熔断、热点参数、实时监控 |
| 📨 消息队列 | RabbitMQ / Kafka | 🟢 RocketMQ | 与阿里中间件深度集成 |
| 🔗 分布式事务 | 无（需第三方） | 🟢 Seata | 提供 AT / TCC / Saga 支持 |
| 🚌 服务总线 | Spring Cloud Bus | ✅ Nacos + RocketMQ 可替代 | 更灵活 |
| 🔍 链路追踪 | Sleuth + Zipkin / OpenTelemetry | ✅ 同样可集成 | 可用 Zipkin/OTEL 兼容方案 |

## 技术栈

### 核心框架

| 技术 | 版本 | 说明 |
|------|------|------|
| 🏗️ Gradle | 8.14.1 | 构建工具 |
| 🍃 Spring Boot | 3.5.8 | 应用框架 |
| ☁️ Spring Cloud | 2025.0.0 | 微服务框架 |
| 🔍 Spring Boot Actuator | 3.5.8 | 健康检查监控 |

### 微服务组件

| 组件 | 版本 | 说明 |
|------|------|------|
| 🏛️ Eureka Server | 最新 | 注册中心server |
| 🏛️ Eureka Client | 最新 | 注册中心client |
| 📁 Config Server | 最新 | 配置中心server |
| 📁 Config Client | 最新 | 配置中心client |
| 🔄 OpenFeign | 最新 | 声明式的 Web 服务客户端 |
| 🚪 Spring Cloud Gateway | 最新 | API 网关 |
| 🔐 Spring Security | 最新 | 安全认证框架 |
| ⚖️ Spring Cloud LoadBalancer | 最新 | 本地负载均衡 |
| 🛡️ Resilience4j | 最新 | 熔断器 |

### 数据存储与消息

| 技术 | 版本 | 说明 |
|------|------|------|
| 🗃️ PostgreSQL | 42.7.7 | 关系型数据库 |
| 🔴 Redis | 7.2.5 | 缓存与消息存储 |
| 🐰 RabbitMQ | 最新 | 消息队列 |
| 🔄 Seata | 最新 | 分布式事务 |

### 监控与日志

| 技术 | 版本 | 说明 |
|------|------|------|
| 📊 Micrometer | 1.3.6 | 应用监控指标 |
| 📈 OpenTelemetry | 最新 | 链路追踪 |
| 📊 Elasticsearch | 8.17.0 | 日志存储与搜索 |
| 📊 Kibana | 8.17.0 | 日志可视化 |
| 📊 Filebeat | 8.17.0 | 日志收集 |
| 📊 Zipkin | 最新 | 分布式链路追踪 |
| 🖥️ Spring Boot Admin | 3.5.6 | 应用监控管理 |

### 工具库

| 技术 | 版本 | 说明 |
|------|------|------|
| 🛠️ Lombok | 1.18.34 | 代码简化工具 |
| 📝 Jackson | 2.17.3 | JSON 序列化/反序列化 |
| 🛠️ Commons Lang3 | 3.12.0 | Java 常用工具包 |
| 🛠️ Hutool Core | 5.8.34 | Java 工具集 |
| 💾 HikariCP | 6.2.0 | 数据库连接池 |
| 📄 Aspose Words | 最新 | 文档处理工具 |

## 模块说明

| 服务名称 | 端口号 | 功能描述 |
|----------|--------|----------|
| 🏛️ gradle-center | 30000 | 注册中心 |
| 📁 gradle-config | 30001 | 配置中心 |
| 🚪 gradle-gateway | 30002 | 服务网关 |
| 👥 gradle-admin | 33001 | 用户管理服务 |
| 🔐 gradle-auth | 33005 | 认证中心 |
| 🎯 gradle-jp | 33006 | 业务示例服务（Redis/RabbitMQ/Seata测试） |
| 🏗️ gradle-base | 33007 | 基础服务（字典查询等） |
| 📊 gradle-spring-boot-admin | 50000 | 应用监控管理 |

### 公共模块

| 模块名称 | 功能描述 |
|----------|----------|
| 🔧 gradle-common-core | 公共核心组件 |
| 💾 gradle-common-mybatis-starter | MyBatis 集成启动器 |
| 🌐 gradle-common-feign-starter | Feign 集成启动器 |
| 🔴 gradle-common-redis-starter | Redis 集成启动器 |
| 🐰 gradle-common-rabbit-mq-starter | RabbitMQ 集成启动器 |
| 🔗 gradle-common-seata-starter | Seata 分布式事务启动器 |
| 📊 gradle-common-spring-boot-admin | Spring Boot Admin 集成 |

## 快速开始

### 环境要求

- JDK 17+
- Gradle 7.6.2+
- Redis 7.0+
- PostgreSQL 14+
- RabbitMQ 3.9+

### 启动步骤

1. **克隆项目**
   ```bash
   git clone [项目地址]
   cd gradle-springcloud
   ```

2. **配置修改**
   - 修改 `gradle-config` 模块中的配置文件，指向你的配置地址
   - 根据实际环境调整数据库、Redis等连接信息

3. **构建项目**
   ```bash
   ./gradlew build -x test
   ```

4. **启动服务**
   - 按依赖顺序启动：注册中心 → 配置中心 → 网关 → 业务服务
   
5. **访问应用**
   - 网关入口: http://localhost:30002
   - Spring Boot Admin: http://localhost:50000

### 启动参数

```bash
-Dfile.encoding=UTF-8 
-javaagent:opentelemetry/opentelemetry-javaagent.jar 
-Dspring.profiles.active=dev 
-Dotel.service.name=gradle-center 
-Dotel.javaagent.logging=none 
-Dsnowflake.worker-id=1 
-Dsnowflake.datacenter-id=1 
-Dsnowflake.enabled=true
```

#### 参数说明

| 参数 | 说明 |
|------|------|
| `-Dspring.profiles.active=dev` | 指定使用 `dev` 环境配置 |
| `-javaagent:opentelemetry-javaagent.jar` | 启用 OpenTelemetry 链路追踪 |
| `-Dotel.service.name=my-service` | 设置 OpenTelemetry 服务名称 |
| `--Dotel.javaagent.logging=none` | 设置 javaagent 不打印日志 |
| `--snowflake.worker-id=1 --snowflake.datacenter-id=1 --snowflake.enabled=true` | 设置 雪花算法配置 |

## 分支学习路径

1. `feature-gateway-openFeign`: 集成 gateway 与 feign 调用的初始化
2. `feature-openFeign-config-server`: 集成 配置中心
3. `feature-openFeign-resilience4j`: 集成 resilience4j
4. `feature-version-manager-update`: 版本管理方式替换为 toml 文件
5. `feature-sql-server`: 集成 SQL Server 数据库，mybatis 插件，简单的调用测试
6. `feature-openTelemetry`: 集成 openTelemetry 统一日志 trace
7. `feature-08-spring-boot-admin`: 集成 spring boot admin
8. `feature-09-openFeign-resilience4j`: openfeign 和 resilience4j 整合优化
9. `feature-10-okhttp3`: 集成 okhttp3
10. `feature-11-knife4j`: 集成 knife4j 文档
11. `feature-12-apache-camel`: 集成 Apache Camel（开发中）
12. `feature-13-spring-security`: 集成 security 安全框架
13. `feature-14-spring-security-auth`: 拆分认证服务
14. `feature-15-jp`: 开发 demo 业务测试，完成 gateway 统一认证，集成 pgSQL，redis 集群，mybatis 插件
15. `feature-16-log`: 日志优化
16. `feature-17-mq`: 集成 MQ 多数据源
17. `feature-18-seata`: 集成 seata 分布式事务
18. `feature-22-dockerfile`: Docker 容器化部署

## 配置说明

### 配置中心

项目使用 Spring Cloud Config 作为配置中心，支持：
- 多环境配置（dev/test/prod）
- 配置动态刷新
- 配置加密（Jasypt）
- Git 仓库配置存储

### 监控配置

项目集成了多种监控方案：
- Spring Boot Admin: 应用状态监控
- Micrometer + Prometheus: 指标收集（暂未实现）
- OpenTelemetry + Zipkin: 链路追踪
- ELK Stack: 日志收集与分析

## 常见问题

### 问题1: Error running XXXApplication Command line is too long

**解决方案：**
在项目的 `.idea/workspace.xml` 文件中，找到 `<component name="PropertiesComponent">`，添加以下行：
```xml
<property name="dynamic.classpath" value="true" />
```

### 问题2: 依赖冲突

**解决方案：**
- 使用 `./gradlew dependencies` 检查依赖树
- 使用 `./gradlew dependencyInsight --dependency [dependency-name]` 查看特定依赖
- 确保使用 BOM 管理版本

### 问题3: 配置不生效

**解决方案：**
- 检查 Bootstrap 配置是否正确
- 确认配置中心服务已启动
- 验证 Git 仓库权限和路径


## 许可证

本项目采用 MIT 许可证。详见 [LICENSE](LICENSE) 文件。

---