你如何处理 Node/Express 应用程序中的 api 版本 [英] How do you handle api version in a Node/Express app

问题描述

我是 Node.js 的新手，我面临以下问题.

I am pretty new to Node.js and I am facing the following issue.

我的中间件从链接 api/v1/login 和一堆端点开始.然后 api/v1.1 引入了另外 2 个端点.api/v1.2 现在是最后一个，并获得了一些新端点.

My middleware started with the link api/v1/login and a bunch of endpoints. Then api/v1.1 introduced 2 more endpoints. api/v1.2 is now the last and got some new endpoints.

我应该如何以有效的方式处理这个 api 版本控制?您如何使一个版本的端点也可用于下一个版本?

How shall I handle this api versioning in an efficient way? How do you make endpoints from a version available to the next versions as well?

推荐答案

首先，如果你正在构建 REST API 并且你刚刚开始，你可能需要考虑使用 Restify 而不是 Express.虽然 Express 当然可以用于此目的，但 Restify 的设计满足了 REST API 服务器的所有要求:标准化异常、API 版本控制等.

First of all, if you are building a REST API and you have just started, you may want to consider using Restify instead of Express. While Express can certainly be used for this purpose, Restify has been designed with all the requirements for a REST API server: standardized exceptions, API versioning, etc.

因此，我相信您的第一个问题是设计缺陷.仅当新 API 与以前的版本不向后兼容时，即当主要版本增加(例如从 v1 到 v2)时，您才应该创建单独的端点.这种情况应该尽可能少发生！
如果您只是添加新功能或进行其他不会破坏现有代码的调整，则不应创建不同的端点.因此，您不应该为 v1.1、v1.2 等创建端点，前提是所有适用于 v1.0 的代码也适用于 v1.1(如果不是这种情况，那么您正在引入更改不向后兼容，因此您应该考虑将版本更改为 v2).
请注意，每次您引入向后不兼容的更改时，您的所有用户都需要更新他们的代码，并且您必须在足够长的时间内支持旧 API，以让您的所有用户都更新.对于您(您需要维护旧的代码库)和您的用户(他们需要更新他们的代码)来说，这是一个昂贵的过程，因此应该尽可能少发生.此外，对于每个版本，您都需要编写文档、创建示例等.
(底线:花费大量时间设计您的 API 服务器，因此它可能会持续下去而不会发生向后不兼容的更改尽可能长时间)

Thus said, I believe your first problem is a design flaw. You should create separate endpoints only when the new APIs are not backward-compatible with the previous version, i.e. when the major version is increased (for example from v1 to v2). This should happen as infrequently as possible!
If you are only adding new features or making other tweaks that do not break existing code, then you should not create a different endpoint. So, you should not create endpoints for v1.1, v1.2, etc, providing that all the code that works with v1.0 will also work with v1.1 (if that's not the case, then you're introducing changes that are not backward-compatible, and thus you should consider changing the version to v2).
Note that every time that you introduce backward-incompatible changes all your users will need to update their code, and you will have to support the old APIs for a period of time sufficient to let all your users update. This is an expensive process, for you (you need to maintain old codebases) and your users as well (they need to update their code), and thus should happen as infrequently as possible. Additionally, for each version you need to write documentation, create examples, etc.
(Bottom line: spend a lot of time designing your API server so it will likely last without backward-incompatible changes for as long as possible)

为了回答您的问题，一种方法是为每个 API 集(每个版本)创建子文件夹，然后相应地设置路由器.例如，您的项目将如下所示:

To answer your question, then, a way to do that could be creating subfolders for each API set (each version), and then set the router accordingly. For example, your project will look like:

/
-- app.js
-- routes/
-- -- v1/
-- -- -- auth.js
-- -- -- list.js
-- -- v2/
-- -- -- auth.js
-- -- -- list.js

这应该不是问题:因为 v2 不向后兼容 v1，所以这两个文件可能有很大不同.
然后，在 Express 上相应地使用路由器.例如:

That should not be a problem: since v2 is not backward-compatible with v1, chances are that the two files are quite a lot different.
Then, on Express just use the router accordingly. For example:

app.get('/v1/list/:id', v1.list)
app.all('/v1/auth', v1.auth)

app.get('/v2/list/:id', v2.list)
app.all('/v2/auth', v2.auth)

不过，还有其他选择.例如，更优雅(虽然稍微高级)的解决方案可以是:http://j-query.blogspot.ca/2013/01/versioned-apis-with-express.html

There are other options, however. For example, a more elegant (though slightly advanced) solution can be: http://j-query.blogspot.ca/2013/01/versioned-apis-with-express.html

虽然，根据 semver，如果您计划实现 v1 和 v2 之间的许多实质性差异(重用代码的可能性很小)，则每个向后不兼容的更改都应该看到 API 主要版本的增加，那么这种方法不适合您.

While, as per semver, every backward-incompatible change should see an increase in the major version of the APIs, if you plan to implement many and substantial differences between v1 and v2 (with very little possibility to re-use code), then this approach is not for you.

在最后一种情况下，您可能需要为 v1 和 v2 创建两个单独的 Node.js 应用程序，然后使用 nginx 配置正确的路由.不会在应用级别进行版本控制(每个应用都会响应/auth"、/list/:id"而不是/v1/auth"、/v1/list:id"等)，而是 nginx会将带有前缀/v1/"的请求转发到一个工作服务器，将带有前缀/v2/"的请求转发到另一台.

In this last case, you may want to create two separate Node.js apps for v1 and v2, and then configure the proper routing using nginx. Versioning will not be done at the app level (each app will respond to '/auth', '/list/:id' and NOT '/v1/auth', '/v1/list:id', etc), but nginx will forward requests with prefix '/v1/' to one worker server, and those with prefix '/v2/' to the other.

这篇关于你如何处理 Node/Express 应用程序中的 api 版本的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！