Spring MVC 整合 Thymeleaf 实验手册(一)

Thymeleaf 是流行的模板引擎，在 Spring MVC 可以用来代替默认的 jsp 视图。本实验手册带学员如何在 Sprng MVC 中集成 Thymeleaf，并通过简单的用例介绍 Thymeleaf 的使用。

实验环境

本手册使用
JDK: 1.8
IDE: IDEA Community
Spring MVC: 4.3.8.RELEASE
Thymeleaf: 3.0.11.RELEASE

新建 Maven 项目

打开 IDEA Community, 选择新建项目，然后选择 maven 项目，在右边的列表中选择 “org.apache.maven.archetypes:maven-archetype-webapp”。然后点击 “Next”。

在接下来的对话框中，填入项目名和项目保存的目录。(在这里，我使用 “springmvc-thymeleaf-getstart” 作为项目名) 然后 “Next”.

在接下来的对话框中，简单的选择 “Finish”。

项目生成后，我们打开 IDEA 中的 “Project” 视图，可以看到如下的项目结构(在这里，只列出关键的目录和文件):

springmvc-thymeleaf-getstart
   + src
      + main
         + webapp
            + WEB-INF
              web.xml
            index.jsp
    pom.xml

可以看到，该模板生成的文件夹少了 java 文件夹，我们手动添加进去。

先用鼠标选择 src/main 目录，点击右键，选择建立目录(Directory), 在弹出框的输入框中输入: java 作为目录名，在弹出框的下半部分的选择框中选择 java 类型。

完成后的目录结构如下:

springmvc-thymeleaf-getstart
   + src
      + main
         + java
         + webapp
            + WEB-INF
              web.xml
            index.jsp
    pom.xml

加入依赖库

因为是 maven 项目，所有依赖的声明都包含在 pom.xml 文件中，打开 pom.xml 文件，加入如下内容:

 <properties>
      <spring.version>4.3.8.RELEASE</spring.version>
      <thymeleaf.version>3.0.11.RELEASE</thymeleaf.version>
      <slf4j.version>1.7.7</slf4j.version>
      <log4j.version>1.2.17</log4j.version>
  </properties>

  <dependencies>
	
<!-- Spring -->
      <dependency>
          <groupId>org.springframework</groupId>
          <artifactId>spring-core</artifactId>
          <version>#123;spring.version}</version>
      </dependency>
      <dependency>
          <groupId>org.springframework</groupId>
          <artifactId>spring-web</artifactId>
          <version>#123;spring.version}</version>
      </dependency>
      <dependency>
          <groupId>org.springframework</groupId>
          <artifactId>spring-oxm</artifactId>
          <version>#123;spring.version}</version>
      </dependency>
      <dependency>
          <groupId>org.springframework</groupId>
          <artifactId>spring-tx</artifactId>
          <version>#123;spring.version}</version>
      </dependency>
      <dependency>
          <groupId>org.springframework</groupId>
          <artifactId>spring-jdbc</artifactId>
          <version>#123;spring.version}</version>
      </dependency>
      <dependency>
          <groupId>org.springframework</groupId>
          <artifactId>spring-webmvc</artifactId>
          <version>#123;spring.version}</version>
      </dependency>
      <dependency>
          <groupId>org.springframework</groupId>
          <artifactId>spring-aop</artifactId>
          <version>#123;spring.version}</version>
      </dependency>
      <dependency>
          <groupId>org.springframework</groupId>
          <artifactId>spring-context-support</artifactId>
          <version>#123;spring.version}</version>
      </dependency>
      <!-- End: Spring -->

      <!-- Thymeleaf -->
      <dependency>
          <groupId>org.thymeleaf</groupId>
          <artifactId>thymeleaf-spring4</artifactId>
          <version>#123;thymeleaf.version}</version>
      </dependency>
      <!-- End: Thymeleaf -->

      <!-- Log -->
      <dependency>
          <groupId>log4j</groupId>
          <artifactId>log4j</artifactId>
          <version>#123;log4j.version}</version>
      </dependency>

      <dependency>
          <groupId>org.slf4j</groupId>
          <artifactId>slf4j-api</artifactId>
          <version>#123;slf4j.version}</version>
      </dependency>

      <dependency>
          <groupId>org.slf4j</groupId>
          <artifactId>slf4j-log4j12</artifactId>
          <version>#123;slf4j.version}</version>
      </dependency>
      <!-- End: Log -->

      <!-- Other -->
      <dependency>
          <groupId>javax</groupId>
          <artifactId>javaee-api</artifactId>
          <version>7.0</version>
      </dependency>

      <dependency>
          <groupId>javax.servlet</groupId>
          <artifactId>javax.servlet-api</artifactId>
          <version>4.0.1</version>
          <scope>provided</scope>
      </dependency>

      <dependency>
          <groupId>com.fasterxml.jackson.core</groupId>
          <artifactId>jackson-core</artifactId>
          <version>2.6.3</version>
      </dependency>
      <dependency>
          <groupId>com.fasterxml.jackson.core</groupId>
          <artifactId>jackson-databind</artifactId>
          <version>2.6.3</version>
      </dependency>
      <!-- End: Other -->

  </dependencies>

