JavaWeb 整合 YMP 框架快速上手 (二)：Maven 專案配置與 Web 整合實戰

前言

YMP (Yamate Platform) 是一款輕量級 Java 開發框架，支援 MVC、緩存、數據存取等核心功能。本文記錄在 IntelliJ IDEA + Maven 環境下，從零建立 Web 專案並整合 YMP 框架的完整步驟。

開發環境準備

• IDE：IntelliJ IDEA 2023.x+
• 構建工具：Maven 3.8+
• JDK：1.8 / 11 / 17
• YMP 版本：2.0-SNAPSHOT (需本地編譯安裝至 Maven 倉庫)

步驟一：建立 Maven Web 專案

1. 新建專案向導

1. File → New → Project
2. 選擇 Maven，勾選 Create from archetype
3. 選擇 maven-archetype-webapp
4. 填寫坐標：GroupId、ArtifactId、Version
5. 確認 Maven 設置與專案路徑
6. 命名專案，完成建立

2. 專案結構確認

ymptest/
├── pom.xml
└── src/
    └── main/
        ├── java/
        ├── resources/
        └── webapp/
            ├── WEB-INF/
            │   └── web.xml
            └── index.jsp

步驟二：添加 YMP 依賴

1. 修改 pom.xml

<dependencies>
    <!-- YMP Web MVC 核心 -->
    <dependency>
        <groupId>net.ymate</groupId>
        <artifactId>ymate-platform-webmvc</artifactId>
        <version>2.0-SNAPSHOT</version>
    </dependency>
    
    <!-- YMP 緩存模組 (可選) -->
    <dependency>
        <groupId>net.ymate.platform</groupId>
        <artifactId>ymate-platform-cache</artifactId>
        <version>2.0-SNAPSHOT</version>
    </dependency>
    
    <!-- Servlet API (provided 範圍) -->
    <dependency>
        <groupId>javax.servlet</groupId>
        <artifactId>javax.servlet-api</artifactId>
        4.0.1
        provided
    </dependency>
</dependencies>

2. 重新導入 Maven 依賴

IDEA 右側 Maven 面板 → Reload All Maven Projects，確認依賴下載成功。

步驟三：配置 web.xml 整合 YMP

1. 升級 web.xml 版本

Maven archetype 生成的 web.xml 為 2.3 版本，需升級至 2.5+ 以支援現代 Servlet 特性：

<?xml version="1.0" encoding="UTF-8"?>
<web-app id="WebApp_ID" version="2.5"
    xmlns="https://java.sun.com/xml/ns/javaee"
    xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="https://java.sun.com/xml/ns/javaee 
        https://java.sun.com/xml/ns/javaee/web-app_2_5.xsd">
    
    <!-- 1. YMP 初始化監聽器 -->
    <listener>
        <listener-class>net.ymate.platform.webmvc.support.WebAppEventListener</listener-class>
    </listener>
    
    <!-- 2. 請求分發 Filter (推薦) -->
    <filter>
        <filter-name>DispatchFilter</filter-name>
        <filter-class>net.ymate.platform.webmvc.support.DispatchFilter</filter-class>
    </filter>
    <filter-mapping>
        <filter-name>DispatchFilter</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>
    
    <!-- 3. 或者使用 Servlet 方式 (二選一) -->
    <!--
    <servlet>
        <servlet-name>DispatchServlet</servlet-name>
        <servlet-class>net.ymate.platform.webmvc.support.DispatchServlet</servlet-class>
    </servlet>
    <servlet-mapping>
        <servlet-name>DispatchServlet</servlet-name>
        <url-pattern>/service/*</url-pattern>
    </servlet-mapping>
    -->
    
    <welcome-file-list>
        <welcome-file>index.html</welcome-file>
        <welcome-file>index.jsp</welcome-file>
    </welcome-file-list>
</web-app>

2. 關鍵配置說明

步驟四：添加 YMP 核心配置文件

1. 建立 ymp-conf.properties

位置：src/main/resources/ymp-conf.properties (類路徑根目錄)

2. 核心配置項

# 開發模式：啟用詳細日誌、熱重載等
ymp.dev_mode=true

# 自動掃描包路徑 (多個用逗號分隔)
ymp.autoscan_packages=com.example.controller,com.example.service

# 數據源配置 (範例)
# jdbc.driverClassName=com.mysql.cj.jdbc.Driver
# jdbc.url=jdbc:mysql://localhost:3306/ymptest?useSSL=false
# jdbc.username=root
# jdbc.password=123456

# 緩存配置 (可選)
# cache.provider=ehcache
# cache.config=ehcache.xml

3. 關鍵參數說明

• ymp.dev_mode：開發模式開關，生產環境務必設為 false
• ymp.autoscan_packages：組件掃描基礎包，控制器、服務、實體等需在此包下
• 更多配置參考 YMP 官方文檔

步驟五：驗證整合是否成功

1. 建立測試控制器

package com.example.controller;

import net.ymate.platform.webmvc.annotation.Controller;
import net.ymate.platform.webmvc.annotation.RequestMapping;
import net.ymate.platform.webmvc.view.View;

@Controller
@RequestMapping("/hello")
public class HelloController {

    @RequestMapping("/world")
    public View world() {
        return new View("/hello.jsp").addVariable("message", "YMP 整合成功！");
    }
}

2. 建立簡單視圖

src/main/webapp/hello.jsp：

<%@ page contentType="text/html;charset=UTF-8" %>
<html>
<body>
    <h1>${message}</h1>
</body>
</html>

3. 啟動測試

1. 配置 Tomcat 伺服器 (Run → Edit Configurations → + → Tomcat Server → Local)
2. Deployment 標籤添加專案藍圖
3. 啟動伺服器，瀏覽器訪問 https://localhost:8080/hello/world
4. 看到「YMP 整合成功！」表示整合完成

常見問題排查

下一步學習方向

• YMP 控制器開發：@Controller、@RequestMapping、參數綁定、返回值類型
• 數據存取整合：YMP JDBC 模板、事務管理
• 視圖技術：JSP、FreeMarker、Thymeleaf 整合
• 攔截器與異常處理
• 單元測試與整合測試

總結

本文完整記錄了 Maven Web 專案整合 YMP 框架的標準流程：建立專案 → 添加依賴 → 配置 web.xml → 添加核心配置 → 驗證控制器。掌握這套流程，可快速搭建基於 YMP 的企業級應用基線專案。