# micro **Repository Path**: 203014/micro ## Basic Information - **Project Name**: micro - **Description**: No description available - **Primary Language**: Java - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2025-01-02 - **Last Updated**: 2025-06-09 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # Micro 微服务框架 ## 项目介绍 Micro 是一个基于 Spring Boot 3.2.5 和 Spring Cloud 2023.0.4 的微服务框架,集成了 Spring Cloud Alibaba 2023.0.1.0 组件,提供了分布式应用开发的一站式解决方案。框架基于Java 17构建,采用了当前最成熟稳定的技术栈组合,确保高性能、高可用的微服务架构。 ## 技术栈 - **Java版本**: 17 - **基础框架**: - Spring Boot 3.2.5 - Spring Cloud 2023.0.4 - Spring Cloud Alibaba 2023.0.1.0 - **服务治理**: - Spring Cloud Gateway 4.1.2 - Nacos 2.2.3 (服务发现和配置中心) - Sentinel 1.8.7 (熔断降级) - Seata 1.7.1 (分布式事务) - **监控与文档**: - Knife4j 4.3.0 (API文档) - Prometheus 2.49.0 (监控) - Grafana 10.3.3 (数据可视化) - SkyWalking 10.0.0 (分布式追踪) - **安全认证**: - Keycloak 24.0.4 (身份认证) - Spring Security & JWT ## 项目结构 ``` micro ├── micro-base-core # 核心基础模块(数据库交互、工具类等) ├── micro-cloud # 微服务云组件 │ ├── micro-cloud-gateway # 服务网关(统一入口、路由、过滤) │ ├── micro-cloud-auth # 认证服务(用户认证、JWT令牌管理) │ └── micro-cloud-system # 系统服务 └── pom.xml # 项目主POM文件 ``` ## 认证服务详细功能 ### 认证服务架构 认证服务(micro-cloud-auth)负责以下主要功能: 1. 用户认证与授权 2. OAuth2授权服务器 3. JWT令牌管理 4. 用户注册与管理 ### JWT令牌管理 认证服务实现了完整的JWT令牌管理,支持: - 令牌生成与签名 - 令牌验证与解析 - 令牌刷新机制 - 令牌撤销管理 ```java // TokenService接口定义的主要功能 public interface TokenService { TokenResponse createToken(Authentication authentication); // 创建新令牌 TokenResponse refreshToken(String refreshToken); // 刷新令牌 void revokeToken(String token); // 撤销令牌 Authentication validateToken(String token); // 验证令牌 boolean isTokenExpired(String token); // 检查令牌是否过期 boolean isTokenRevoked(String token); // 检查令牌是否被撤销 } ``` ### 认证流程 ![认证流程](https://mermaid.ink/img/pako:eNpVkU9PwzAMxb_K1ROXVv3DZttlBw5IExLiwGXqDK1IE-QksHXdd8dppw285PF7P8d2j7VpLaoE11KZvVUDNdvSgfCLI72eBw4VdM4PJMN1a3EgdChDG5xnhgCaM2uPxG-uNJpPvFdmpD6KHXzQgKLFDvpAZO1bNFgQ0XUbTVvPzIUKY-CJfhB_pJQD3g0ukkOVmfZ4SnJmyY1zJStqtbLIE9k7oQMPqJz8AuW5jVZLB2kkU3JjAm7mJlf4e5SqNF6gjbBLR47K2X1rFYbXZV6vFpW70D-qpnDLVdVZDm1dN5_3y_Vss1-3WT_LVrOHxep9kzezxWq_nO1Ws-w8pfpSMKc_aICQW9lhdLVSbHcO2ZGKI-sSTFalRc4jc0hiS1JXfKpQJelE3VCCLw04jC56bXv6Apx0iOY?type=png) ## 服务调用说明 本框架使用OpenFeign进行微服务间的调用,集成了负载均衡和服务发现功能: ### 1. 服务注册与发现 - 服务注册使用Nacos作为注册中心 - 每个微服务启动时会自动向Nacos注册 - 服务调用基于服务名称进行,无需关心具体IP和端口 ### 2. OpenFeign调用示例 ```java // 创建Feign客户端接口 @FeignClient(name = "micro-cloud-system", path = "/system") public interface SystemServiceClient { @GetMapping("/user/{id}") UserDTO getUserById(@PathVariable("id") Long id); @PostMapping("/user/create") Boolean createUser(@RequestBody UserDTO user); } // 在Service中注入并使用 @Service public class UserService { @Autowired private SystemServiceClient systemServiceClient; public UserDTO getUser(Long id) { return systemServiceClient.getUserById(id); } } ``` ### 3. 负载均衡 框架内置Spring Cloud LoadBalancer实现负载均衡,支持以下策略: - 轮询(默认) - 随机 - 权重 ### 4. 熔断与限流 使用Sentinel实现服务熔断与限流保护,支持: - 服务降级 - 流量控制 - 系统自适应保护 ## 通过网关访问认证服务 ### 1. 网关概述 系统使用Spring Cloud Gateway作为API网关,统一管理服务入口。网关提供了路由转发、认证鉴权、限流熔断等功能。 ### 2. 认证流程 ``` ┌─────────┐ ┌─────────────┐ ┌────────────────┐ │ 客户端 │──────▶ API网关 │──────▶ 认证服务 │ └─────────┘ └─────────────┘ └────────────────┘ │ ▼ ┌────────────────┐ │ 返回Token │ └────────────────┘ ``` ### 3. 认证接口调用示例 #### 登录获取Token ```http POST /auth/api/login HTTP/1.1 Host: gateway.micro.org Content-Type: application/json { "username": "admin", "password": "password" } ``` 响应: ```json { "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...", "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...", "tokenType": "Bearer", "expiresIn": 3600, "expiresAt": "2025-05-03T12:00:00Z", "username": "admin" } ``` #### 刷新Token ```http POST /auth/api/refresh HTTP/1.1 Host: gateway.micro.org Content-Type: application/json { "refreshToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." } ``` #### 使用Token访问接口 ```http GET /system/user/info HTTP/1.1 Host: gateway.micro.org Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9... ``` ### 4. 网关路由配置 网关默认将服务名映射为路径前缀,示例配置: ```yaml spring: cloud: gateway: routes: - id: auth-service uri: lb://micro-cloud-auth predicates: - Path=/auth/** filters: - StripPrefix=1 - id: system-service uri: lb://micro-cloud-system predicates: - Path=/system/** filters: - StripPrefix=1 - AuthFilter ``` ## 环境配置 项目配置了多环境支持: - 开发环境 (dev) - 测试环境 (test) - 生产环境 (prod) ## Bean管理与冲突解决 为避免Bean定义冲突,我们采用了以下最佳实践: 1. 使用`@Qualifier`注解指定具体Bean 2. 合理命名避免重复 3. 必要时使用`spring.main.allow-bean-definition-overriding=true`配置 ## 构建与部署 项目使用Maven构建: ```bash # 编译构建项目 mvn clean package -P dev ``` ## 开发团队 - zs (2770369393@qq.com) ## 常见问题与故障排除 ### 1. Jakarta Servlet API兼容性问题 #### Cookie API错误 ``` java.lang.NoSuchMethodError: 'void jakarta.servlet.http.Cookie.setAttribute(java.lang.String, java.lang.String)' ``` **原因**: Jakarta Servlet API中的`Cookie`类没有`setAttribute`方法。此错误通常出现在从旧版本迁移到Jakarta EE 9+时。 **解决方案**: - 使用标准的Cookie API方法,如`setValue()`, `setPath()`, `setMaxAge()`等 - 对于高级属性(如SameSite),使用HTTP头手动设置: ```java String cookieHeader = String.format("%s=%s; Path=%s; Max-Age=%d; SameSite=Lax; HttpOnly", cookie.getName(), cookie.getValue(), cookie.getPath(), cookie.getMaxAge()); response.setHeader("Set-Cookie", cookieHeader); ``` - 或升级到支持这些属性的更新版本的Spring框架 #### Tomcat内部Cookie错误 ``` java.lang.NoSuchMethodError: 'void jakarta.servlet.http.Cookie.setAttribute(java.lang.String, java.lang.String)' at org.apache.catalina.core.ApplicationSessionCookieConfig.createSessionCookie(ApplicationSessionCookieConfig.java:224) ``` **解决方案**: 1. 降级Tomcat版本到10.1.12(已知兼容) 2. 修改应用配置,移除已弃用的`server.servlet.session.cookie.comment`配置 ### 2. Bean定义冲突问题 ``` The bean 'jwtDecoder', defined in class path resource [...], could not be registered. A bean with that name has already been defined in class path resource [...] and overriding is disabled. ``` **解决方案**: 1. 重命名冲突的Bean ```java @Bean public JwtDecoder tokenJwtDecoder() { ... } ``` 2. 使用限定符明确注入 ```java public TokenServiceImpl(@Qualifier("tokenJwtDecoder") JwtDecoder tokenJwtDecoder) { ... } ``` 3. 启用Bean覆盖功能 ```yaml spring: main: allow-bean-definition-overriding: true ```