SpringBoot 2 验证表单输入框

开篇词

该指南将引导你完成配置 Web 应用表单以支持验证。
 

你将创建的应用

我们将构建一个简单的 Spring MVC 应用，该应用接受用户的输入并通过使用标准验证注解来检查输入。我们还将看到如何在屏幕上显示错误消息，以便用户可以重新输入以使其有效。
 

你将需要的工具

• 大概 15 分钟左右；
• 你最喜欢的文本编辑器或集成开发环境（IDE）
• JDK 1.8 或更高版本；
• Gradle 4+ 或 Maven 3.2+
• 你还可以将代码直接导入到 IDE 中：
  • Spring Too Suite (STS)
  • IntelliJ IDEA
     

如何完成这个指南

像大多数的 Spring 入门指南一样，你可以从头开始并完成每个步骤，也可以绕过你已经熟悉的基本设置步骤。如论哪种方式，你最终都有可以工作的代码。

• 要从头开始，移步至从 Spring Initializr 开始；
• 要跳过基础，执行以下操作：
  • 下载并解压缩该指南将用到的源代码，或借助 Git 来对其进行克隆操作：git clone https://github.com/spring-guides/gs-validating-form-input.git
  • 切换至 gs-validating-form-input/initial 目录；
  • 跳转至该指南的创建 PersonForm 对象。

待一切就绪后，可以检查一下 gs-validating-form-input/complete 目录中的代码。

从 Spring Initializr 开始

对于所有的 Spring 应用来说，你应该从 Spring Initializr 开始。Initializr 提供了一种快速的方法来提取应用程序所需的依赖，并为你完成许多设置。该示例需要 Spring Web 和 Thymeleaf 依赖。下图显示了此示例项目的 Initializr 设置：

上图显示了选择 Maven 作为构建工具的 Initializr。你也可以使用 Gradle。它还将 com.example 和 validating-form-input 的值分别显示为 Group 和 Artifact。在本示例的其余部分，将用到这些值。

以下清单显示了选择 Maven 时创建的 pom.xml 文件：

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
	<modelVersion>4.0.0</modelVersion>
	<parent>
		<groupId>org.springframework.boot</groupId>
		<artifactId>spring-boot-starter-parent</artifactId>
		<version>2.2.2.RELEASE</version>
		<relativePath/> <!-- lookup parent from repository -->
	</parent>
	<groupId>com.example</groupId>
	<artifactId>validating-form-input</artifactId>
	<version>0.0.1-SNAPSHOT</version>
	<name>validating-form-input</name>
	<description>Demo project for Spring Boot</description>

	<properties>
		<java.version>1.8</java.version>
	</properties>

	<dependencies>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-thymeleaf</artifactId>
		</dependency>
		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-web</artifactId>
		</dependency>

		<dependency>
			<groupId>org.springframework.boot</groupId>
			<artifactId>spring-boot-starter-test</artifactId>
			<scope>test</scope>
			<exclusions>
				<exclusion>
					<groupId>org.junit.vintage</groupId>
					<artifactId>junit-vintage-engine</artifactId>
				</exclusion>
			</exclusions>
		</dependency>
	</dependencies>

	<build>
		<plugins>
			<plugin>
				<groupId>org.springframework.boot</groupId>
				<artifactId>spring-boot-maven-plugin</artifactId>
			</plugin>
		</plugins>
	</build>

</project>

以下清单显示了在选择 Gradle 时创建的 build.gradle 文件：

plugins {
	id 'org.springframework.boot' version '2.2.2.RELEASE'
	id 'io.spring.dependency-management' version '1.0.8.RELEASE'
	id 'java'
}

group = 'com.example'
version = '0.0.1-SNAPSHOT'
sourceCompatibility = '1.8'

repositories {
	mavenCentral()
}

dependencies {
	implementation 'org.springframework.boot:spring-boot-starter-thymeleaf'
	implementation 'org.springframework.boot:spring-boot-starter-web'
	testImplementation('org.springframework.boot:spring-boot-starter-test') {
		exclude group: 'org.junit.vintage', module: 'junit-vintage-engine'
	}
}

