Vault 仓库
使用 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, 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(Pattern pattern) |
(无关键字) | findById(String name) |
Not | findByIdNot(String id) |
And | findByLastnameAndFirstname |
Or | findByLastnameOrFirstname |
Is,Equals | findByFirstname,findByFirstnameIs,findByFirstnameEquals |
Top,First | findFirst10ByFirstname,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));