另外，我们还需要在 pom.xml 文件中加入一些编译、构建选项。如下:

<build>
    <finalName>springmvc-thymeleaf-getstart</finalName>
    <resources>
        <resource>
            <directory>src/main/java</directory>
            <excludes>
                <exclude>**/*.java</exclude>
            </excludes>
        </resource>
        <resource>
            <directory>src/main/resources</directory>
            <includes>
                <include>**/*.*</include>
            </includes>
        </resource>
    </resources>
    <plugins>
        <plugin>
            <groupId>org.apache.tomcat.maven</groupId>
            <artifactId>tomcat7-maven-plugin</artifactId>
            <version>2.2</version>
            <configuration>
                <port>8080</port>
                <path>/</path>
            </configuration>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.7.0</version>
            <configuration>
                <source>1.8</source>
                <target>1.8</target>
            </configuration>
        </plugin>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-war-plugin</artifactId>
            <version>2.6</version>
        </plugin>
    </plugins>
</build>

其中，tomcat7-maven-plugin 是为了在开发阶段能使用 tomcat7 来运行项目。

最后，为了加快依赖库的下载，指名项目使用国内的 maven 仓库:

<repositories>
     <repository>
         <id>alimaven</id>
         <name>aliyun maven</name>
         <url>http://maven.aliyun.com/nexus/content/groups/public/</url>
         <releases>
             <enabled>true</enabled>
         </releases>
         <snapshots>
             <enabled>false</enabled>
         </snapshots>
     </repository>
 </repositories>

修改完成后，保存 pom.xml，如果 IDEA Community 没有开始下载依赖，则需要手动选择: 鼠标右键选择项目(springmvc-thymeleaf-getstart) ，然后在弹出菜单中选择 maven -> reload project。

配置 web.xml 文件

作为 Java Web Application, web.xml 是项目的核心配置文件，我们需要在这里加入Spring MVC 的入口点:

