4. 开发实战

4.1 后台开发架构搭建 demo 讲解

获取代码

git clone https://gitlab.yelinksaas.com/demo/springboot3-demo.git

---

项目架构

多模块 Maven 工程，包含以下核心模块：

模块	说明
web-server	核心 Web 服务，提供 RESTful 接口
public-common/yelink-doc-starter	SpringDoc OpenAPI 文档自动配置
public-common/yelink-minio-starter	MinIO 对象存储集成
public-common/yelink-redis-starter	Redis 缓存服务（Lettuce 连接池）
public-common/yelink-security-starter	Keycloak JWT 安全认证组件

---

技术栈

核心框架

组件	版本
Java	21
Spring Boot	3.3.0
Spring Cloud	2023.0.1
Spring Cloud Alibaba	2023.0.1.0

基础设施

类别	技术方案
安全认证	Keycloak（Spring Security OAuth2 Resource Server + JWT）
数据持久化	MyBatis Plus 3.5.12 + MySQL 8.0.33
连接池	HikariCP
数据库迁移	Flyway
缓存	Redis（Lettuce）
对象存储	MinIO
消息队列	Kafka
服务注册发现	Nacos
远程调用	OpenFeign
熔断限流	Resilience4j（熔断 / 重试 / 限流 / 舱壁）
API 文档	SpringDoc OpenAPI（Swagger 3.x）
工具库	Hutool、Lombok、Fastjson2、Caffeine

---

核心功能

1. 安全认证 — 基于 Keycloak 的 OAuth2/OIDC 认证，JWT 无状态校验
2. 数据操作 — MyBatis Plus CRUD、分页、条件查询示例
3. 缓存服务 — Redis 单条 / 批量读写，附压测接口
4. 消息队列 — Kafka 消息生产与消费示例
5. 文件存储 — MinIO 文件上传，返回相对路径供前端访问
6. 跨服务调用 — OpenFeign 调用，支持 Token 透传和 AK/SK 两种认证方式
7. 熔断限流 — Resilience4j 熔断器 / 重试 / 速率限制 / 舱壁隔离
8. 请求日志 — AOP 切面记录请求参数、响应体、耗时，可配置慢请求阈值
9. 异常处理 — 全局统一异常处理，结构化错误响应
10. 数据库迁移 — Flyway 版本化 SQL 脚本管理

---

本地开发

环境要求

• JDK 21+
• Maven 3.8+
• Docker & Docker Compose
• MySQL 8.0+
• Redis 6.0+
• Kafka 3.x+
• Nacos 2.x

关键配置项

应用启动前需确认以下环境变量或 application.yml 中的对应配置：

# 数据库
spring.datasource.url: jdbc:mysql://${MYSQL_URL:127.0.0.1:3306}/demo
spring.datasource.username: yelink
spring.datasource.password: <密码>

# Redis
spring.data.redis.host: ${REDIS_URL:127.0.0.1}
spring.data.redis.port: ${REDIS_PORT:6379}
spring.data.redis.database: 12

# Nacos
spring.cloud.nacos.discovery.server-addr: ${NACOS_URL:172.16.0.3}:8001

# MinIO
minio.endpoint: ${MINIO_ENDPOINT:http://172.16.0.3:28301}
minio.access-key: ${MINIO_ACCESS_KEY:miniouser}
minio.secret-key: ${MINIO_SECRET_KEY:yelink123}

# Kafka
spring.kafka.bootstrap-servers: ${KAFKACLOUD_URL:172.16.0.3:9092}

Keycloak 安全配置通过独立文件注入，路径优先级：

optional:file:/usr/app/resources/config/security.yml   # 容器内
optional:classpath:config/security.yml                  # 本地开发

构建

# 编译打包（跳过测试）
mvn clean package -DskipTests

打包产物位于 web-server/target/，分三部分：

• yelink-demo.jar — 应用主包（不含依赖和配置）
• lib/ — 依赖 jar
• resources/ — 配置文件

本地启动

推荐通过 IDE 直接运行 WebServerApplication，或使用 Spring Boot Maven 插件：

cd web-server
mvn spring-boot:run

服务默认端口：38104

---

Docker 部署

# 构建镜像（先完成 mvn package）
docker build -t yelink-demo:1.0.0 .

# 启动服务
docker-compose -f deploy/docker-compose.yml up -d

镜像基于 openjdk:21-jdk，日志目录挂载至宿主机 /opt/partner/data/${APP_NAME}/logs/。

---

API 文档

启动后访问：http://localhost:38104/swagger-ui.html

---

模块说明

web-server

主服务模块，包含：

• controller/ — REST API 控制器（带 Swagger 注解）
• service/ — 业务服务实现
• model/ — 数据库实体（MyBatis Plus）
• handler/ — 全局异常处理、熔断降级 Fallback
• aspect/ — Web 日志 AOP、熔断器 AOP
• client/ — OpenFeign 客户端定义与降级工厂
• config/ — MyBatis Plus、Resilience4j、Web 日志等配置类
• kafka/ — Kafka 消费者监听示例

yelink-security-starter

基于 Spring Security 6 的 OAuth2 Resource Server 封装，核心实现：

@AutoConfiguration
@ConditionalOnProperty(prefix = "app.security", name = "enable", havingValue = "true")
public class KeycloakSecurityAutoConfiguration {

    @Bean
    public SecurityFilterChain securityFilterChain(HttpSecurity http, JwtDecoder jwtDecoder) throws Exception {
        http
            .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
            .oauth2ResourceServer(oauth2 -> oauth2
                .jwt(jwt -> jwt
                    .decoder(jwtDecoder)
                    .jwtAuthenticationConverter(keycloakJwtAuthenticationConverter())
                )
            );
        return http.build();
    }
}

通过 app.security.enable=true 启用；app.security.anon-uris 配置白名单路径。

yelink-redis-starter

基于 Lettuce 的 Redis 自动配置，提供 RedisService 模板类，支持单条和批量读写。

yelink-minio-starter

封装 MinIO Java SDK，提供 MinioService 统一上传/下载接口，自动装配桶策略。

yelink-doc-starter

封装 SpringDoc OpenAPI，通过 doc.* 配置项统一管理文档标题、包扫描路径、作者信息等。