# YeApi

**Repository Path**: steda/ye-api

## Basic Information

- **Project Name**: YeApi
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-17
- **Last Updated**: 2025-12-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SpringBoot 3.x 企业级开发脚手架

一个基于Spring Boot 3.x的企业级多模块开发脚手架，为二开团队提供快速入门和新项目创建的完整示例。集成了企业开发中常用的技术栈和最佳实践。

## 📋 项目简介

本项目是一个**生产就绪**的Spring Boot 3.x脚手架，旨在帮助开发团队：
- 🚀 快速启动新项目
- 📚 学习Spring Boot 3.x最佳实践  
- 🏗️ 了解企业级项目架构设计
- 🔧 掌握常用中间件集成方式

## 🏢 项目结构

```
springboot3-demo/
├── pom.xml                    # 父项目POM文件
├── public-common/             # 公共Starter模块
│   ├── yelink-security-starter/   # 安全认证模块（Keycloak集成）
│   ├── yelink-redis-starter/       # Redis缓存模块
│   ├── yelink-minio-starter/       # MinIO对象存储模块
│   └── yelink-doc-starter/         # API文档模块（Swagger）
├── web-server/                # 主应用模块
│   ├── src/main/java/
│   │   └── com/yelink/example/web/
│   │       ├── WebServerApplication.java  # 启动类
│   │       ├── controller/               # 控制器层
│   │       ├── service/                  # 业务逻辑层
│   │       ├── repository/               # 数据访问层
│   │       ├── model/                    # 数据模型
│   │       ├── config/                   # 配置类
│   │       ├── aspect/                   # AOP切面
│   │       ├── handler/                  # 异常处理器
│   │       └── utils/                    # 工具类
│   └── src/main/resources/
│       ├── application.yml               # 主配置文件
│       ├── config/security.yml           # 安全配置
│       └── db.migration/                 # 数据库迁移脚本
├── deploy/                    # 部署相关文件
│   ├── docker-compose.yml               # Docker编排文件
│   └── deploy.sh                        # 部署脚本
└── style/                     # 代码规范
    ├── CheckStyle.xml                   # 代码检查规则
    └── code-style-for-idea.xml          # IDEA代码格式化配置
```

## 🛠 技术栈

### 核心框架
- **Java**: JDK 21
- **Spring Boot**: 3.3.0
- **Spring Security**: OAuth2 + JWT
- **Spring Data JPA**: 数据访问层

### 数据库与缓存
- **MySQL**: 8.0+ (主数据库)
- **Redis**: 缓存与会话存储
- **Flyway**: 数据库版本管理

### 中间件集成
- **Keycloak**: 统一身份认证
- **MinIO**: 对象存储
- **Kafka**: 消息队列
- **Nacos**: 服务发现与配置中心

### 开发工具
- **Swagger**: API文档生成
- **Maven**: 项目构建
- **Docker**: 容器化部署
- **Lombok**: 代码简化

## ✨ 核心特性

### 🔐 安全认证
- **Keycloak集成**: 统一身份认证与授权
- **JWT令牌**: 无状态认证机制
- **RBAC权限**: 基于角色的访问控制
- **安全配置**: 可动态开启/关闭认证

### 📊 监控与日志
- **AOP日志**: 自动记录请求响应日志
- **慢请求监控**: 可配置阈值的性能监控
- **参数截取**: 大参数自动截取，避免日志过大
- **异常捕获**: 全局异常处理与记录

### 🚀 开发效率
- **代码生成**: 基于模板的快速开发
- **统一响应**: 标准化的API响应格式
- **参数校验**: Bean Validation集成
- **API文档**: Swagger自动生成文档

### 🏗 架构设计
- **模块化**: 清晰的分层架构
- **配置分离**: 环境配置外部化
- **熔断降级**: Circuit Breaker模式
- **异步处理**: Kafka消息队列

### 📦 部署运维
- **容器化**: Docker + Docker Compose
- **配置中心**: Nacos动态配置
- **健康检查**: Spring Boot Actuator
- **日志收集**: 结构化日志输出

## 🚀 快速开始

### 1. 环境准备

```bash
# 基础环境要求
- JDK 21+
- Maven 3.8+
- Docker & Docker Compose (可选)
- Git

# 推荐IDE
- IntelliJ IDEA 2023.3+
- VS Code + Java Extension Pack
```

### 2. 项目初始化

```bash
# 克隆项目
git clone <your-repo-url>
cd springboot3-demo

# 安装依赖
mvn clean install -DskipTests

# 导入代码格式化配置
# 在IDEA中导入 style/code-style-for-idea.xml
```

### 3. 外部依赖启动

使用Docker Compose启动所需的中间件：

```bash
cd deploy
docker-compose up -d

# 验证服务状态
docker-compose ps
```

