spring - 有记录 Spring @Value 字段的好方法吗？

Question

在编写 Spring Boot 应用程序的过程中，我们的团队添加了很多 @Value 注释来帮助实现可配置。在某些时候，我们开始忘记我们到底添加了什么以及可以配置什么。我们从 QA 和 DevOps 团队那里收到了很多关于什么可以配置什么不能配置的问题。

目前我们只是通过代码库执行 grep 并应用一些粗略的正则表达式来尝试解析出有意义的部分。但这并不能捕获 100% 的情况，我们不可避免地最终会深入挖掘代码以找出可以配置哪些字段。

我知道我们可以使用 JavaDoc 在某种程度上实现我们的目标，但是文档将与其他 JavaDoc(方法、字段、类等)一起被掩埋，并且它仍然依赖于开发人员记住将 JavaDoc 添加到每个字段。

有没有人找到一种更自动化的方法来记录他们的 @Value 字段？我正在考虑类似 Swagger 的东西，但专门针对 Spring 以及它可以外部化配置的各种方式。

Answer 1

Javadoc 确实是一种为开发人员而不是 QA 或操作人员记录文档的方式。 您的问题真的很有趣，但是很难规范地回答这个问题，因为 @Value 是组件的实现细节。大摇大摆地引用文档 REST contracts，这是一个重要的区别。

这里有一些想法:

• 为他们编写 BDD 测试也可以用作文档在功能上确实没有意义，但在技术上却有意义。 事实上，您可以编写 BDD 集成测试(使用 Cucumber 或任何其他库)，在其中记录和测试每个预期属性的存在。

• 这不是一个完美的解决方案，但您至少可以使用 these Spring Boot actuators 检索公开的属性和更多信息:

configprops : Displays a collated list of all @ConfigurationProperties.

env : Exposes properties from Spring’s ConfigurableEnvironment.

• 只要有可能，请使用 @ConfigurationProperties 注入(inject)来对协同工作的属性进行分组，而不是使用 @Value。将它们隔离在 @ConfigurationProperties 类中并为它们添加 javadoc 可以很好地记录它们的存在和用法。

• 根据 caco3 的建议，您还可以生成 your own metadata by using the Annotation Processor :

You can easily generate your own configuration metadata file from items annotated with @ConfigurationProperties...

The processor picks up both classes and methods that are annotated with @ConfigurationProperties. The Javadoc for field values within configuration classes is used to populate the description attribute.

它与前一点相结合:只要有可能，就支持@ConfigurationProperties。