# javafree2025-examples

**Repository Path**: javafree-cloud/javafree2025-examples

## Basic Information

- **Project Name**: javafree2025-examples
- **Description**: 用于保存JavaFree 框架使用示例工程
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2025-10-30
- **Last Updated**: 2025-12-01

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# JavaFreeCloud2025 快速入门

> 使用 JavaFreeCloud2025 框架（v2.0.1）快速搭建企业级微服务应用。

本仓库包含两个示例工程，分别展示了 JavaFreeCloud2025 框架在不同场景下的应用：

------

## 示例工程概览

### 🟢 **`javafree-springboot-demo`** - 单体应用示例

一个功能完整的独立 Spring Boot 应用，适用于快速上手和学习。

- 特点：
  - 集成数据库、缓存、安全认证等全套功能。
  - 所有配置文件（如 `mysql.yml`, `jwt.yml`）直接存放于项目 `resources` 目录下。
- **适用场景**：快速原型开发、框架功能学习、小型独立服务部署。

------

### 🔵 **`javafree-springcloud-demo`** - 微服务应用示例

一个基于 Spring Cloud 的分布式微服务系统，体现生产级架构设计。

- 特点：
  - 通过 `application.yml` 从 **Nacos 配置中心**动态拉取名为 `javafree-local-xxx.yaml` 的配置。
  - 实现配置的集中管理与运行时动态刷新。
- **适用场景**：构建大型、高可用、可扩展的分布式微服务系统。

------

## 准备工作

### 环境要求

