创建自定义 Apollo 路由器核心二进制文件

了解如何编译自定义二进制文件Apollo 路由核心源代码，它是创建路由的自定义原生 Rust 插件所必须的。

⚠️Apollo 不建议为 Apollo 路由核心或 GraphOS 路由创建原生插件，以下是一些原因

• 原生插件需要熟悉 Rust 编程。
• 原生插件需要从源代码编译自定义的路由二进制文件，这可能会在您的路由中引入难以诊断和支持的预期行为。

因此，对于大多数路由定制，Apollo 建议创建一个Rhai 脚本或者一个外部协处理器。这两项定制都由 Apollo 支持，并提供强大的关注点分离和错误隔离。

如果您必须创建原生插件，请在 GitHub 上提交一个问题，Apollo 可以调查将自定义功能添加到标准路由二进制文件的可行性。

先决条件

要编译路由，您需要安装以下软件：

• Rust 1.76.0 或更高版本
• Node.js 16.9.1 或更高版本
• CMake 3.5.1 或更高版本

安装上述软件后，还需要安装cargo-xtask 和 cargo-scaffold 软件包：

1
cargo install cargo-xtask
2
cargo install cargo-scaffold

1. 创建一个新的项目

1. 使用 cargo-scaffold 命令创建一个用于您自定义 router 的项目：

   Bash

   1
   cargo-scaffold scaffold https://github.com/apollographql/router.git -r apollo-router-scaffold/templates/base -t main

   复制

2. 执行 cargo-scaffold 命令后，系统会提示你进行一些配置设置。出于本教程的目的，将您的项目名称设置为 starstuff。

3. 您的项目创建后，切换到 starstuff 目录：

   Bash

   1
   cd starstuff

   复制

生成的项目的布局如下

1
starstuff
2
├── Cargo.toml       # Dependencies are declared here
3
├── README.md
4
├── router.yaml      # Router yaml config
5
├── src
6
│   ├── main.rs      # Entry point
7
│   └── plugins      # Custom plugins are located here
8
│       └── mod.rs
9
└── xtask            # Build support files
10
    ├── Cargo.toml
11
    └── src
12
        └── main.rs

router 使用自动发现机制来插件，因此您添加的任何插件都可以在运行时自动使用 router。

2. 编译 router

使用以下命令为 router 创建一个调试版本：

1
cargo build

生成的调试二进制文件位于 target/debug/router。

要为生产环境创建一个发布版本，请使用以下命令代替

1
cargo build --release

生成的发布二进制文件现在位于 target/release/router。

3. 运行编译好的二进制文件

现在，您可以用一个示例 supergraph 模式 测试编译好的 router。

1. 使用以下命令下载示例模式：

   Bash

   1
   curl -sSL https://supergraph.demo.starstuff.dev/ > supergraph-schema.graphql

   复制

2. 运行 router 并按照如下方式提供示例模式：

   Bash

   1
   cargo run -- --hot-reload --config router.yaml --supergraph supergraph-schema.graphql

   复制

   在开发期间，使用 cargo run 运行 router 会很有帮助。

如果您使用的是 托管联邦，请设置环境变量 APOLLO_KEY 和 APOLLO_GRAPH_REF，而不是将 supergraph 模式指定为文件。有关详细信息，请参阅 本节。

4. 创建一个插件

1. 在您的项目目录中，使用以下命令创建一个新插件

   Bash

   1
   cargo router plugin create hello_world

   复制

2. 命令提示您选择一个起始模板

   Bash

   1
   Select a plugin template:
   2
   > "basic"
   3
   "auth"
   4
   "tracing"

   复制

   可用的模板有

   • basic - 一个基本插件
   • auth - 一个用于外部调用的认证插件
   • tracing - 一个添加自定义指标span和日志消息的遥测插件

   对于本教程的目的，请选择 basic.

3. 将创建的插件配置选项添加到您的 router.yaml 文件中：

   YAML

   router.yaml

   1
   plugins:
   2
     starstuff.hello_world:
   3
       message: "starting my plugin"

   复制

4. 再次运行 router：

   Bash

   1
   cargo run -- --hot-reload --config router.yaml --supergraph supergraph-schema.graphql

   复制

   这次，您应该看到以下类似日志行

   Bash

   1
   2022-05-21T09:16:33.160288Z  INFO router::plugins::hello_world: starting my plugin

   复制

做得好！您现在有一个具有相关插件的自定义 router二进制文件。接下来，您可以根据需要扩展插件的功能或添加更多插件。

移除插件

要从您的 router 项目中移除之前添加的插件，请使用以下命令：

1
cargo router plugin remove hello_world

注意，根据插件的结构，该命令可能无法删除其所有相关文件。

内存分配器

在 Linux 上，apollo-router crate 将 jemalloc 设置为 Rust 的全局内存分配器，以减少内存fragmentation。未来的版本可能将在更多平台上这样做，或者切换到另一个分配器。默认启用此功能，并由 global-allocator Cargo 功能标志控制。如果您想选择不同的分配器，请在您的 Cargo.toml 中禁用它：

1
[dependencies]
2
apollo-router = {version = "[…]", default-features = false}

如果您创建了一个库crate，也请指定 default-features = false 以便最终的可执行crate具有选择权。"(Cargo默认功能仅在 所有 依赖项指定 default-features = false 时才禁用。)"

Docker

您可以使用提供的 Dockerfile 来构建发布容器。

确保您的 router 配置为监听 0.0.0.0 以便您可以从容器外部 查询 它：

1
supergraph:
2
   listen: 0.0.0.0:4000

使用您的 APOLLO_KEY 和 APOLLO_GRAPH_REF 环境变量来以 managed federation 运行 router。

1
docker build -t my_custom_router .
2
   docker run -e APOLLO_KEY="your apollo key" -e APOLLO_GRAPH_REF="your apollo graph ref" my_custom_router

否则，在 Dockerfile 中添加一个 COPY 步骤，并编辑 entrypoint：

1
# Copy configuration for docker image
2
COPY router.yaml /dist/config.yaml
3
# Copy supergraph for docker image
4
COPY my_supergraph.graphql /dist/supergraph.graphql
5

6
# [...] and change the entrypoint
7

8
# Default executable is the router
9
ENTRYPOINT ["/dist/router", "-s", "/dist/supergraph.graphql"]

相关主题

• 优化自定义 Router 构建