# my-demo-app

**Repository Path**: zhouzq2046/my-demo-app

## Basic Information

- **Project Name**: my-demo-app
- **Description**: 一个基于 Spring Boot 的 Maven 多模式打包示例项目，展示了如何构建灵活、可维护的 Java 应用部署方案。
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-07
- **Last Updated**: 2026-04-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Product README - My Demo App

> **👥 目标读者**: 开发人员、技术爱好者  
> **📖 本文档内容**: 项目简介、快速开始、开发指南

基于 Spring Boot 的 Maven 多模式打包示例项目。

## ✨ 核心特性

- 🚀 **双模式打包** - Thin（瘦身）和 Fat（胖包）两种模式，通过 Maven Profile 灵活切换
- 🎯 **Profile 组合扩展** - 可选包含文档、源码等附加内容，满足不同场景需求
- 📦 **精确 Classpath 管理** - 避免 MANIFEST.MF 长度限制
- ⚙️ **配置外部化** - 配置文件不打包进 JAR，支持动态修改
- 📝 **资源版本化管理** - Release 文档自动添加版本号
- 🌍 **跨平台支持** - Linux、Mac、Windows

## 🚀 快速开始

### 构建项目

```bash
# Thin 模式（默认）- 瘦身 JAR + 外部依赖
mvn clean verify

# Fat 模式 - 包含所有依赖的可执行 JAR
mvn clean verify -Pfat
```

构建完成后，分发包位于 `target/release/` 目录。

**详细部署指南请查看**: [Installation Guide](documents/Admin-Guide.md)

### 本地测试

构建完成后，您可以直接在 `target/release/` 目录测试应用，无需解压 ZIP：

```bash
# 进入 release 目录（或在 bin 目录下直接执行亦可）
cd target/release

# Linux/Mac（在release根目录或bin目录均可执行）
./bin/run.sh
# 或 cd bin && ./run.sh

# Windows（在release根目录或bin目录均可执行）
bin\run.cmd
# 或 cd bin && run.cmd
```

> **💡 提示**: 启动脚本会自动检测是否存在 `classpath.txt` 文件来判断运行模式：
> - 存在 `classpath.txt` → Thin模式（使用-cp参数）
> - 不存在 → Fat模式（使用-jar参数）

应用启动后，访问 http://localhost:8080 查看结果。

> **💡 提示**: 这种测试方式与生产环境完全一致，确保部署前验证通过。

## 🔧 Maven Profile 说明

本项目提供了多个 Maven Profile，可以组合使用以满足不同的构建需求。

### 核心 Profile

#### 1. `thin`（默认）- Thin 模式打包

**特点**：
- 生成瘦身 JAR（约 5KB），只包含应用代码
- 依赖库独立存放在 `lib/` 目录
- 生成 `classpath.txt` 精确管理依赖路径
- 适合微服务架构和频繁迭代的场景

**使用方式**：
```bash
# 默认激活，无需指定
mvn clean verify

# 显式指定
mvn clean verify -Pthin
```

**产物**：`my-demo-app-{version}-thin-dist.zip`

> **⚠️ 注意**: 默认情况下（不指定任何profile），只会激活 `thin` profile，不会包含文档和源码。
> 如需包含文档或源码，请显式指定对应的profile（见下方Profile组合示例）。

---

#### 2. `fat` - Fat 模式打包

**特点**：
- 生成包含所有依赖的可执行 JAR（约 20MB）
- 单个文件，部署简单
- 可直接使用 `java -jar` 运行
- 适合容器化部署和独立部署场景

**使用方式**：

```bash
mvn clean verify -Pfat
```

**产物**：`my-demo-app-{version}-fat-dist.zip`

> **⚠️ 注意**: Fat模式生成的JAR包含所有依赖（约20MB），而Thin模式的JAR仅包含应用代码（约5KB）。
>
> 如需包含文档或源码，请显式指定对应的profile（见下方Profile组合示例）。

---

### 可选 Profile（可与核心 Profile 组合使用）

#### 3. `include-documents` - 包含产品文档

**作用**：将以下产品文档复制到分发包中
- Release.md
- Admin-Guide.md
- Upgrade-Guide.md
- Full-Installation.md
- White-paper.md
- assets/ 目录（SQL脚本、配置附件等）

**使用方式**：

