找不到 REST 资源时返回 404 是否正确？

Question

假设我有一个简单的 (Jersey) REST 资源，如下所示：

@Path("/foos")
public class MyRestlet
        extends BaseRestlet
{

    @GET
    @Path("/{fooId}")
    @Produces(MediaType.APPLICATION_XML)
    public Response getFoo(@PathParam("fooId") final String fooId)
            throws IOException, ParseException
    {
        final Foo foo = fooService.getFoo(fooId);

        if (foo != null)
        {
            return Response.status(Response.Status.OK).entity(foo).build();
        }
        else
        {
            return Response.status(Response.Status.NOT_FOUND).build();
        }
    }

}

根据上面的代码，返回 NOT_FOUND 状态 (404) 是否正确，或者我应该返回 204 或其他更合适的代码？

Answer 1

在这种情况下，404 响应非常典型，API 用户很容易使用。

一个问题是，客户端很难判断他们是否收到了 404，原因是未找到特定实体，还是由于 URI 中的结构问题。在您的示例中，/foos/5 可能会返回 404，因为 id=5 的 foo 不存在。但是，/food/1 将返回 404，即使存在带有 id=1 的 foo（因为 foos 拼写错误）。换句话说，404 意味着要么是构造错误的 URI，要么是对不存在的资源的引用。

当您有一个引用多个资源的 URI 时，会出现另一个问题。通过简单的 404 响应，客户端不知道哪个引用的资源没有找到。

这两个问题都可以通过在响应正文中返回额外信息来部分缓解，让调用者确切知道没有找到什么。

Answer 2

是的，对于未找到的资源返回 404 是很常见的。就像网页一样，当它找不到时，你会得到一个 404。这不仅仅是 REST，而是一种 HTTP 标准。

每个资源都应该有一个 URL 位置。 URL 不需要是静态的，它们可以是templated。因此，实际请求的 URL 可能没有资源。服务器的职责是从模板中分解 URL 以查找资源。如果他们的资源不存在，那么它是“未找到”

来自HTTP 1.1 spec

404 未找到

服务器没有找到任何匹配 Request-URI 的东西。没有说明这种情况是暂时的还是永久性的。如果服务器通过一些内部可配置的机制知道旧资源永久不可用并且没有转发地址，则应该使用 410 (Gone) 状态代码。当服务器不希望确切地显示请求被拒绝的原因或没有其他响应适用时，通常使用此状态代码。

---

这里是 204

204 无内容

服务器已完成请求但不需要返回实体主体，并且可能希望返回更新的元信息。响应可能包含实体标头形式的新的或更新的元信息，如果存在，则应该与请求的变体相关联。

如果客户端是用户代理，它不应该改变导致请求被发送的文档视图。此响应的主要目的是允许输入操作发生，而不会导致用户代理的活动文档视图发生变化，尽管任何新的或更新的元信息都应该应用于当前在用户代理的活动视图中的文档。

204 响应不得包含消息正文，因此始终以标头字段后的第一个空行终止。

通常在更新或创建表示且无需发回响应正文时使用 204。在 POST 的情况下，您可以只发回新创建资源的位置。类似的东西

@POST
@Path("/something")
@Consumes(...)
public Response createBuzz(Domain domain, @Context UriInfo uriInfo) {
    int domainId = // create domain and get created id
    UriBuilder builder = uriInfo.getAbsolutePathBuilder();
    builder.path(Integer.toString(domainId));  // concatenate the id.
    return Response.created(builder.build()).build();
}

created(URI) 将使用 Location 标头中新创建的 URI 发回响应。

---

添加到第一部分。您只需要记住，来自客户端的每个请求都是访问资源的请求，无论是获取资源还是使用 PUT 进行更新。资源可以是服务器上的任何东西。如果资源不存在，那么一般的响应是告诉客户端我们找不到该资源。

扩展您的示例。假设FooService 访问数据库。数据库中的每一行都可以被视为一个资源。并且这些行（资源）中的每一行都有一个唯一的 URL，例如 foo/db/1 可能会找到主键为 1 的行。如果找不到 id，那么 resource 就是 “未找到”

