REST WS 中的控制器 return 类型和 httpStatus 最佳实践以及 production/consumption 方法

Question

我开始学习 REST，我有一些问题：

控制器必须是什么类型return？通常，我问我的 Rest @Controller 是否必须按原样 return Item 对象或将其封装在 ResponseEntity 中以指定 http-status-code.
如果给定的项目不存在，在特定项目的 GET 方法中使用什么 http 状态代码 ("/items/2")：HttpMediaStatus.OK(200) 和 null return 或 HttpStatus.NO_CONTENT(204) 和 null return ?

第二部分：我看到可以在 WS 方法上指定 @Produces 和 @Consumes 但那有什么用呢？我的应用程序和我的方法如此有效，为什么要指定 MediaType.APPLICATION_JSON_VALUE？ Spring/SpringBoot 不会自动将 Item 或 ResponseEntity 转换为 json 吗？

上下文：使用 Spring 引导、休眠、REST 网络服务。

谢谢。

Answer 1

很多问题，我会提供一些 link 相关文章和参考文档的简短答案。

What type must the controller return?

取决于您的注释和服务的 RESTful-ness。 controllers 可以使用三种注解：@Controller、@RestController 和 @RepositoryRestController.

Controller is the base annotation to mark your class as a controller. The return type of the controller endpoint methods can be many things, I invite you to read this dedicated post来掌握一下。在开发 pure-REST 服务时，您将专注于使用 RestController and RepositoryRestController。 RestController 是 Controller + ResponseBody。它将端点方法的 return 值绑定到 Web 响应 body:

@RestController
public ItemController {

    @RequestMapping("/items/{id}")
    public Item getItem(@PathVariable("id") String id) {
         Item item = ...

         return item;
    }

}

有了这个，当您点击 http:/.../api/items/foo 时，Spring 会发挥它的魔力，自动将项目转换为具有相关 40X 状态代码和一些默认 HTTP [=76] 的 ResponseEntity =].

在某些时候，您将需要更多地控制状态代码和 headers，同时仍然受益于 Spring Data REST 的设置。那时您将使用 RepositoryRestController 和 ResponseEntity<Item> 作为 return 类型，请参阅 example 和 Spring 数据 REST 参考。

What http status code to use in a GET method on a particular item if the given item does not exists?

直白地说：用HttpStatus.NOT_FOUND。您正在查找不存在的资源，有问题。

也就是说，如何处理项目中缺失的资源完全由您决定。如果您的工作流程证明了这一点，那么缺少资源可能是完全可以接受的，确实 return 是 20 倍的响应，但如果您没有警告或提供一些信息，您的 API 用户可能会感到困惑文档（我们是习惯和惯例的产物）。但我仍然会从 404 状态代码开始。

(...) @Produces and @Consumes on WS method but what the use of that? My application and my methods work so, why specify MediaType.APPLICATION_JSON_VALUE? Doesn't Spring/SpringBoot automatically convert Item or ResponseEntity into json?

@Consumes 和 @Produces 分别与请求中的 content-type 和 accept headers 匹配。这是一种限制接受的输入和端点方法提供的输出的方法。

由于我们讨论的是 REST 服务，因此 API 的客户端与服务之间的通信应该是 JSON-formatted。感谢 Spring HATEOAS，答案实际上是用 application/hal+json content-type 格式化的。在那种情况下，您确实可以不用理会这两个注释。如果您开发的服务接受不同的 content-type（application/text、application/json、application/xml...）并提供例如 HTML 对您网站用户的浏览量和 JSON 或 XML 对您服务的自动客户端的响应。

现实生活中的例子：

Facebook 为应用程序提供 Graph API 从其图形中读取 to/write，同时用户愉快地 (?) 浏览网页
Google 与 Google Maps API

REST WS 中的控制器 return 类型和 httpStatus 最佳实践以及 production/consumption 方法

Controller return type and httpStatus best practice and production/consumption on method in REST WS

rest

web-services

spring-boot

controller

media-type