rest_REST API的演变

rest

每个开发人员都以某种方式接触到API 。 要么为一家大公司集成一个主要系统，或者使用最新的图形库生成一些精美的图表，要么直接与他最喜欢的编程语言进行交互。 事实是，API无处不在！ 它们实际上代表了当今Internet的基本组成部分，在不同系统和设备之间发生的数据交换过程中扮演着重要角色。 从您手机上的简单天气小部件到您在网上商店中执行的信用卡付款，如果这些系统无法通过调用彼此的API彼此通信，那么所有这些都是不可能的。

因此，随着不断增长的异构设备生态系统连接到Internet，API面临着一系列新的挑战。 尽管它们必须继续以可靠和安全的方式运行，但它们还必须与所有这些设备兼容，从手表到数据中心内最先进的服务器。

REST来解救

用于构建此类API的最广泛使用的技术之一就是所谓的REST API。 这些API旨在提供异构系统之间通用且标准化的通信方式。 由于它们严重依赖于标准的通信协议和数据表示(例如HTTP，XML或JSON)，因此很容易在大多数编程语言上提供客户端实现，从而使其与绝大多数系统和设备兼容。

因此，尽管这些REST API可以与大多数设备和技术兼容，但它们也必须不断发展。 演化的问题在于，有时您必须保持与旧客户端版本的回溯兼容性。

让我们建立一个例子。

让我们想象一个约会系统，在该系统中您具有一个用于创建和检索约会的API。 为简化起见，让我们想象一下约会对象和日期以及来宾姓名。 像这样：

public class AppointmentDTO {
    public Long id;
    public Date date;
    public String guestName;
}

一个非常简单的REST API如下所示：

@Path("/api/appointments")
public class AppointmentsAPI {

    @GET
    @Path("/{id}")
    public AppointmentDTO getAppointment(@PathParam("id") String id) { ... }

    @POST
    public void createAppointment(AppointmentDTO appointment) { ... }

}

让我们假设这个简单的简单API可以正常工作，并且可以在允许预订和显示约会的手机，平板电脑和各种网站上使用。 到现在为止还挺好。

在某个时候，您认为开始收集有关您的约会系统的一些统计信息将非常有趣。 为了使事情简单，您只想知道谁是预订次数最多的人。 为此，您需要将访客之间关联起来，并决定需要为每个访客添加唯一的标识符。 让我们使用电子邮件。 因此，现在您的对象模型将如下所示：

public class AppointmentDTO {
    public Long id;
    public Date date;
    public GuestDTO guest;
}

public class GuestDTO {
    public String email;
    public String name;
}

因此，我们的对象模型稍有变化，这意味着我们将不得不在api上调整业务逻辑。

问题

尽管可以轻松调整API以存储和检索新的对象类型，但问题是您当前的所有客户端都在使用旧模型，并且将继续这样做直到更新。 可以说您不必为此担心，客户应该更新到较新的版本，但事实是您不能真正地从头到尾进行更新。 始终会有一个时间窗口，您必须保持两个模型都在运行，这意味着您的api必须是复古兼容的。

这是您的问题开始的地方。

回到我们的示例，在这种情况下，这意味着我们的API将必须处理两个对象模型，并能够根据客户端存储和检索那些模型。 因此，让我们将guestName添加回我们的对象中，以保持与旧客户端的兼容性：

public class AppointmentDTO {
    public Long id;
    public Date date;

    @Deprecated //For retro compatibility purposes
    public String guestName;

    public GuestDTO guest;
}

请记住，关于API对象的一个​​好的经验法则是，您永远不要删除字段。 添加新字段通常不会破坏任何客户端实现(假设它们遵循忽略新字段的良好经验法则)，但是删除字段通常是噩梦之路。

现在，为了保持API的兼容性，有几种不同的选择。 让我们看一些替代方案：

• 复制：单纯。 为新客户端创建一种新方法，并让旧客户端使用相同的方法。
• 查询参数：引入一个标志来控制行为。 诸如useGuests = true之类的东西。
• API版本控制：在您的URL路径中引入一个版本，以控制要调用的方法版本。

