Vault 存储库

使用 VaultTemplate 和映射到 Java 类的响应允许执行基本的数据库操作，例如读取、写入和删除。Vault 存储库在 Vault 之上应用了 Spring Data 的存储库概念。Vault 存储库公开了基本的 CRUD 功能，并支持使用谓词约束标识符属性、分页和排序的查询派生。Vault 存储库使用键值密钥引擎功能来持久化和查询数据。从 2.4 版开始，Spring Vault 还可以使用键值版本 2 密钥引擎，实际的密钥引擎版本在运行时发现。

版本化的键值密钥引擎中的删除操作使用 DELETE 操作。密钥不会通过 CrudRepository.delete(…) 销毁。

在 Spring Data Commons 参考文档中阅读有关 Spring Data 存储库的更多信息。参考文档将为您介绍 Spring Data 存储库。

用法

要访问存储在 Vault 中的域实体，您可以利用存储库支持，这可以大大简化实现。

示例 1. 示例凭据实体

@Secret
class Credentials {

  @Id String id;
  String password;
  String socialSecurityNumber;
  Address address;
}

这里有一个非常简单的域对象。请注意，它具有一个名为 id 的属性，该属性使用 org.springframework.data.annotation.Id 进行注释，并且其类型上有一个 @Secret 注释。这两个注释负责创建用于将对象作为 JSON 持久化到 Vault 中的实际密钥。

使用 @Id 注释的属性以及名为 id 的属性都被视为标识符属性。使用注释的属性优先于其他属性。

下一步是声明一个使用域对象的存储库接口。

示例 2. Credentials 实体的基本存储库接口

interface CredentialsRepository extends CrudRepository<Credentials, String> {

}

由于我们的存储库扩展了 CrudRepository，因此它提供了基本的 CRUD 和查询方法。Vault 存储库需要 Spring Data 组件。确保在类路径中包含 spring-data-commons 和 spring-data-keyvalue 工件。

实现此目的最简单的方法是设置依赖项管理并将工件添加到您的 pom.xml 中。

然后将以下内容添加到 pom.xml 依赖项部分。

示例 3. 使用 Spring Data BOM

<dependencyManagement>
  <dependencies>
    <dependency>
      <groupId>org.springframework.data</groupId>
      <artifactId>spring-data-bom</artifactId>
      <version>2023.1.9</version>
      <scope>import</scope>
      <type>pom</type>
    </dependency>
  </dependencies>
</dependencyManagement>

<dependencies>

  <!-- other dependency elements omitted -->

  <dependency>
    <groupId>org.springframework.vault</groupId>
    <artifactId>spring-vault-core</artifactId>
    <version>3.1.2</version>
  </dependency>

  <dependency>
    <groupId>org.springframework.data</groupId>
    <artifactId>spring-data-keyvalue</artifactId>
    <!-- Version inherited from the BOM -->
  </dependency>

</dependencies>

我们需要在中间将所有内容粘合在一起的是相应的 Spring 配置。

示例 4. Vault 存储库的 JavaConfig

@Configuration
@EnableVaultRepositories
class ApplicationConfig {

  @Bean
  VaultTemplate vaultTemplate() {
    return new VaultTemplate(…);
  }
}

在完成上述设置后，我们可以继续将 CredentialsRepository 注入到我们的组件中。

示例 5. 访问 Person 实体

@Autowired CredentialsRepository repo;

void basicCrudOperations() {

  Credentials creds = new Credentials("heisenberg", "327215", "AAA-GG-SSSS");
  rand.setAddress(new Address("308 Negra Arroyo Lane", "Albuquerque", "New Mexico", "87104"));

  repo.save(creds);                                        (1)

  repo.findOne(creds.getId());                             (2)

  repo.count();                                            (3)

  repo.delete(creds);                                      (4)
}

1	将 `Credentials` 的属性存储在 Vault 哈希中，密钥模式为 `keyspace/id`，在本例中为 `credentials/heisenberg`，位于键值密钥引擎中。
2	使用提供的 id 检索存储在 `keyspace/id` 处的对象。
3	计算 `Credentials` 上 `@Secret` 定义的键空间 credentials 中可用的实体总数。
4	从 Vault 中删除给定对象的密钥。

