backstage~openapi的接入与protobuf的对比
<h1 id="swagger外部文档">swagger外部文档</h1><pre><code>apiVersion: backstage.io/v1alpha1
kind: API
metadata:
name: petstore
description: The Petstore API
spec:
type: openapi
lifecycle: production
owner: petstore@example.com
definition:
$text: https://petstore.swagger.io/v2/swagger.json
</code></pre>
<h1 id="嵌入openapi文档">嵌入openapi文档</h1>
<pre><code>apiVersion: backstage.io/v1alpha1
kind: API
metadata:
name: artist-api
description: Retrieve artist details
spec:
type: openapi
lifecycle: production
owner: artist-relations-team
system: artist-engagement-portal
definition: |
openapi: "3.0.0"
info:
version: 1.0.0
title: Artist API
license:
name: MIT
servers:
- url: http://artist.spotify.net/v1
paths:
/artists:
get:
summary: List all artists
...
</code></pre>
<h1 id="占位符text解释当前仓库相对路径">占位符$text解释当前仓库相对路径</h1>
<pre><code>apiVersion: backstage.io/v1alpha1
kind: API
metadata:
name: pet-store-api
spec:
type: openapi
lifecycle: experimental
owner: guests
system: user-system
# 使用 $text 占位符和相对路径引用同一仓库内的 OpenAPI 文件
# 路径相对于 catalog-info.yaml 文件的位置
definition:
$text: ./src/main/resources/petstore.yaml
</code></pre>
<h1 id="openapi和protobuf的对比">openapi和protobuf的对比</h1>
<p>简单来说：<strong>OpenAPI 是 API 的描述规范和文档标准，而 Protobuf 是一种高效的数据序列化协议和接口定义语言。</strong> 它们常常结合使用，但核心目标不同。</p>
<p>以下是详细的对比：</p>
<table>
<thead>
<tr>
<th style="text-align: left">维度</th>
<th style="text-align: left"><strong>OpenAPI (Swagger)</strong></th>
<th style="text-align: left"><strong>Protobuf (Protocol Buffers)</strong></th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left"><strong>核心定位</strong></td>
<td style="text-align: left"><strong>API 描述规范</strong> 和 <strong>文档标准</strong>。专注于定义 <strong>RESTful API</strong> 的契约，包括路径、参数、请求/响应格式、认证等。</td>
<td style="text-align: left"><strong>接口定义语言 (IDL)</strong> 和 <strong>序列化协议</strong>。专注于定义<strong>数据结构</strong>和<strong>服务接口</strong>，并生成高效、跨平台的序列化代码。</td>
</tr>
<tr>
<td style="text-align: left"><strong>主要产出</strong></td>
<td style="text-align: left">机器可读的 API 规范文件 (YAML/JSON) 和<strong>交互式 API 文档</strong>。</td>
<td style="text-align: left">平台相关的<strong>代码</strong>（如 <code>.pb.go</code>, <code>.pb.cs</code> 文件）和序列化后的<strong>二进制数据流</strong>。</td>
</tr>
<tr>
<td style="text-align: left"><strong>数据格式</strong></td>
<td style="text-align: left">通常使用人类可读的 <strong>JSON</strong> 或 <strong>YAML</strong> 编写规范，API 通信也常用 JSON/XML。</td>
<td style="text-align: left">使用自定义的 <strong>.proto</strong> 文本格式定义接口，但传输和存储时使用紧凑的<strong>二进制格式</strong>。</td>
</tr>
<tr>
<td style="text-align: left"><strong>主要场景</strong></td>
<td style="text-align: left"><strong>对外暴露的 HTTP API</strong>，特别是面向 Web、移动端或第三方开发者的 RESTful 服务。强调可读性、易用性和标准化。</td>
<td style="text-align: left"><strong>内部服务间的 RPC 通信</strong>（如 gRPC）、需要高性能和强类型约束的后端微服务、数据存储。</td>
</tr>
<tr>
<td style="text-align: left"><strong>性能</strong></td>
<td style="text-align: left">规范文件本身是文本，较大。API 通信使用 JSON/XML，<strong>序列化/反序列化开销较大，数据体积也较大</strong>。</td>
<td style="text-align: left">二进制编码，<strong>序列化/反序列化极快，生成的数据体积非常小</strong>，网络传输效率高。</td>
</tr>
<tr>
<td style="text-align: left"><strong>工具生态</strong></td>
<td style="text-align: left">围绕<strong>文档生成</strong>、<strong>客户端 SDK 生成</strong>、<strong>Mock 服务器</strong>、<strong>代码生成</strong>、<strong>测试</strong>等。是一个强大的 API 开发生命周期工具链。</td>
<td style="text-align: left">围绕<strong>代码生成</strong>和<strong>RPC 框架</strong>。最经典的搭配是 <strong>Protobuf + gRPC</strong>，提供完整的 RPC 解决方案。</td>
</tr>
<tr>
<td style="text-align: left"><strong>开发体验</strong></td>
<td style="text-align: left"><strong>面向开发者友好</strong>，前端、后端、测试人员可以通过一个文档页面清晰地了解和使用 API。</td>
<td style="text-align: left"><strong>面向机器和系统友好</strong>，通过强类型接口和自动生成的代码，保障了前后端的类型安全，但需要一定的学习成本。</td>
</tr>
</tbody>
</table>
<hr>
<h3 id="核心关系与如何选择">核心关系与如何选择</h3>
<ol>
<li>
<p><strong>不是“二选一”，而是“如何搭配”</strong>：</p>
<ul>
<li>你可以用 <strong>Protobuf 定义内部微服务接口</strong>（通过 gRPC），然后用 <strong>OpenAPI 定义对外的 RESTful API 网关</strong>。网关负责将外部 REST 调用转换为内部的 gRPC 调用。</li>
<li>也有工具（如 <strong>grpc-gateway</strong>）能从一个 <strong>.proto</strong> 文件<strong>同时生成 gRPC 服务代码和对应的 OpenAPI 规范</strong>，实现“一套定义，两种暴露”。</li>
</ul>
</li>
<li>
<p><strong>选择建议</strong>：</p>
<ul>
<li><strong>选择 OpenAPI 当</strong>：
<ul>
<li>你的 API 主要给<strong>浏览器、移动 App 或第三方开发者</strong>调用。</li>
<li><strong>API 文档</strong>和<strong>易用性</strong>是首要考虑。</li>
<li>你需要与现有的、基于 HTTP/JSON 的生态系统（如大多数云服务、前端框架）集成。</li>
</ul>
</li>
<li><strong>选择 Protobuf (gRPC) 当</strong>：
<ul>
<li>你的系统是<strong>内部微服务架构</strong>，服务间需要高性能、低延迟的通信。</li>
<li><strong>强类型安全</strong>和<strong>接口契约</strong>对团队协作至关重要。</li>
<li>你需要支持<strong>流式通信</strong>（如 gRPC 的流）。</li>
<li>网络带宽和性能是瓶颈。</li>
</ul>
</li>
</ul>
</li>
</ol>
<h3 id="总结">总结</h3>
<table>
<thead>
<tr>
<th style="text-align: left">特性</th>
<th style="text-align: left">OpenAPI</th>
<th style="text-align: left">Protobuf</th>
</tr>
</thead>
<tbody>
<tr>
<td style="text-align: left"><strong>强项</strong></td>
<td style="text-align: left"><strong>标准化、文档化、生态工具链、对人类友好</strong></td>
<td style="text-align: left"><strong>性能、体积、类型安全、对机器友好</strong></td>
</tr>
<tr>
<td style="text-align: left"><strong>典型搭配</strong></td>
<td style="text-align: left">RESTful API, HTTP/JSON, 文档站点</td>
<td style="text-align: left">gRPC, 二进制流, 微服务间通信</td>
</tr>
<tr>
<td style="text-align: left"><strong>类比</strong></td>
<td style="text-align: left"><strong>建筑的“设计蓝图”和“使用说明书”</strong>，所有人都能看懂。</td>
<td style="text-align: left"><strong>建筑预制件的“标准化模具”和“组装接口”</strong>，用于高效、精确地搭建。</td>
</tr>
</tbody>
</table>
<p>在现代云原生架构中，两者通常协同工作：用 Protobuf/gRPC 构建高效、稳定的后端服务网格，然后用基于 OpenAPI 的 API 网关作为统一、安全的对外入口。</p>
</div>
<div id="MySignature" role="contentinfo">
<p></p>
<div class="navgood">
<p>作者：仓储大叔，张占岭，<br>
荣誉：微软MVP<br>QQ：853066980</p>
<p><strong>支付宝扫一扫，为大叔打赏!</strong>
<br><img src="https://images.cnblogs.com/cnblogs_com/lori/237884/o_IMG_7144.JPG"></p>
</div><br><br>
来源：https://www.cnblogs.com/lori/p/19884360
頁:
[1]