因此，所有这些替代方案都有其优缺点。 尽管复制很简单，但它可以轻松地将您的API类变成一碗重复的代码。

可以(并且应该)将查询参数用于行为控制(例如，将分页添加到列表中)，但我们应避免将其用于实际的API演变，因为这些参数通常是永久性的，因此您不希望使用对于消费者来说是可选的。

版本控制似乎是个好主意。 它提供了一种发展API的干净方法，它使旧客户端与新客户端保持隔离，并为您在API使用寿命期间发生的各种更改提供了通用基础。 另一方面，它也引入了一些复杂性，特别是如果您在不同版本上有不同的调用时。 您的客户最终将不得不通过升级调用而不是API来自己管理API的演变。 就像您没有升级库到下一个版本，而是只升级了该库的某个类。 这很容易变成版本梦night……

为了克服这个问题，我们必须确保我们的版本涵盖整个API。 这意味着我应该能够使用/ v2来调用/ v1上的每个可用方法。 当然，如果v2上存在给定方法的较新版本，则应在/ v2调用上运行它。 但是，如果给定的方法在v2中没有更改，我希望可以无缝调用v1版本。

基于继承的API版本控制

为了实现这一点，我们可以利用Java对象的多态功能。 我们可以以分层的方式构建API版本，以便较新版本可以覆盖较旧版本的方法，而对未更改方法的较新版本的调用可以无缝地回退到其较早版本。

因此，回到我们的示例，我们可以构建一个新版本的create方法，以便API如下所示：

@Path("/api/v1/appointments")    //We add a version to our base path
public class AppointmentsAPIv1 { //We add the version to our API classes

    @GET
    @Path("/{id}")
    public AppointmentDTO getAppointment(@PathParam("id") String id) { ... }

    @POST
    public void createAppointment(AppointmentDTO appointment) { 
        //Your old way of creating Appointments only with names
    }
}

//New API class that extends the previous version
@Path("/api/v2/appointments")                      
public class AppointmentsAPIv2 extends AppointmentsAPIv1 {

    @POST
    @Override
    public void createAppointment(AppointmentDTO appointment) { 
        //Your new way of creating appointments with guests
    }
}

因此，现在我们有2个有效的API版本。 尽管所有尚未升级到新版本的旧客户端将继续使用v1，并且不会看到任何更改，但您的所有新客户现在都可以使用最新的v2。 请注意，所有这些调用均有效：

呼叫	结果
GET /api/v1/appointments/123	将在v1类上运行getAppointment
GET /api/v2/appointments/123	将在v1类上运行getAppointment
POST /api/v1/appointments	将在v1类上运行createAppointment
POST /api/v2/appointments	将在v2类上运行createAppointment

这样，任何想要开始使用最新版本的使用者都只需将其基本URL更新为相应的版本，并且所有API都将无缝转换到最新的实现，同时保持旧的不变。

警告

出于敏锐的眼光，这种方法立即引起了警告。 如果您的API由十分之几的不同类组成，那么即使您实际上没有任何更改，较新的版本也意味着将它们全部复制为较高版本。 这是一些可以自动生成的样板代码。 仍然很烦。

尽管没有快速的方法可以解决此问题，但是使用接口可能会有所帮助。 除了创建新的实现类之外，您还可以创建一个新的带路径注释的接口，并在当前的实现类中对其进行实现。 尽管您将不得不为每个API类创建一个接口，但它有点干净。 它有一点帮助，但仍然是一个警告。

最后的想法

API版本控制似乎是当前的热门话题。 存在许多不同的观点和意见，但似乎缺乏标准的最佳实践。 尽管本文并非旨在提供这样的内容，但我希望它有助于实现更好的API结构并有助于其可维护性。

最后要说的是罗伯托·科尔特斯( Roberto Cortez)鼓励并允许将此帖子发布到他的博客上。 这实际上是我的第一篇博文，因此请加载大炮并随意开火。 :)

翻译自: https://www.javacodegeeks.com/2015/03/rest-api-evolution.html

rest