# 配置重构后的编译说明

**日期**: 2025-01-10
**适用版本**: v1.0.1+

---

## ❓ 配置重构后，编译命令需要改吗？

### 答案：❌ 不需要改！

---

## 📋 编译命令保持不变

### 开发环境编译

```bash
# 完整编译
mvn clean install

# 跳过测试（更快）
mvn clean install -DskipTests

# 只编译 admin 模块
cd qaup-admin
mvn clean package -DskipTests
```

### 生产环境打包

```bash
# 打包生产版本
mvn clean package -DskipTests

# 或指定 profile（可选）
mvn clean package -DskipTests -Pprod
```

---

## 🔍 为什么不需要修改？

### 1. 配置文件自动打包

Maven 会自动将 `src/main/resources/` 下的所有文件打包到 jar 中，包括：

```
qaup-admin/src/main/resources/
├── application.yml              ✅ 自动打包
├── application-dev.yml          ✅ 自动打包
├── application-prod.yml         ✅ 自动打包
└── application-druid.yml        ✅ 自动打包
```

### 2. 环境变量是运行时机制

- `.env` 文件**不打包**到 jar 中（也不应该打包）
- 环境变量在应用**启动时**由 `qaup.sh` 加载
- 与编译过程无关

### 3. Profile 在运行时指定

- Profile 通过 `--spring.profiles.active` 在启动时指定
- 不影响编译过程

---

## 📦 打包后的结构

### jar 包内部结构

```
qaup-admin.jar
├── BOOT-INF/
│   ├── classes/
│   │   ├── application.yml              ✅ 打包
│   │   ├── application-dev.yml          ✅ 打包
│   │   ├── application-prod.yml         ✅ 打包
│   │   ├── application-druid.yml        ✅ 打包
│   │   └── com/qaup/...                 (Java类)
│   └── lib/                             (依赖jar)
├── META-INF/
└── org/springframework/boot/loader/
```

### 部署目录结构

```
/app/                          # 部署目录
├── qaup-admin.jar            # 打包的jar（包含所有配置文件）
├── qaup.sh                   # 启动脚本
├── .env                      ❌ 不打包，部署时手动创建
├── .env.example              📝 可选（建议通过Git获取）
└── logs/                     # 日志目录
```

---

## 🎯 完整的开发-部署流程

### 1️⃣ 开发阶段（本地）

```bash
# 方式1: IDEA 中直接启动
# 自动使用 dev profile，无需编译

# 方式2: Maven 启动
cd qaup-admin
mvn spring-boot:run -Dspring-boot.run.profiles=dev,druid
```

### 2️⃣ 打包阶段

```bash
# 在项目根目录执行
mvn clean package -DskipTests

# 生成的 jar 包位置
ls -lh qaup-admin/target/qaup-admin.jar
```

### 3️⃣ 部署阶段

```bash
# 1. 复制文件到服务器
scp qaup-admin/target/qaup-admin.jar user@server:/app/
scp qaup.sh user@server:/app/
scp .env.example user@server:/app/

# 2. 在服务器上创建配置
cd /app
cp .env.example .env
vim .env

# 3. 启动应用
./qaup.sh start
```

---

## 🔒 重要提醒

### ✅ 应该做的

1. **打包所有配置文件到 jar**
   ```bash
   # application*.yml 会自动打包
   mvn clean package -DskipTests
   ```

2. **在部署时创建 .env**
   ```bash
   # 在服务器上创建
   cp .env.example .env
   vim .env
   ```

3. **通过 Git 管理配置模板**
   ```bash
   # .gitignore
   .env              # 忽略实际配置
   !.env.example     # 保留模板
   ```

### ❌ 不应该做的

1. **不要把 .env 打包到 jar**
   - 包含敏感信息
   - 每个环境配置不同

2. **不要在编译时指定环境变量**
   ```bash
   # ❌ 错误
   mvn clean package -DAIRPORT_API_BASE_URL=http://...

   # ✅ 正确：编译时不指定，运行时通过 .env 加载
   mvn clean package -DskipTests
   ```

3. **不要打包备份文件**
   ```bash
   # 打包前删除
   rm qaup-admin/src/main/resources/*.backup
   ```

---

## 📋 建议的 .gitignore 配置

```bash
# 环境变量配置（重要！）
.env
.env.local
.env.production
.env.*.local

# 配置备份文件
*.backup

# 日志文件
logs/
*.log

# Maven 构建目录
target/

# IDEA 项目文件
.idea/
*.iml
```

---

## 🆚 配置重构前后对比

| 项目 | 重构前 | 重构后 |
|-----|--------|--------|
| **编译命令** | `mvn clean package` | `mvn clean package` ✅ 不变 |
| **配置修改** | 修改配置文件 → 重新打包 | 修改 .env → 重启应用 |
| **环境切换** | 修改配置文件 → 重新打包 | 切换 .env → 重启应用 |
| **敏感信息** | 打包到 jar 中 ❌ | 保存在 .env 中 ✅ |

---

## 💡 常见问题

### Q1: `.env.example` 要打包到 jar 吗？

**A**: 📝 建议不打包

**原因**:
- 可以通过 Git 获取
- 减小 jar 体积
- 部署时从项目源码复制

**操作**:
```bash
# 部署时从项目获取
git clone <repo>
cp <project>/.env.example /app/.env
```

### Q2: 如果我只修改了 .env，需要重新编译吗？

**A**: ❌ 不需要

```bash
# 只需要
vim .env
./qaup.sh restart
```

### Q3: 如果我修改了 application-prod.yml，需要重新编译吗？

**A**: ✅ 需要

```bash
# 修改配置文件后
mvn clean package -DskipTests

# 重新部署 jar
scp qaup-admin/target/qaup-admin.jar user@server:/app/
./qaup.sh restart
```

**建议**: 尽量使用环境变量方式，避免重新打包

---

## 🎯 最佳实践总结

1. ✅ **编译命令保持不变**: `mvn clean package -DskipTests`
2. ✅ **配置文件自动打包**: 所有 `application*.yml` 都会打包
3. ✅ **环境变量运行时加载**: `.env` 不打包，部署时创建
4. ✅ **敏感信息不打包**: 密码、地址等通过 `.env` 管理
5. ✅ **一次打包，多环境部署**: 通过不同的 `.env` 文件区分环境

---

## 📚 相关文档

- [配置文件重构说明](../working/20250110_配置文件重构说明.md)
- [环境变量配置方案](../working/20250110_环境变量配置方案.md)
- [qaup.sh 更新说明](../working/20250110_qaup.sh更新说明.md)
- [CLAUDE.md - 项目说明](../../CLAUDE.md)

---

**文档结束**

**最后更新**: 2025-01-10
**维护者**: QAUP Team