包含以下服务：
- MySQL 8.0 (端口: 3306)
- Redis 6.2 (端口: 6379) 
- Nacos 2.0 (端口: 8848)
- Keycloak (端口: 8080)
- MinIO (端口: 9000)

### 4. 配置调整

根据实际环境修改配置文件：

```yaml
# web-server/src/main/resources/application.yml
server:
  port: 38104  # 应用端口

# web-server/src/main/resources/config/security.yml  
app:
  security:
    enable: false  # 开发时可关闭认证
```

### 5. 启动应用

```bash
# 方式一：使用Maven插件
mvn spring-boot:run -pl web-server

# 方式二：使用IDE
# 直接运行 WebServerApplication.java

# 方式三：打包运行
mvn clean package -DskipTests
java -jar web-server/target/yelink-demo.jar
```

### 6. 验证部署

```bash
# 健康检查
curl http://localhost:38104/actuator/health

# API文档
http://localhost:38104/swagger-ui/index.html

```

## 📖 开发指南

### 🔧 新建模块

1. **创建新的Starter模块**
```bash
# 在public-common下创建新模块
mkdir public-common/yelink-xxx-starter
```

2. **添加模块POM**
```xml
<!-- 参考其他starter的pom.xml结构 -->
<parent>
    <groupId>com.example</groupId>
    <artifactId>public-common</artifactId>
    <version>1.0.0</version>
</parent>
```

3. **实现自动配置类**
```java
@AutoConfiguration
@EnableConfigurationProperties(XxxProperties.class)
@ConditionalOnProperty(prefix = "app.xxx", name = "enabled", havingValue = "true")
public class XxxAutoConfiguration {
    // 自动配置逻辑
}
```

### 🎯 添加新接口

1. **Controller示例**
```java
@RestController
@RequestMapping("/api/xxx")
@Slf4j
public class XxxController {
    
    @GetMapping("/{id}")
    public Result<XxxVO> getById(@PathVariable Long id) {
        // 业务逻辑
        return Result.success(data);
    }
}
```

2. **Service层开发**
```java
@Service
@Transactional(rollbackFor = Exception.class)
public class XxxService {
    // 业务逻辑实现
}
```

### ⚙️ 配置管理

1. **应用配置**
```yaml
# application.yml - 基础配置
server:
  port: 38104

spring:
  profiles:
    active: dev
```

2. **功能开关**
```yaml
# config/security.yml - 功能配置
app:
  security:
    enable: true      # 是否启用安全认证
  web:
    log:
      enabled: true   # 是否启用请求日志
      slow-request-threshold: 1000  # 慢请求阈值(ms)
```

### 🔍 日志配置

```yaml
# logback.xml 配置示例
logging:
  level:
    com.yelink.example: DEBUG
    org.springframework.web: DEBUG
    org.springframework.security: DEBUG
```

### 🧪 测试开发

```java
@SpringBootTest
@ActiveProfiles("test")
class XxxServiceTest {
    
    @Autowired
    private XxxService xxxService;
    
    @Test
    void testMethod() {
        // 测试逻辑
    }
}
```

## 🧩 示例接口

项目提供了丰富的示例接口，帮助理解各种开发场景：

### 日志测试接口 (`/api/log-test/*`)

```bash
# 简单GET请求
curl "http://localhost:38104/api/log-test/simple?message=hello"

# POST请求测试
curl -X POST "http://localhost:38104/api/log-test/data" \
  -H "Content-Type: application/json" \
  -d '{"name": "test", "value": 123}'

# 大数据量测试（测试日志截取）
curl -X POST "http://localhost:38104/api/log-test/large-data" \
  -H "Content-Type: application/json" \
  -d '{"data": "large amount of data..."}'

# 慢请求测试（默认休眠2秒）
curl "http://localhost:38104/api/log-test/slow?sleepTime=3000"

# 异常测试
curl "http://localhost:38104/api/log-test/error?throwError=true"
```

### 演示Controller (`/api/demo/*`)

```bash
# 分页查询示例
curl "http://localhost:38104/api/demo?page=1&size=10"

# 数据操作示例  
curl -X POST "http://localhost:38104/api/demo" \
  -H "Content-Type: application/json" \
  -d '{"name": "demo", "description": "test"}'
```

### 服务调用示例 (`/call/service/api`)

```bash
# 内部服务调用
curl -X POST "http://localhost:38104/call/service/api" \
  -H "Content-Type: application/json" \
  -d '{"service": "example", "method": "test"}'
```

## 📋 配置详解

### 安全配置 (`config/security.yml`)

```yaml
app:
  security:
    enable: false  # 是否启用认证，开发时建议关闭
    anon-uris: /actuator/**,/swagger-ui/**,/v3/api-docs/**,/call/service/api
    keycloak:
      server-url: ${AUTH_URL:http://localhost:8080/auth}
      realm: ${KEYCLOAK_REALM:example}
      client-id: ${KEYCLOAK_CLIENT_ID:demo}
```