```bash
# Thin 模式 + 文档
mvn clean verify -Pthin,include-documents

# Fat 模式 + 文档
mvn clean verify -Pfat,include-documents
```

**特性**：
- ✅ 自动添加版本号到文档文件名（如 `Release-1.1.0.md`）
- ✅ 自动更新文档内部的交叉引用链接
- ✅ 版本文档和资源统一存储在 `documents/assets/{version}/` 目录
- ✅ 支持自定义文档的版本化管理(需要修改pom.xml)

**分发包结构**：
```
my-demo-app-{version}/
├── documents/
│   ├── Release-{version}.md
│   ├── Admin-Guide-{version}.md
│   ├── Upgrade-Guide-{version}.md
│   ├── Full-Installation-{version}.md
│   ├── White-paper-{version}.md
│   └── assets/                    # 版本资源（含文档、SQL、附件）
│       └── {version}/
│           ├── *.md               # 版本文档
│           ├── sql/               # 数据库脚本
│           └── attachments/       # 配置附件
└── ...
```

---

#### 4. `include-custom-source-code` - 包含完整源码

**作用**：将完整的源代码复制到分发包的 `source-code/` 目录

**使用方式**：
```bash
# Thin 模式 + 源码
mvn clean verify -Pthin,include-custom-source-code

# Fat 模式 + 文档 + 源码
mvn clean verify -Pfat,include-documents,include-custom-source-code
```

**包含内容**：
- ✅ Java 源代码（`src/main/java/`）
- ✅ 配置文件（`src/main/resources/`）
- ✅ 启动脚本（`src/main/scripts/`）
- ✅ Maven 配置（`pom.xml`）
- ✅ Assembly 描述符（`src/assembly/`）
- ✅ 产品文档（`documents/`，排除 assets）
- ✅ 项目说明（`README.md`）

**不包含的内容**：
- ❌ `documents/assets/` - 版本资源（在源码仓库中，但分发包中只包含当前版本）
- ❌ `target/` - 构建产物

**适用场景**：
- 开源项目发布
- 供客户学习研究
- 技术分享和演示

---

#### 5. `include-standard-source-code` - 生成标准源码包

**作用**：生成标准的 Maven 源码包（`-sources.jar`），用于仓库部署

**使用方式**：
```bash
mvn clean deploy -Pinclude-standard-source-code
```

**产物**：`my-demo-app-{version}-sources.jar`

**特点**：
- 符合 Maven 中央仓库规范
- IDE 可自动下载并关联源码
- 便于开发者阅读和学习

**注意**：此 Profile 通常与 `deploy` 阶段配合使用，而不是 `verify`。

---

### Profile 组合示例

#### 示例 1：生产环境部署（推荐）

```bash
# Thin 模式 + 文档
mvn clean verify -Pthin,include-documents
```

**适用场景**：生产环境部署，提供完整的文档支持

---

#### 示例 2：开源项目发布

```bash
# Thin 模式 + 文档 + 完整源码
mvn clean verify -Pthin,include-documents,include-custom-source-code
```

**适用场景**：GitHub 发布，提供完整的源代码和文档

---

#### 示例 3：Maven 仓库部署

```bash
# Fat 模式 + 标准源码包
mvn clean deploy -Pfat,include-standard-source-code
```

**适用场景**：部署到 Nexus/Artifactory，供其他项目依赖

---

#### 示例 4：最小化构建

```bash
# 仅 Thin 模式，无文档无源码
mvn clean verify
```

**适用场景**：CI/CD 流水线，快速构建和测试

---

### Profile 优先级和冲突

- **互斥 Profile**：`thin` 和 `fat` 不能同时使用（后指定的会覆盖先指定的）
- **可组合 Profile**：`include-documents`、`include-custom-source-code`、`include-standard-source-code` 可以与任意核心 Profile 组合
- **默认 Profile**：未指定时，默认使用 `thin` 模式

### 查看当前激活的 Profile

```bash
mvn help:active-profiles
```

输出示例：
```
The following profiles are active:
 - thin (source: com.example:my-demo-app:1.1.0)
 - include-documents (source: com.example:my-demo-app:1.1.0)
```

## 📂 项目结构

