在 Java 中构建高效 REST API 的四大关键技巧

提升 Java REST API 的关键技巧

在使用 Java 创建可靠的 REST API 时，不仅需要对 HTTP 请求和响应有基本了解，还需确保 API 设计良好、可维护且安全。本文将提供四个关键技巧，以改进 REST API。假设已经熟悉 Richardson 成熟度模型，尤其是达到 2 级，这是良好 API 的最低要求。如需快速了解理查森成熟度模型，建议阅读 Martin Fowler 的文章《理查森成熟度模型》。

在了解上述先决条件后，接下来将深入探讨这些技巧。为便于说明，以下示例来自探险领域。尽管不会详细探讨实体和层，但假设存在以下实体类：

public class Expedition {
    private String name;
    private String location;
    private LocalDate date;

    public Expedition(String name, String location, LocalDate date) {
        this.name = name;
        this.location = location;
        this.date = date;
    }

    public String getName() {
        return name;
    }

    public String getLocation() {
        return location;
    }

    public LocalDate getDate() {
        return date;
    }
}

术语和资源命名的一致性

设计良好的 REST API 的关键之一是确保术语的一致性，并仔细关注服务的词汇。首先应遵循通用命名约定，然后再向更具体的术语细化。可以借助领域驱动设计（DDD）原则，从主域出发，逐步细化到子域。

一个简单的经验法则是使用复数名词表示资源，例如：

GET /expeditions – 返回所有探险
GET /expeditions/{id} – 通过 ID 检索特定探险

示例代码：

@Path("expeditions")
public class ExpeditionResource {

    @GET
    public List<Expedition> list() {
        // 实现代码
    }

    @GET
    @Path("/{id}")
    public Expedition get(@PathParam("id") String id) {
        // 实现代码
    }

    @GET
    @Path("/search")
    public List<Expedition> mine() {
        // 实现代码
    }
}

有关保持一致性的更详细指南，请参考《REST API 设计规则手册》。

可维护性、可扩展性和文档

随着 API 的复杂性不断增加，维护和扩展变得至关重要。确保可维护性的一种有效方式是提供适当的文档。尽管文档可能不是许多开发人员最喜欢的任务，但它是不可或缺的。OpenAPI 是一个优秀的工具，能够自动生成和增强文档。欲了解更多信息，请访问 OpenAPI。

另一个关键方面是版本控制。版本控制可以确保向后兼容性，并实现不同 API 版本之间的平滑过渡。它允许同时支持新旧版本，从而鼓励用户在方便时迁移到最新版本。在 Java 中，可以通过为每个版本使用单独的包构建代码，并创建适配器层来管理版本之间的交互，来实现这一点。

示例：

package os.expert.demo.expeditions.v1;

@Path("/api/v1/expeditions")
public class ExpeditionResource {
    // 实现代码
}

package os.expert.demo.expeditions.v2;

@Path("/api/v2/expeditions")
public class ExpeditionResource {
    // 实现代码
}

安全性：永远不要信任用户

安全性是任何 API 的基本组成部分。一般原则是永远不要信任用户；始终验证其访问所请求资源的权限。采用身份验证的方法，可以确定用户可以访问哪些探险，而无需依赖用户提供的 ID。

示例：

@GET
@Path("/my-expeditions")
public List<Expedition> myExpeditions() {
    // 用户已通过身份验证，无需请求 ID
    // 实现代码
}

这一原则同样适用于编辑或删除资源等其他操作。在继续执行之前，务必验证权限。

异常处理与正确的 HTTP 状态代码

设计良好的 API 应具备强大的异常处理机制，将错误映射到正确的 HTTP 状态代码。例如，如果未找到探险，API 应返回 404 Not Found 状态，以确保 Java 代码与 REST API 语义之间的一致性。

示例：

@Provider
public class ExpeditionNotFoundExceptionMapper implements ExceptionMapper<ExpeditionNotFoundException> {

    @Override
    public Response toResponse(ExpeditionNotFoundException exception) {
        return Response.status(Response.Status.NOT_FOUND)
                       .entity(exception.getMessage())
                       .build();
    }
}