或早或晚,大多数积极使用REST(ful) Web服务和API的开发人员都偶然发现了这种真正的外星事物,即HATEOAS : 超文本作为应用程序状态的引擎 。 对HATEOAS是什么以及它与REST的关系的好奇最终将导致发现Richardson成熟度模型 ,该模型使REST和RESTful的行业定义神秘化。 后者是一个启发,但提出了一个问题:这些年来,我们是否一直在错误地进行REST ?
让我们尝试从不同的角度回答这个问题。 HATEOAS是REST核心架构约束之一。 从这个角度来看,答案是“是”,为了声称符合REST ,Web服务或API应该支持它。 但是,如果您四处看看(甚至参考您过去或现在的经验),您可能会发现大多数Web服务和API只是域模型周围的CRUD包装器,而没有HATEOAS支持。 这是为什么? 可能有多个原因,但是从开发人员的工具箱角度来看, HATEOAS的支持不是那么好。
在今天的帖子中,我们将讨论有关HATEOAS的 JAX-RS 2.x必须提供的内容 ,如何从服务器和客户端的角度使用它以及如何增强OpenAPI v3.0.x规范以暴露超媒体。作为合同的一部分。 如果您很兴奋,请让我们开始吧。
因此,我们的JAX-RS Web API将围绕管理公司及其员工而构建。 基础是Spring Boot和Apache CXF ,其中Swagger是OpenAPI规范的实现。 AppConfig是我们需要定义的唯一配置,以启动和运行应用程序(这要归功于Spring Boot的自动配置功能)。
@SpringBootConfiguration public class AppConfig {
@Bean
OpenApiFeature createOpenApiFeature() {
final OpenApiFeature openApiFeature = new OpenApiFeature();
openApiFeature.setSwaggerUiConfig( new SwaggerUiConfig().url( "/api/openapi.json" ));
return openApiFeature;
}
@Bean
JacksonJsonProvider jacksonJsonProvider() {
return new JacksonJsonProvider();
} }
Company和Person这个模型非常简单(请注意,这两个类之间没有直接关系)。
public class Company {
private String id;
private String name; } public class Person {
private String id;
private String email;
private String firstName;
private String lastName; }
该模型通过CompanyResource公开, CompanyResource是典型的JAX-RS资源类,带有@Path注释,此外还带有OpenAPI的@Tag注释。
@Component @Path ( "/companies" ) @Tag (name = "companies" ) public class CompanyResource {
@Autowired private CompanyService service; }
很好,资源类尚未定义端点,因此让我们加强一下。 我们的第一个端点将通过标识符查找公司,并以JSON格式返回其表示形式。 但是,由于我们没有包含任何与员工相关的细节,因此提示消费者(Web UI或任何其他客户端)在哪里查找真是太棒了。 有多种方法可以执行此操作,但是由于我们坚持使用JAX-RS ,因此可以使用开箱即用的Web链接 ( RFC-5988 )。 该代码段包含数千个单词。
@Produces (MediaType.APPLICATION_JSON) @GET @Path ( "{id}" ) public Response getCompanyById( @Context UriInfo uriInfo, @PathParam ( "id" ) String id) {
return service
.findCompanyById(id)
.map(company -> Response
.ok(company)
.links(
Link.fromUriBuilder(uriInfo
.getRequestUriBuilder())
.rel( "self" )
.build(),
Link.fromUriBuilder(uriInfo
.getBaseUriBuilder()
.path(CompanyResource. class ))
.rel( "collection" )
.build(),
Link.fromUriBuilder(uriInfo
.getBaseUriBuilder()
.path(CompanyResource. class )
.path(CompanyResource. class , "getStaff" ))
.rel( "staff" )
.build(id)
)
.build())
.orElseThrow(() -> new NotFoundException( "The company with id '" + id + "' does not exists" )); }
这里几乎没有发生任何事情。 我们关心的是使用ResponseBuilder :: links方法,其中提供了三个链接。 第一个是self ,它本质上是链接上下文(定义为RFC-5988的一部分)。 第二个是collection ,它指向CompanyResource端点,该端点返回公司列表(也包含在标准关系注册表中)。 最后,第三个是我们自己的员工关系,我们通过一个名为getStaff的方法实现的另一CompanyResource端点组装(我们将看到它不久)。 这些链接将在“ 链接”响应标头中传递,并指导客户端下一步去向。 让我们通过运行该应用程序来实际查看它。
$ mvn clean package $ java -jar target/jax-rs- 2.1 -hateaos- 0.0 . 1 -SNAPSHOT.jar
然后使用curl检查来自此资源端点的响应(不必要的详细信息已被滤除)。
$ curl -v http: //localhost:8080/api/companies/1 > GET /api/companies/ 1 HTTP/ 1.1 > Host: localhost: 8080 > User-Agent: curl/ 7.47 . 1 > Accept: */* > < HTTP/ 1.1 200 < Link: <http: //localhost:8080/api/companies/1>;rel="self" < Link: <http: //localhost:8080/api/companies/1/staff>;rel="staff" < Link: <http: //localhost:8080/api/companies>;rel="collection" < Content-Type: application/json < Transfer-Encoding: chunked < {
"id" : "1" ,
"name" : "HATEOAS, Inc." }
链接头在那里,指的是其他感兴趣的端点。 从客户的角度来看,事情看起来也很简单。 Response类提供专用的getLinks方法来包装对Link响应标头的访问,例如:
final Client client = ClientBuilder.newClient(); try ( final Response response = client
.target( " http://localhost:8080/api/companies/ {id}" )
.resolveTemplate( "id" , "1" )
.request()
.accept(MediaType.APPLICATION_JSON)
.get()) {
final Optional staff = response
.getLinks()
.stream()
.filter(link -> Objects.equals(link.getRel(), "staff" ))
.findFirst();
staff.ifPresent(link -> {
// follow the link here
}); } finally {
client.close(); }
到目前为止,一切都很好。 展望未来,由于HATEOAS本质上是Web API合同的一部分,因此让我们在桌上找出OpenAPI规范所具有的内容。 不幸的是, 到目前为止 尚不支持 HATEOAS ,但是从好的方面来说,存在链接的概念(尽管不应将它们与Web链接混淆,它们有些相似,但并不相同)。 为了说明作为OpenAPI规范一部分的链接的用法,让我们用Swagger注释装饰端点。
@Operation (
description = "Find Company by Id" ,
responses = {
@ApiResponse (
content = @Content (schema = @Schema (implementation = Company. class )),
links = {
@io .swagger.v3.oas.annotations.links.Link(
name = "self" ,
operationRef = "#/paths/~1companies~1{id}/get" ,
description = "Find Company" ,
parameters = @LinkParameter (name = "id" , expression = "$response.body#/id" )
),
@io .swagger.v3.oas.annotations.links.Link(
name = "staff" ,
operationRef = "#/paths/~1companies~1{id}~1staff/get" ,
description = "Get Company Staff" ,
parameters = @LinkParameter (name = "id" , expression = "$response.body#/id" )
),
@io .swagger.v3.oas.annotations.links.Link(
name = "collection" ,
operationRef = "#/paths/~1companies/get" ,
description = "List Companies"
)
},
description = "Company details" ,
responseCode = "200"
),
@ApiResponse (
description = "Company does not exist" ,
responseCode = "404"
)
} ) @Produces (MediaType.APPLICATION_JSON) @GET @Path ( "{id}" ) public Response getCompanyById( @Context UriInfo uriInfo, @PathParam ( "id" ) String id) {
// ... }
如果我们运行该应用程序并浏览到浏览器中的http:// localhost:8080 / api / api-docs (这是Swagger UI的托管位置),我们将能够看到每个响应中的链接部分。
但是除此之外……您可以使用那里的链接做很多事情(如果您对该主题感兴趣,请注意此问题 )。 吸引公司员工的资源终点看起来非常相似。
@Operation (
description = "Get Company Staff" ,
responses = {
@ApiResponse (
content = @Content (array = @ArraySchema (schema = @Schema (implementation = Person. class ))),
links = {
@io .swagger.v3.oas.annotations.links.Link(
name = "self" ,
operationRef = "#/paths/~1companies~1{id}~1staff/get" ,
description = "Staff" ,
parameters = @LinkParameter (name = "id" , expression = "$response.body#/id" )
),
@io .swagger.v3.oas.annotations.links.Link(
name = "company" ,
operationRef = "#/paths/~1companies~1{id}/get" ,
description = "Company" ,
parameters = @LinkParameter (name = "id" , expression = "$response.body#/id" )
)
},
description = "The Staff of the Company" ,
responseCode = "200"
),
@ApiResponse (
description = "Company does not exist" ,
responseCode = "404"
)
} ) @Produces (MediaType.APPLICATION_JSON) @GET @Path ( "{id}/staff" ) public Response getStaff( @Context UriInfo uriInfo, @PathParam ( "id" ) String id) {
return service
.findCompanyById(id)
.map(c -> service.getStaff(c))
.map(staff -> Response
.ok(staff)
.links(
Link.fromUriBuilder(uriInfo
.getRequestUriBuilder())
.rel( "self" )
.build(),
Link.fromUriBuilder(uriInfo
.getBaseUriBuilder()
.path(CompanyResource. class )
.path(id))
.rel( "company" )
.build()
)
.build())
.orElseThrow(() -> new NotFoundException( "The company with id '" + id + "' does not exists" )); }
如您所料,除了指向self的链接之外,它还包括指向公司的链接。 当我们使用curl尝试时,预期的响应标头将返回。
$ curl -v http: //localhost:8080/api/companies/1/staff > GET /api/companies/ 1 /staff HTTP/ 1.1 > Host: localhost: 8080 > User-Agent: curl/ 7.47 . 1 > Accept: */* > < HTTP/ 1.1 200 < Link: <http: //localhost:8080/api/companies/1/staff>;rel="self" < Link: <http: //localhost:8080/api/companies/1>;rel="company" < Content-Type: application/json < Transfer-Encoding: chunked < [
{
"id" : "1" ,
"email" : "john@smith.com" ,
"firstName" : "John" ,
"lastName" : "Smith"
},
{
"id" : "2" ,
"email" : "bob@smith.com" ,
"firstName" : "Bob" ,
"lastName" : "Smith"
} ]
那么我们可以得出什么样的结论呢? HATEOAS实际上通过动态地驱动对话来统一Web API提供者和使用者之间的交互模型。 这非常强大,但是其中的大多数框架和工具要么都对HATEOAS提供了相当基本的支持(例如Web Linking ),要么根本没有。
在很多情况下,只要使用Web链接就足够了(到目前为止,我们已经看到了示例,例如分页,导航等),但是假设创建,编辑或修补现有资源又如何呢? 如何用超媒体丰富集合中返回的各个元素(在RFC-6537中进行描述)? HATEOAS是否值得所有这些努力?
与往常一样,答案是“取决于”,也许我们应该超越JAX-RS ? 在下一篇文章中(s_,我们将继续解决问题。
完整的源代码可在Github上找到 。
翻译自: https://www.javacodegeeks.com/2019/02/hypermedia-apis-support-jax-rs-openapi.html