四条建议：帮你构建健壮的 Java REST API

在 Java 中构建一个可靠的 REST API，需要的不仅仅是对 HTTP 请求和响应的基本了解。确保你的 API 设计良好、易于维护且安全可靠是至关重要的。 本文将提供四个关键建议来提升你的 REST API。

作为前提，我会提供以下实体类：

java 复制代码

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;
    }
}

1. 术语和资源命名的一致性

设计良好 REST API 的一个重要方面是确保术语的一致性和对服务词汇的细致关注。从通用命名约定开始，然后转向更具体的术语。遵循领域驱动设计（DDD）原则，从主领域开始，然后将其细化为子领域。

一个简单的经验法则是使用复数名词作为资源名称。例如：

GET /expeditions - 返回所有探险活动
GET /expeditions/{id} - 根据 ID 检索特定的探险活动

示例代码：

java 复制代码

@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 设计规则手册》：

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

随着 API 的复杂性增加，维护和扩展你的 API 至关重要。确保可维护性的一个方法是通过适当的文档。虽然文档可能不是许多开发人员的最爱任务，但它不可或缺。

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

示例：

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 {
    // 实现代码
}

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

安全性是任何 API 的基本方面。一个通用规则是永远不要信任用户；始终验证他们访问请求资源的权限。一个实用的方法是使用身份验证来确定用户可以访问哪些探险活动，而不是依赖用户提供的 ID。

示例：

java 复制代码

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

这一原则也应适用于编辑或删除资源等其他操作。在继续之前，始终进行权限的验证。

4. 异常处理和正确的 HTTP 状态码

最后，设计良好的 API 应该具有强大的异常处理能力，将错误映射到正确的 HTTP 状态码。例如，如果找不到探险活动，你的 API 应该返回 404 未找到 状态码，保持你的 Java 代码和 REST API 语义之间的一致性。

java 复制代码

@Provider
public class ExpeditionNotFoundExceptionMapper implements ExceptionMapper<ExpeditionNotFoundException> {

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

总结

总之，构建一个可靠的 REST API 涉及几个关键步骤：

使用一致的术语 - 遵循清晰一致的资源命名约定。
关注可维护性和文档 - 使用 AI 工具实现版本控制并生成文档。
优先考虑安全性 - 始终验证用户权限。
实现适当的异常处理 - 确保你的 API 返回适当的 HTTP 状态码。

希望通过遵循这些建议，你能够开发出一个可靠且易于维护的 Java REST API。