使用 @azure/storage-queue 构建 TypeScript 消息队列应用:Azure Queue Storage 完整实战指南

原创2026-09-21 12:05:291,845 阅读
文章标签:人工智能AI 技能AI 插件MCP 服务开发工具AI 应用

使用 @azure/storage-queue 构建 TypeScript 消息队列应用:Azure Queue Storage 完整实战指南

导读

本文以 Agentic Awesome Skills 仓库中的 azure-storage-queue-ts 技能文档为核心,系统讲解 Azure Queue Storage 的 TypeScript/JavaScript SDK(@azure/storage-queue)在消息发送、接收、窥视、删除等队列操作上的完整用法。你将掌握四种认证方式的选择、客户端对象层次结构、五种消息处理模式(含毒消息转移与可见性延长)、SAS 令牌生成、错误处理与类型体系,并能在自己的 Node.js 或浏览器应用中直接落地一套生产级消息队列方案。该技能在仓库中被归类为 cloud 类别、风险等级 critical(见 catalog.json),并被纳入多个技能包(见 bundles.json),同时兼容 Claude 与 Codex 两类运行目标(见 plugin-compatibility.json),是 Azure 消息驱动架构场景下的核心技能。

技能背景:它在仓库中的定位

在深入代码之前,先了解该技能在仓库中的编排信息,这有助于你理解何时应加载它:

  • 身份标识:azure-storage-queue-ts,规范 ID(canonical_id)与之一致,主文件为 skills/azure-storage-queue-ts/SKILL.md(见 catalog.json)。
  • 分类与风险:分类为 cloud,风险等级 critical——意味着该技能涉及云端资源的创建、修改或删除操作,使用前必须确认目标账户与资源边界。
  • 来源与触发词:来源为社区(community),触发词覆盖 azure、storage、queue、ts、javascript、typescript、sdk、message、operations、sending、receiving、peeking 等(见 catalog.json),当任务涉及这些关键词时即匹配该技能。
  • 目标平台兼容性:在 plugin-compatibility.json 中,targets 显示 codex: supported 与 claude: supported,且 setup.type 为 none、无 runtime_files——即该技能无需额外的环境安装步骤,加载即可使用。

技能本体 SKILL.md 定义激活条件、适用范围与限制,完整操作流程集中在 references/detailed-guide.md(下文的实战内容均源自该详细指南)。

安装与版本要求

开始前先安装 SDK。需要两个包:核心队列 SDK 与身份认证 SDK。

npm install @azure/storage-queue @azure/identity

版本前提(依据详细指南):

项目 要求
当前版本 12.x
Node.js >= 18.0.0

@azure/identity 提供 DefaultAzureCredential 等 AAD(Microsoft Entra ID)认证能力,是推荐的生产认证方式;如果你只使用连接字符串或共享密钥,可以省略该依赖。

环境变量与连接配置

建议通过环境变量注入凭据,避免将密钥硬编码进源码:

AZURE_STORAGE_ACCOUNT_NAME=<account-name>
AZURE_STORAGE_ACCOUNT_KEY=<account-key>
# 或者直接使用连接字符串
AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...
  • AZURE_STORAGE_ACCOUNT_NAME / AZURE_STORAGE_ACCOUNT_KEY:配合 StorageSharedKeyCredential 或 DefaultAzureCredential 使用。
  • AZURE_STORAGE_CONNECTION_STRING:一种把协议、账户名与密钥打包的便捷方式,适合快速接入。

此外,若使用 SAS 认证,还需要 AZURE_STORAGE_SAS_TOKEN 环境变量(见下文 SAS 一节)。

认证方式:四种选型与代码示例

@azure/storage-queue 支持四种认证途径。选择顺序建议:优先 AAD(DefaultAzureCredential),其次是 SAS、共享密钥,连接字符串仅在受限环境使用。

1. DefaultAzureCredential(推荐)

