|
此版本仍在开发中，尚不被认为是稳定的。对于最新的稳定版本，请使用 Spring Vault 3.2.0！ |
Vault 存储库
使用VaultTemplate映射到 Java 类的响应允许读取、写入和删除等基本数据作。
Vault 存储库在 Vault 之上应用了 Spring Data 的存储库概念。
Vault 存储库公开了基本的 CRUD 功能，并支持使用约束标识符属性、分页和排序的谓词进行查询派生。
保管库存储库使用键/值机密引擎功能来保存和查询数据。
从版本 2.4 开始，Spring Vault 还可以使用键/值版本 2 密钥引擎，实际的密钥引擎版本是在运行时发现的。
版本控制的键/值密钥引擎中的删除使用DELETE操作。机密不会通过CrudRepository.delete(…). |
Vault 存储库确定通过 Vault 的sys/internal/ui/mounts/…端点。确保策略允许访问该路径，否则将无法使用存储库抽象。 |
| 在 Spring Data Commons 参考文档中阅读有关 Spring Data Repositories 的更多信息。 参考文档将向您介绍 Spring Data 存储库。 |
用法
要访问存储在 Vault 中的域实体，您可以利用存储库支持来显着简化这些实体的实现。
@Secret
class Credentials {
@Id String id;
String password;
String socialSecurityNumber;
Address address;
}我们这里有一个非常简单的域对象。
请注意，它有一个名为id注释为org.springframework.data.annotation.Id和@Secret注释。
这两个负责创建用于在 Vault 中将对象作为 JSON 持久化的实际密钥。
用@Id以及那些被命名的id被视为标识符属性。
那些有注释的人比其他人更受青睐。 |
下一步是声明使用域对象的存储库接口。
Credentials实体interface CredentialsRepository extends CrudRepository<Credentials, String> {
}随着我们的存储库的扩展CrudRepository它提供了基本的 CRUD 和查询方法。
Vault 存储库需要 Spring Data 组件。
确保包括spring-data-commons和spring-data-keyvalue项目。
实现此目的的最简单方法是设置依赖项管理并将工件添加到pom.xml:
然后将以下内容添加到pom.xmldependencies 部分。
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.data</groupId>
<artifactId>spring-data-bom</artifactId>
<version>2025.1.0-M4</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>4.0.0-M2</version>
</dependency>
<dependency>
<groupId>org.springframework.data</groupId>
<artifactId>spring-data-keyvalue</artifactId>
<!-- Version inherited from the BOM -->
</dependency>
</dependencies>我们将东西粘合在一起需要的是相应的 Spring 配置。
@Configuration
@EnableVaultRepositories
class ApplicationConfig {
@Bean
VaultTemplate vaultTemplate() {
return new VaultTemplate(…);
}
}鉴于上述设置，我们可以继续注入CredentialsRepository进入我们的组件。
@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 Hash 中，带有密钥模式keyspace/id，在本例中credentials/heisenberg，在键值机密机密引擎中。 |
| 2 | 使用提供的 id 检索存储在keyspace/id. |
| 3 | 计算由@Secret上Credentials. |
| 4 | 从 Vault 中删除给定对象的键。 |
对象到保管库的 JSON 映射
Vault 存储库使用 JSON 作为交换格式将对象存储在 Vault 中。
JSON 和实体之间的对象映射由VaultConverter.
转换器读写SecretDocument包含来自VaultResponse.VaultResponses 从 Vault 中读取，并且 Jackson 将正文反序列化为Map之String和Object.
默认值VaultConverter实现读取Map嵌套值，List和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. |
| 类型 | 样本 | 映射值 |
|---|---|---|
简单类型 |
字符串 firstname = “Walter”; |
“firstname”： “沃尔特” |
复杂类型 |
地址地址 = 新地址（“308 Negra Arroyo Lane”）; |
“地址”： { “street”： “内格拉阿罗约巷 308 号” } |
简单类型列表 |
List<String>昵称 = asList（“walt”， “heisenberg”）; |
“昵称”： [“沃尔特”、“海森堡”] |
简单类型的地图 |
Map<String， Integer> atts = asMap（“age”， 51） |
“atts” ： {“年龄” ： 51} |
复杂类型列表 |
List<Address> 地址 = asList（new Address（“308... |
“地址”： [{ “street”： “308 Negra Arroyo Lane” }， ...] |
您可以通过注册Converter在VaultCustomConversions.
这些转换器可以负责从/转换为类型，例如LocalDate以及SecretDocument而第一个适用于将简单属性转换为简单属性，最后一个则适合将复杂类型转换为其 JSON 表示形式。
第二个选项提供对结果的完全控制SecretDocument.
将对象写入Vault将删除内容并重新创建整个条目，因此未映射的数据将丢失。
查询和查询方法
查询方法允许从方法名称自动派生简单查询。 Vault 没有查询引擎，但需要直接访问 HTTP 上下文路径。 Vault 查询方法将 Vault 的 API 可能性转换为查询。 查询方法执行在上下文路径下列出子项，对 Id 应用筛选，（可选）使用偏移量/限制限制 Id 流，并在提取结果后应用排序。
interface CredentialsRepository extends CrudRepository<Credentials, String> {
List<Credentials> findByIdStartsWith(String prefix);
}Vault 存储库的查询方法仅支持对@Id财产。 |
以下是 Vault 支持的关键字的概述。
| 关键词 | 样本 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
排序和分页
查询方法通过在内存中选择从 Vault 上下文路径检索的子列表（偏移量/限制）ID 来支持排序和分页。 与查询方法谓词不同，排序不限于特定字段。 在 ID 过滤后应用未分页排序，并从 Vault 获取所有生成的密钥。 这样，查询方法仅获取也作为结果的一部分返回的结果。
使用分页和排序需要在筛选 ID 之前进行机密提取，这会影响性能。 排序和分页保证返回相同的结果，即使 Vault 返回的 Id 的自然顺序发生变化也是如此。 因此，首先从 Vault 获取所有 ID，然后应用排序，然后进行过滤和偏移/限制。
interface CredentialsRepository extends PagingAndSortingRepository<Credentials, String> {
List<Credentials> findTop10ByIdStartsWithOrderBySocialSecurityNumberDesc(String prefix);
List<Credentials> findByIdStarts(String prefix, Pageable pageRequest);
}乐观锁定
保管库密钥/值机密引擎版本 2 可以维护版本控制的机密。
Spring Vault 支持通过域模型中的版本属性进行版本控制，这些属性带有@Version.
使用乐观锁定可确保更新仅应用于具有匹配版本的机密。
因此，version 属性的实际值通过cas财产。
如果另一个作在此期间更改了机密，则会引发 OptimisticLockingFailureException，并且不会更新机密。
版本属性必须是数字属性，例如int或long并映射到cas属性。
@Secret
class VersionedCredentials {
@Id String id;
@Version int version;
String password;
String socialSecurityNumber;
Address address;
}以下示例显示了这些功能：
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 机密引擎维护可通过实现RevisionRepository在 Vault 存储库界面声明中。
修订存储库定义查找方法以获取特定标识符的修订。
标识符必须是String.
RevisionRepositoryinterface RevisionCredentialsRepository extends CrudRepository<Credentials, String>,
RevisionRepository<Credentials, String, Integer> (1)
{
}| 1 | 第一个类型参数 （Credentials） 表示实体类型，第二个 （String） 表示 id 属性的类型，最后一个 （Integer） 是修订号的类型。Vault 仅支持Stringidentifiers 和Integer修订号。 |
用法
您现在可以使用RevisionRepository查询实体的修订，如以下示例所示：
RevisionRepositoryRevisionCredentialsRepository repo = …;
Revisions<Integer, Credentials> revisions = repo.findRevisions("my-secret-id");
Page<Revision<Integer, Credentials>> firstPageOfRevisions = repo.findRevisions("my-secret-id", Pageable.ofSize(4));