```
my-demo-app/
├── src/
│   ├── main/
│   │   ├── java/            # 应用代码
│   │   ├── resources/       # 配置文件（不打包进 JAR）
│   │   └── scripts/         # 启动脚本
│   └── assembly/            # 打包描述符
├── documents/               # 文档目录
│   ├── assets/              # 版本资源（文档、SQL、附件）
│   │   └── {version}/       # 版本号目录
│   │       ├── *.md         # 版本文档
│   │       ├── sql/         # 数据库脚本
│   │       └── attachments/ # 配置附件
│   ├── Admin-Guide.md       # 运维说明（源文件）
│   ├── Upgrade-Guide.md     # 升级安装说明（源文件）
│   ├── Full-Installation.md # 安装说明（源文件）
│   ├── White-paper.md       # 产品白皮书（源文件）
│   └── Release.md           # 发布说明（源文件）
├── pom.xml                  # Maven 配置
└── README.md                # 本文件
```

### 📁 documents/assets 目录规范

`documents/assets/` 目录用于存储版本相关的所有资源，包括版本文档、数据库脚本、配置模板等。

#### 目录结构

```
documents/assets/
├── {version}/                                  # 版本号目录（如 1.0.0, 1.1.0）
│    ├── Release-{version}.md                   # 版本文档
│    ├── White-paper-{version}.md
│    ├── Admin-Guide-{version}.md
│    ├── Upgrade-Guide-{version}.md
│    ├── Full-Installation-{version}.md
│    ├── README-{version}.md
│    ├── sql/                                   # 数据库脚本
│    │   ├── {version}-init.sql                 # 全量初始化脚本
│    │   ├── {version}-{14位时间戳}-{tag}.sql   # 增量升级脚本
│    │   └── ...                                # 更多升级脚本
│    └── attachments/                           # 该版本的配置文件、模板等附加资源
└── ...                                         # 更多版本
```

#### 文件命名规范

**SQL 脚本**：

- `{version}-init.sql` - 全量初始化脚本（全新安装使用）
- `{version}-{14位时间戳}-{tag}.sql` - 增量升级脚本（从上一版本升级）

**附件目录**：

- `attachments` - 按版本组织的附件目录
- 每个版本只包含该版本**新增**的附件

#### 使用场景

**1. 全新安装**（参考 [Full Installation Guide](documents/Full-Installation.md)）
```bash
# 执行全量初始化脚本
mysql -u root -p my_demo_app < documents/assets/{version}/sql/{version}-init.sql
```

**2. 版本升级**（参考 [Upgrade Guide](documents/Upgrade-Guide.md)）
```bash
# 按时间戳顺序执行增量升级脚本
mysql -u root -p my_demo_app < documents/assets/{version}/sql/{version}-{14位时间戳}-{tag}.sql
```

**3. 配置附件**
```bash
# 复制当前版本的配置模板
cp documents/assets/{version}/attachments/custom-config.yml config/
```

#### 版本管理原则

- ✅ **累积性**：全量安装脚本包含所有历史版本的变更
- ✅ **增量性**：升级脚本只包含从上一版本到当前版本的变更
- ✅ **独立性**：每个版本的附件独立存放，便于追溯
- ✅ **自动化**：构建时自动合并生成全量脚本和带版本号的文档

#### 添加新版本资源

当发布新版本（如 v1.2.0）时：

1. **创建版本目录**：`documents/assets/1.2.0/`
2. **构建时自动生成版本文档** - Maven 会自动处理并保存到该目录
3. **创建全量脚本**：`documents/assets/1.2.0/sql/1.2.0-init.sql`
4. **创建升级脚本**：`documents/assets/1.2.0/sql/1.2.0-{14位时间戳}-{tag}.sql`
5. **添加新附件**：`documents/assets/1.2.0/attachments/`
6. **更新文档**：在 Full-Installation.md 和 Upgrade-Guide.md 中引用新资源
7. **构建验证**：运行 `mvn clean verify -Pinclude-documents` 检查资源是否正确打包

## 🛠️ 技术栈

- **Java**: 21
- **Spring Boot**: 3.5.13
- **Maven**: 3.6+

详细的技术栈和插件版本请查看 [Release Notes](documents/Release.md)。

## 📚 更多文档