利用 @azure/identity 的 DefaultAzureCredential,它会按顺序尝试环境变量、Azure CLI 登录态、托管身份等多种凭据源,适合本地开发与生产环境无缝切换:

import { QueueServiceClient } from "@azure/storage-queue";
import { DefaultAzureCredential } from "@azure/identity";

const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME!;
const client = new QueueServiceClient(
  `https://${accountName}.queue.core.windows.net`,
  new DefaultAzureCredential()
);

2. 连接字符串

最简单但安全性较低(密钥以明文内嵌),适合快速原型:

import { QueueServiceClient } from "@azure/storage-queue";

const client = QueueServiceClient.fromConnectionString(
  process.env.AZURE_STORAGE_CONNECTION_STRING!
);

3. StorageSharedKeyCredential(仅 Node.js)

使用账户名与账户密钥显式构造凭据:

import { QueueServiceClient, StorageSharedKeyCredential } from "@azure/storage-queue";

const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME!;
const accountKey = process.env.AZURE_STORAGE_ACCOUNT_KEY!;

const sharedKeyCredential = new StorageSharedKeyCredential(accountName, accountKey);
const client = new QueueServiceClient(
  `https://${accountName}.queue.core.windows.net`,
  sharedKeyCredential
);

4. SAS Token

使用共享访问签名令牌附加到 URL 末尾,适合向第三方授予限时限权的访问:

import { QueueServiceClient } from "@azure/storage-queue";

const accountName = process.env.AZURE_STORAGE_ACCOUNT_NAME!;
const sasToken = process.env.AZURE_STORAGE_SAS_TOKEN!;

const client = new QueueServiceClient(
  `https://${accountName}.queue.core.windows.net${sasToken}`
);

客户端对象层次结构

SDK 采用三级对象模型,理解它有助于组织代码:

QueueServiceClient (账户级)
└── QueueClient (队列级)
    └── Messages (send, receive, peek, delete)
  • QueueServiceClient:操作整个存储账户的队列集合(创建、列举、删除队列,生成 SAS 等)。
  • QueueClient:操作单个队列(元数据、属性、消息收发)。
  • 消息操作全部经由 QueueClient 的实例方法完成,不存在独立的 Messages 类对象。

队列级操作

创建队列

const queueClient = client.getQueueClient("my-queue");
await queueClient.create();

// 或者:不存在时才创建(幂等)
await queueClient.createIfNotExists();

createIfNotExists 适用于初始化场景,避免并发创建时抛出 QueueAlreadyExists 错误。

列举队列

for await (const queue of client.listQueues()) {
  console.log(queue.name);
}

// 带前缀过滤
for await (const queue of client.listQueues({ prefix: "task-" })) {
  console.log(queue.name);
}

listQueues 返回异步迭代器,prefix 选项可筛选指定前缀的队列,适合多租户或按业务域命名(如 task-、email-)的场景。

删除队列

await queueClient.delete();

// 或者:存在才删除(幂等)
await queueClient.deleteIfExists();

获取队列属性

const properties = await queueClient.getProperties();
console.log("Approximate message count:", properties.approximateMessagesCount);
console.log("Metadata:", properties.metadata);

approximateMessagesCount 为近似值,仅作监控参考,不应作为精确计数的依据。

设置队列元数据

await queueClient.setMetadata({
  department: "engineering",
  priority: "high",
});

元数据以键值对形式附加到队列,可用于标注归属、优先级等信息,与队列属性一同返回。

消息级操作

发送消息

const queueClient = client.getQueueClient("my-queue");

// 简单文本消息
await queueClient.sendMessage("Hello, World!");

// 带选项:延迟可见 + 设置过期时间
await queueClient.sendMessage("Delayed message", {
  visibilityTimeout: 60, // 隐藏 60 秒后可见
  messageTimeToLive: 3600, // 1 小时后过期
});

