Web API 的正确返回

Question

我有一个返回单个对象的 ASP.NET Core 控制器。假设这个对象是类型/类，Person。您调用 API 函数是问题接受一个代表人名的参数。所以 API 的目的是按姓名返回一个人。如果找不到人，最佳实践返回是什么？我应该返回null吗？我应该返回/抛出异常吗？

return new ObjectResult(person); 
return NotFound(); // NotFound() is framework function - returns 404

我担心 Not Found 通常意味着在 HTTP 中找不到资源本身。也可以/应该用 Not Found 表示未找到查询的对象吗？

Answer 1

执行此操作的正确 REST 方式是返回 HTTP 404 状态代码。

Person 是 API 上下文中的资源，所以应该没问题。 REST 客户端和开发人员知道如何处理 HTTP 错误，404 错误非常有意义。

您可以在 404 响应正文中写一个原因，但我不介意。

为了进一步扩展 REST API 响应的 HTTP 状态代码的使用，如果您要返回一个集合而不是单个对象，例如 特定部门下的员工，您可以生成一个HTTP 204 (NO CONTENT) 状态，如果该部门确实存在但它下面没有员工（意味着现有部门的一个空集），或者如果没有这样的部门，则为 HTTP 404 (NOT FOUND) 状态。您应该始终记录您的 API 和返回的状态代码的语义。

---

解决此问题的另一种方法是使用包含成功/错误信息以及有效负载的标准化 JSON 响应。例如，您的控制器的所有“JSON”操作都可以返回一个继承自该基类的类：

public class ApiResponse {
    // I use lowercase properties so that the JSON follows common JavaScript naming conventions
    public bool success { get; set; }
    public String errorMessage { get; set; }
    public int? errorCode { get; set; }
}

你的返回人的控制器方法可以使用这样的东西：

public class GetPersonResponse : ApiResponse {
    public PersonModel person { get; set; }
}

在您的控制器中，您可以执行以下操作：

public GetPersonResponse Person(string id) {
    var person = FindPersonByName(id);
    var response = new GetPersonResponse {
        success = person != null,
        person = person
    }
    if (person == null) {
        response.errorCode = 404, // suggestion only
        response.errorMessage = "Person not found"
    }        
    return response;
}

由于 JSON 序列化程序不会序列化（默认情况下）空属性，因此上面的代码通过在未找到有效负载（人）时不序列化它，或者如果是，则不序列化错误信息来覆盖您。