对象到 Vault JSON 映射

Vault 存储库使用 JSON 作为交换格式将对象存储在 Vault 中。JSON 和实体之间的对象映射由 VaultConverter 完成。转换器读取和写入包含 VaultResponse 中主体内容的 SecretDocument。VaultResponse 从 Vault 中读取，主体由 Jackson 反序列化为 String 和 Object 的 Map。默认的 VaultConverter 实现读取具有嵌套值、List 和 Map 对象的 Map，并将这些值转换为实体，反之亦然。

给定上一节中的 Credentials 类型，默认映射如下

{
  "_class": "org.example.Credentials",                 (1)
  "password": "327215",                                (2)
  "socialSecurityNumber": "AAA-GG-SSSS",
  "address": {                                         (3)
    "street": "308 Negra Arroyo Lane",
    "city": "Albuquerque",
    "state": "New Mexico",
    "zip": "87104"
  }
}

1	`_class` 属性包含在根级别以及任何嵌套接口或抽象类型上。
2	简单属性值按路径映射。
3	复杂类型的属性作为嵌套对象映射。

@Id 属性必须映射到 String。

表 1. 默认映射规则
类型	示例	映射值
简单类型 (例如 String)	String firstname = "Walter";	"firstname": "Walter"
复杂类型 (例如 Address)	Address adress = new Address("308 Negra Arroyo Lane");	"address": { "street": "308 Negra Arroyo Lane" }
列表简单类型	List<String> nicknames = asList("walt", "heisenberg");	"nicknames": ["walt", "heisenberg"]
映射简单类型	Map<String, Integer> atts = asMap("age", 51)	"atts" : {"age" : 51}
列表复杂类型	List<Address> addresses = asList(new Address("308…	"address": [{ "street": "308 Negra Arroyo Lane" }, …]

您可以通过在 VaultCustomConversions 中注册 Converter 来自定义映射行为。这些转换器可以处理从/到诸如 LocalDate 和 SecretDocument 等类型的转换，其中第一个转换器适合转换简单属性，最后一个转换器将复杂类型转换为其 JSON 表示形式。第二个选项提供对生成的 SecretDocument 的完全控制。将对象写入 Vault 将删除内容并重新创建整个条目，因此未映射的数据将丢失。

查询和查询方法

查询方法允许根据方法名自动推导出简单的查询。Vault 没有查询引擎，但需要直接访问 HTTP 上下文路径。Vault 查询方法将 Vault 的 API 功能转换为查询。查询方法执行会在上下文路径下列出子节点，对 Id 应用过滤，可选地使用偏移量/限制对 Id 流进行限制，并在获取结果后应用排序。

示例 6. 示例存储库查询方法

interface CredentialsRepository extends CrudRepository<Credentials, String> {

  List<Credentials> findByIdStartsWith(String prefix);
}

Vault 存储库的查询方法仅支持对@Id属性进行谓词的查询。

以下是 Vault 支持的关键字概述。

表 2. 查询方法支持的关键字
关键字	示例
`After`, `GreaterThan`	`findByIdGreaterThan(String id)`
`GreaterThanEqual`	`findByIdGreaterThanEqual(String id)`
`Before`, `LessThan`	`findByIdLessThan(String id)`
`LessThanEqual`	`findByIdLessThanEqual(String id)`
`Between`	`findByIdBetween(String from, String to)`
`In`	`findByIdIn(Collection ids)`
`NotIn`	`findByIdNotIn(Collection ids)`
`Like`, `StartingWith`, `EndingWith`	`findByIdLike(String id)`
`NotLike`, `IsNotLike`	`findByIdNotLike(String id)`
`Containing`	`findByFirstnameContaining(String id)`
`NotContaining`	`findByFirstnameNotContaining(String name)`
`Regex`	`findByIdRegex(String id)`
`(无关键字)`	`findById(String name)`
`Not`	`findByIdNot(String id)`
`And`	`findByLastnameAndFirstname`
`Or`	`findByLastnameOrFirstname`
`Is,Equals`	`findByFirstname`,`findByFirstnameIs`,`findByFirstnameEquals`
`Top,First`	`findFirst10ByFirstname`,`findTop5ByFirstname`

排序和分页

查询方法支持排序和分页，方法是在内存中选择从 Vault 上下文路径检索到的 Id 的子列表（偏移量/限制）。与查询方法谓词不同，排序不受限于特定字段。无分页排序在 Id 过滤后应用，并且从 Vault 中获取所有结果机密。这样，查询方法仅获取也作为结果一部分返回的结果。

使用分页和排序需要在过滤 Id 之前获取机密，这会影响性能。即使 Vault 返回的 Id 的自然顺序发生变化，排序和分页也能保证返回相同的结果。因此，首先从 Vault 中获取所有 Id，然后应用排序，之后进行过滤和偏移量/限制。

示例 7. 分页和排序存储库

interface CredentialsRepository extends PagingAndSortingRepository<Credentials, String> {

  List<Credentials> findTop10ByIdStartsWithOrderBySocialSecurityNumberDesc(String prefix);

  List<Credentials> findByIdStarts(String prefix, Pageable pageRequest);
}

乐观锁

Vault 键/值机密引擎版本 2 可以维护版本化的机密。Spring Vault 通过域模型中的版本属性支持版本控制，这些属性使用@Version进行注释。使用乐观锁可确保仅将更新应用于版本匹配的机密。因此，版本属性的实际值将通过cas属性添加到更新请求中。如果在此期间另一个操作更改了机密，则会抛出 OptimisticLockingFailureException，并且机密不会更新。

版本属性必须是数字属性，例如int或long，并在更新机密时映射到cas属性。

示例 8. 示例版本化实体

@Secret
class VersionedCredentials {

  @Id String id;
  @Version int version;
  String password;
  String socialSecurityNumber;
  Address address;
}

以下示例展示了这些功能

示例 9. 示例版本化实体

VersionedCredentialsRepository repo = …;

VersionedCredentials credentials = repo.findById("sample-credentials").get();    (1)

VersionedCredentials concurrent = repo.findById("sample-credentials").get();     (2)

credentials.setPassword("something-else");

repos.save(credentials);                                                         (3)


concurrent.setPassword("concurrent change");

repos.save(concurrent); // throws OptimisticLockingFailureException              (4)

1	根据其 Id `sample-credentials`获取机密。
2	根据其 Id `sample-credentials`获取机密的第二个实例。
3	更新机密并让 Vault 增加版本。
4	更新使用先前版本的第二个实例。该操作失败并出现`OptimisticLockingFailureException`，因为在此期间 Vault 中的版本已增加。

删除版本化机密时，按 Id 删除会删除最新的机密。按实体删除会删除提供的版本处的机密。

访问版本化机密

键/值版本 2 机密引擎维护机密的版本，可以通过在 Vault 存储库接口声明中实现RevisionRepository来访问这些版本。修订存储库定义查找方法以获取特定标识符的修订版本。标识符必须为String。

示例 10. 实现RevisionRepository

interface RevisionCredentialsRepository extends CrudRepository<Credentials, String>,
                                        RevisionRepository<Credentials, String, Integer> (1)
{

}

1	第一个类型参数（`Credentials`）表示实体类型，第二个（`String`）表示 id 属性的类型，最后一个（`Integer`）是修订版本号的类型。Vault 仅支持`String`标识符和`Integer`修订版本号。

用法

您现在可以使用RevisionRepository中的方法查询实体的修订版本，如下例所示

示例 11. 使用RevisionRepository

RevisionCredentialsRepository repo = …;

Revisions<Integer, Credentials> revisions = repo.findRevisions("my-secret-id");

Page<Revision<Integer, Credentials>> firstPageOfRevisions = repo.findRevisions("my-secret-id", Pageable.ofSize(4));