// JSON 消息(必须序列化为字符串)
const task = { type: "process", data: { id: 123 } };
await queueClient.sendMessage(JSON.stringify(task));

要点:

  • visibilityTimeout(秒):消息进入队列后先保持"不可见",到期后对消费者可见——即延迟投递。
  • messageTimeToLive(秒):消息存活时长,超时未消费会被自动清除。
  • 消息正文只能是字符串;结构化数据必须 JSON.stringify,消费端再 JSON.parse。
  • 单条消息最大 64 KB(见下文消息限制表)。

接收消息

// 一次最多接收 32 条(默认 1 条)
const response = await queueClient.receiveMessages({
  numberOfMessages: 10,
  visibilityTimeout: 30, // 30 秒处理窗口
});

for (const message of response.receivedMessageItems) {
  console.log("Message ID:", message.messageId);
  console.log("Content:", message.messageText);
  console.log("Dequeue Count:", message.dequeueCount);
  console.log("Pop Receipt:", message.popReceipt);

  // 处理消息...

  // 处理完成后必须删除,否则可见性超时后消息会重新可见
  await queueClient.deleteMessage(message.messageId, message.popReceipt);
}

核心语义:

  • 接收即"租借":消息进入不可见状态,visibilityTimeout 秒内未删除则会重新可见,可能被其他消费者再次取到。
  • dequeueCount 记录消息被取出的次数,是识别毒消息的关键字段。
  • popReceipt 是本次租借的唯一凭据,后续删除/更新操作必须携带它。
  • numberOfMessages 最大 32,一次批量接收可显著降低轮询开销。

窥视消息

窥视不将消息移出队列,也不触发可见性变更(无可见性超时),适合巡检或监控:

const response = await queueClient.peekMessages({
  numberOfMessages: 5,
});

for (const message of response.peekedMessageItems) {
  console.log("Message ID:", message.messageId);
  console.log("Content:", message.messageText);
  // 注意:窥视结果没有 popReceipt,不能删除窥视到的消息
}

更新消息

更新可用于修改消息内容或延长可见性超时(长任务保活):

// 先接收一条消息
const response = await queueClient.receiveMessages();
const message = response.receivedMessageItems[0];

if (message) {
  // 更新内容并延长可见性
  const updateResponse = await queueClient.updateMessage(
    message.messageId,
    message.popReceipt,
    "Updated content",
    60 // 新的可见性超时(秒)
  );

  // 重要:更新后 popReceipt 会轮换,后续操作必须使用新的
  console.log("New pop receipt:", updateResponse.popReceipt);
}

删除消息

删除必须在接收(拿到 popReceipt)之后执行:

const response = await queueClient.receiveMessages();
const message = response.receivedMessageItems[0];

if (message) {
  await queueClient.deleteMessage(message.messageId, message.popReceipt);
}

清空队列

await queueClient.clearMessages();

clearMessages 立即删除队列中所有消息,操作不可逆,生产环境请谨慎调用。

消息处理模式:从基础 Worker 到毒消息治理

基础 Worker 模式

一个常驻轮询消费者,批量拉取、逐个处理、删除,空队列时退避等待:

async function processQueue(queueClient: QueueClient): Promise<void> {
  while (true) {
    const response = await queueClient.receiveMessages({
      numberOfMessages: 10,
      visibilityTimeout: 30,
    });

    if (response.receivedMessageItems.length === 0) {
      // 无消息,等待 5 秒后继续轮询
      await sleep(5000);
      continue;
    }

    for (const message of response.receivedMessageItems) {
      try {
        await processMessage(message.messageText);
        await queueClient.deleteMessage(message.messageId, message.popReceipt);
      } catch (error) {
        console.error(`Failed to process message ${message.messageId}:`, error);
        // 不删除:可见性超时后消息将重新可见,等待重试
      }
    }
  }
}

async function processMessage(content: string): Promise<void> {
  const task = JSON.parse(content);
  // 处理任务...
}

