跳到主要内容
版本:4.1.0

Vault 仓库

Doubao 中英对照 Vault Repositories

使用 VaultTemplate 并将响应映射到 Java 类,可以实现读取、写入和删除等基本数据操作。Vault 仓库在 Vault 之上应用 Spring Data 的仓库概念。Vault 仓库暴露基本的 CRUD 功能,并支持使用约束标识符属性的谓词进行查询派生、分页和排序。Vault 仓库使用键/值机密引擎功能来持久化和查询数据。自版本 2.4 起,Spring Vault 还可以使用键/值版本 2 机密引擎,实际的机密引擎版本在运行时发现。

备注

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

备注

Vault 仓库通过 Vault 的 sys/internal/ui/mounts/… 端点确定挂载路径。请确保你的策略允许访问该路径,否则你将无法使用仓库抽象。

备注

在 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 组件。请确保在你的 classpath 中包含 spring-data-commons 和 spring-data-keyvalue 构件。

实现这一目标的最简单方式是设置依赖管理并将构件添加到你的 pom.xml:

然后将以下内容添加到 pom.xml 的 dependencies 部分。

示例 3:使用 Spring Data BOM

<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.springframework.data</groupId>
<artifactId>spring-data-bom</artifactId>
<version>2026.0.0</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.1.0</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
}
  • 将 Credentials 的属性存储在 Vault Hash 中,键模式为 keyspace/id,此例中为 credentials/heisenberg,位于键-值机密引擎中。

  • 使用提供的 id 检索存储在 keyspace/id 的对象。

  • 计算由 Credentials 上的 @Secret 定义的 keyspace credentials 内可用的实体总数。

  • 从 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"
}
}
  • _class 属性包含在根级别以及任何嵌套的接口或抽象类型上。

  • 简单的属性值按路径映射。

  • 复杂类型的属性映射为嵌套对象。

备注

@Id 属性必须映射为 String。

表 1. 默认映射规则

类型示例映射值
简单类型
(例如 String)
String firstname = "Walter";"firstname": "Walter"
复杂类型
(例如 Address)
Address address = new Address("308 Negra Arroyo Lane");"address": { "street": "308 Negra Arroyo Lane" }
简单类型列表
(例如 List<String>)
List<String> nicknames = asList("walt", "heisenberg");"nicknames": ["walt", "heisenberg"]
简单类型映射
(例如 Map<String, Integer>)
Map<String, Integer> atts = asMap("age", 51)"atts" : {"age" : 51}
复杂类型列表
(例如 List<Address>)
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 应用过滤,可选地使用 offset/limit 限制 Id 流,并在获取结果后应用排序。

示例 6:示例仓库查询方法

interface CredentialsRepository extends CrudRepository<Credentials, String> {

List<Credentials> findByIdStartsWith(String prefix);
}
备注

Vault 仓库的查询方法只支持对 @Id 属性使用谓词的查询。

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

表 2. 查询方法支持的关键字

关键字示例
After, GreaterThanfindByIdGreaterThan(String id)
GreaterThanEqualfindByIdGreaterThanEqual(String id)
Before, LessThanfindByIdLessThan(String id)
LessThanEqualfindByIdLessThanEqual(String id)
BetweenfindByIdBetween(String from, String to)
InfindByIdIn(Collection ids)
NotInfindByIdNotIn(Collection ids)
Like, StartingWith, EndingWithfindByIdLike(String id)
NotLike, IsNotLikefindByIdNotLike(String id)
ContainingfindByFirstnameContaining(String id)
NotContainingfindByFirstnameNotContaining(String name)
RegexfindByIdRegex(Pattern pattern)
(无关键字)findById(String name)
NotfindByIdNot(String id)
AndfindByLastnameAndFirstname
OrfindByLastnameOrFirstname
Is,EqualsfindByFirstname,findByFirstnameIs,findByFirstnameEquals
Top,FirstfindFirst10ByFirstname,findTop5ByFirstname

排序与分页​

查询方法支持排序和分页,方法是在内存中选择从 Vault 上下文路径检索到的 Id 的子列表(offset/limit)。与查询方法谓词不同,排序不限于特定字段。无分页的排序在 Id 过滤之后应用,所有生成结果的机密都会从 Vault 获取。这样,查询方法只会获取同样作为结果一部分返回的结果。

使用分页和排序需要在过滤 Id 之前获取机密,这会影响性能。排序和分页保证返回相同的结果,即使 Vault 返回的 Id 的自然顺序发生变化。因此,先从 Vault 获取所有 Id,然后应用排序,之后再应用过滤和 offset/limit。

示例 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>
  • 通过其 Id sample-credentials 获取一个机密。

  • 通过其 Id sample-credentials 获取该机密的第二个实例。

  • 更新机密并让 Vault 递增版本。

  • 更新使用先前版本的第二个实例。由于版本已在 Vault 中递增,该操作会以 OptimisticLockingFailureException 失败。

备注

删除有版本的机密时,按 Id 删除会删除最近的机密。按实体删除会删除所提供版本处的机密。

访问有版本的机密​

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

示例 10:实现 RevisionRepository

interface RevisionCredentialsRepository extends CrudRepository<Credentials, String>,
RevisionRepository<Credentials, String, Integer> 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));