跳到主要内容
版本:5.1.1

配置 REST URL 路径

Doubao 中英对照 Configuring the REST URL Path

您可以配置 URL 路径的各个段,JPA 仓库的资源将在这些段之下导出。为此,请在类级别或查询方法级别添加注解。

默认情况下,导出器使用领域类的名称来暴露您的 CrudRepository。Spring Data REST 还会应用 Evo Inflector 对该词进行复数化。请考虑以下仓库定义:

interface PersonRepository extends CrudRepository<Person, Long> {}

前述示例所定义的仓库会在 [localhost:8080/persons/](http://localhost:8080/persons/) 处暴露。

要更改仓库的导出方式,请在类级别添加 @RestResource 注解,如下例所示:

@RepositoryRestResource(path = "people")
interface PersonRepository extends CrudRepository<Person, Long> {}

前述示例所定义的仓库可通过 [localhost:8080/people/](http://localhost:8080/people/) 访问。

如果您定义了查询方法,这些方法默认也会按其名称暴露,如下例所示:

interface PersonRepository extends CrudRepository<Person, Long> {

List<Person> findByName(String name);
}

前述示例中的方法会在 [localhost:8080/persons/search/findByName](http://localhost:8080/persons/search/findByName) 处暴露。

备注

所有查询方法资源都在 search 资源之下暴露。

要更改该查询方法所暴露的 URL 段,您可以再次使用 @RestResource 注解,如下例所示:

@RepositoryRestResource(path = "people")
interface PersonRepository extends CrudRepository<Person, Long> {

@RestResource(path = "names")
List<Person> findByName(String name);
}

现在,前述示例中的查询方法会在 [localhost:8080/people/search/names](http://localhost:8080/people/search/names) 处暴露。

处理 rel 属性​

由于这些资源都是可发现的,您还可以影响导出器发出的链接中 rel 属性的显示方式。

例如,在默认配置下,如果您向 [localhost:8080/persons/search](http://localhost:8080/persons/search) 发起请求以查看暴露了哪些查询方法,您会得到一个类似于下面这样的链接列表:

{
"_links" : {
"findByName" : {
"href" : "http://localhost:8080/persons/search/findByName"
}
}
}

要更改 rel 的值,请使用 @RestResource 注解上的 rel 属性,如下例所示:

@RepositoryRestResource(path = "people")
interface PersonRepository extends CrudRepository<Person, Long> {

@RestResource(path = "names", rel = "names")
List<Person> findByName(String name);
}

前述示例会产生如下链接值:

{
"_links" : {
"names" : {
"href" : "http://localhost:8080/persons/search/names"
}
}
}
备注

这些 JSON 片段假设您使用 Spring Data REST 默认的 HAL 格式。您可以关闭 HAL,这会使输出看起来有所不同。不过,您覆盖 rel 名称的能力与渲染格式完全无关。

您可以更改仓库的 rel,如下例所示:

@RepositoryRestResource(path = "people", rel = "people")
interface PersonRepository extends CrudRepository<Person, Long> {

@RestResource(path = "names", rel = "names")
List<Person> findByName(String name);
}

更改仓库的 rel 会改变顶层名称,如下例输出所示:

{
"_links" : {
"people" : {
"href" : "http://localhost:8080/people"
},
…
}
}

在前述输出所示的顶层片段中:

  • path = "people" 将 href 中的值从 /persons 改为 /people。

  • rel = "people" 将该链接的名称从 persons 改为 people。

当您导航到该仓库的 search 资源时,查找方法的 @RestResource 注解已经改变了路径,如下所示:

{
"_links" : {
"names" : {
"href" : "http://localhost:8080/people/search/names"
}
}
}

仓库定义中的这组注解带来了以下变化:

  • 仓库级注解的 path = "people" 体现在基础 URI 中为 /people。

  • 包含一个查找方法会为您提供 /people/search。

  • path = "names" 创建了 /people/search/names 这一 URI。

  • rel = "names" 将该链接的名称从 findByNames 改为 names。

隐藏特定仓库、查询方法或字段​

您可能不希望某个仓库、仓库上的某个查询方法,或实体的某个字段被导出。例如,隐藏 User 对象上的 password 等字段以及类似的敏感数据。要告知导出器不要导出这些项,请用 @RestResource 为它们添加注解,并将 exported 设为 false。

例如,要跳过导出某个仓库,您可以创建一个类似于下面这样的仓库定义:

@RepositoryRestResource(exported = false)
interface PersonRepository extends CrudRepository<Person, Long> {}

要跳过导出某个查询方法,您可以用 @RestResource(exported = false) 为该查询方法添加注解,如下所示:

@RepositoryRestResource(path = "people", rel = "people")
interface PersonRepository extends CrudRepository<Person, Long> {

@RestResource(exported = false)
List<Person> findByName(String name);
}

类似地,要跳过导出某个字段,您可以用 @RestResource(exported = false) 为该字段添加注解,如下所示:

@Entity
public class Person {

@Id @GeneratedValue private Long id;

@OneToMany
@RestResource(exported = false)
private Map<String, Profile> profiles;
}
注意

投影提供了改变导出内容的手段,并能有效地绕过这些设置。如果您针对同一领域对象创建了任何投影,请务必不要导出这些字段。

隐藏仓库 CRUD 方法​

如果您不希望在 CrudRepository 上暴露 save 或 delete 方法,可以通过重写想要关闭的方法,并在重写版本上添加 @RestResource(exported = false) 注解来使用该设置。例如,要阻止 HTTP 用户调用 CrudRepository 的 delete 方法,请重写所有这些方法,并在重写后的方法上添加该注解,如下所示:

@RepositoryRestResource(path = "people", rel = "people")
interface PersonRepository extends CrudRepository<Person, Long> {

@Override
@RestResource(exported = false)
void delete(Long id);

@Override
@RestResource(exported = false)
void delete(Person entity);
}
注意

务必同时重写 两个 delete 方法。为了获得更快的运行时性能,导出器目前使用一种略显简单的算法来确定应使用哪个 CRUD 方法。您目前无法做到关闭接受 ID 的 delete 版本,却导出接受实体实例的版本。眼下,您只能要么导出 delete 方法,要么都不导出。如果您想关闭它们,请记住必须为两个版本都加上 exported = false 注解。