From e5ea9db86842de370d816eb257f8c7749edb46a1 Mon Sep 17 00:00:00 2001 From: Wonder Date: Tue, 7 Oct 2025 03:35:05 +0800 Subject: [PATCH] =?UTF-8?q?Docs:=20=E6=9B=B4=E6=96=B0=E9=A1=B9=E7=9B=AE?= =?UTF-8?q?=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- PRD.md | 109 ----------------------------------------- README.md | 141 ++++++++++++++++++++++++++++++++++++++++++++++-------- 2 files changed, 121 insertions(+), 129 deletions(-) delete mode 100644 PRD.md diff --git a/PRD.md b/PRD.md deleted file mode 100644 index 41b08cc..0000000 --- a/PRD.md +++ /dev/null @@ -1,109 +0,0 @@ -# 产品需求文档（PRD） - -## 一、项目概述 - -### 1.1 项目背景 -随着业务的发展，系统逐渐复杂多变。为提升系统的可维护性、可扩展性和高可用性，计划构建一个基于 Spring Cloud 的微服务架构项目模板，用于快速搭建出符合 Best Practices 的微服务系统。 - -### 1.2 项目目标 -- 构建一个基础的 Spring Cloud 微服务项目结构。 -- 提供服务注册与发现、配置中心、远程调用、负载均衡等核心功能。 -- 项目结构清晰，便于后续扩展和开发人员协作。 -- 能够作为一个通用模板用于多个业务场景。 - ---- - -## 二、功能需求 - -### 2.1 项目结构要求 -项目应包含以下模块： - -| 模块名称 | 功能描述 | -|----------------------|-------------------------------------------| -| `spring-cloud-template` | 项目根目录，maven 父工程 | -| `eureka-server` | 服务注册中心（Eureka Server） | -| `config-server` | 配置中心（Spring Cloud Config） | -| `service-a` | 服务A（提供 REST API） | -| `service-b` | 服务B（提供 REST API） | -| `api-gateway` | API 网关（Spring Cloud Gateway） | -| `demo-client` | 示例客户端（消费服务A和服务B） | - -### 2.2 核心功能说明 - -#### Eureka Server -- 提供微服务注册与发现功能。 -- 单机部署。 -- 页面展示服务实例列表。 - -#### Config Server -- 提供统一的配置管理。 - -#### Service A & B -- 提供基本的 REST 接口，例如 `/api/service-a/hello` 和 `/api/service-b/hello`。 -- 包含基本的 logging 和 health check 功能。 -- 支持通过 Feign 进行服务间通信。 - -#### API Gateway -- 提供统一的 API 入口。 -- 实现路由跳转（如 `/api/service-a/**` 路由到 service-a）。 -- 支持基本的负载均衡（使用 Ribbon）。 - -#### Demo Client -- 调用通过 API Gateway 路由的服务 A 和 B。 -- 展示如何通过配置和方式访问远程服务。 - -### 2.3 非功能需求 -| 需求类型 | 说明 | -|----------|------| -| 可扩展性 | 模块设计清晰，便于后续增加新服务 | -| 可维护性 | 配置集中管理，日志统一采集 | -| 可靠性 | 服务提供健康检查、断路机制（Hystrix） | -| 开发便捷性 | 提供演示和可运行的模板，适合快速启动 | -| 技术兼容性 | 使用 Spring Boot、Spring Cloud 的主流版本（如 2023.0.x） | - ---- - -## 三、项目架构 - -``` -├── spring-cloud-template (父工程) -│ ├── eureka-server -│ ├── config-server -│ ├── service-a -│ ├── service-b -│ ├── api-gateway -│ └── demo-client -``` - -### 架构特点： -- 服务注册与发现：使用 Eureka Server -- 配置中心：使用 Spring Cloud Config -- 服务间调用：使用 Feign Client + Ribbon -- 服务网关：使用 Spring Cloud Gateway -- 服务健康：HealthCheck + Hystrix（断路器） -- 日志统一：支持 SLF4J + Logback + ELK（可选扩展） - ---- - -## 四、环境要求 - -### 4.1 开发环境 -- JDK 21 -- Maven 3.x -- Spring Boot 3.x -- Spring Cloud 2023.0.x -- Git - -### 4.2 项目依赖 -- Eureka Server -- Spring Cloud Config -- Spring Cloud Gateway -- Spring Cloud Feign -- Spring Cloud Ribbon -- Spring Cloud Hystrix -- Spring Boot Actuator（用于健康检查） - -### 4.3 工具 -- IntelliJ IDEA / VS Code -- API fox（测试 API） -- Gitea（配置文件托管） diff --git a/README.md b/README.md index dd49a02..66ef187 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,125 @@ -# spring-cloud-template +# Spring Cloud 微服务模板项目 本项目是一个基于 Spring Cloud 的微服务架构模板，提供服务注册、配置管理、API 网关、服务间调用等核心功能，结构清晰、易于扩展，适用于快速搭建高可用的微服务系统。 -## 任务清单 +## 项目结构 -| **任务编号** | **任务名称** | **说明** | -|----------|---------------------------------------------------|--------------------------------------------------------------------------| -| ✅T01 | 创建项目根目录 `spring-cloud-template` | 作为 Maven 父工程，统一管理子模块的依赖和版本 | -| ✅T02 | 搭建 Eureka Server 模块 | 配置单机模式，实现服务注册与发现功能，提供服务实例列表页面 | -| ✅T03 | 搭建 Config Server 模块 | 配置 Spring Cloud Config，实现统一配置管理 | -| ✅T04 | 创建 Service A 模块 | 实现 `/api/service-a/hello` REST 接口，配置 logging 和 health check | -| ✅T05 | 创建 Service B 模块 | 实现 `/api/service-b/hello` REST 接口，配置 logging 和 health check | -| T06 | 集成 Feign Client 和 Ribbon 服务调用 | 服务间使用 Feign 进行远程调用，Ribbon 实现负载均衡 | -| T07 | 搭建 API Gateway 模块 | 配置路由规则（如 `/api/service-a/**` 路由到 service-a） | -| T08 | 创建 Demo Client 模块 | 调用通过 API Gateway 路由的服务 A 和 B，展示客户端访问逻辑 | -| T09 | 配置 Spring Boot 和 Spring Cloud 版本 | 使用 Spring Boot 3.x 和 Spring Cloud 2023.0.x 作为技术栈版本 | -| T10 | 集成日志系统（SLF4J + Logback） | 统一日志输出，支持日志管理 | -| T11 | 配置 Git 项目结构，支持代码托管 | 使用 Gitea 或其他 Git 服务管理代码和配置文件 | -| T12 | 检查开发环境是否满足要求 | 确保 JDK 21、Maven 3.x、IDE 等工具已安装并配置正确 | -| T13 | 验证服务注册、配置获取、路由和调用功能 | 确保各模块之间能正常通信、注册、访问和负载均衡 | -| T14 | 添加 Hystrix 支持，实现断路机制 | 为服务调用增加容错能力，防止雪崩效应 | -| T15 | 测试健康检查接口 | 使用 Spring Boot Actuator 提供健康状态检查 | -| T16 | 编写项目说明文档和运行指南 | 为后续开发人员提供使用和启动说明 | \ No newline at end of file +``` +spring-cloud-template +├── eureka-server # 服务注册中心（Eureka Server） +├── config-server # 配置中心（Spring Cloud Config） +├── service-producer # 服务提供者（示例服务A） +├── service-consumer # 服务消费者（示例服务B） +├── api-gateway # API 网关（Spring Cloud Gateway） +└── pom.xml # 父工程 POM 文件 +``` + +## 核心功能 + +### 1. 服务注册与发现 +- 使用 Eureka Server 实现服务注册与发现 +- 提供服务实例列表页面，便于监控服务状态 + +### 2. 配置中心 +- 使用 Spring Cloud Config 实现统一配置管理 +- 支持配置的动态刷新 + +### 3. 服务间调用 +- 使用 OpenFeign 实现声明式服务调用 +- 集成 Ribbon 实现客户端负载均衡 + +### 4. API 网关 +- 使用 Spring Cloud Gateway 作为统一 API 入口 +- 支持路由配置和请求转发 + +### 5. 服务健康检查 +- 集成 Spring Boot Actuator 实现服务健康检查 +- 提供监控端点，便于系统运维 + +## 技术栈 + +- **Spring Boot**: 3.3.13 +- **Spring Cloud**: 2023.0.6 +- **JDK**: 21 +- **Maven**: 3.x +- **Eureka Server**: Netflix Eureka +- **Config Server**: Spring Cloud Config +- **API Gateway**: Spring Cloud Gateway +- **OpenFeign**: 声明式 HTTP 客户端 +- **Ribbon**: 客户端负载均衡 + +## 快速开始 + +### 1. 环境要求 +- JDK 21 +- Maven 3.x + +### 2. 启动服务 + +#### 启动服务注册中心 (Eureka Server) +```bash +cd eureka-server +mvn spring-boot:run +``` + +#### 启动配置中心 (Config Server) +```bash +cd config-server +mvn spring-boot:run +``` + +#### 启动服务提供者 (Service Producer) +```bash +cd service-producer +mvn spring-boot:run +``` + +#### 启动服务消费者 (Service Consumer) +```bash +cd service-consumer +mvn spring-boot:run +``` + +#### 启动 API 网关 (API Gateway) +```bash +cd api-gateway +mvn spring-boot:run +``` + +### 3. 访问服务 + +- Eureka Server: http://localhost:8761 +- Service Producer: http://localhost:8081/api/health +- Service Consumer: http://localhost:8082/api/health +- API Gateway: http://localhost:8080/api/consumer/print + +## 项目模块说明 + +### eureka-server +服务注册中心，负责服务的注册与发现。 + +### config-server +配置中心，统一管理微服务的配置信息。 + +### service-producer +服务提供者示例，提供 REST API 接口。 + +### service-consumer +服务消费者示例，调用其他服务提供的接口。 + +### api-gateway +API 网关，统一处理所有外部请求的入口。 + +## 开发指南 + +### 添加新服务 +1. 创建新的 Maven 模块 +2. 添加必要的依赖 +3. 配置服务注册与发现 +4. 实现业务逻辑 + +### 配置管理 +所有服务都通过 Spring Cloud Config 进行配置管理，配置文件位于 config-server 中。 + +### 负载均衡 +服务间调用使用 Ribbon 实现客户端负载均衡。