我的文章的读者可能熟悉采用 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 祝您度过愉快的一天！

2022 - HackerNoon Contributor of the Year - Cloud Computing

2022 - HackerNoon Contributor of the Year - Design

2022 - HackerNoon Contributor of the Year - Heroku

2022 - HackerNoon Contributor of the Year - Javascript

2022 - HackerNoon Contributor of the Year - Salesforce

2022 - Hackernoons Tech Storyteller of the Year

I ♥ writing code. Find me on GitLab.

Nominated for 2022 - HackerNoon Contributor of the Year - Javascript

Nominated for 2022 - Hackernoons Tech Storyteller of the Year

Nominated for 2022 - HackerNoon Contributor of the Year - Cloud Computing

Nominated for 2022 - HackerNoon Contributor of the Year - Heroku

Nominated for 2022 - HackerNoon Contributor of the Year - Design

Nominated for 2022 - HackerNoon Contributor of the Year - Salesforce

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

太長; 讀書

Make resilience your competitive advantage

FastAPI 让我快速获得了 OpenAPI 规范

FastAPI 让我快速获得了 OpenAPI 规范

About Author

註釋

標籤

这篇文章刊登在

Related Stories

成功云迁移的完整指南：策略和最佳实践

释放人工智能的力量。前沿技术的系统评价：摘要与介绍

比特币 UTXO 模型，为独特的生态系统提供动力

创建以用户为中心的加密产品：客户反馈的重要性

成功云迁移的完整指南：策略和最佳实践

释放人工智能的力量。前沿技术的系统评价：摘要与介绍

比特币 UTXO 模型，为独特的生态系统提供动力

创建以用户为中心的加密产品：客户反馈的重要性

Light-Mode

Classic

Newspaper

Dark-Mode

Neon Noir

Minty

HN StartUps