Deno管理API版本-灵析社区

API版本管理方案

通常来说，API的版本管理有2种方案：

1、URI

以v1或v2这种版本号为前缀：

请求：http://localhost:8080/v1/student 响应：{"name":"aa bb"} 请求：http://localhost:8080/v2/student 响应：{"name":{"firstName":"aa","lastName":"bb"}}

或者将版本以参数形式拼接到后面：

请求：http://localhost:8080/student/param?version=v1 响应：{"name":"aa bb"} 请求：http://localhost:8080/student/param?version=v2 响应：{"name":{"firstName":"aa","lastName":"bb"}}

优点：

1. 不破坏现有浏览器缓存机制，服务端、中间层也不需要额外考虑headers的缓存控制。
2. GET请求可以直接在浏览器执行。如果您有非技术消费者，那么基于URI的版本将更容易使用。

缺点：

1. URI污染。
2. API文档。如何让文档生成理解两个不同的url是同一服务的版本？

2、自定义Header

例：

请求：http://localhost:8080/student/header header：X-API-VERSION = 1 请求：http://localhost:8080/student/header header：X-API-VERSION = 2

优点：

1. 如果是已经上线的服务，不会影响现有的客户端（默认没有版本）。
2. 没有URI污染。

缺点：

1. 滥用请求头。请求头并不是为版本控制而设计的。
2. 缓存。不能仅仅基于URL缓存，需要考虑特定的请求头。
3. 即使是GET请求，也不能在浏览器直接执行。

API版本控制原则

1. 一旦发布，API应被视为契约，如果没有新版本，则不能被替换。
2. 服务端上线后，客户端新版本才能上线。
3. 必须所有API使用者迁移后，旧版本的API才能废除。
4. API的输入参数或输出的数据结构如果有变化，或者JSON数据中有调用者使用的字段修改、删除，即视为破坏性变更，需要增加版本。

开发实践

通常来说，URI的方式更符合我们的直觉。

Node.js

以nestjs工程为例：