5.2创建自己的配置属性

5.2创建自己的配置属性

正如前面提到的，配置属性只不过是指定来接受Spring环境抽象配置的bean的属性。没有提到的是如何指定这些bean来使用这些配置。

为了支持配置属性的属性注入，Spring Boot提供了@ConfigurationProperties注释。当放置在任何Spring bean上时，它指定可以从Spring环境中的属性注入到该bean的属性。

为了演示@ConfigurationProperties是如何工作的，假设已经将以下方法添加到OrderController中，以列出经过身份验证的用户之前的订单：

@GetMapping
public String ordersForUser(
    @AuthenticationPrincipal User user, Model model) {
    model.addAttribute("orders",
        orderRepo.findByUserOrderByPlaceAtDesc(user));

    return "orderList";
}

除此之外，还需要向OrderRepository添加了必要的findByUser()方法：

List<Order> findByUserOrderByPlaceAtDesc(User user);

请注意，此存储库方法是用OrderByPlacedAtDesc子句命名的。OrderBy部分指定一个属性，通过该属性对结果排序 —— 在本例中是placedAt属性。最后的Desc让排序按降序进行。因此，返回的订单列表将按时间倒序排序。

如前所述，在用户下了一些订单之后，这个控制器方法可能会很有用。但对于最狂热的taco鉴赏家来说，它可能会变得有点笨拙。在浏览器中显示的一些命令是有用的；一长串没完没了的订单只是噪音。假设希望将显示的订单数量限制为最近的20个订单，可以更改ordersForUser()：

@GetMapping
public String ordersForUser(
    @AuthenticationPrincipal User user, Model model) {
    Pageable pageable = PageRequest.of(0, 20);
    model.addAttribute("orders",
        orderRepo.findByUserOrderByPlaceAtDesc(user));

    return "orderList";
}

随着这个改变，OrderRepository跟着需要变为：

List<Order> findByUserOrderByPlaceAtDesc(User user, Pageable pageable);

这里，已经更改了findByUserOrderByPlacedAtDesc()方法的签名，以接受可分页的参数。可分页是Spring Data通过页码和页面大小选择结果子集的方式。在ordersForUser()控制器方法中，构建了一个PageRequest对象，该对象实现了Pageable来请求第一个页面（page zero），页面大小为20，以便为用户获得最多20个最近下的订单。

虽然这工作得非常好，但它让我感到有点不安，因为已经硬编码了页面大小。如果后来发现20个订单太多，而决定将其更改为10个订单，该怎么办？因为它是硬编码的，所以必须重新构建和重新部署应用程序。

可以使用自定义配置属性来设置页面大小，而不是硬编码页面大小。首先，需要向OrderController添加一个名为pageSize的新属性，然后在OrderController上使用@ConfigurationProperties注解 ，如下面的程序清单所示。程序清单5.1在OrderController中使用配置属性

@Controller
@RequestMapping("/orders")
@SessionAttributes("order")
@ConfigurationProperties(prefix="taco.orders")
public class OrderController {

    private int pageSize = 20;

    public void setPageSize(int pageSize) {
        this.pageSize = pageSize;
    }

    ...

    @GetMapping
    public String ordersForUser(
        @AuthenticationPrincipal User user, Model model) {
        Pageable pageable = PageRequest.of(0, pageSize);
        model.addAttribute("orders",
            orderRepo.findByUserOrderByPlacedAtDesc(user, pageable));
        return "orderList";
    }
}

程序清单5.1中最重要的变化是增加了@ConfigurationProperties注解。其prefix属性设置为taco。这意味着在设置pageSize属性时，需要使用一个名为taco.orders.pageSize的配置属性。

新的pageSize属性默认为20。但是可以通过设置taco.orders.pageSize属性轻松地将其更改为想要的任何值。例如，可以在application.yml中设置此属性：

taco:
  orders:
    pageSize: 10

或者，如果需要在生产环境中进行快速更改，可以通过设置taco.orders.pageSize属性作为环境变量来重新构建和重新部署应用程序：

$ export TACO_ORDERS_PAGESIZE=10

可以设置配置属性的任何方法，都可以用来调整最近订单页面的大小。接下来，我们将研究如何在属性持有者中设置配置数据。

5.2.1定义配置属性持有者

这里没有说@ConfigurationProperties必须设置在控制器或任何其他特定类型的bean上，@ConfigurationProperties实际上经常放在bean上。在应用程序中，这些bean的惟一目的是作为配置数据的持有者，这使控制器和其他应用程序类不涉及特定于配置的细节，它还使得在几个可能使用该信息的bean之间共享公共配置属性变得很容易。

对于OrderController中的pageSize属性，可以将其提取到一个单独的类中。下面的程序清单以这种方式使用了OrderProps类。程序清单5.2提取pageSize到持有者类

package tacos.web;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;
import lombok.Data;

@Component
@ConfigurationProperties(prefix="taco.orders")
@Data
public class OrderProps {
    private int pageSize = 20;
}

正如在OrderController中所做的，pageSize属性默认为20，同时OrderProps使用@ConfigurationProperties进行注解，以具有taco.orders前缀。

它还带有@Component注解，因此Spring组件扫描时将自动发现它并在Spring应用程序上下文中将其创建为bean。这很重要，因为下一步是将OrderProps bean注入到OrderController中。