Answer 3

4XX 错误代码表示来自客户端的错误。
当您请求静态资源作为图像或 html 页面时，返回 404 response 是有意义的：

HTTP 404 Not Found 客户端错误响应代码表示 服务器找不到请求的资源。导致 404 的链接 页面通常被称为损坏或死链接，并且可能受到链接 腐烂。

当您向客户提供一些 REST 方法时，您依赖 HTTP 方法，但您不应将 REST 服务视为简单资源。
对于客户端，REST 方法中的错误响应通常在接近其他处理错误的情况下处理。

例如，要在 REST 调用期间或其他地方捕获错误，客户端可以使用 catchError() 或 RxJS。

我们可以用这种方式编写代码（示例代码在 TypeScript/Angular 2 中）将错误处理委托给一个函数：

return this.http
  .get<Foo>("/api/foos")
  .pipe(
      catchError(this.handleError)
  )
  .map(foo => {...})

问题是任何 HTTP 错误（5XX 或 4XXX）都会在 catchError() 回调中终止。
它可能真的会使 REST API 响应对客户端产生误导。

如果我们与编程语言做一个并行，我们可以将 5XX/4XX 视为异常流​​。
通常，我们不会仅仅因为未找到数据而引发异常，我们会在未找到数据并且已找到该数据时抛出异常。
对于 REST API，我们应该遵循相同的逻辑。

如果实体可能找不到，在这两种情况下返回OK是完全可以的：

@GET
@Path("/{fooId}")
@Produces(MediaType.APPLICATION_XML)
public Response getFoo(@PathParam("fooId") final String fooId)
        throws IOException, ParseException {
    final Foo foo = fooService.getFoo(fooId);

    if (foo != null){
        return Response.status(Response.Status.OK).entity(foo).build();
    }

    return Response.status(Response.Status.OK).build();

}

客户端可以根据结果是否存在来处理结果。
我不认为返回 204 会带来任何有用的价值。
The HTTP 204 documentation 表示：

客户端不需要离开当前页面。

但请求 REST 资源，尤其是通过 GET 方法，并不意味着客户端要终止工作流（这对于 POST/PUT 方法更有意义）。

文档还添加了：

常见的用例是作为 PUT 请求的结果返回 204， 更新资源，而不更改页面的当前内容 显示给用户。

我们真的不是这种情况。

一些用于经典浏览的特定 HTTP 代码与 REST API 的返回代码（201、202、401 等等......）非常匹配，但情况并非总是如此。 所以对于这些情况，我宁愿使用更通用的代码来保持它们的简单性，而不是扭曲原始代码：200，400。

Answer 4

虽然这个问题已经有了一个公认的答案，但我相信这确实是一个固执己见的事情。添加我的两分钱以帮助您对响应代码做出更明智的决定。

404 - 未找到。 (Reference)

源服务器没有找到目标资源的当前表示，或者不愿意透露存在。

资源可能存在而您可能无权查看该资源，也将等同于未找到。因此，在数据不存在的情况下调用 404 是一件非常合适的事情。

现在对于一个不存在的 URL；虽然 404 是一个广泛适用的响应代码，但 400 是一个更合适的代码。

400 - 错误请求 (Reference)

由于某些被认为是客户端错误（例如，格式错误的请求语法、无效的请求消息帧或欺骗性请求路由），服务器无法或不会处理请求。

如果你在请求中输入了一个无效参数，那么响应码是什么？ 如果查询参数有错字，响应码应该是什么？

两者的答案都是 400。

大多数文件服务器对于无效 URL 返回 404，因为对于无效 URL，它们会尝试查找在存储中找不到的文件 ~= Resource Not Found

除了 HTTP 状态码之外，响应中还会包含一些关于错误详细信息的信息，其中可以更详细地描述错误并消除歧义。

如果客户端使用无效的 URL 进行调用，则这是一个集成问题，至少在正常情况下应该被捕获。他们绝不会在没有测试和捕获的情况下将代码推送到生产环境中。即使他们这样做了，上帝保佑他们！

tl;dr - 404 表示未找到资源； 400 表示未找到的 URL。