- **[Release Notes](documents/Release.md)** - 版本发布说明和交付产物
- **[Installation Guide](documents/Admin-Guide.md)** - 部署指南、配置管理和运维手册
- **[Product White Paper](documents/White-paper.md)** - 产品白皮书和技术架构详解

## ❓ 常见问题

### 执行 `mvn deploy` 时会部署什么文件？

**部署的文件**：
- ✅ 主 JAR（`my-demo-app-{version}.jar`）
- ✅ ZIP 分发包（`my-demo-app-{version}-thin-dist.zip` 或 `fat-dist.zip`）
- ✅ 源码包（`my-demo-app-{version}-sources.jar`，需激活 `include-standard-source-code` profile）
- ✅ POM 文件（`my-demo-app-{version}.pom`）

**原因**：
- `maven-deploy-plugin` 使用默认配置，会部署所有构件（包括主 JAR 和附加构件）
- `maven-assembly-plugin` 配置了 `<attach>true</attach>`，将 ZIP 作为附加构件部署
- `maven-source-plugin` 在激活 `include-standard-source-code` profile 时生成并附加源码包

**设计理念**：
- 这是一个分发型项目，主要交付物是 ZIP 分发包
- 主 JAR 也会部署到仓库，供其他项目直接依赖（可选）
- ZIP 分发包适合最终用户下载和部署
- 源码包供 IDE 开发者参考和学习（可选）

> **💡 提示**: 如果不想部署任何文件（包括主 JAR 和 ZIP），可以在 pom.xml 中为 `maven-deploy-plugin` 添加 `<skip>true</skip>` 配置来完全跳过 deploy 阶段。

### 如何保证 target/release 目录下的文件与 ZIP 文件内的文件一致性？

**目标**：

- `target/release/` 目录下有构建产物（bin、config、documents、JAR等）
- ZIP 包中的内容应该与 `target/release/` **完全一致**

**设计原则**：

本项目采用了**“所见即所得”**的设计理念：