打开 web.xml 文件，加入以下内容:

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xmlns="http://java.sun.com/xml/ns/javaee"
         xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_3_0.xsd"
         version="3.0">
    <display-name>SpringMVC thymeleaf Starter Web Application</display-name>

    <!-- Spring和mybatis的配置文件 -->
    <context-param>
        <param-name>contextConfigLocation</param-name>
        <param-value>classpath:spring-app.xml</param-value>
    </context-param>

    <!-- 编码过滤器 -->
    <filter>
        <filter-name>encodingFilter</filter-name>
        <filter-class>org.springframework.web.filter.CharacterEncodingFilter</filter-class>
        <async-supported>true</async-supported>
        <init-param>
            <param-name>encoding</param-name>
            <param-value>UTF-8</param-value>
        </init-param>
    </filter>
    <filter-mapping>
        <filter-name>encodingFilter</filter-name>
        <url-pattern>/*</url-pattern>
    </filter-mapping>
    <!-- Spring监听器 -->
    <listener>
        <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
    </listener>

    <!-- Spring MVC servlet -->
    <servlet>
        <servlet-name>SpringMVC</servlet-name>
        <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
        <init-param>
            <param-name>contextConfigLocation</param-name>
            <param-value>classpath:spring-mvc.xml</param-value>
        </init-param>
        <load-on-startup>1</load-on-startup>
        <async-supported>true</async-supported>
    </servlet>
    <servlet-mapping>
        <servlet-name>SpringMVC</servlet-name>
        <!-- 此处可以可以配置成*.do，对应struts的后缀习惯 -->
        <url-pattern>/</url-pattern>
    </servlet-mapping>
    <!-- 配置SESSION超时，单位是分钟 -->
    <session-config>
        <session-timeout>15</session-timeout>
    </session-config>

 </web-app>

配置 Spring MVC

在上面的 web.xml 文件中，我们指名了 Spring MVC 的配置文件是: spring-mvc.xml, 现在，我们就来建立该文件。

在 src/main/resources 目录中新建名为: spring-mvc.xml, 内容如下:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:context="http://www.springframework.org/schema/context"
	xmlns:mvc="http://www.springframework.org/schema/mvc"
	xsi:schemaLocation="http://www.springframework.org/schema/beans  
                        http://www.springframework.org/schema/beans/spring-beans-3.1.xsd  
                        http://www.springframework.org/schema/context  
                        http://www.springframework.org/schema/context/spring-context-3.1.xsd  
                        http://www.springframework.org/schema/mvc  
                        http://www.springframework.org/schema/mvc/spring-mvc-4.0.xsd">

	<mvc:annotation-driven/>

	<mvc:resources mapping="/static/**" location="/static/"/>

	<!-- 自动扫描该包，使SpringMVC认为包下用了@controller注解的类是控制器 -->
	<context:component-scan base-package="cn.com.hohistar.training.petstore.web" />

	<!-- 启动SpringMVC的注解功能，完成请求和注解POJO的映射 -->
	<bean
		class="org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerAdapter">
		<property name="messageConverters">
			<list>
				<bean class="org.springframework.http.converter.json.MappingJackson2HttpMessageConverter"/>
				<bean class="org.springframework.http.converter.ByteArrayHttpMessageConverter"/>
				<bean class="org.springframework.http.converter.xml.SourceHttpMessageConverter"/>
				<bean class="org.springframework.http.converter.FormHttpMessageConverter"/>
				<bean class="org.springframework.http.converter.StringHttpMessageConverter"/>
			</list>
		</property>
	</bean>

	<!-- 定义跳转的文件的前后缀 ，视图模式配置-->
	<bean id="templateResolver"
		  class="org.thymeleaf.templateresolver.ServletContextTemplateResolver">
		<property name="prefix" value="/WEB-INF/views/" />
		<property name="suffix" value=".html" />
		<property name="templateMode" value="HTML5" />
		<property name="characterEncoding" value="UTF-8"/>
	</bean>

	<bean id="templateEngine"
		  class="org.thymeleaf.spring4.SpringTemplateEngine">
		<property name="templateResolver" ref="templateResolver" />
	</bean>

	<bean class="org.thymeleaf.spring4.view.ThymeleafViewResolver">
		<property name="templateEngine" ref="templateEngine" />
		<property name="characterEncoding" value="UTF-8"/>
	</bean>

</beans>

配置 Spring

在 web.xml 中，我们指名 Spring 的配置文件为 spring-app.xml, 现在就来建立该文件。

在 src/main/resources 目录中新建名为: spring-app.xml, 内容如下:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:context="http://www.springframework.org/schema/context"
	xmlns:mvc="http://www.springframework.org/schema/mvc"
	xsi:schemaLocation="http://www.springframework.org/schema/beans  
                        http://www.springframework.org/schema/beans/spring-beans-3.1.xsd  
                        http://www.springframework.org/schema/context  
                        http://www.springframework.org/schema/context/spring-context-3.1.xsd  
                        http://www.springframework.org/schema/mvc  
                        http://www.springframework.org/schema/mvc/spring-mvc-4.0.xsd">
	<!-- 自动扫描 -->
	<context:component-scan base-package="cn.com.hohistar.training.petstore" />

</beans>

建立 Controller

在 src/main/java 中建立名为: cn.com.hohistar.training.petstore.web 的java包。

右键选择 src/main/java, 在菜单中选择 package, 然后在弹出框中输入: cn.com.hohistar.training.petstore.web

再右键选择新建好的 cn.com.hohistar.training.petstore.web 包，在菜单中选择 Class, 输入名: IndexController。

打开新建的 IndexController.java 文件，填入如下内容:

@Controller
public class IndexController {

    @GetMapping({"/", "/index"})
    public String index() {
        return "index";
    }
}

建立首页

因为在 spring-mvc.xml 中，我们配置 Thymeleaf 视图的位置为：views, 所以需要首先在 WEB-INF 中建立一个名为 views 的目录。后续建立的所有视图文件都放在该目录下, 建立以后的项目结构如下:

+ src
   + main
      + java
      + webapp
         + WEB-INF
           + views
           web.xml
         index.jsp
 pom.xml

然后在 views 中新建一个名为: index.html 的文件，内容如下:

<!DOCTYPE html>
<html lang="en" xmlns="http://www.w3.org/1999/xhtml" xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="utf-8"/>
    <title th:text="'Hello Thymeleaf !'"></title>
</head>
<body>
<h2 class="hello-title" th:text="'Hello Thymeleaf ！'"></h2>
</body>
</html>

删除原来 WEB-INF 目录下的 index.jsp 文件。

运行程序

在 IDEA Community 中选择 Maven 视图，然后找到: “Plugins” -> “Tomcat7” -> “tomcat7:run-war”, 双击该选择以运行程序。

如果启动争取，可以在输出中看到类似如下的内容:

1	信息: Starting ProtocolHandler ["http-bio-8080"]

表明程序已经运行在本机的 8080 端口了。

现在，打开一个浏览器，访问:

1	http://localhost:8080

就可以看到页面上输出 “Hello Thymeleaf ！” 。

下一步

在下一步中，我们将学习一些 Thymeleaf 的基本使用。