test {
	useJUnitPlatform()
}

创建 PersonForm 对象

该应用涉及验证用户的姓名和年龄，因此我们首先需要创建一个类来支持用于创建一个人的表单。以下清单（来自 src/main/java/com/example/validatingforminput/PersonForm.java）显示了如何执行该操作：

package com.example.validatingforminput;

import javax.validation.constraints.Min;
import javax.validation.constraints.NotNull;
import javax.validation.constraints.Size;

public class PersonForm {

	@NotNull
	@Size(min=2, max=30)
	private String name;

	@NotNull
	@Min(18)
	private Integer age;

	public String getName() {
		return this.name;
	}

	public void setName(String name) {
		this.name = name;
	}

	public Integer getAge() {
		return age;
	}

	public void setAge(Integer age) {
		this.age = age;
	}

	public String toString() {
		return "Person(Name: " + this.name + ", Age: " + this.age + ")";
	}
}

PersonForm 类拥有两个属性：name 和 age。它被标记了一些标准的验证注解：

• @Size(min=2,max=30)：允许名称长度在 2 至 30 个字符之间；
• @NotNull：不允许空值，如果条目为空，Spring MVC 将生成该值；
• @Min(18)：不允许年龄小于 18 岁。

除此之外，我们还可以看到 name 和 age 的获取和设置方法，以及便捷的 toString() 方法。
 

创建 Web 控制器

现在，我们已经定义了一个表单支持的对象，是时候创建一个简单的 Web 控制器了。以下清单（来自 src/main/java/com/example/validatingforminput/WebController.java）显示了如何做到：

package com.example.validatingforminput;

import javax.validation.Valid;

import org.springframework.stereotype.Controller;
import org.springframework.validation.BindingResult;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.servlet.config.annotation.ViewControllerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;


@Controller
public class WebController implements WebMvcConfigurer {

	@Override
	public void addViewControllers(ViewControllerRegistry registry) {
		registry.addViewController("/results").setViewName("results");
	}

	@GetMapping("/")
	public String showForm(PersonForm personForm) {
		return "form";
	}

	@PostMapping("/")
	public String checkPersonInfo(@Valid PersonForm personForm, BindingResult bindingResult) {

		if (bindingResult.hasErrors()) {
			return "form";
		}

		return "redirect:/results";
	}
}

该控制器具有 GET 和 POST 方法。两种方法都被映射到 /。

showForm 方法返回 form 模版。它在其方法签名中包含 PersonForm，以便模版可以将表单属性与 PersonForm 关联。

checkPersonFormInfo 方法接受两个参数：

• 一个标有 @Valid 注解的 personForm 对象，用于收集表单中填写的属性；
• 一个 bindingResult 对象，以便我们可以测试和检索验证错误。

我们可以从绑定到 PersonForm 对象的表单中检索所有属性。在代码中，我们测试错误。如果遇到错误，则可以将用户送回原始 form 模版。在这种情况下，将显示所有错误属性。

如果该用户的所有属性均有效，则它将浏览器重定向到最终 results 模版。
 

创建 HTML 前端

现在构建 “主” 页面，如以下清单（来自 src/main/resources/templates/form.html）所示：

<html>
    <body>
        <form action="#" th:action="@{/}" th:object="${personForm}" method="post">
            <table>
                <tr>
                    <td>Name:</td>
                    <td><input type="text" th:field="*{name}" /></td>
                    <td th:if="${#fields.hasErrors('name')}" th:errors="*{name}">Name Error</td>
                </tr>
                <tr>
                    <td>Age:</td>
                    <td><input type="text" th:field="*{age}" /></td>
                    <td th:if="${#fields.hasErrors('age')}" th:errors="*{age}">Age Error</td>
                </tr>
                <tr>
                    <td><button type="submit">Submit</button></td>
                </tr>
            </table>
        </form>
    </body>
</html>

该页面包含一个简单的表单，其每个字段都位于表的单独单元格中。该表单适合发布到 /。它被标记为由我们在 Web 控制器的 GET 方法中看到的 personForm 对象的支持。这就是所谓的 “bean 支持形式”。PersonForm bean 中有两个字段，我们可以看到它们被标记为 th:field="{name}" 和 th:field="{age}"。每个字段旁边是一个辅助元素，用于显示任何验证错误。

