agentic-awesome-skills 中的 Azure Queue Storage TypeScript 技能:@azure/storage-queue 完整实战指南
agentic-awesome-skills 中的 Azure Queue Storage TypeScript 技能:@azure/storage-queue 完整实战指南
本文以 agentic-awesome-skills 仓库中
azure-storage-queue-ts技能包的 references/detailed-guide.md 为核心骨架展开。该技能面向 Azure Queue Storage 的 JavaScript/TypeScript SDK(@azure/storage-queue),覆盖消息队列的发送、接收、窥视、更新与删除等全流程操作。读完本文,你将掌握四种认证方式(DefaultAzureCredential、连接字符串、共享密钥、SAS)的选型与写法,理解QueueServiceClient → QueueClient → Messages三层客户端模型,能够实现带可见性超时管理、死信(毒消息)隔离、长任务可见性续期的可靠消费 Worker,并完成 SAS 令牌生成、错误处理与消息编码定制等生产级配置。
一、技能定位与使用前提
在 agentic-awesome-skills 仓库中,azure-storage-queue-ts 是一个 risk: critical、来源为 source: community 的技能(见 data/catalog.json)。它的入口 SKILL.md 定义了技能的触发条件(name 为 azure-storage-queue-ts,描述为“Azure Queue Storage JavaScript/TypeScript SDK 消息队列操作,用于队列中消息的发送、接收、窥视与删除”)与使用边界;而详细操作手册即 references/detailed-guide.md,本文全部实操内容均继承自该手册。
使用本技能需注意其声明的限制(来源 SKILL.md):
- 仅当任务明确匹配上述范围时使用;
- 技能输出不能替代针对具体环境的验证、测试或专家评审;
- 当输入、权限、安全边界或成功标准缺失时,应停止并请求澄清。
在仓库中,同一技能以镜像形式存在于 agentic-awesome-skills 插件与 agentic-awesome-skills-claude 插件两处,其 detailed-guide.md 内容完全一致,下文示例可直接在任一套技能目录下对照查阅。
二、安装与环境变量
2.1 安装依赖
npm install @azure/storage-queue @azure/identity
@azure/storage-queue:队列存储 SDK 本体,提供QueueServiceClient、QueueClient、各类 SAS 生成工具等;@azure/identity:提供DefaultAzureCredential等 Azure 身份认证实现。
手册标注的版本与运行环境前提为:
- 当前版本:12.x
- Node.js:>= 18.0.0
注意:浏览器环境并非完全支持所有能力(见下文“平台差异”一节),若面向浏览器打包,需要关注 SDK 对 Buffer、crypto 等 Node 内置模块的依赖情况。
2.2 环境变量约定
AZURE_STORAGE_ACCOUNT_NAME=<account-name>
AZURE_STORAGE_ACCOUNT_KEY=<account-key>
# OR connection string
AZURE_STORAGE_CONNECTION_STRING=DefaultEndpointsProtocol=https;AccountName=...
- 使用账号名 + 账号密钥组合时,分别设置
AZURE_STORAGE_ACCOUNT_NAME与AZURE_STORAGE_ACCOUNT_KEY,用于构造StorageSharedKeyCredential; - 使用连接字符串时,直接设置
AZURE_STORAGE_CONNECTION_STRING,格式为DefaultEndpointsProtocol=https;AccountName=...(其后通常还包含AccountKey=...;EndpointSuffix=...等字段,此处以省略号示意); - 使用 SAS 令牌时,手册示例中还引入了
AZURE_STORAGE_SAS_TOKEN环境变量。
这些环境变量并非 SDK 强制要求,而是本技能的约定;在代码中通过 process.env.AZURE_STORAGE_ACCOUNT_NAME! 读取,! 表示假定变量必然存在(若缺失会在运行时抛出 undefined 相关错误,可配合下文的错误处理章节做防御性校验)。
三、四种认证方式与选型建议
QueueServiceClient 的构造函数接受“服务 URL + 凭据对象”,凭据对象决定了认证方式。手册给出四种写法。
3.1 DefaultAzureCredential(推荐)
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()
);
DefaultAzureCredential 会按顺序尝试多种 Azure 身份来源(环境变量、Azure CLI 登录态、托管标识等),适合本地开发与生产环境共用一套代码。手册明确标注其为推荐方式。
3.2 连接字符串
import { QueueServiceClient } from "@azure/storage-queue";
const client = QueueServiceClient.fromConnectionString(
process.env.AZURE_STORAGE_CONNECTION_STRING!
);
这是最快的上手方式,无需显式创建凭据对象;但连接字符串中携带账号密钥,应严格保密,避免提交到版本库。
3.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
);
共享密钥方式由 SDK 内部完成请求签名,需要 Node 环境支持 HMAC 计算,因此仅限 Node.js(见平台差异表)。
3.4 SAS 令牌
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}`
);
SAS 令牌直接拼接到 URL 查询串中,无需在客户端保存密钥,适合将受限访问权下发给不可信或外部调用方;令牌的有效期与权限在生成时即已固化(生成方法见后文“SAS 令牌生成”章节)。
四、客户端层级模型
手册给出了清晰的层级关系:
QueueServiceClient (account level)
└── QueueClient (queue level)
└── Messages (send, receive, peek, delete)
QueueServiceClient:存储账号级别的入口,负责队列的增删查(createQueue、listQueues、deleteQueue等)以及账号级 SAS 生成;QueueClient:单个队列的句柄,通过client.getQueueClient("queue-name")获取,负责队列属性、元数据管理;- Messages:由
QueueClient直接操作的消息层,包含sendMessage、receiveMessages、peekMessages、updateMessage、deleteMessage、clearMessages。
这一模型与 Azure Queue Storage 的 REST 语义一一对应:消息不单独构成“客户端”,而是绑定在队列客户端之上。
五、队列操作详解
5.1 创建队列
const queueClient = client.getQueueClient("my-queue");
await queueClient.create();
// Or create if not exists
await queueClient.createIfNotExists();
create():队列已存在时抛错(HTTP 409,见错误处理章节);createIfNotExists():幂等写法,适合初始化流程反复执行。
5.2 列出队列
for await (const queue of client.listQueues()) {
console.log(queue.name);
}
// With prefix filter
for await (const queue of client.listQueues({ prefix: "task-" })) {
console.log(queue.name);
}
listQueues() 返回异步迭代器,可通过 prefix 选项按名称前缀过滤;对大型账号,逐页迭代由 SDK 自动处理。
5.3 删除队列
await queueClient.delete();
// Or delete if exists
await queueClient.deleteIfExists();
delete() 对不存在的队列会抛错;deleteIfExists() 提供幂等删除。
5.4 获取队列属性
const properties = await queueClient.getProperties();
console.log("Approximate message count:", properties.approximateMessagesCount);
console.log("Metadata:", properties.metadata);
approximateMessagesCount 是近似值(并非强一致实时计数,Azure 服务端周期性更新),可用于监控面板的粗略指标,不应作为精确计数依据;metadata 返回该队列上设置的键值元数据。
5.5 设置队列元数据
await queueClient.setMetadata({
department: "engineering",
priority: "high",
});
元数据以键值对形式附着在队列上,可用于团队归属、环境标识(dev/staging/prod)、优先级标注等运维信息;调用会覆盖既有元数据。
六、消息操作详解
6.1 发送消息
const queueClient = client.getQueueClient("my-queue");
// Simple message
await queueClient.sendMessage("Hello, World!");
// With options
await queueClient.sendMessage("Delayed message", {
visibilityTimeout: 60, // Hidden for 60 seconds
messageTimeToLive: 3600, // Expires in 1 hour
});
// JSON message (must be string)
const task = { type: "process", data: { id: 123 } };
await queueClient.sendMessage(JSON.stringify(task));
visibilityTimeout:消息入队后不可见的秒数,实现“延迟消息”效果(手册示例中 60 秒后消费者才能收到);messageTimeToLive:消息在队列中的存活秒数,超时后自动过期(手册示例 1 小时);设为-1表示永久存活(见消息限制表);- 消息内容必须是字符串:结构化数据需先
JSON.stringify,消费端再JSON.parse。
6.2 接收消息(租约语义核心)
// Receive up to 32 messages (default: 1)
const response = await queueClient.receiveMessages({
numberOfMessages: 10,
visibilityTimeout: 30, // 30 seconds to process
});
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);
// Process the message...
// Delete after processing
await queueClient.deleteMessage(message.messageId, message.popReceipt);
}
这是 Azure Queue Storage 消费模型的核心,理解以下几点才能正确实现可靠消费:
- 接收 ≠ 删除:
receiveMessages只是把消息“租约”给当前消费者(隐藏一段时间); popReceipt(弹出回执):每次成功接收/更新后由服务端颁发,是后续updateMessage/deleteMessage的必填凭证——消费端若在租约期内未删除消息,租约到期后消息自动重新可见,dequeueCount加 1;dequeueCount(出队计数):消息被接收但未被确认删除的次数,是毒消息检测的关键信号;numberOfMessages最大 32,默认 1;visibilityTimeout默认 30 秒(见消息限制表)。
6.3 窥视消息(不产生租约)
const response = await queueClient.peekMessages({
numberOfMessages: 5,
});
for (const message of response.peekedMessageItems) {
console.log("Message ID:", message.messageId);
console.log("Content:", message.messageText);
// Note: No popReceipt - cannot delete peeked messages
}
peekMessages 读取消息内容但不改变其可见性、不产生 popReceipt,因此:
- 适合做监控、统计、调试,不影响线上消费;
- 返回项中没有
popReceipt,无法对窥视到的消息执行删除/更新,这是手册明确强调的边界。
6.4 更新消息(续期与内容修改)
// Receive a message
const response = await queueClient.receiveMessages();
const message = response.receivedMessageItems[0];
if (message) {
// Update content and extend visibility
const updateResponse = await queueClient.updateMessage(
message.messageId,
message.popReceipt,
"Updated content",
60 // New visibility timeout in seconds
);
// Use new popReceipt for subsequent operations
console.log("New pop receipt:", updateResponse.popReceipt);
}
两个核心用途:
- 内容更新:将处理中间态写回消息;
- 可见性续期:为长任务延长租约,防止处理未完成时消息被重新消费。
关键陷阱:每次 updateMessage 都会颁发新的 popReceipt,后续操作必须使用最新的回执,否则会因回执过期(HTTP 409)而失败。这是“批处理 + 可见性续期”模式中必须动态追踪 popReceipt 的原因。
6.5 删除消息(消费成功的确认)
// After receiving
const response = await queueClient.receiveMessages();
const message = response.receivedMessageItems[0];
if (message) {
await queueClient.deleteMessage(message.messageId, message.popReceipt);
}
删除是消费流程的“最终确认”动作。若跳过删除,消息将在可见性超时后重新入队,造成重复处理——这也是最佳实践中“处理后务必删除”的第一原则。
6.6 清空队列
await queueClient.clearMessages();
一次性移除队列中全部消息,适合环境重置、错误数据批量清理等场景;操作不可逆,需谨慎执行。
七、三种典型消息处理模式
7.1 基础 Worker 轮询模式
async function processQueue(queueClient: QueueClient): Promise<void> {
while (true) {
const response = await queueClient.receiveMessages({
numberOfMessages: 10,
visibilityTimeout: 30,
});
if (response.receivedMessageItems.length === 0) {
// No messages, wait before polling again
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);
// Message will become visible again after timeout
}
}
}
}
async function processMessage(content: string): Promise<void> {
const task = JSON.parse(content);
// Process task...
}
function sleep(ms: number): Promise<void> {
return new Promise((resolve) => setTimeout(resolve, ms));
}
设计要点:
- 空队列退避:无消息时
sleep(5000)再轮询,避免对服务端造成无效请求压力; - 失败不删除:单条消息处理异常时仅记录日志,消息会在 30 秒可见性超时后自动回到队列重试;
- 批量接收:单次最多取 10 条,减少网络往返。
7.2 毒消息(Poison Message)处理
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) {
// Move to poison queue
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);
}
}
}
毒消息模式解决“永远处理失败、永远重新入队”的僵尸消息问题:
- 以
dequeueCount > MAX_DEQUEUE_COUNT(示例为 5 次)作为判定阈值; - 超过阈值的消息被转投到专用死信队列(
poisonQueueClient.sendMessage),并从原队列删除,避免阻塞主队列; - 死信队列可供人工排查、修复后重新入队或归档审计。
7.3 批处理 + 可见性续期(长任务)
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;
// Start visibility extension timer
const extensionInterval = setInterval(async () => {
try {
const updateResponse = await queueClient.updateMessage(
message.messageId,
popReceipt,
message.messageText,
60 // Extend by another 60 seconds
);
popReceipt = updateResponse.popReceipt;
} catch (error) {
console.error("Failed to extend visibility:", error);
}
}, 45000); // Extend every 45 seconds
try {
await longRunningProcess(message.messageText);
await queueClient.deleteMessage(message.messageId, popReceipt);
} finally {
clearInterval(extensionInterval);
}
}
适用于处理耗时可能超过单个可见性窗口的任务:
- 首次接收时设置 60 秒可见性;
- 每 45 秒调用一次
updateMessage续期(留出网络抖动与重试余量),并同步更新本地保存的 popReceipt; finally中清除定时器,确保无论成败都不再续期;- 长流程结束后用最新 popReceipt 删除消息。
这种模式把“固定租约”变成了“动态心跳租约”,是 Azure Queue Storage 上运行分钟级任务的常用解法。
八、消息编码定制
Azure Queue Storage 服务端默认要求消息以 Base64 编码传输,SDK 默认即采用 Base64:
import { QueueClient } from "@azure/storage-queue";
// Custom encoder/decoder for plain text
const queueClient = new QueueClient(
`https://${accountName}.queue.core.windows.net/my-queue`,
credential,
{
messageEncoding: "text", // "base64" (default) or "text"
}
);
// Or with custom encoder
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(),
},
}
);
要点:
messageEncoding: "text":明文传输,便于在 Azure 门户/存储浏览器中直接阅读消息内容,但需自行确认服务端兼容性;- 自定义 encoder 对象:提供
encode/decode两个函数即可完全接管编解码逻辑,可在此处扩展压缩、加密等能力; - 跨语言互操作注意:队列消费方/生产方如果混用不同 SDK(如 Python、Rust),必须保证编码约定一致,否则会出现乱码或解析失败。仓库中同系列的
azure-storage-queue-py、azure-storage-queue-rust技能(见 data/catalog.json)可作为对照参考。
九、SAS 令牌生成(仅 Node.js)
SAS 生成依赖共享密钥完成签名,因此仅限 Node.js(见平台差异表)。
9.1 生成队列级 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 hour
},
sharedKeyCredential
).toString();
const sasUrl = `https://${accountName}.queue.core.windows.net/my-queue?${sasToken}`;
permissions通过QueueSASPermissions.parse("raup")解析:r(read,读消息/属性)、a(add,添加消息)、u(update,更新消息)、p(process,接收与删除消息)——权限是按需组合的字符串,最小化授权是安全基线;startsOn/expiresOn限定令牌生效窗口,示例为 1 小时有效;- 生成的
sasUrl可直接分发给受限调用方。
9.2 生成账号级 SAS
import {
AccountSASPermissions,
AccountSASResourceTypes,
AccountSASServices,
generateAccountSASQueryParameters,
} from "@azure/storage-queue";
const sasToken = generateAccountSASQueryParameters(
{
services: AccountSASServices.parse("q").toString(), // queue
resourceTypes: AccountSASResourceTypes.parse("sco").toString(),
permissions: AccountSASPermissions.parse("rwdlacupi"),
expiresOn: new Date(Date.now() + 24 * 3600 * 1000),
},
sharedKeyCredential
).toString();
账号级 SAS 覆盖面更广:
services: "q":仅限队列服务;resourceTypes: "sco":s(service,服务)、c(container,容器)、o(object,对象)——对队列服务而言表示服务级/队列级操作范围;permissions: "rwdlacupi":读、写、删除、列出、添加、创建、更新、处理、查询权限的组合串;- 示例有效期为 24 小时。
安全提醒:SAS 等同于携带权限的令牌,应设置尽量短的有效期、最小化权限,并通过安全通道分发;泄露后应在 Azure 门户吊销对应密钥。
十、错误处理
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;
}
SDK 的错误对象统一为 RestError,通过 statusCode 分类处理:
| 状态码 | 含义 | 典型触发场景 |
|---|---|---|
| 400 | 请求无效 | 消息体过大或非法(见 64 KB 限制) |
| 403 | 访问被拒绝 | 密钥/SAS 权限不足、签名错误 |
| 404 | 资源不存在 | 队列未创建即被访问 |
| 409 | 冲突 | create() 时队列已存在;使用过期的 popReceipt 删除/更新消息 |
注意 switch 之外默认分支统一记录后,throw error 会重新抛出,由上层决定重试或终止;生产代码建议在此基础上叠加指数退避重试。
十一、TypeScript 类型速查
手册给出了完整的类型导入清单,按用途分组:
import {
// Clients
QueueServiceClient,
QueueClient,
// Authentication
StorageSharedKeyCredential,
AnonymousCredential,
// SAS
QueueSASPermissions,
AccountSASPermissions,
AccountSASServices,
AccountSASResourceTypes,
generateQueueSASQueryParameters,
generateAccountSASQueryParameters,
// Messages
DequeuedMessageItem,
PeekedMessageItem,
QueueSendMessageResponse,
QueueReceiveMessageResponse,
QueueUpdateMessageResponse,
// Queue
QueueItem,
QueueGetPropertiesResponse,
// Errors
RestError,
} from "@azure/storage-queue";
- 客户端:
QueueServiceClient(账号级)、QueueClient(队列级); - 认证:
StorageSharedKeyCredential、AnonymousCredential(匿名访问,配合 SAS 或公开队列); - 消息类型:
DequeuedMessageItem携带 popReceipt 与 dequeueCount,PeekedMessageItem无回执字段,与 6.3 节的语义限制呼应; - 响应类型:
QueueSendMessageResponse、QueueReceiveMessageResponse、QueueUpdateMessageResponse便于为调用声明精确返回结构。
十二、消息与队列的硬性限制
| Limit | Value |
|---|---|
| Max message size | 64 KB |
| Max visibility timeout | 7 days |
| Max time-to-live | 7 days (or -1 for infinite) |
| Max messages per receive | 32 |
| Default visibility timeout | 30 seconds |
在代码中注意:
- 64 KB 是消息体(经编码后)上限,超出会收到 HTTP 400;大载荷应拆片或改用 Blob + 引用;
- 可见性超时与 TTL 上限均为 7 天,
-1表示 TTL 无限; - 单次
receiveMessages最多 32 条; - 默认可见性超时 30 秒,未显式指定时按此执行。
十三、最佳实践清单
- 优先使用 DefaultAzureCredential——用 Azure AD(AAD)身份替代连接字符串/密钥,避免密钥散布与轮换成本;
- 处理后务必删除——防止可见性超时后消息重新可见导致的重复处理;
- 处理毒消息——将反复失败的消息转入死信队列(见 7.2);
- 设置合理的可见性超时——依据预估处理时长设定,避免过短导致重复消费或过长拖慢吞吐;
- 长任务续期可见性——用
updateMessage动态续期并同步更新 popReceipt(见 7.3); - 结构化数据用 JSON——对象先序列化为字符串再发送,消费端解析;
- 检查 dequeueCount——作为失败检测与毒消息判定的依据;
- 批量接收——单次接收多条以减少网络开销、提升吞吐。
十四、Node.js 与浏览器平台差异
| Feature | Node.js | Browser |
|---|---|---|
StorageSharedKeyCredential |
✅ | ❌ |
| SAS generation | ✅ | ❌ |
| DefaultAzureCredential | ✅ | ❌ |
| Anonymous/SAS access | ✅ | ✅ |
| All message operations | ✅ | ✅ |
解读:
- 共享密钥签名与 SAS 生成依赖 Node 的加密/缓冲能力,浏览器不可用;浏览器场景只能使用 SAS 令牌或匿名访问;
DefaultAzureCredential依赖 Azure 身份 SDK 的环境探测能力,同样仅限 Node.js;- 无论哪个平台,消息的收发、窥视、更新、删除等核心操作均可用(配合 SAS URL 使用)。
十五、结语与技能使用建议
azure-storage-queue-ts 技能完整覆盖了 Azure Queue Storage 在 TypeScript/JavaScript 生态中的核心操作面:从认证、客户端模型、队列与消息 CRUD,到可靠性编程范式(毒消息、可见性续期)、SAS 签发与错误处理。建议在实际项目中按以下节奏落地:
- 先通过 SKILL.md 确认任务匹配度与安全边界;
- 完整通读 references/detailed-guide.md(即本文的原始母本),按需加载对应小节;
- 将环境变量、认证方式与消费模式示例作为脚手架,结合所在环境的密钥管理与监控告警体系做生产化改造。
需要说明的是:技能手册中标注的版本号(12.x)与 Node.js 要求(>= 18.0.0)为编写时的参考值,接入项目前请以实际安装的 SDK 版本与官方发布说明为准进行校验。