使用 Rust 接入 Azure Service Bus：agentic-awesome-skills 官方技能中的队列、主题与可靠消息收发实战指南

• AI 技能
• AI 插件
• 人工智能

导读

本文以 agentic-awesome-skills 仓库中收录的官方技能文档 azure-servicebus-rust 为主体，系统讲解如何用 Rust 通过官方azure_messaging_servicebuscrate 接入 Azure Service Bus，实现基于队列的点对点消息与基于主题/订阅的发布-订阅消息。读完本文，你将掌握从依赖安装、Entra ID 认证、发送/接收消息到消息结算（complete/abandon）与 RBAC 授权的完整落地路径，并理解该 SDK 目前处于早期开发阶段这一关键前提。

技能定位与使用场景

该技能对应微软官方 Skills 仓库中azure-sdk-rust插件下的同名技能，source_type 标注为official，风险等级为critical，日期为 2026-07-01。其触发词包括"service bus rust"、"ServiceBusClient rust"、"send message servicebus rust"、"receive message servicebus rust"、"queue rust messaging"、"topic subscription rust"。

适用场景非常明确：

• 应用需要从 Rust 中通过 Azure Service Bus 发送或接收消息；
• 需要基于队列的点对点消息，配合竞争消费者（competing consumers）模型；
• 需要基于主题和订阅的发布-订阅消息，实现一对多扇出；
• 需要具备完成语义（completion semantics）的可靠消息投递。

⚠️重要警告：该 crate 正处于早期开发阶段，不应在生产环境中使用，API 可能在没有通知的情况下发生变化。任何引入该依赖的工程都需要接受这一风险，并通过固定版本号来约束升级。

⚠️包来源约束：只能使用由 crates.io 上 azure-sdk 用户发布的官方azure_messaging_servicebuscrate，不要使用非官方或社区 crate。官方 crate 均使用下划线命名，且没有任何官方 crate 的版本是 0.21.0——这是甄别山寨包的重要信号。

安装与依赖管理

技能文档明确要求通过cargo add管理依赖，永远不要直接手改Cargo.toml：

cargo add azure_messaging_servicebus azure_identity tokio

依赖取舍要点：

• 如果代码中直接使用了azure_core的类型（例如azure_core::http::Url、azure_core::http::RequestContent、azure_core::error::ErrorKind），需要额外cargo add azure_core；
• 如果只使用azure_messaging_servicebus重导出的类型，则azure_core的直接依赖是可选的；
• azure_identity提供全部认证凭据类型，tokio为异步运行时，二者均为必选项。

环境变量与命名空间

使用 Entra ID（原 Azure AD）认证时，唯一的必需环境变量是命名空间：

SERVICEBUS_NAMESPACE=<namespace>.servicebus.windows.net # Required — fully qualified namespace

<namespace>.servicebus.windows.net是全限定命名空间主机名，Service Bus 客户端通过该主机名定位到命名空间下的全部消息组件。

若使用服务主体（Service Principal）认证，可参考同仓库 azure-identity-rust 技能补充以下环境变量：

# Service Principal（生产/CI 环境） AZURE_TENANT_ID=<your-tenant-id> AZURE_CLIENT_ID=<your-client-id> AZURE_CLIENT_SECRET=<your-client-secret> # 用户分配托管身份（可选） AZURE_CLIENT_ID=<managed-identity-client-id>

关键概念

理解这四个实体的关系是使用本技能的前提：Queue 适合任务分发与负载均衡；Topic + Subscription 适合事件广播与扇出（fan-out）场景——当多个消费者需要同一份消息时，应选择主题而非队列。

认证：从本地开发到生产

该 SDK 采用与 azure-sdk-for-rust 一致的凭据模型。技能文档强调：Rust 没有单一的DefaultAzureCredential类型，因此本地开发使用DeveloperToolsCredential，生产环境使用ManagedIdentityCredential。

use azure_identity::DeveloperToolsCredential; use azure_messaging_servicebus::ServiceBusClient; #[tokio::main] async fn main() -> Result<(), Box<dyn std::error::Error>> { // Local dev: DeveloperToolsCredential. Production: use ManagedIdentityCredential. let credential = DeveloperToolsCredential::new(None)?; let client = ServiceBusClient::builder() .open("your_namespace.servicebus.windows.net", credential.clone()) .await?; Ok(()) }

凭据链与凭据类型

据同仓库 azure-identity-rust 技能文档，DeveloperToolsCredential会按固定顺序尝试开发者工具：

完整的凭据类型覆盖了本地、Azure 托管资源与 CI 等全部场景：

生产环境使用托管身份的写法：

use azure_identity::ManagedIdentityCredential; // 系统分配托管身份 let credential = ManagedIdentityCredential::new(None)?; // 用户分配托管身份 let options = ManagedIdentityCredentialOptions { client_id: Some("<user-assigned-mi-client-id>".into()), ..Default::default() }; let credential = ManagedIdentityCredential::new(Some(options))?;

若采用服务主体 + 密钥（适合无托管身份的 CI 场景）：

use azure_identity::ClientSecretCredential; let credential = ClientSecretCredential::new( "<tenant-id>".into(), "<client-id>".into(), "<client-secret>".into(), None, )?;

凭据是Arc包裹的，clone 成本极低，同一凭据实例可复用于多个客户端（Service Bus、Event Hubs、Cosmos DB 等），这是 azure-sdk-for-rust 的统一约定。