最后，我们有一个提交表单的按钮。通常，如果用户输入的姓名或年龄违反 @Valid 约束，是会跳回到该页面并显示错误消息。如果输入了有效的姓名和年龄，则该用户将被转到下一个页面。

以下示例（来自 src/main/resources/templates/results.html）显示了结果页面：

<html>
	<body>
		Congratulations! You are old enough to sign up for this site.
	</body>
</html>

在这个简单的示例中，这些网页没有任何复杂的 CSS 或 JavaScript。

运行应用

对于该应用，我们正在使用 Thymeleaf 的模版语言。该应用需要的不仅仅是原始 HTML。Spring Initializr 为我们创建了一个应用类。以下清单（来自 src/main/java/com/example/validatingforminput/ValidatingFormInputApplication.java）显示了该类：

package com.example.validatingforminput;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class ValidatingFormInputApplication {

	public static void main(String[] args) throws Exception {
		SpringApplication.run(ValidatingFormInputApplication.class, args);
	}

}

要激活 Spring MVC，通常需要将 @EnableWebMvc 添加到 Application 类。但当 Spring Boot 的 @SpringBootApplication 在我们的类路径中监测到 spring-webmvc 时，其已经添加了该注释。通过相同的注释，它可以找到带注释的 @Controller 类及其方法。

Thymeleaf 的配置也由 @SpringBootApplication 处理。默认情况下，模版位于类路径中的 template/ 下并通过从文件名中删除 ‘.html’ 后缀来将其解析为视图。（可以根据需要实现的方式以多种方式更改和覆盖 Thymeleaf 设置，但详细信息与该指南无关。）

构建可执行 JAR

我们可以结合 Gradle 或 Maven 来从命令行运行该应用。我们还可以构建一个包含所有必须依赖项、类以及资源的可执行 JAR 文件，然后运行该文件。在整个开发生命周期中，跨环境等等情况下，构建可执行 JAR 可以轻松地将服务作为应用进行发布、版本化以及部署。

如果使用 Gradle，则可以借助 ./gradlew bootRun 来运行应用。或通过借助 ./gradlew build 来构建 JAR 文件，然后运行 JAR 文件，如下所示：

java -jar build/libs/gs-validating-form-input-0.1.0.jar

由官网提供的以上这条命令的执行结果与我本地的不一样，我需要这样才能运行：java -jar build/libs/validating-form-input-0.0.1-SNAPSHOT.jar。

如果使用 Maven，则可以借助 ./mvnw spring-boot:run 来运行该用。或可以借助 ./mvnw clean package 来构建 JAR 文件，然后运行 JAR 文件，如下所示：

java -jar target/gs-validating-form-input-0.1.0.jar

由官网提供的以上这条命令的执行结果与我本地的不一样，我需要这样才能运行：java -jar target/validating-form-input-0.0.1-SNAPSHOT.jar。

我们还可以构建一个经典的 WAR 文件。

如果我们访问 http://localhost:8080/，应该看到如下图所示的内容：

以下图像显示了如果我们输入姓名 N 以及输入年龄 15 并单击 Submit 后会发生什么：


上图显示，由于值违反了 PersonForm 类中的约束，因此我们会跳回到 “主” 页面。请注意，如果在输入框中什么都没有填并单击提交的话，将会收到另一个错误消息，如下图所示：

如果输入有效的姓名和年龄，我们将进入结果页面，如下图所示：

 

概述

恭喜你！我们已经编写了一个简单的 Web 应用，并在领域对象内置了验证功能。这样，我们可以确保数据符合特定条件，并且用户可以正确输入数据。
 

参见

以下指南也可能会有所帮助：

• 使用 Spring MVC 服务 Web 内容（尽请期待～）
• 处理表单提交（尽请期待～）
• 保护 Web 应用（尽请期待～）
• 使用 Spring Boot 2 构建应用（尽请期待～）

想看指南的其他内容？请访问该指南的所属专栏：《Spring 官方指南》