1. **target/release/** - Maven 构建的中间产物
   - 用于本地测试和验证
   - 所有插件（maven-resources-plugin、maven-dependency-plugin等）都将文件复制到此目录
   - 用户可以直接在此目录运行应用，无需解压 ZIP

2. **ZIP 分发包** - 最终交付给用户的产物
   - 由 maven-assembly-plugin 根据 `src/assembly/{profile}-dist.xml` 生成
   - **直接打包整个 `target/release/` 目录**，不做额外过滤或转换
   - 确保 ZIP 内容与本地测试环境完全一致

**如果发现`target/release/` 和 ZIP 内容不一致**，可能的原因：

- Assembly 配置中添加了额外的 `<excludes>` 规则
- 构建过程中某些文件在 assembly 执行后被修改
- 手动修改了 `target/release/` 目录但未重新构建

**解决方案**：

```bash
# 清理并重新构建
mvn clean verify

# 验证一致性
# 1. 检查 target/release/ 目录内容
ls -R target/release/

# 2. 查看 ZIP 包内容
jar tf target/my-demo-app-{version}-{profile}-dist.zip

# 最后参考《如何增加或减少资源文件》进行处理
```

### 如何增加或减少资源文件？

如果您需要修改分发包中包含的资源文件（如添加新的配置文件、脚本或文档），需要同时修改以下两处配置：

#### 步骤 1: 修改 maven-resources-plugin 配置

在 `pom.xml` 的公共插件配置中，找到对应的 execution 并修改 `<resources>` 配置：

**示例：添加新的配置文件**
```xml
<execution>
    <id>copy-config</id>
    <phase>process-resources</phase>
    <goals><goal>copy-resources</goal></goals>
    <configuration>
        <outputDirectory>${project.build.directory}${release-basedir}/config</outputDirectory>
        <resources>
            <resource>
                <directory>${project.basedir}/src/main/resources</directory>
                <includes>
                    <include>application*.yml</include>
                    <include>application*.properties</include>
                    <include>custom-config.yml</include> <!-- 新增 -->
                </includes>
            </resource>
        </resources>
    </configuration>
</execution>
```

**示例：添加新的启动脚本**
```xml
<execution>
    <id>copy-scripts</id>
    <phase>process-resources</phase>
    <goals><goal>copy-resources</goal></goals>
    <configuration>
        <outputDirectory>${project.build.directory}${release-basedir}/bin</outputDirectory>
        <resources>
            <resource>
                <directory>${project.basedir}/src/main/scripts</directory>
                <includes>
                    <include>*.sh</include>
                    <include>*.cmd</include>
                    <include>*.ps1</include> <!-- 新增 PowerShell 脚本 -->
                </includes>
            </resource>
        </resources>
    </configuration>
</execution>
```

#### 步骤 2: 修改 assembly 描述符

在 `src/assembly/thin-dist.xml`（或 `fat-dist.xml`）中，确保新文件被包含在 ZIP 包中：

**示例：添加新的配置文件到 documents**
```xml
<files>
    <!-- 现有文件... -->
    <file>
        <source>${project.basedir}/documents/Custom-Guide.md</source>
        <outputDirectory>/documents</outputDirectory>
        <destName>Custom-Guide-${project.version}.md</destName>
    </file>
</files>
```

**注意**：如果新文件需要版本化管理（如文档），还需要执行以下额外步骤：

**1. 在 `include-documents` profile 的 `maven-resources-plugin` 中排除该文件**
```xml
<!-- pom.xml - include-documents profile -->
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-resources-plugin</artifactId>
    <executions>
        <execution>
            <id>copy-documents</id>
            <configuration>
                <resources>
                    <resource>
                        <directory>${project.basedir}/documents</directory>
                        <excludes>
                            <exclude>Release.md</exclude>
                            <exclude>White-paper.md</exclude>
                            <exclude>Install.md</exclude>
                            <exclude>Custom-Guide.md</exclude> <!-- 新增：排除需要版本化的文件 -->
                            <exclude>history/**</exclude>
                        </excludes>
                    </resource>
                </resources>
            </configuration>
        </execution>
    </executions>
</plugin>
```

**2. 在 `maven-antrun-plugin` 中添加重命名和链接替换逻辑**
```xml
<!-- pom.xml - include-documents profile -->
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-antrun-plugin</artifactId>
    <executions>
        <execution>
            <id>rename-release-notes</id>
            <phase>process-resources</phase>
            <goals><goal>run</goal></goals>
            <configuration>
                <target>
                    <!-- 复制并重命名 Custom-Guide.md -->
                    <copy file="${project.basedir}/documents/Custom-Guide.md"
                          tofile="${project.build.directory}${release-basedir}/documents/Custom-Guide-${project.version}.md"/>
                    
                    <!-- 替换 Custom-Guide.md 内部的链接 -->
                    <replaceregexp file="${project.build.directory}${release-basedir}/documents/Custom-Guide-${project.version}.md"
                                   match="\(Release\.md\)"
                                   replace="(Release-${project.version}.md)"
                                   byline="true"/>
                    <replaceregexp file="${project.build.directory}${release-basedir}/documents/Custom-Guide-${project.version}.md"
                                   match="\(Install\.md\)"
                                   replace="(Install-${project.version}.md)"
                                   byline="true"/>
                    <replaceregexp file="${project.build.directory}${release-basedir}/documents/Custom-Guide-${project.version}.md"
                                   match="\(White-paper\.md\)"
                                   replace="(White-paper-${project.version}.md)"
                                   byline="true"/>
                </target>
            </configuration>
        </execution>
    </executions>
</plugin>
```

**3. 在 `backup-all-documents` execution 中添加备份逻辑**
```xml
<!-- pom.xml - backup-all-documents execution -->
<execution>
    <id>backup-all-documents</id>
    <phase>initialize</phase>
    <goals><goal>run</goal></goals>
    <configuration>
        <target>
            <mkdir dir="${project.basedir}/documents/assets/${project.version}"/>
            
            <!-- 从源文档处理并保存到 assets/{version} -->
            <copy file="${project.basedir}/documents/Custom-Guide.md"
                  tofile="${project.basedir}/documents/assets/${project.version}/Custom-Guide-${project.version}.md"
                  overwrite="true"/>
            
            <!-- 添加版本号标记和链接替换逻辑... -->
        </target>
    </configuration>
</execution>
```

#### 步骤 3: 重新构建

```bash
mvn clean verify
```

#### 验证

检查 `target/release/` 目录和生成的 ZIP 包，确认新文件已正确包含。

> **💡 提示**: 修改后建议运行 `mvn clean verify` 并检查 `target/release/` 目录，确保所有更改生效。

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

MIT License