关于配置属性持有者，没有什么特别的。它们是从Spring环境中注入属性的bean。它们可以被注入到任何需要这些属性的其他bean中。对于OrderController，这意味着从OrderController中删除pageSize属性，而不是注入并使用OrderProps bean：

@Controller
@RequestMapping("/orders")
@SessionAttributes("order")
public class OrderController {

    private OrderRepository orderRepo;

    private OrderProps props;

    public OrderController(OrderRepository orderRepo,
             OrderProps props) {
        this.orderRepo = orderRepo;
        this.props = props;
    }

    ...

    @GetMapping
    public String ordersForUser(
        @AuthenticationPrincipal User user, Model model) {
        Pageable pageable = PageRequest.of(0, props.getPageSize());
        model.addAttribute("orders",
            orderRepo.findByUserOrderByPlacedAtDesc(user, pageable));
        return "orderList";
    }

    ...
}

现在OrderController不再负责处理它自己的配置属性。这使得OrderController中的代码稍微整洁一些，并允许在任何其他需要它们的bean中重用OrderProps中的属性。此外，正在收集与一个地方的订单相关的配置属性：OrderProps类。如果需要添加、删除、重命名或以其他方式更改其中的属性，只需要在OrderProps中应用这些更改。

例如，假设在其他几个bean中使用pageSize属性，这时最好对该属性应用一些验证，以将其值限制为不小于5和不大于25。如果没有持有者bean，将不得不对OrderController、pageSize属性以及使用该属性的所有其他类应用验证注解。但是因为已经将pageSize提取到OrderProps中，所以只需要更改OrderProps：

package tacos.web;

import javax.validation.constraints.Max;
import javax.validation.constraints.Min;
import org.springframework.boot.context.properties.
ConfigurationProperties;
import org.springframework.stereotype.Component;
import org.springframework.validation.annotation.Validated;
import lombok.Data;

@Component
@ConfigurationProperties(prefix="taco.orders")
@Data
@Validated
public class OrderProps {
    @Min(value=5, message="must be between 5 and 25")
    @Max(value=25, message="must be between 5 and 25")
    private int pageSize = 20;
}
//end::validated[]

尽管可以很容易地将@Validated、@Min和@Max注解应用到OrderController（以及可以注入OrderProps的任何其他bean），但这只会使OrderController更加混乱。通过使用配置属性持有者bean，就在在一个地方收集了配置属性的细节，使得需要这些属性的类相对干净。

5.2.2声明配置属性元数据

根据IDE的情况，你可能已经注意到application.yml（或是appication.properties）中的taco.orders.pageSize属性有一个警告，说类似未知属性 ’taco’ 之类的东西。出现此警告是因为缺少关于刚刚创建的配置属性的元数据。图5.2显示了我将鼠标悬停在Spring Tool Suite中taco属性时的效果。


图5.2缺少配置属性元数据出现的警告

配置属性元数据是完全可选的，并不会阻止配置属性的工作。但是元数据对于提供有关配置属性的最小文档非常有用，特别是在IDE中。

例如，当我将鼠标悬停在security.user.password属性上时，如图5.3所示，虽然悬停帮助你获得的是最小的，但它足以帮助你了解属性的用途以及如何使用它。


图5.3在Spring Tool Suite中悬停显示配置属性文档

为了帮助那些可能使用你定义的配置属性（甚至可能是你自己定义的）的人，通常最好是围绕这些属性创建一些元数据，至少它消除了IDE中那些恼人的黄色警告。

要为自定义配置属性创建元数据，需要在META-INF（例如，在项目下的src/main/resources/META-INF中）中创建一个名为addition-spring-configuration-metadata.json的文件。

快速修复缺失的元数据。

如果正在使用Spring Tool Suite，则有一个用于创建丢失的属性元数据的快速修复选项。将光标放在缺少元数据警告的行上，然后按下Mac上的CMD-1或Windows和Linux上的Ctrl-1弹出的快速修复（参见图5.4）。


图5.4在Spring Tool Suite中使用快速弹出方式创建配置属性元数据

然后选择 Create Metadata for… 选项来为属性添加一些元数据（在additional-spring-configuration-metadata中)。如果该文件不存在，则创建该文件。

对于taco.orders.pageSize属性，可以用以下JSON设置元数据：

{
  "properties": [
    {
      "name": "taco.orders.page-size",
      "type": "java.lang.String",
      "description": "Sets the maximum number of orders to display in a list."
    }
  ]
}

注意，元数据中引用的属性名是taco.orders.pagesize。Spring Boot灵活的属性命名允许属性名的变化，比如taco.orders.page-size相当于taco.orders.pageSize。

有了这些元数据，警告就应该消失了。更重要的是，如果你悬停在taco.orders.pageSize属性，你将看到如图5.5所示的描述。


图5.5悬停显示自定义配置属性帮助

另外，如图5.6所示，可以从IDE获得自动完成帮助，就像Springprovided的配置属性一样。


图5.6配置属性元数据让属性值自动填充

配置属性对于调整自动配置的组件和注入到应用程序bean中的细节非常有用。但是，如果需要为不同的部署环境配置不同的属性呢？让我们看看如何使用Spring配置文件来设置特定于环境的配置。