### Web日志配置

```yaml
app:
  web:
    log:
      enabled: true                    # 是否启用Web日志
      max-param-length: 1000          # 请求参数最大长度
      max-response-length: 2000       # 响应数据最大长度  
      log-headers: true               # 是否记录请求头
      log-args: true                  # 是否记录请求参数
      log-response: true              # 是否记录响应数据
      slow-request-threshold: 1000    # 慢请求阈值(毫秒)
```

### 数据源配置

```yaml
spring:
  datasource:
    url: jdbc:mysql://${MYSQL_URL:127.0.0.1:3306}/demo
    username: ${MYSQL_USERNAME:root}
    password: ${MYSQL_PASSWORD}
    driver-class-name: com.mysql.cj.jdbc.Driver
    
  data:
    redis:
      host: ${REDIS_URL:127.0.0.1}
      port: 6379
      database: 12
```

## 🚢 部署指南

### Docker Compose部署

```bash
# 启动所有服务
cd deploy
docker-compose up -d

# 查看服务状态
docker-compose ps

# 查看应用日志
docker-compose logs -f web-server

# 停止所有服务
docker-compose down
```

### 生产环境配置

```bash
# 设置环境变量
export MYSQL_URL=prod-mysql:3306
export MYSQL_USERNAME=app_user
export MYSQL_PASSWORD=secure_password
export REDIS_URL=prod-redis
export NACOS_URL=prod-nacos:8848

# 启动应用
java -jar -Dspring.profiles.active=prod web-server/target/yelink-demo.jar
```

### K8s部署示例

```yaml
# k8s-deployment.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: springboot-demo
spec:
  replicas: 2
  selector:
    matchLabels:
      app: springboot-demo
  template:
    metadata:
      labels:
        app: springboot-demo
    spec:
      containers:
      - name: web-server
        image: springboot-demo:latest
        ports:
        - containerPort: 38104
        env:
        - name: SPRING_PROFILES_ACTIVE
          value: "prod"
```

## 🔧 开发工具配置

### IDEA配置

1. **导入代码格式化配置**
   - File → Settings → Editor → Code Style
   - 点击设置图标 → Import Scheme → IntelliJ IDEA code style XML  
   - 选择 `style/code-style-for-idea.xml`

2. **启用CheckStyle插件**
   - File → Settings → Plugins → 搜索 "CheckStyle-IDEA"
   - 安装并启用插件
   - 配置检查规则文件：`style/CheckStyle.xml`

3. **配置Maven**
   - File → Settings → Build Tools → Maven
   - 设置Maven home directory
   - 设置User settings file

### VS Code配置

```json
// .vscode/settings.json
{
    "java.compile.nullAnalysis.mode": "automatic",
    "java.configuration.updateBuildConfiguration": "interactive",
    "files.associations": {
        "*.yml": "yaml"
    }
}
```

## 🤝 团队协作

### Git工作流

```bash
# 创建功能分支
git checkout -b feature/xxx-功能描述

# 提交代码
git add .
git commit -m "feat: 添加xxx功能"

# 推送并创建MR
git push origin feature/xxx-功能描述
```

### 代码提交规范

```
<type>(<scope>): <subject>

<body>

<footer>
```

**Type类型：**
- `feat`: 新功能
- `fix`: 修复bug  
- `docs`: 文档更新
- `style`: 代码格式调整
- `refactor`: 重构代码
- `test`: 添加测试
- `chore`: 构建/工具变动

## 📚 学习资源

### 相关文档
- [Spring Boot 3.x 官方文档](https://spring.io/projects/spring-boot)
- [Spring Security 6.x 指南](https://spring.io/projects/spring-security)
- [Keycloak 集成指南](https://www.keycloak.org/docs/)
- [Docker Compose 参考](https://docs.docker.com/compose/)

### 推荐阅读
- 《Spring Boot实战》
- 《微服务架构设计模式》  
- 《Java并发编程实战》
- 《Clean Code》

## 🆘 常见问题

### Q: 启动时出现端口占用错误？
A: 检查是否有其他服务占用38104端口，或修改`application.yml`中的端口配置。

### Q: 无法连接到MySQL/Redis？
A: 确认Docker服务已启动，检查防火墙设置，验证连接配置。

### Q: Keycloak认证失败？
A: 检查`config/security.yml`中的Keycloak配置，确认服务地址和realm配置正确。

### Q: 如何关闭某个功能模块？
A: 在对应的配置文件中设置`enabled: false`，如关闭安全认证：`app.security.enable: false`

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件

## 👥 贡献指南

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交变更 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request