建立新專案

本指南說明如何從 app-server 參考實作建立新的 Spring Boot 專案。

方式一：從參考實作複製（推薦）

1. 複製 app-server 專案

app-server 位於 monorepo 的 modules/app-server 目錄中：

# 複製整個 monorepo
git clone https://gitlab.com/appfuse/webapp/appfuse-webapps-v1.git
cd appfuse-webapps-v1/modules

# 複製 app-server 到新專案目錄
cp -r app-server /path/to/my-project
cd /path/to/my-project

# 初始化新的 Git 歷史
rm -rf .git
git init

2. 更新專案資訊

編輯 build.gradle.kts，修改專案資訊：

group = "com.yourcompany"  // 改為你的組織
version = "0.0.1-SNAPSHOT"

application {
    mainClass = "com.yourcompany.yourapp.Application"  // 改為你的主類別
}

3. 重新命名套件

# 將所有 Java 檔案從 io.leandev.app 重新命名為你的套件
# 範例：重新命名為 com.yourcompany.yourapp
find src -type f -name "*.java" -exec sed -i '' 's/io.leandev.app/com.yourcompany.yourapp/g' {} +

# 移動目錄結構
mkdir -p src/main/java/com/yourcompany/yourapp
mkdir -p src/test/java/com/yourcompany/yourapp
mv src/main/java/io/leandev/app/* src/main/java/com/yourcompany/yourapp/
mv src/test/java/io/leandev/app/* src/test/java/com/yourcompany/yourapp/
rm -rf src/main/java/io
rm -rf src/test/java/io

4. 更新配置檔

重新命名應用程式配置檔並更新 spring.application.name：

# 將 app-server.yml 重新命名為你的應用程式名稱
mv src/main/resources/app-server.yml src/main/resources/my-project.yml

# 更新 application.yml 中的應用程式名稱
# 將 spring.application.name: app-server 改為你的應用程式名稱

編輯 src/main/resources/application.yml：

spring:
  application:
    name: my-project  # 改為你的應用程式名稱（需與 .yml 檔名一致）

5. 清理示範資料

app-server 包含花店管理系統的示範資料，建議保留結構但清空業務邏輯：

# 保留目錄結構，但移除示範 Entity
rm -rf src/main/java/com/yourcompany/yourapp/entity/sales
rm -rf src/main/java/com/yourcompany/yourapp/entity/order
rm -rf src/main/java/com/yourcompany/yourapp/entity/customer
# 保留 tenant、auth、base、file 等基礎模組

# 移除示範 Controller
rm -rf src/main/java/com/yourcompany/yourapp/controller/sales
rm -rf src/main/java/com/yourcompany/yourapp/controller/order
rm -rf src/main/java/com/yourcompany/yourapp/controller/customer

# 移除示範 Service
rm -rf src/main/java/com/yourcompany/yourapp/service/sales
rm -rf src/main/java/com/yourcompany/yourapp/service/order
rm -rf src/main/java/com/yourcompany/yourapp/service/customer

# 移除示範 Repository
rm -rf src/main/java/com/yourcompany/yourapp/repository/sales
rm -rf src/main/java/com/yourcompany/yourapp/repository/order
rm -rf src/main/java/com/yourcompany/yourapp/repository/customer

6. 驗證建置

./gradlew clean build
./gradlew bootRun

訪問 http://localhost:8080/actuator/health 確認應用程式正常運行。

方式二：從零建立（進階）

如果你希望完全自己建立專案結構：

1. 建立 Spring Boot 專案

使用 Spring Initializr 或 IDE 建立基本專案。

2. 添加 AppFuse Server 依賴

在 build.gradle.kts 中添加：

repositories {
    maven {
        url = uri("https://devops.leandev.io/repository/maven-releases/")
    }
}

dependencies {
    implementation("io.leandev.appfuse:appfuse-server:0.0.2-SNAPSHOT")
}

3. 配置應用程式

AppFuse 採用配置檔分離策略，建立以下檔案：

檔案	內容
application.yml	Spring 內建屬性（server、spring、logging 等）
{app-name}.yml	應用程式自訂屬性（app.* 等）

其中 {app-name} 需與 spring.application.name 一致。

參考 app-server 配置

專案結構建議

建議的套件結構（參考 app-server）：

com.yourcompany.yourapp/
├── config/              # 配置類別
│   ├── SecurityConfig.java
│   ├── CacheConfig.java
│   └── ...
├── entity/              # 領域模型（Entity）
│   ├── tenant/          # 多租戶
│   ├── auth/            # 認證（帳號、角色、權限）
│   ├── base/            # 基礎實體（參考資料等）
│   └── yourmodule/      # 你的業務模組
├── repository/          # 資料存取層
│   └── ...
├── service/             # 業務邏輯層
│   └── ...
├── controller/          # REST API 控制器
│   └── ...
└── AppServer.java       # 主程式入口

下一步

• 專案結構說明 - 了解推薦的專案組織方式
• 第一個 API - 建立你的第一個 RESTful API
• 開發最佳實踐 - 學習開發最佳實踐

參考資源

• app-server 原始碼 - 參考實作完整程式碼
• Spring Boot 官方文檔 - Spring Boot 官方指南