我的文章的读者可能熟悉采用 API First 方法开发微服务的想法。无数次，我意识到在开始任何开发之前描述预期的 URI 和底层对象模型的好处。 然而，在我 30 多年的技术探索历程中，我已经开始期待 的现实。换句话说，我完全预料到，在某些情况下，API First 是不可能实现的。 替代流程 在本文中，我想通过一个示例来说明如何让生产微服务的团队无需手动定义 openapi.json 文件就能成功地为其他人提供 OpenAPI 规范。 我还想走出自己的舒适区，不使用 Java、.NET 甚至 JavaScript 来做到这一点。 发现 FastAPI 在我的大多数文章的结尾，我经常提到我的个人使命宣言： “将时间集中在提供能够扩展知识产权价值的功能上。其他一切都可以利用框架、产品和服务。” – J. Vester 我在此使命宣言中的观点是，在努力实现更高层次的目标和目的时，我有责任充分利用自己的时间。基本上，如果我们的重点是销售更多小部件，那么我的时间应该花在寻找实现这一目标的方法上——避开现有框架、产品或服务已经解决的挑战。 我选择 Python 作为我的新微服务的编程语言。到目前为止，我为之前的文章编写的 Python 代码中有 99% 都是 (SODD) 或 ChatGPT 驱动答案的结果。显然，Python 超出了我的舒适区。 Stack Overflow 驱动开发 现在我已经确定了事情的现状，我想创建一个新的基于 Python 的 RESTful 微服务，该微服务符合我的个人使命宣言，同时对源语言有最少的经验。 就在那时，我发现了 。 FastAPI FastAPI 自 2018 年问世以来，一直是一个专注于使用 Python 类型提示提供 RESTful API 的框架。FastAPI 最棒的地方在于它能够自动生成 OpenAPI 3 规范，而从开发人员的角度来看，无需任何额外的努力。 文章 API 用例 对于这篇文章，我想到了一个文章 API 的想法，提供一个 RESTful API，允许消费者检索我最近发布的文章列表。 为了简单起见，我们假设给定的 包含以下属性： Article – 简单、唯一的标识符属性（数字） id – 文章标题（字符串） title – 文章的完整 URL（字符串） url – 文章发表的年份（数字） year 文章 API 将包含以下 URI： GET – 将检索文章列表 /articles GET – 将通过 id 属性检索单个文章 /articles/{article_id} POST – 添加新文章 /articles FastAPI 实际应用 在我的终端中，我创建了一个名为 fast-api-demo 的新 Python 项目，然后执行了以下命令： $ pip install --upgrade pip $ pip install fastapi $ pip install uvicorn 我创建了一个名为 的新 Python 文件并添加了一些导入，并建立了一个 变量： api.py app from fastapi import FastAPI, HTTPException from pydantic import BaseModel app = FastAPI() if __name__ == "__main__": import uvicorn uvicorn.run(app, host="localhost", port=8000) 接下来，我定义了一个 对象来匹配 Article API 用例： Article class Article(BaseModel): id: int title: str url: str year: int 建立模型后，我需要添加 URI......这实际上很容易： # Route to add a new article @app.post("/articles") def create_article(article: Article): articles.append(article) return article # Route to get all articles @app.get("/articles") def get_articles(): return articles # Route to get a specific article by ID @app.get("/articles/{article_id}") def get_article(article_id: int): for article in articles: if article.id == article_id: return article raise HTTPException(status_code=404, detail="Article not found") 为了避免涉及外部数据存储，我决定以编程方式添加一些我最近发布的文章： articles = [ Article(id=1, title="Distributed Cloud Architecture for Resilient Systems: Rethink Your Approach To Resilient Cloud Services", url="https://dzone.com/articles/distributed-cloud-architecture-for-resilient-syste", year=2023), Article(id=2, title="Using Unblocked to Fix a Service That Nobody Owns", url="https://dzone.com/articles/using-unblocked-to-fix-a-service-that-nobody-owns", year=2023), Article(id=3, title="Exploring the Horizon of Microservices With KubeMQ's New Control Center", url="https://dzone.com/articles/exploring-the-horizon-of-microservices-with-kubemq", year=2024), Article(id=4, title="Build a Digital Collectibles Portal Using Flow and Cadence (Part 1)", url="https://dzone.com/articles/build-a-digital-collectibles-portal-using-flow-and-1", year=2024), Article(id=5, title="Build a Flow Collectibles Portal Using Cadence (Part 2)", url="https://dzone.com/articles/build-a-flow-collectibles-portal-using-cadence-par-1", year=2024), Article(id=6, title="Eliminate Human-Based Actions With Automated Deployments: Improving Commit-to-Deploy Ratios Along the Way", url="https://dzone.com/articles/eliminate-human-based-actions-with-automated-deplo", year=2024), Article(id=7, title="Vector Tutorial: Conducting Similarity Search in Enterprise Data", url="https://dzone.com/articles/using-pgvector-to-locate-similarities-in-enterpris", year=2024), Article(id=8, title="DevSecOps: It's Time To Pay for Your Demand, Not Ingestion", url="https://dzone.com/articles/devsecops-its-time-to-pay-for-your-demand", year=2024), ] 无论你是否相信，这已经完成了 Article API 微服务的开发。 为了快速检查完整性，我在本地启动了我的 API 服务： $ python api.py INFO: Started server process [320774] INFO: Waiting for application startup. INFO: Application startup complete. INFO: Uvicorn running on http://localhost:8000 (Press CTRL+C to quit) 然后，在另一个终端窗口中，我发送了一个 curl 请求（并将其通过管道传输到 ）： json_pp $ curl localhost:8000/articles/1 | json_pp { "id": 1, "title": "Distributed Cloud Architecture for Resilient Systems: Rethink Your Approach To Resilient Cloud Services", "url": "https://dzone.com/articles/distributed-cloud-architecture-for-resilient-syste", "year": 2023 } 准备部署 与其在本地运行 Article API，我还想看看部署微服务有多容易。由于我之前从未在 部署过 Python 微服务，我觉得现在是尝试的好时机。 Heroku 在深入研究 Heroku 之前，我需要创建一个 文件来描述服务的依赖关系。为此，我安装并执行了 ： requirements.txt pipreqs $ pip install pipreqs $ pipreqs 这为我创建了一个 文件，其中包含以下信息： requirements.txt fastapi==0.110.1 pydantic==2.6.4 uvicorn==0.29.0 我还需要一个名为 的文件，它告诉 Heroku 如何使用 启动我的微服务。其内容如下： Procfile uvicorn web: uvicorn api:app --host=0.0.0.0 --port=${PORT} 让我们部署到 Heroku 对于那些刚接触 Python 的人（就像我一样），我使用了 文档作为有用的指南。 《使用 Python 开始使用 Heroku》 由于我已经安装了 Heroku CLI，所以我只需要从我的终端登录到 Heroku 生态系统： $ heroku login 我确保将所有更新都签入到 GitLab 上的存储库中。 接下来，可以通过以下命令使用 CLI 在 Heroku 中创建新应用程序： $ heroku create CLI 使用唯一的应用程序名称以及应用程序的 URL 和与应用程序关联的基于 git 的存储库进行响应： Creating app... done, powerful-bayou-23686 https://powerful-bayou-23686-2d5be7cf118b.herokuapp.com/ | https://git.heroku.com/powerful-bayou-23686.git 请注意 - 当您阅读本文时，我的应用程序将不再在线。 看看这个。当我发出 git remote 命令时，我可以看到远程服务器已自动添加到 Heroku 生态系统中： $ git remote heroku origin 要将 应用程序部署到 Heroku，我只需使用以下命令： fast-api-demo $ git push heroku main 一切设置完成后，我能够在 Heroku 仪表板中验证我的新基于 Python 的服务是否已启动并正在运行： 在服务运行时，可以通过发出以下 curl 命令从 Article API 中检索 ： id = 1 Article $ curl --location 'https://powerful-bayou-23686-2d5be7cf118b.herokuapp.com/articles/1' curl 命令返回 响应和以下 JSON 负载： 200 OK { "id": 1, "title": "Distributed Cloud Architecture for Resilient Systems: Rethink Your Approach To Resilient Cloud Services", "url": "https://dzone.com/articles/distributed-cloud-architecture-for-resilient-syste", "year": 2023 } 自动交付 OpenAPI 3 规范 利用 FastAPI 的内置 OpenAPI 功能，消费者可以通过导航到自动生成的 URI 来接收功能齐全的 v3 规范： /docs https://powerful-bayou-23686-2d5be7cf118b.herokuapp.com/docs 调用此 URL 将使用广泛采用的 Swagger UI 返回 Article API 微服务： 对于那些寻找 文件来生成客户端以使用 Article API 的人来说，可以使用 URI： openapi.json /openapi.json https://powerful-bayou-23686-2d5be7cf118b.herokuapp.com/openapi.json 就我的示例而言，基于 JSON 的 OpenAPI v3 规范如下所示： { "openapi": "3.1.0", "info": { "title": "FastAPI", "version": "0.1.0" }, "paths": { "/articles": { "get": { "summary": "Get Articles", "operationId": "get_articles_articles_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { } } } } } }, "post": { "summary": "Create Article", "operationId": "create_article_articles_post", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Article" } } }, "required": true }, "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } }, "/articles/{article_id}": { "get": { "summary": "Get Article", "operationId": "get_article_articles__article_id__get", "parameters": [ { "name": "article_id", "in": "path", "required": true, "schema": { "type": "integer", "title": "Article Id" } } ], "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": { } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } } } }, "components": { "schemas": { "Article": { "properties": { "id": { "type": "integer", "title": "Id" }, "title": { "type": "string", "title": "Title" }, "url": { "type": "string", "title": "Url" }, "year": { "type": "integer", "title": "Year" } }, "type": "object", "required": [ "id", "title", "url", "year" ], "title": "Article" }, "HTTPValidationError": { "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "type": "array", "title": "Detail" } }, "type": "object", "title": "HTTPValidationError" }, "ValidationError": { "properties": { "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "type": "array", "title": "Location" }, "msg": { "type": "string", "title": "Message" }, "type": { "type": "string", "title": "Error Type" } }, "type": "object", "required": [ "loc", "msg", "type" ], "title": "ValidationError" } } } } 因此，以下规范可用于通过 生成多种不同语言的客户端。 OpenAPI Generator 结论 在本文开头，我已经准备好与那些不愿意使用 API First 方法的人展开斗争。从这次练习中我学到的是，像 FastAPI 这样的产品可以帮助快速定义和生成有效的 RESTful 微服务，同时还自动包含完全可用的 OpenAPI v3 规范…… 事实证明，FastAPI 允许团队通过利用一个框架来产生供其他人依赖的标准化合同，从而专注于他们的目标和目的。因此，出现了另一条坚持我的个人使命宣言的道路。 在此过程中，我第一次使用 Heroku 部署基于 Python 的服务。事实证明，除了查看一些精心编写的文档外，我几乎不需要做任何努力。因此，Heroku 平台的另一个使命宣言奖励也需要提及。 如果你对本文的源代码感兴趣，可以在 上找到它。 GitLab 祝您度过愉快的一天！

該音頻是用故事的原始語言製作的！

太長; 讀書

Making security fun one episode at a time

FastAPI 让我快速获得了 OpenAPI 规范

太長; 讀書

John Vester

About Author

標籤

Languages

这篇文章刊登在...

FastAPI 让我快速获得了 OpenAPI 规范

太長; 讀書

John Vester

About Author

標籤

Languages

这篇文章刊登在...

相關故事