使用 @azure/storage-queue 构建 TypeScript 消息队列应用:Azure Queue Storage 完整实战指南
使用 @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 天的任务不适合直接用队列可见性窗口承载,需要配合外部任务状态存储。
最佳实践清单
综合详细指南中的经验,生产使用建议如下:
- 优先使用 DefaultAzureCredential —— 用 AAD 认证替代连接字符串与共享密钥,降低密钥泄露面。
- 处理完成后立即删除消息 —— 防止可见性超时导致的重复消费。
- 为毒消息设置死信队列 —— 基于
dequeueCount阈值转移失败消息,避免阻塞主队列。 - 按预期处理时长设置可见性超时 —— 过短导致误重试,过长拖慢故障恢复。
- 长任务主动延长可见性 —— 通过
updateMessage周期续期,并回写新的popReceipt。 - 结构化数据使用 JSON —— 序列化为字符串传输,消费端解析,避免依赖 SDK 隐式转换。
- 监控 dequeueCount —— 它是识别反复失败消息的第一信号。
- 批量接收消息 ——
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 与 详细指南 的流程,落地一个最小可运行的收发链路:
- 安装依赖:
npm install @azure/storage-queue @azure/identity。 - 配置环境:设置
AZURE_STORAGE_ACCOUNT_NAME与AZURE_STORAGE_ACCOUNT_KEY(或连接字符串)。 - 初始化客户端:按上文四种认证方式之一构造
QueueServiceClient。 - 创建队列:
client.getQueueClient("task-queue").createIfNotExists()。 - 发送消息:
queueClient.sendMessage(JSON.stringify({ type: "process", id: 1 }))。 - 消费消息:用基础 Worker 模式批量接收、处理、删除,并叠加毒消息处理与可见性延长。
- 验证:本地可用 Azurite 模拟器先行验证,再切换到真实存储账户;注意 SDK 版本(12.x)与 Node.js >= 18 的前提条件。
该技能在仓库中属于 critical 风险级别,执行涉及真实云端资源的操作前,务必确认资源边界、权限范围与成功判定标准;若缺少必要输入、权限或安全边界信息,应先向使用者澄清再继续执行。