function sleep(ms: number): Promise<void> {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

该模式的关键设计:处理失败不删除消息,依赖可见性超时自动回队重试,天然具备 at-least-once 语义;代价是消费端必须实现幂等处理。

毒消息处理

反复处理失败的消息会无限重试,必须通过 dequeueCount 阈值将其转移到毒消息队列(死信队列):

const MAX_DEQUEUE_COUNT = 5;

async function processWithPoisonHandling(
  queueClient: QueueClient,
  poisonQueueClient: QueueClient
): Promise<void> {
  const response = await queueClient.receiveMessages({
    numberOfMessages: 10,
    visibilityTimeout: 30,
  });

  for (const message of response.receivedMessageItems) {
    if (message.dequeueCount > MAX_DEQUEUE_COUNT) {
      // 超出重试上限,转移到毒消息队列
      await poisonQueueClient.sendMessage(message.messageText);
      await queueClient.deleteMessage(message.messageId, message.popReceipt);
      console.log(`Moved message ${message.messageId} to poison queue`);
      continue;
    }

    try {
      await processMessage(message.messageText);
      await queueClient.deleteMessage(message.messageId, message.popReceipt);
    } catch (error) {
      console.error(`Processing failed (attempt ${message.dequeueCount}):`, error);
    }
  }
}

毒消息队列可另行配置告警与人工排查流程,避免坏消息阻塞主队列。

批量处理 + 可见性延长

当单条消息处理时间可能超过可见性超时时,用定时器周期性调用 updateMessage 续期:

async function processBatchWithExtension(queueClient: QueueClient): Promise<void> {
  const response = await queueClient.receiveMessages({
    numberOfMessages: 1,
    visibilityTimeout: 60,
  });

  const message = response.receivedMessageItems[0];
  if (!message) return;

  let popReceipt = message.popReceipt;

  // 启动可见性延长定时器
  const extensionInterval = setInterval(async () => {
    try {
      const updateResponse = await queueClient.updateMessage(
        message.messageId,
        popReceipt,
        message.messageText,
        60 // 每次再延长 60 秒
      );
      popReceipt = updateResponse.popReceipt; // 更新后的凭据必须回写
    } catch (error) {
      console.error("Failed to extend visibility:", error);
    }
  }, 45000); // 每 45 秒续期一次(略小于 60 秒窗口)

  try {
    await longRunningProcess(message.messageText);
    await queueClient.deleteMessage(message.messageId, popReceipt);
  } finally {
    clearInterval(extensionInterval);
  }
}

实现要点:

  • 续期间隔必须小于可见性窗口(本例 45s < 60s),预留网络延迟余量。
  • updateMessage 会轮换 popReceipt,务必把返回值回写,否则后续续期/删除会因凭据过期而失败。
  • 用 finally 清理定时器,防止任务完成后泄漏。

消息编码机制

默认情况下消息以 Base64 编码传输。可通过 messageEncoding 选项自定义:

import { QueueClient } from "@azure/storage-queue";

// 使用纯文本编码(不经过 Base64)
const queueClient = new QueueClient(
  `https://${accountName}.queue.core.windows.net/my-queue`,
  credential,
  {
    messageEncoding: "text", // "base64"(默认)或 "text"
  }
);

// 或提供自定义编解码器
const customQueueClient = new QueueClient(
  `https://${accountName}.queue.core.windows.net/my-queue`,
  credential,
  {
    messageEncoding: {
      encode: (message: string) => Buffer.from(message).toString("base64"),
      decode: (message: string) => Buffer.from(message, "base64").toString(),
    },
  }
);

编码器必须实现 encode 与 decode 两个函数。自定义编码适合需要兼容其他语言客户端或特殊字符集的场景;需要注意的是,messageEncoding: "text" 与自定义编码器要求构造 QueueClient 时显式传入连接信息与凭据,无法直接复用 QueueServiceClient.getQueueClient 的快捷方式。

SAS 令牌生成(仅 Node.js)

SAS 可以精确控制授权范围与有效期,适合为外部调用方签发临时访问凭证。

生成队列级 SAS

import {
  QueueSASPermissions,
  generateQueueSASQueryParameters,
  StorageSharedKeyCredential,
} from "@azure/storage-queue";

const sharedKeyCredential = new StorageSharedKeyCredential(accountName, accountKey);

const sasToken = generateQueueSASQueryParameters(
  {
    queueName: "my-queue",
    permissions: QueueSASPermissions.parse("raup"), // read, add, update, process
    startsOn: new Date(),
    expiresOn: new Date(Date.now() + 3600 * 1000), // 1 小时后过期
  },
  sharedKeyCredential
).toString();

const sasUrl = `https://${accountName}.queue.core.windows.net/my-queue?${sasToken}`;

QueueSASPermissions.parse("raup") 中每个字符对应一类操作:

字符 含义
r read(窥视/读取消息)
a add(添加消息)
u update(更新消息)
p process(接收并删除消息)

生成账户级 SAS

import {
  AccountSASPermissions,
  AccountSASResourceTypes,
  AccountSASServices,
  generateAccountSASQueryParameters,
} from "@azure/storage-queue";

const sasToken = generateAccountSASQueryParameters(
  {
    services: AccountSASServices.parse("q").toString(), // q = queue 服务
    resourceTypes: AccountSASResourceTypes.parse("sco").toString(),
    permissions: AccountSASPermissions.parse("rwdlacupi"),
    expiresOn: new Date(Date.now() + 24 * 3600 * 1000), // 24 小时
  },
  sharedKeyCredential
).toString();

账户级 SAS 的权限字符集更广(rwdlacupi 对应读/写/删除/列举/添加/创建/更新/处理/查询权限),并需指定 services 与 resourceTypes。应遵循最小权限原则:services 只写用到的 q,resourceTypes 按需选择。

错误处理:基于 RestError 的分诊

SDK 抛出的异常通常为 RestError,可按 statusCode 精确分诊:

import { RestError } from "@azure/storage-queue";

try {
  await queueClient.sendMessage("test");
} catch (error) {
  if (error instanceof RestError) {
    switch (error.statusCode) {
      case 404:
        console.log("Queue not found");
        break;
      case 400:
        console.log("Bad request - message too large or invalid");
        break;
      case 403:
        console.log("Access denied");
        break;
      case 409:
        console.log("Queue already exists or being deleted");
        break;
      default:
        console.error(`Storage error ${error.statusCode}: ${error.message}`);
    }
  }
  throw error; // 重新抛出,交由上层重试策略处理
}

常见状态码速查:

  • 404:队列不存在(可能被误删,或 getQueueClient 指向错误队列名)。
  • 400:请求非法,常见于消息超过 64 KB。
  • 403:凭据无权限或 SAS 已过期。
  • 409:并发创建/删除冲突,可使用 createIfNotExists / deleteIfExists 规避。

建议对 403 与 429(暂未在示例中列出)等可恢复错误接入指数退避重试,对 400 类确定性错误直接记录并告警。

TypeScript 类型体系速查

SDK 导出的核心类型(供 IDE 自动补全与类型检查参考):

import {
  // 客户端
  QueueServiceClient,
  QueueClient,

  // 认证
  StorageSharedKeyCredential,
  AnonymousCredential,

  // SAS
  QueueSASPermissions,
  AccountSASPermissions,
  AccountSASServices,
  AccountSASResourceTypes,
  generateQueueSASQueryParameters,
  generateAccountSASQueryParameters,

  // 消息
  DequeuedMessageItem,
  PeekedMessageItem,
  QueueSendMessageResponse,
  QueueReceiveMessageResponse,
  QueueUpdateMessageResponse,

  // 队列
  QueueItem,
  QueueGetPropertiesResponse,

  // 错误
  RestError,
} from "@azure/storage-queue";
  • DequeuedMessageItem / PeekedMessageItem:接收与窥视返回的消息结构(后者不含 popReceipt)。
  • QueueReceiveMessageResponse:receiveMessages 的完整返回,含 receivedMessageItems 数组。
  • AnonymousCredential:配合 SAS URL 或公共队列使用。

消息限制与配额速查

使用前请牢记以下硬性限制(依据详细指南):

限制项 值
单条消息最大体积 64 KB
最大可见性超时 7 天
最大生存时间(TTL) 7 天(-1 表示永不过期)
单次接收最大条数 32
默认可见性超时 30 秒

这些限制直接影响架构选型:超过 64 KB 的负载应存入 Blob 并在消息中携带引用(messageText 只存路径或 ID);处理时长超过 7 天的任务不适合直接用队列可见性窗口承载,需要配合外部任务状态存储。

最佳实践清单

综合详细指南中的经验,生产使用建议如下:

  1. 优先使用 DefaultAzureCredential —— 用 AAD 认证替代连接字符串与共享密钥,降低密钥泄露面。
  2. 处理完成后立即删除消息 —— 防止可见性超时导致的重复消费。
  3. 为毒消息设置死信队列 —— 基于 dequeueCount 阈值转移失败消息,避免阻塞主队列。
  4. 按预期处理时长设置可见性超时 —— 过短导致误重试,过长拖慢故障恢复。
  5. 长任务主动延长可见性 —— 通过 updateMessage 周期续期,并回写新的 popReceipt。
  6. 结构化数据使用 JSON —— 序列化为字符串传输,消费端解析,避免依赖 SDK 隐式转换。
  7. 监控 dequeueCount —— 它是识别反复失败消息的第一信号。
  8. 批量接收消息 —— numberOfMessages 设为合理值(如 10~32),降低轮询频率与请求成本。

平台差异:Node.js 与浏览器

@azure/storage-queue 同时支持 Node.js 与浏览器,但部分认证与 SAS 能力仅限 Node.js(依赖 Node 的 Buffer 与密钥运算):

能力 Node.js 浏览器
StorageSharedKeyCredential ✅ ❌
SAS 生成 ✅ ❌
DefaultAzureCredential ✅ ❌
Anonymous / SAS 访问 ✅ ✅
全部消息操作 ✅ ✅

浏览器端必须使用 SAS 令牌或匿名访问;共享密钥与 AAD 凭据链在浏览器不可用。若需在浏览器做 SAS 生成,只能由后端(Node.js)签发后下发到前端。

快速上手指引

结合 SKILL.md 与 详细指南 的流程,落地一个最小可运行的收发链路:

  1. 安装依赖:npm install @azure/storage-queue @azure/identity。
  2. 配置环境:设置 AZURE_STORAGE_ACCOUNT_NAME 与 AZURE_STORAGE_ACCOUNT_KEY(或连接字符串)。
  3. 初始化客户端:按上文四种认证方式之一构造 QueueServiceClient。
  4. 创建队列:client.getQueueClient("task-queue").createIfNotExists()。
  5. 发送消息:queueClient.sendMessage(JSON.stringify({ type: "process", id: 1 }))。
  6. 消费消息:用基础 Worker 模式批量接收、处理、删除,并叠加毒消息处理与可见性延长。
  7. 验证:本地可用 Azurite 模拟器先行验证,再切换到真实存储账户;注意 SDK 版本(12.x)与 Node.js >= 18 的前提条件。

该技能在仓库中属于 critical 风险级别,执行涉及真实云端资源的操作前,务必确认资源边界、权限范围与成功判定标准;若缺少必要输入、权限或安全边界信息,应先向使用者澄清再继续执行。

登录后查看全文
agentic-awesome-skills