如何使用 Apicurio Registry 统一管理 API 和 Schema

想象一下，你正在构建一个微服务架构，数据通过 Kafka 或 REST 请求流动。你已经积累了十几个 Avro Schema、多个 OpenAPI 规范和一些 Protobuf 文件。在某个时刻，一个团队更新了消息 Schema，而另一个团队的系统“崩溃”了，因为他们没有及时了解到这些变化。听起来很熟悉？当然，你可以把 Schema 存储在 Git 中，然后在项目之间复制，但这很快就会变成一团乱麻。

我在寻找标准 API 契约管理解决方案的替代品时发现了 Apicurio Registry。这是一个 CNCF 沙箱项目，解决了一个特定的痛点：它为你的 API 和 Schema 提供了一个集中式存储库。

有了 Git 还需要它做什么

关键特性不仅仅是把文件“放在架子上”——而在于注册表如何处理这些数据。Apicurio Registry 可以实时验证 Schema 的兼容性。当生产者服务尝试发布新版本的 Schema 时，如果新版本破坏了向后兼容性，注册表可以阻止更新。你可以在错误数据进入消息队列之前就捕获到错误。

此外，该项目还为你处理版本管理。每个 Schema 都有清晰的生命周期，消费者始终知道应该使用哪个版本。

内部原理及工作方式

Apicurio 的开发者选择 Quarkus 作为基础，使这个工具快速且轻量。但最有趣的部分是存储选项的灵活性。以前，每个数据库都有一个独立的二进制文件，在 3.0 版本中他们切换到了单一制品。现在你只需要设置 APICURIO_STORAGE_KIND 环境变量，就可以从以下选项中选择：

• SQL — 经典选择。默认使用 H2（方便测试），但在生产环境中最好使用 PostgreSQL 或 SQL Server。
• KafkaSQL — 直接在 Kafka 主题中存储数据。如果你不想在基础设施中添加单独的关系数据库，而且你已经有 Kafka 集群，这会很方便。
• GitOps — 面向想要声明式管理的人的选择。

对于使用 Kubernetes 的人来说，有一个现成的 operator。更新通过 OLM 渠道推送，因此在集群中保持最新版本不会太痛苦。

如何尝试使用

最快的方式是运行现成的 Docker 镜像。但重要的是要记住：UI 被移到了单独的容器中。

运行服务器本身：

docker run -it -p 8080:8080 apicurio/apicurio-registry:latest-snapshot

以及界面：

docker run -it -p 8888:8080 apicurio/apicurio-registry-ui:latest-snapshot

之后，管理仪表板将在 localhost:8888 可用，注册表自身 API 的文档将在 localhost:8080/apis。

如果你想部署一个带有 PostgreSQL 的完整设置来进行适当的测试，最简单的方法是编写一个 Docker Compose 文件：

services:
  postgres:
    image: postgres
    environment:
      POSTGRES_USER: apicurio-registry
      POSTGRES_PASSWORD: password
  app:
    image: apicurio/apicurio-registry:3.0.0
    ports:
      - 8080:8080
    environment:
      APICURIO_STORAGE_KIND: 'sql'
      APICURIO_STORAGE_SQL_KIND: 'postgresql'
      APICURIO_DATASOURCE_URL: 'jdbc:postgresql://postgres/apicurio-registry'
      APICURIO_DATASOURCE_USERNAME: apicurio-registry
      APICURIO_DATASOURCE_PASSWORD: password

面向急躁者的构建层级

如果你决定深入源代码并自己构建项目，该项目提供了三种构建“层级”。这节省了大量时间。

使用 -Dlocal 标志，你只构建服务器核心和 Java SDK，不包含额外的样式检查和 Javadoc 生成。构建大约需要 3 分钟。如果你需要包含 Go SDK 和 operator 的完整包，请使用 -Dfull。这是项目为贡献者时间着想的绝佳范例。

安全问题

开箱即用，注册表不需要授权，这对于本地开发来说没问题，但在企业网络中就很危险了。该工具支持 OpenID Connect (OIDC) 集成。你可以通过传递几个环境变量来连接 Keycloak 或任何其他兼容服务器：QUARKUS_OIDC_AUTH_SERVER_URL 和 QUARKUS_OIDC_CLIENT_ID。该配置涵盖 REST API 和用户界面。

总结：谁应该关注

Apicurio Registry 对于以下团队绝对有用：

1. 积极使用 Kafka 并为维护 Avro/Protobuf Schema 而苦恼。
2. 想要自动化 API 兼容性检查（OpenAPI/AsyncAPI）。
3. 在寻找 Confluent Schema Registry 的轻量级替代方案，且不想与单一生态系统紧密耦合。

这个项目看起来很有活力，文档（包括内置的 API 文档）也很详细，切换到 Quarkus 使其运行起来很愉快。如果你的微服务在契约方面处于“自由放任”的状态——试着花一个小时启动这个注册表。更有可能的是，它会解决你大部分的 Schema 版本管理问题。