最近，一个团队与我接触，需要帮助测试其快速API的破坏变化。 Fastify使得很容易快速运输许多新功能，但是破坏的变化是通过代码评论来实现的。他们没有发现更改正在破裂，直到消费者给他们发送电子邮件不好。伸出援手的开发人员看到了我在the Optic project上的工作，并寻求帮助。
这篇文章是关于我如何帮助他们测试破坏CI的变化的。它的写作就像一个教程，所以您也可以关注。
API Lockfiles
API是合同。当您发布新的端点时，您将向消费者做出新的承诺。当您更改API的工作方式时，它可能会破坏这一承诺。困难是知道您已经做出了什么承诺，并弄清楚您的代码是否会破坏它们。借助后端代码库中的所有抽象，更改一行代码可以轻松更改十几个API端点，而无需任何人意识到它。
我们需要的是用于我们的API行为的锁紧file。那将使很容易：
- 评论API差异（行为变化）同时我们进行代码审查
- 可以测试打破CI 中的API变化
- 重构我们的后端安全 - 很多代码可能会更改，但是Lockfile应该保持相同的状态
Fastify从代码中对generating OpenAPI有很大的支持。像许多其他流行的后端框架一样，使用JSON模式进行验证和导出OpenAPI具有一流的支持。我们可以将此生成的OpenAPI规范用作API的Lockfile。
生成我们的API Lockfile（OpenAPI）
首先，让我们从fastify和文件系统中获取当前的OpenAPI规范。如果您尚未添加https://github.com/fastify/fastify-swagger插件，请首先执行此操作。然后使用我称为generate-spec.ts的简单脚本将您的OpenAPI规范写入文件系统。
import fs from "node:fs/promises";
import { setupApp } from "./app";
const FILE_PATH = "./openapi.json";
(async () => {
const app = await setupApp();
await app.ready();
await fs.writeFile(FILE_PATH, JSON.stringify(app.swagger(), null, 2));
})();
我将其添加到包json的scripts部分，因此很容易致电。
"scripts": {
"build": "yarn run tsc --build --verbose",
"generate-spec": "yarn ts-node ./src/generate-spec"
},
现在，最近的OpenAPI在openapi.json上，每当我运行时都会重新生成：
yarn run generate-spec
用git跟踪我们的API Lockfile
Lockfiles是使用Git跟踪的少数生成的工件之一。将生成的OpenAPI规格添加到我们的GIT存储库中，可以使用Git标签，提交SHA和分支名称在各个时间点上的API来查找API的工作方式。
建议：如果要确保每个分支上的OpenAPI准确，请考虑添加以下CI任务：
yarn run generate-spec
git diff --cached --exit-code --quiet # will exit 1 if the checked-in spec is stale
打破变化的测试
现在，我们可以通过GIT查找API的行为，我们可以开始测试以破坏API版本之间的更改。我们将使用Optic（an open source tool I created）来做到这一点。如果您正在寻找其他选项，我建议https://github.com/OpenAPITools/openapi-diff或https://github.com/Tufin/oasdiff。
首先安装光学CLI：
yarn global add @useoptic/optic
然后使用diff命令测试要在特征分支和main分支之间打破更改。这将在代码审核期间标记任何破坏更改。
optic diff openapi.json --base main --check
如果检测到破裂的变化，则此命令将退出1，因此可以像CI中的测试一样使用。
将所有这些融合在一起
- 生成的OpenAPI规格可以用作API Lockfiles。许多最受欢迎的API框架一直在增加生成OpenAPI的一流支持。
-
fastify+fastify-swagger使您易于从您的代码生成准确的OpenAPI规格 -
optic使其测试了git分支和标签之间的API更改
现在，您可以充满信心地将更改转换为您的快速API，因为您不会打破消费者。