核心工作流：队列消息收发

向队列发送消息

use azure_identity::DeveloperToolsCredential; use azure_messaging_servicebus::{ServiceBusClient, Message}; #[tokio::main] async fn main() -> Result<(), Box<dyn std::error::Error>> { let credential = DeveloperToolsCredential::new(None)?; let client = ServiceBusClient::builder() .open("your_namespace.servicebus.windows.net", credential.clone()) .await?; let sender = client.create_sender("my_queue", None).await?; let message = Message::from("Hello, Service Bus!"); sender.send_message(message, None).await?; Ok(()) }

关键点：create_sender("my_queue", None)返回Sender句柄；Message::from从字符串构造消息；send_message第二个参数为可选选项（此处传None）。

从队列接收消息

use azure_identity::DeveloperToolsCredential; use azure_messaging_servicebus::ServiceBusClient; #[tokio::main] async fn main() -> Result<(), Box<dyn std::error::Error>> { let credential = DeveloperToolsCredential::new(None)?; let client = ServiceBusClient::builder() .open("your_namespace.servicebus.windows.net", credential.clone()) .await?; let receiver = client.create_receiver("my_queue", None).await?; let messages = receiver.receive_messages(5, None).await?; for message in messages { println!("Received: {}", message.body_as_string()?); receiver.complete_message(&message, None).await?; } Ok(()) }

receive_messages(5, None)一次性拉取至多 5 条消息；body_as_string()解码消息体；处理成功后必须调用complete_message，否则消息会被重新投递。

核心工作流：主题与订阅

向主题发送消息

let sender = client.create_sender("my_topic", None).await?; let message = Message::from("Hello, Topic subscribers!"); sender.send_message(message, None).await?;

发送到主题与发送到队列的 API 完全一致，区别仅在于目标实体：发送到主题后，该消息会被投递到主题下每个订阅的独立副本中。

从订阅接收消息

let receiver = client .create_receiver_for_subscription("my_topic", "my_subscription", None) .await?; let messages = receiver.receive_messages(5, None).await?; for message in messages { println!("Received: {}", message.body_as_string()?); receiver.complete_message(&message, None).await?; }

接收订阅消息使用create_receiver_for_subscription，需要同时指定主题名与订阅名。循环内的complete_message语义与队列接收完全一致。

消息结算（Message Settlement）

务必在成功处理之后完成（complete）消息，以防止重复投递。abandon 场景则用于处理失败时主动交还消息，让其他消费者重试。

RBAC 角色与授权

使用 Entra ID 认证时，需要为身份（用户、服务主体或托管身份）分配以下数据平面角色之一：

最小权限原则下：只发送就分配 Data Sender，只接收就分配 Data Receiver，避免直接使用 Data Owner。与 Event Hubs 等其他 Azure 消息服务的 RBAC 模型保持一致，可在 Azure 门户的命名空间"访问控制 (IAM)"中完成分配。

最佳实践清单

技能文档给出 8 条最佳实践，逐条展开如下：

1. 用cargo add管理依赖，不要直接编辑Cargo.toml。添加/移除 Rust SDK 依赖一律通过 cargo 命令，避免手改清单导致版本漂移或依赖图损坏。
2. 仅在直接导入azure_core类型时才添加azure_core依赖。判断标准是代码中是否出现azure_core::http::Url、azure_core::http::RequestContent、azure_core::error::ErrorKind等路径；否则直接依赖可选。
3. 本地开发用DeveloperToolsCredential，生产用ManagedIdentityCredential。Rust 生态没有DefaultAzureCredential单类型方案，必须按环境显式选择。
4. 绝不硬编码凭据——使用环境变量或托管身份。
5. 分配 RBAC 角色——确保身份具备恰当的 Service Bus 数据角色（见上节）。
6. 总是完成消息——处理完成后调用complete_message，将消息从队列/订阅移除，防止重复投递。
7. 扇出场景用主题——当多个消费者需要同一份消息时，使用主题 + 订阅而非队列。
8. 该 crate 处于预发布阶段——API 可能变动，务必在依赖工作流中固定依赖版本（pin version）。

参考资源

• API 参考：azure_messaging_servicebus的 docs.rs 最新文档（对应 crate 名称azure_messaging_servicebus）；
• 发布页面：crates.io 上的azure_messaging_servicebus页面，注意甄别发布者为 azure-sdk 用户；
• 源码：Azure/azure-sdk-for-rust 仓库的sdk/servicebus/azure_messaging_servicebus目录。

在 agentic-awesome-skills 仓库中，本文所依据的技能文件位于 azure-servicebus-rust/SKILL.md，与之配套的认证技能 azure-identity-rust 提供了完整的凭据体系说明；同为消息家族的 azure-eventhub-rust 与数据库客户端 azure-cosmos-rust 展示了 azure-sdk-for-rust 统一的"凭据 + 客户端 builder/open"使用模式，可交叉参考。

使用限制与注意事项

• 仅在任务与技能的上游来源及本地项目上下文明确匹配时使用本技能；
• 应用改动前，务必验证命令、生成的代码、依赖、凭据及外部服务行为；
• 不要将示例当作环境特定测试、安全审查或对破坏性/高成本操作的用户批准的替代品；
• 再次强调：当前 crate 处于早期开发阶段，引入生产系统前需充分评估 API 稳定性风险并固定版本。

• AI 技能
• AI 插件
• 人工智能