1. Introduction

1.绪论

In most typical web applications, we often need to restrict a request parameter to a set of predefined values. Enums are a great way to do this.

在大多数典型的网络应用中，我们经常需要将一个请求参数限制在一组预定义的值中。枚举是一种很好的方法。

In this quick tutorial, we’ll demonstrate how to use enums as web request parameters in Spring MVC.

在这个快速教程中，我们将演示如何在Spring MVC中使用枚举作为Web请求参数。

2. Use Enums as Request Parameters

2.使用枚举作为请求参数

Let’s first define an enum for our examples:

让我们首先为我们的例子定义一个枚举。

public enum Modes {
    ALPHA, BETA;
}

We can then use this enum as a RequestParameter in a Spring controller:

然后我们可以在Spring控制器中使用这个枚举作为RequestParameter。

@GetMapping("/mode2str")
public String getStringToMode(@RequestParam("mode") Modes mode) {
    // ...
}

Or we can use it as a PathVariable:

或者我们可以把它作为一个PathVariable。

@GetMapping("/findbymode/{mode}")
public String findByEnum(@PathVariable("mode") Modes mode) {
    // ...
}

When we make a web request, such as /mode2str?mode=ALPHA, the request parameter is a String object. Spring can try to convert this String object to an Enum object by using its StringToEnumConverterFactory class.

当我们发出一个Web请求，例如/mode2str?mode=ALPHA，请求参数是一个String对象。Spring可以通过使用其StringToEnumConverterFactory类，尝试将这个String对象转换为Enum对象。

The back-end conversion uses the Enum.valueOf method. Therefore, the input name string must exactly match one of the declared enum values.

后端转换使用Enum.valueOf method。因此，输入的名称字符串必须与声明的枚举值之一完全匹配。

When we make a web request with a string value that doesn’t match one of our enum values, like /mode2str?mode=unknown, Spring will fail to convert it to the specified enum type. In this case, we’ll get a ConversionFailedException.

当我们用一个与我们的枚举值不匹配的字符串请求时，比如/mode2str?mode=unknown，Spring将无法将其转换为指定的枚举类型。在这种情况下，我们会得到一个ConversionFailedException.。

3. Custom Converter

3.自定义转换器

In Java, it’s considered good practice to define enum values with uppercase letters, as they are constants. However, we may want to support lowercase letters in the request URL.

在Java中，用大写字母定义枚举值被认为是好的做法，因为它们是常量。然而，我们可能希望在请求URL中支持小写字母。

In this case, we need to create a custom converter:

在这种情况下，我们需要创建一个自定义转换器。

public class StringToEnumConverter implements Converter<String, Modes> {
    @Override
    public Modes convert(String source) {
        return Modes.valueOf(source.toUpperCase());
    }
}

To use our custom converter, we need to register it in the Spring configuration:

为了使用我们的自定义转换器，我们需要在Spring配置中注册它。

@Configuration
public class WebConfig implements WebMvcConfigurer {
    @Override
    public void addFormatters(FormatterRegistry registry) {
        registry.addConverter(new StringToEnumConverter());
    }
}

4. Exception Handling

4.异常处理

The Enum.valueOf method in the StringToEnumConverter will throw an IllegalArgumentException if our Modes enum doesn’t have a matched constant. We can handle this exception in our custom converter in different ways, depending on our requirements.

如果我们的Modes枚举没有匹配的常量，StringToEnumConverter中的Enum.valueOf方法将抛出IllegalArgumentException。我们可以在我们的自定义转换器中以不同的方式处理这个异常，这取决于我们的要求。

For example, we can simply have our converter return null for non-matching Strings:

例如，我们可以简单地让我们的转换器对不匹配的Strings返回null。

public class StringToEnumConverter implements Converter<String, Modes> {
    @Override
    public Modes convert(String source) {
        try {
            return Modes.valueOf(source.toUpperCase());
        } catch (IllegalArgumentException e) {
            return null;
        }
    }
}

However, if we don’t handle the exception locally in the custom converter, Spring will throw a ConversionFailedException exception to the calling controller method. There are several ways to handle this exception.

然而，如果我们不在本地处理自定义转换器中的异常，Spring将向调用控制器方法抛出一个ConversionFailedException异常。有几种方法来处理这个异常。

For example, we can use a global exception handler class:

例如，我们可以使用一个全局异常处理类。

@ControllerAdvice
public class GlobalControllerExceptionHandler {
    @ExceptionHandler(ConversionFailedException.class)
    public ResponseEntity<String> handleConflict(RuntimeException ex) {
        return new ResponseEntity<>(ex.getMessage(), HttpStatus.BAD_REQUEST);
    }
}

5. Conclusion

5.总结

In this brief article, we learned how to use enums as request parameters in Spring with some code examples.

在这篇简短的文章中，我们通过一些代码实例学习了如何在Spring中使用枚举作为请求参数。

We also provided a custom converter example that can map the input string to an enum constant.

我们还提供了一个自定义转换器的例子，可以将输入的字符串映射到一个枚举常量。

Finally, we discussed how to handle the exception thrown by Spring when it encounters an unknown input string.

最后，我们讨论了如何处理Spring遇到未知输入字符串时抛出的异常。

As always, the source code for this article is available over on GitHub.

一如既往，本文的源代码可在GitHub上获得over。