| 工具  | 版本                    | 推荐下载                                                     |
| ----- | ----------------------- | ------------------------------------------------------------ |
| JDK   | 17 或以上               | [Eclipse Temurin](https://adoptium.net/)                     |
| Maven | 3.6.3+                  | [Apache Maven](https://maven.apache.org/download.cgi)        |
| IDE   | IntelliJ IDEA / Eclipse | [IntelliJ IDEA](https://www.jetbrains.com/idea/)             |
| MySQL | 5.7 / 8.0+              | [MySQL Community](https://dev.mysql.com/downloads/mysql/)    |
| Redis | 5.0+                    | [Windows版 5.0.14.1 ](https://github.com/tporadowski/redis/releases/) |

> ✅ 建议使用 JDK 17+ 和 Maven 3.8+，确保兼容性。

------

## 配置 Maven（关键）

JavaFreeCloud 使用私有 Maven 仓库，需配置 `settings.xml`。

### 1. 文件路径

```bash
# 全局配置（推荐）
{MAVEN_HOME}/conf/settings.xml

# 用户配置
{USER_HOME}/.m2/settings.xml
```

### 2. 配置内容（关键片段）

将以下配置**合并**到你的 `settings.xml` 中：

```xml
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0">
  <!-- 本地仓库（可选） -->
  <localRepository>E:/maven-repo</localRepository>

  <!-- 镜像：阿里云代理中央仓库 -->
  <mirrors>
    <mirror>
      <id>aliyun-central</id>
      <mirrorOf>central,!2602177-release-16ys0R,!2602177-snapshot-tixmOn</mirrorOf>
      <name>Aliyun Central</name>
      <url>https://maven.aliyun.com/repository/central</url>
    </mirror>
  </mirrors>

  <!-- 私有仓库认证 -->
  <servers>
    <server>
      <id>2602177-release-16ys0R</id>
      <username>68ecafb91a2f30e9eb4f0a45</username>
      <password>4M3ESLdeE3(D</password>
    </server>
    <server>
      <id>2602177-snapshot-tixmOn</id>
      <username>68ecafb91a2f30e9eb4f0a45</username>
      <password>4M3ESLdeE3(D</password>
    </server>
  </servers>

  <!-- 仓库地址 -->
  <profiles>
    <profile>
      <id>javafree-public</id>
      <repositories>
        <repository>
          <id>2602177-release-16ys0R</id>
          <url>https://packages.aliyun.com/68ecb026ccf3499544d8ade3/maven/2602177-release-16ys0r</url>
          <releases><enabled>true</enabled></releases>
          <snapshots><enabled>false</enabled></snapshots>
        </repository>
        <repository>
          <id>2602177-snapshot-tixmOn</id>
          <url>https://packages.aliyun.com/68ecb026ccf3499544d8ade3/maven/2602177-snapshot-tixmon</url>
          <releases><enabled>false</enabled></releases>
          <snapshots><enabled>true</enabled></snapshots>
        </repository>
        <repository>
          <id>central</id>
          <url>https://repo1.maven.org/maven2</url>
          <releases><enabled>true</enabled></releases>
        </repository>
      </repositories>
      <pluginRepositories>
        <!-- 同上，略 -->
      </pluginRepositories>
    </profile>
  </profiles>

  <!-- 激活 profile -->
  <activeProfiles>
    <activeProfile>javafree-public</activeProfile>
  </activeProfiles>
</settings>
```

> ✅ 重点说明：
>
> - `mirrorOf` 中排除私有仓库 ID，避免镜像覆盖。
> - `server` 提供私有仓库认证。
> - `activeProfiles` 确保配置生效。

------

## 选择并配置您的工程

请根据您的需求选择对应的工程进行开发。

### 工程一：`javafree-springboot-demo` (单体应用)

#### 1. 项目结构

```bash
javafree-springboot-demo/
├── src/
│   └── main/
│       ├── java/
│       │   └── com/example/MyApplication.java
│       └── resources/
│           ├── application.yml
│           ├── mysql.yml
│           ├── jwt.yml
│           ├── cache.yml
│           ├── accesslog.yml
│           └── springdoc.yml
├── pom.xml
```

#### 2. `pom.xml` 配置

```xml
<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0">
  <modelVersion>4.0.0</modelVersion>

  <groupId>com.example</groupId>
  <artifactId>my-javafree-app</artifactId>
  <version>1.0-SNAPSHOT</version>

  <properties>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <spring-boot.version>3.5.6</spring-boot.version>
    <javafree.cloud.version>2.0.1</javafree.cloud.version>
  </properties>

  <!-- 依赖管理 -->
  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>cn.javafree.cloud</groupId>
        <artifactId>javafree-cloud-dependencies</artifactId>
        <version>${javafree.cloud.version}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>

  <dependencies>
    <!-- 核心 Starter -->
    <dependency>
      <groupId>cn.javafree.springboot</groupId>
      <artifactId>javafree-spring-boot-starter</artifactId>
    </dependency>

    <!-- Lombok（简化代码） -->
    <dependency>
      <groupId>org.projectlombok</groupId>
      <artifactId>lombok</artifactId>
      <scope>provided</scope>
    </dependency>
  </dependencies>

  <!-- 构建插件 -->
  <build>
    <plugins>
      <plugin>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-maven-plugin</artifactId>
        <version>${spring-boot.version}</version>
      </plugin>
    </plugins>
  </build>
</project>
```

> ✅ 说明：
>
> - 使用 BOM 管理版本，避免冲突。
> - 引入 `javafree-spring-boot-starter` 即获得全套功能。

#### 3. 主启动类

```java
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class MyApplication {
    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}
```

#### 4. 核心配置文件说明

该工程的所有配置文件均位于 `src/main/resources` 目录下，通过 `application.yml` 的 `spring.config.import` 功能进行加载。

**`application.yml`**

```yaml
server:
  port: 8090

spring:
  application:
    name: javafree-cloud-demo
  config:
    import:
      - classpath:mysql.yml
      - classpath:jwt.yml
      - classpath:cache.yml
      - classpath:accesslog.yml
      - classpath:springdoc.yml
      
   # 文件上传配置
  servlet:
    multipart:
      max-file-size: 512MB
      max-request-size: 512MB
      enabled: true
      file-size-threshold: 0

logging:
  level:
    ROOT: INFO
    cn.javafree.cloud: INFO
  file:
    name: javafree-springboot-demo.log

debug: false
```

> ✅ **说明**：通过 `import` 机制引入多个 YAML 配置文件，实现配置分离。
>
> 文件说明：
>
> | 文件            | 用途                                                 |
> | --------------- | ---------------------------------------------------- |
> | `mysql.yml`     | 数据库连接配置（如 Druid、JPA、MyBatis）             |
> | `jwt.yml`       | JWT 认证相关配置（密钥、过期时间等）                 |
> | `cache.yml`     | 缓存配置（如 Redis、Caffeine）                       |
> | `accesslog.yml` | 访问日志记录配置（如拦截器、日志格式）               |
> | `springdoc.yml` | API 文档配置（集成 SpringDoc OpenAPI，替代 Swagger） |
>
> ⚠️ 注意：这些文件需放在 `src/main/resources` 目录下。

------

### 工程二：`javafree-springcloud-demo` (微服务应用)

#### 1. 项目结构

```bash
javafree-springcloud-demo/
├── src/
│   └── main/
│       ├── java/
│       │   └── com/example/SpringCloudDemoApplication.java
│       └── resources/
│           ├── application.yml 
│           └── logback-spring.xml
├── pom.xml
```

> 💡 说明： 
>
> - `application.yml`：应用主配置。优先加载，用于连接 Nacos 配置中心。

#### 2. `pom.xml` 配置

```xml
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>javafree-springcloud-demo</artifactId>
  <version>1.0-SNAPSHOT</version>
  <packaging>jar</packaging>
  <name>javafree-springcloud-demo</name>
  <description>JavaFree SpringCloud 示例工程</description>
  <properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.source>17</maven.compiler.source>
    <maven.compiler.target>17</maven.compiler.target>
    <javafree.cloud.version>2.0.1</javafree.cloud.version>
  </properties>
  <dependencyManagement>
    <dependencies>
      <dependency>
        <groupId>cn.javafree.cloud</groupId>
        <artifactId>javafree-cloud-dependencies</artifactId>
        <version>${javafree.cloud.version}</version>
        <type>pom</type>
        <scope>import</scope>
      </dependency>
    </dependencies>
  </dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>cn.javafree.springcloud</groupId>
      <artifactId>javafree-spring-cloud-starter</artifactId>
    </dependency>
  </dependencies>
</project>
```

> ✅ 说明：
>
> - 使用 `javafree-cloud-dependencies` 统一管理 Spring Cloud 版本。
> - 引入 `javafree-spring-cloud-starter` 即集成 Nacos、OpenFeign、Gateway、Sentinel 等全套微服务组件。

#### 3. 主启动类

```java
package com.example;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.cloud.client.discovery.EnableDiscoveryClient;
 
@SpringBootApplication
@EnableDiscoveryClient
public class SpringCloudDemoApplication {
   public static void main(String[] args) { 
        SpringApplication.run(SpringCloudDemoApplication.class, args);
    }
}
```

#### 4. 核心配置文件说明

**`application.yml`**

```yaml
spring:
  cloud:
    nacos:
      config:
        server-addr: 127.0.0.1:8848
        file-extension: yaml
        namespace: dev
        group: DEFAULT_GROUP
        timeout: 3000

      # 注册中心配置
      discovery:
        server-addr: 127.0.0.1:8848
        namespace: dev
        group: DEFAULT_GROUP
        service: ${spring.application.name}
        enabled: true

  # 👇 关键：导入多个 Nacos 配置文件（Data ID）
  config:
    import:
      - optional:nacos:javafree-local-application.yaml?refreshEnabled=true
      - optional:nacos:javafree-local-datasource.yaml?refreshEnabled=true
      - optional:nacos:javafree-local-jwt.yaml?refreshEnabled=true
      - optional:nacos:javafree-local-cache.yaml?refreshEnabled=true
      - optional:nacos:javafree-local-logging.yaml?refreshEnabled=true
      - optional:nacos:javafree-local-accesslog.yaml?refreshEnabled=true

# 建议关闭，除非调试自动配置
debug: false

# 可保留，但优先级低于 logging.yaml 或 logback-spring.xml
logging:
  level:
    root: info
```

> **核心概念：Nacos 配置中心与 Data ID**
>
> 代码中 `spring.config.import` 列表里的每一项： `optional:nacos:javafree-local-xxx.yaml?refreshEnabled=true`
>
> - `optional:nacos:`: 表示这是一个可选的 Nacos 配置，即使 Nacos 服务器暂时不可用或该配置不存在，应用也能启动（只是缺少这部分配置）。
> - `javafree-local-xxx.yaml`: 这就是你要从 Nacos 拉取的 **Data ID**。
> - `?refreshEnabled=true`: 表示开启配置的动态刷新。当 Nacos 上的这个配置文件被修改并发布后，你的应用能自动感知并更新配置，而无需重启。
>
> ------
>
> **这些 `javafree-local-xxx.yaml` 文件的说明**（需在 Nacos 控制台创建）
>
> | Data ID                           | 用途说明                                                     |
> | --------------------------------- | ------------------------------------------------------------ |
> | `javafree-local-application.yaml` | 应用通用配置，如服务端口、文件上传限制等。                   |
> | `javafree-local-datasource.yaml`  | **数据库配置**，包含数据库 URL、用户名、密码等敏感信息。     |
> | `javafree-local-jwt.yaml`         | **JWT 安全认证配置**，包含密钥路径、过期时间、白名单等。     |
> | `javafree-local-cache.yaml`       | **缓存配置**，定义 Redis 服务器地址、连接池参数、多级缓存策略等。 |
> | `javafree-local-logging.yaml`     | **日志级别配置**，动态调整不同包的日志输出级别。             |
> | `javafree-local-accesslog.yaml`   | **访问日志配置**，控制操作日志的存储方式（JPA/Elasticsearch）、保留时间等。 |

------

## 启动 Nacos 服务

### 1. 下载并启动 Nacos

```bash
# 下载 Nacos Server
wget https://github.com/alibaba/nacos/releases/download/3.0.2/nacos-server-3.0.2.zip
unzip nacos-server-3.0.2.zip

# 启动（单机模式）
cd nacos/bin
sh startup.sh -m standalone
```

访问：`http://localhost:8080/nacos`
默认账号：`nacos` / `nacos`

### 2. 在 Nacos 中创建配置

在 Nacos 控制台创建 前面介绍的几个`javafree-local-xxx.yaml` 文件

![nacos中配置文件目录](docs/images/nacos-yml.png)

------

## 数据库初始化

JavaFreeCloud 支持 JPA 自动建表或手动 SQL 初始化。

### 1. 创建数据库

```sql
CREATE DATABASE javafree_demo CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

### 2. 初始化方式

#### ✅ 方式一：使用 Flyway（推荐）

```xml
<dependency>
  <groupId>org.flywaydb</groupId>
  <artifactId>flyway-core</artifactId>
</dependency>
```

> 脚本路径：`classpath:db/migration/mysql/V1.0__create_tables.sql`

#### ✅ 方式二：手动执行 SQL

从工程目录中提取 SQL 并执行：

```

db/migration/
├── V1.0__create_tables.sql
|── V1.1__insert_data.sql 
```

------

## 启动与验证

### 1. 启动应用

运行对应工程的 `Application.java`。

### 2. 验证结果

#### 对于 `javafree-springboot-demo`

| 项目     | 地址                                    | 预期结果                                                 |
| -------- | --------------------------------------- | -------------------------------------------------------- |
| 应用启动 | 控制台                                  | 输出 `Started MyApplication`                             |
| 系统登录 | `GET http://localhost:8090/`            | 进入系统登录页，输入用户名密码可登录系统(admin/12345678) |
| API 文档 | `http://localhost:8090/swagger-ui.html` | 显示 Swagger UI                                          |
| 日志输出 | 控制台                                  | 包含 INFO 级别日志                                       |

#### 对于 `javafree-springcloud-demo`

| 项目         | 地址 / 操作                             | 预期结果                                  |
| ------------ | --------------------------------------- | ----------------------------------------- |
| Nacos 控制台 | `http://localhost:8080/nacos`           | 在「服务列表」中看到 `javafree-cloud-web` |
| 应用日志     | 控制台                                  | 输出 `Registered service` 和 `Started`    |
| API 文档     | `http://localhost:8090/swagger-ui.html` | 显示 Swagger UI                           |

------

## 核心功能模块

| 模块        | 功能                                    | 适用工程 |
| ----------- | --------------------------------------- | -------- |
| `auth`      | JWT 认证、权限控制、登录拦截            | 两者     |
| `cache`     | Redis + Caffeine 二级缓存               | 两者     |
| `accesslog` | 请求日志自动记录（JPA / Elasticsearch） | 两者     |
| `springdoc` | OpenAPI 3 文档生成                      | 两者     |
| `common`    | 统一响应、异常处理、工具类              | 两者     |
| `nacos`     | 服务注册与发现 + 配置中心               | 微服务   |
| `openfeign` | 声明式 HTTP 客户端，服务间调用          | 微服务   |
| `sentinel`  | 流量控制、熔断降级、系统保护            | 微服务   |

------

## 常见问题

| 问题                            | 解决方案                                                     |
| ------------------------------- | ------------------------------------------------------------ |
| 依赖下载失败                    | 检查 `settings.xml` 是否正确配置私有仓库                     |
| 启动报 `ClassNotFoundException` | 安装 Lombok 插件并启用注解处理                               |
| Swagger 打不开                  | 检查端口是否被占用，或 `springdoc.enabled` 是否为 `true`     |
| 日志未输出                      | 检查 `logging.level` 配置                                    |
| 服务未注册到 Nacos              | 检查 `application.yml` 中 `nacos.discovery.server-addr` 配置 |
| 配置未生效 (微服务)             | 检查 Nacos 中 `dataId` 和 `group` 是否匹配，配置内容是否正确 |

------

## 📚 下一步

- 查看 [JavaFreeCloud 完整文档](http://docs.javafree.cn/)

------

## ⚖️ 商业授权说明

**重要提示：自 2025年11月1日起，JavaFreeCloud Framework 已正式启用商业授权协议。** 本项目中的 `javafree-springboot-demo` 和 `javafree-springcloud-demo` 仅为技术演示工程，**不得在生产环境中直接使用**。

### 授权主体

本产品的版权所有者与授权方为 **JavaFree 软件工作室**。

### 授权模式

JavaFreeCloud 提供两种商业授权模式，您可根据企业需求选择：

| 功能项                      | 源码授权版 | 非源码授权版   |
| --------------------------- | ---------- | -------------- |
| 获取前后端源代码            | ✅ 是       | ❌ 否           |
| 允许二次开发与修改          | ✅ 是       | ❌ 禁止反向工程 |
| 获取构建包（二进制）        | ✅ 是       | ✅ 是           |
| 多生产环境部署              | ✅ 是       | ✅ 是           |
| 组织内分发                  | ✅ 是       | ✅ 是           |
| 构建 SaaS/PaaS 平台对外提供 | ❌ 禁止     | ❌ 禁止         |
| 不得移除版权标识            | ✅ 必须保留 | ✅ 必须保留     |

#### 定价方案

**1. 源码授权 · 企业版（推荐）**

- **企业版年费**：¥9,999 元/年/项目
- **永久授权**：¥29,999 元/项目（含三年免费升级）
- **团队体验版**：¥2,999 元/年（限1项目 & 1生产环境）

> **优势**：获取完整源代码，支持深度定制、无缝集成与自主可控，适合有技术团队的企业构建核心业务系统。

**2. 非源码授权 · 二进制包**

- **企业版年费**：¥3,999 元/年/项目
- **永久授权**：¥9,999 元/项目（含三年免费升级）
- **团队体验版**：¥999 元/年（限1项目用于生产环境）

> **优势**：低成本快速上线，直接使用官方构建包。

### 使用规则

- **授权凭证**：正式授权客户将获得电子版《商业授权证书》及唯一授权码，需在系统中验证。

- 授权期限：

  - **年费授权**：有效期1年，到期续费可继续使用新版本与技术支持。
  - **永久授权**：一次性买断，永久使用当前及未来三年内的所有版本更新。
  
- **免责声明**：本软件按“原样”提供，不提供任何明示或暗示的担保。JavaFree 软件工作室不对因使用本产品而导致的数据丢失、业务中断或其他间接损失承担责任。

- **违规处理**：对于未经授权的使用、分发、破解或转售行为，JavaFree 软件工作室将依法追责，包括但不限于终止授权、要求赔偿损失和提起法律诉讼。

### 开源依赖声明

本产品集成以下开源项目，并严格遵循其原始许可证：

- Spring Boot / Spring Cloud Alibaba（Apache License 2.0）
- Nacos（Apache License 2.0）
- Vue.js / React（MIT License）
- element-plus（MIT License）
- tdesign-vue-next（MIT License）

### 联系我们

- 📧 **商务与授权咨询**：[gwz126@126.com](mailto:gwz126@126.com)
- 🌐 **官方网站**：[http://www.javafree.cn](http://www.javafree.cn/)
- 💬 **立即咨询**：[点击发送邮件](mailto:gwz126@126.com?subject=JavaFreeCloud 授权咨询)

**在您将 JavaFreeCloud 框架用于生产环境前，请务必联系官方获取正式授权。**