【免费下载链接】flociLight, fluffy, and always free - The AWS Local Emulator alternative项目地址https://gitcode.com/gh_mirrors/fl/floci点击查看免费下载Floci 是一个轻量、免费、开源的 AWS 本地模拟器LocalStack 的替代方案其 SQS 服务在 docs/services/sqs.md 中有着完整的协议、操作与配置说明。本指南以该文档为骨架结合 SqsService.java 等核心源码与集成测试系统讲解 Floci SQS 的端点协议、队列操作、长轮询、可见性超时、FIFO 去重、死信队列DLQ以及消息迁移任务读完你可以直接用aws sqsCLI 在本地上手完整的队列工作流并理解其底层实现行为。协议与端点Query (XML) 与 JSON 1.0 双协议并存与真实 AWS SQS 一致Floci 的 SQS 同时支持两种请求协议Query (XML)经典 AWS 查询协议基于application/x-www-form-urlencoded表单参数响应为 XMLJSON 1.0application/x-amz-json-1.0请求与响应均为 JSON。统一端点为POST http://localhost:4566/协议分发在源码中有清晰体现SqsQueryHandler通过AwsQueryController接收 Query 协议请求并按Action参数做switch分发见 SqsQueryHandler.javaSqsJsonHandler则复用 DynamoDB 控制器的 JSON 1.0 端点为 SQS 目标请求提供相同的一组 Action见 SqsJsonHandler.java。两个处理器最终都调用同一个SqsService因此协议不同不影响业务语义——你可以放心混用两种客户端AWS CLI 走 Query较新的 SDK 走 JSON。支持的 Actions 一览Floci SQS 覆盖了 AWS SQS 的绝大多数常用操作包括标准队列与 FIFO 队列、批量操作、DLQ 与消息迁移任务、队列权限与标签Action说明CreateQueue创建标准队列或 FIFO 队列DeleteQueue删除队列ListQueues列出所有队列GetQueueUrl按名称查找队列 URLGetQueueAttributes获取队列配置属性SendMessage向队列发送消息ReceiveMessage轮询获取消息DeleteMessage确认并删除消息DeleteMessageBatch批量删除多条消息SendMessageBatch单次调用发送最多 10 条消息ChangeMessageVisibility延长或重置消息的可见性超时ChangeMessageVisibilityBatch批量修改可见性超时SetQueueAttributes更新队列配置TagQueue为队列添加标签UntagQueue移除队列标签ListQueueTags列出队列标签PurgeQueue清空队列中的全部消息ListDeadLetterSourceQueues查找将本队列作为 DLQ 的源队列StartMessageMoveTask启动 DLQ 消息迁移redrive任务ListMessageMoveTasks列出 DLQ 迁移任务CancelMessageMoveTask取消正在进行的迁移任务AddPermission向队列策略添加跨账户授权语句RemovePermission从队列策略移除授权语句从源码看SqsService为上述每个 Action 都提供了对应方法例如createQueueSqsService.java、sendMessageL606-L752、receiveMessageL882-L938以及整套 move task 生命周期L1114-L1339。队列 URL 格式Floci 的队列 URL 与 LocalStack / 真实 AWS 形态一致由基础地址、12 位账户 ID 与队列名组成http://localhost:4566/000000000000/queue-name源码中createQueue正是按baseUrl / accountId / queueName拼接队列 URLSqsService.java。值得注意的是存储键与查找逻辑会剥离主机名只保留路径部分extractQueuePathL1583-L1597因此无论客户端使用localhost还是localhost.localstack.cloud等主机名都能命中同一队列同时normalizeQueueUrlL1564-L1573允许调用方直接传裸队列名而不传完整 URL。快速上手完整的队列工作流示例以下示例可直接复制运行默认 Floci 监听localhost:4566export AWS_ENDPOINT_URLhttp://localhost:4566 # 创建标准队列 aws sqs create-queue --queue-name orders --endpoint-url $AWS_ENDPOINT_URL # 创建 FIFO 队列名称必须以 .fifo 结尾 aws sqs create-queue \ --queue-name orders.fifo \ --attributes FifoQueuetrue \ --endpoint-url $AWS_ENDPOINT_URL # 发送一条消息 QUEUE_URL$AWS_ENDPOINT_URL/000000000000/orders aws sqs send-message \ --queue-url $QUEUE_URL \ --message-body {event:order.placed,id:abc123} \ --endpoint-url $AWS_ENDPOINT_URL # 接收消息最多 10 条 aws sqs receive-message \ --queue-url $QUEUE_URL \ --max-number-of-messages 10 \ --endpoint-url $AWS_ENDPOINT_URL # 删除消息将 RECEIPT_HANDLE 替换为 ReceiveMessage 的返回值 aws sqs delete-message \ --queue-url $QUEUE_URL \ --receipt-handle RECEIPT_HANDLE \ --endpoint-url $AWS_ENDPOINT_URL # 配置死信队列先取 DLQ 的 ARN DLQ_ARN$(aws sqs get-queue-attributes \ --queue-url $AWS_ENDPOINT_URL/000000000000/orders-dlq \ --attribute-names QueueArn \ --query Attributes.QueueArn \ --output text \ --endpoint-url $AWS_ENDPOINT_URL) # 为 orders 队列挂上 RedrivePolicy接收 3 次后进入 DLQ aws sqs set-queue-attributes \ --queue-url $QUEUE_URL \ --attributes {\RedrivePolicy\:\{\\\deadLetterTargetArn\\\:\\\$DLQ_ARN\\\,\\\maxReceiveCount\\\:3}\} \ --endpoint-url $AWS_ENDPOINT_URLFIFO 队列方面源码会做双向校验FifoQueuetrue但名称不以.fifo结尾时报InvalidParameterValue反过来名称以.fifo结尾时会自动补上FifoQueuetrue属性SqsService.java。重复create-queue同名队列时如果属性存在冲突会返回QueueAlreadyExists属性一致则幂等返回已有队列L457-L475。本地检查端点不消费消息的 Peek 与一键清空在测试断言与调试场景下直接ReceiveMessage会消耗消息并推进接收计数破坏测试状态。为此 Floci 提供了一个LocalStack 兼容的检查端点MethodPath说明GET/_aws/sqs/messages?QueueUrlurl列出队列中的所有消息非破坏性DELETE/_aws/sqs/messages?QueueUrlurl清空队列中的所有消息GET返回队列中当前存在的每一条消息——包括 in-flight已被接收但未删除的消息且不会改变可见性超时也不会推进ApproximateReceiveCount更不会移除消息。DELETE等价于PurgeQueue会移除全部消息。该端点由 JAX-RS 控制器 SqsInspectionController.java 实现内部委托SqsService.peekMessages非破坏性快照SqsService.java与purgeQueue。响应形状{ messages: [ { MessageId: abc123, MD5OfBody: ..., Body: {\event\:\order.placed\}, ReceiptHandle: null, Attributes: { SentTimestamp: 1714000000000, ApproximateReceiveCount: 0 }, MessageAttributes: {} } ] }字段说明ReceiptHandle对尚未被接收过的消息为null一旦被ReceiveMessage认领则返回对应的接收句柄源码中Message的receiptHandle与visibleAt是瞬态字段见 Message.javaFIFO 消息若设置了对应字段Attributes中会额外包含MessageGroupId、MessageDeduplicationId和SequenceNumberSqsInspectionController.java消息属性MessageAttributes中会展开每个属性的DataType与StringValue/BinaryValue。使用示例QUEUE_URLhttp://localhost:4566/000000000000/orders # 不消费消息直接窥视队列内容包括 in-flight 消息 curl http://localhost:4566/_aws/sqs/messages?QueueUrl$QUEUE_URL # 一键清空队列 curl -X DELETE http://localhost:4566/_aws/sqs/messages?QueueUrl$QUEUE_URL注意QueueUrl查询参数缺失时端点会返回 HTTP 400 与 JSON 错误体SqsInspectionController.java。长轮询ReceiveMessage 的等待语义ReceiveMessage支持长轮询其行为与 AWS 对齐WaitTimeSeconds取值范围0 到 20超出范围返回InvalidParameterValue源码常量MAX_RECEIVE_WAIT_TIME_SECONDS 20SqsService.java请求省略WaitTimeSeconds时采用队列属性ReceiveMessageWaitTimeSeconds默认0即短轮询长轮询期间只要队列中有一条消息到达就立即返回不必等满等待时间。底层实现是receiveMessage内的循环 Object.wait每轮先尝试认领消息没有消息则最多等待 1 秒再重试直到耗尽等待预算SqsService.java。sendMessage写入消息后通过notifyReceivers唤醒正在阻塞的轮询者L855-L862实现「消息到达即刻返回」的低延迟长轮询。另一个细节是DeleteQueue会唤醒挂起的长轮询让它们感知队列已删除并空手返回避免删除后重建同名队列时旧轮询误消费新队列的消息L523-L527。# 为队列的所有消费者启用长轮询等待最多 20 秒 aws sqs set-queue-attributes \ --queue-url $QUEUE_URL \ --attributes ReceiveMessageWaitTimeSeconds20 \ --endpoint-url $AWS_ENDPOINT_URL队列属性详解GetQueueAttributes传--attribute-names All时Floci 返回与 AWS 标准队列一致的属性集合QueueArn、CreatedTimestamp、LastModifiedTimestamp、ApproximateNumberOfMessages、ApproximateNumberOfMessagesNotVisible、ApproximateNumberOfMessagesDelayed、VisibilityTimeout、MaximumMessageSize、MessageRetentionPeriod、DelaySeconds、ReceiveMessageWaitTimeSeconds和SqsManagedSseEnabled。以下几点行为值得注意Policy、RedrivePolicy、KmsMasterKeyId仅在设置后才会出现在返回中FIFO 队列额外报告FifoQueue与ContentBasedDeduplicationApproximateNumberOfMessages*三个计数由GuardedMessageQueue.messageCounts()实时计算可见消息计为 visible已被认领有 receipt handle且不可见计为 in-flight未认领但等待延迟到期的计为 delayedGuardedMessageQueue.java属性过滤只传部分属性名时仅返回请求列表中存在的属性SqsService.java。MaximumMessageSize 的取值边界与语义MaximumMessageSize默认值为1048576字节1 MiB这也是 AWS 自 2025 年 8 月起将默认值与上限同时从262144256 KiB提升后的新值。Floci 的取值规则源码常量 SqsService.javaCreateQueue与SetQueueAttributes对范围10241 KiB到 10485761 MiB之外的值拒绝返回InvalidAttributeValuevalidateMaximumMessageSizeL771-L788通过环境变量FLOCI_SERVICES_SQS_MAX_MESSAGE_SIZE调高该值时接受的上限随之抬高你可以配置更大的默认消息尺寸调低该变量时只改变新建队列得到的默认值接受上限仍保持 AWS 上限 1048576——即仍可显式把队列设置为 1048576。发送路径同样强制执行该上限sendMessage按「UTF-8 消息体字节 每条消息属性名称 类型 值字节」计算线级总大小computeMessageSizeL823-L841超过队列MaximumMessageSize时返回InvalidParameterValueSendMessageBatch则按整批总大小校验超限返回顶层错误BatchRequestTooLongL806-L817。SqsManagedSseEnabled 的派生逻辑SqsManagedSseEnabled的行为与 AWS 对齐未设置KmsMasterKeyId的队列为true设置 KMS 密钥后为false。它是读取时派生而非存储的属性SqsService.java因此清除KmsMasterKeyId后队列会回到true除非你显式设置过SqsManagedSseEnabled此时以你设置的值false为准。需要说明AWS 官方文档并未清晰描述清除 KMS 密钥后的行为因此「清除后回落到默认值」是 Floci 自身的设计选择而非照搬 AWS 的行为。环境变量配置SQS 服务可通过以下环境变量配置对应源码 EmulatorConfig.java 中的SqsServiceConfig变量默认值说明FLOCI_SERVICES_SQS_ENABLEDtrue启用或禁用 SQS 服务FLOCI_SERVICES_SQS_DEFAULT_VISIBILITY_TIMEOUT30默认消息可见性超时秒FLOCI_SERVICES_SQS_MAX_MESSAGE_SIZE1048576最大消息尺寸字节1 MiBFLOCI_SERVICES_SQS_CLEAR_FIFO_DEDUPLICATION_CACHE_ON_PURGEfalse为true时PurgeQueue同时清除该队列及订阅它的 SNS FIFO 主题的 FIFO 去重缓存配置项在SqsService构造时注入defaultVisibilityTimeout用作新建队列的VisibilityTimeout默认值maxMessageSize用作新建队列的MaximumMessageSize默认值clearFifoDeduplicationCacheOnPurge控制purgeQueue是否联动清理去重缓存SqsService.java。启用开关enabled()由服务注册层消费用于决定是否挂载 SQS 相关端点其它 Floci 服务的环境变量约定可参考 docs/configuration/environment-variables.md。FIFO 队列有序性、组锁定与 5 分钟去重窗口FIFO 队列是 Floci SQS 支持最深入的部分之一其实现要点如下强制的MessageGroupId与组内串行向 FIFO 队列发送消息必须携带MessageGroupId否则返回MissingParameter。接收端GuardedMessageQueue.claimFifoGuardedMessageQueue.java实现跨调用的组锁定某个组已有 in-flight 消息时后续ReceiveMessage调用会跳过该组直到消息被删除或可见性超时到期——保证同一组内消息的有序消费。单次调用内可以返回同一组的多条消息保持插入顺序上限为MaxNumberOfMessages。被延迟DelaySeconds等待、从未被认领的消息不会锁定其组。5 分钟去重窗口FIFO 队列维护 5 分钟常量DEDUP_WINDOW_SECONDS 300SqsService.java的去重窗口显式提供MessageDeduplicationId时按该 ID 去重未提供时若队列开启ContentBasedDeduplicationtrue则用消息体的 MD5 作为去重 IDcomputeMd5两者都没有时返回InvalidParameterValue窗口内的重复消息返回原消息的MessageId与SequenceNumber但响应的 MD5 按本次请求的 body 与属性重新计算避免 SDK 客户端的 MD5 校验失败L676-L709支持DeduplicationScopemessageGroup此时去重按MessageGroupId NUL MessageDeduplicationId复合键进行不同组的相同去重 ID 不算重复L680-L684。序列号FIFO 消息的SequenceNumber由进程内AtomicLong单调递增分配L71。FIFO 队列的延迟只能走队列级DelaySecondsSendMessage请求级delaySeconds会被忽略并回落到队列属性L652-L656。FIFO 专属行为在 SqsFifoIntegrationTest.java 与 SqsJsonProtocolTest.java 中有系统性覆盖包括组锁定、去重、内容去重与DeduplicationScope等场景。可见性超时与消息生命周期消息生命周期围绕「可见性」展开核心状态机在GuardedMessageQueue.claimVisibleMessagesGuardedMessageQueue.java每条消息在认领时ReceiveCount 1记录首次接收时间戳生成新的ReceiptHandleUUID并将visibleAt置为当前时间 可见性超时tryClaimL95-L113认领时若未显式传VisibilityTimeout使用队列属性默认来自FLOCI_SERVICES_SQS_DEFAULT_VISIBILITY_TIMEOUT即 30 秒ChangeMessageVisibility/ChangeMessageVisibilityBatch通过ReceiptHandle定位消息并重置visibleAtL170-L181无效句柄返回ReceiptHandleIsInvalidDeleteMessage同样按ReceiptHandle匹配删除找不到句柄返回ReceiptHandleIsInvalidSqsService.java所有复合操作认领、删除、变更可见性、清空都在ReentrantLock保护下原子执行并同步持久化到存储后端persist因此模拟器重启后消息与队列状态可恢复。死信队列DLQ与消息迁移任务DLQ 投递队列设置了RedrivePolicydeadLetterTargetArnmaxReceiveCount后消息被认领的次数超过maxReceiveCount即成为 DLQ 候选由receiveMessage直接从源队列移除并投递到目标 DLQSqsService.java。RedrivePolicy会被解析缓存redrivePolicyCacheL949-L968。ListDeadLetterSourceQueues反向扫描所有队列的RedrivePolicy找出以目标队列为 DLQ 的源队列L1100-L1112。消息迁移任务AWS 的 DLQ redrive 能力完整支持三个操作StartMessageMoveTask要求SourceArn指向一个被其他队列的RedrivePolicy引用的 DLQ同一源队列同一时刻只允许一个活跃任务并发启动会返回InvalidParameterValue。支持可选DestinationArn不传时消息会被送回其originalSourceQueueUrl记录的来源队列该字段在消息进入 DLQ 时记录见 L1001-L1004。任务由后台线程执行MaxNumberOfMessagesPerSecond控制限速——首条消息在请求线程内同步迁移让调用方在StartMessageMoveTask返回后立即轮询目标队列就能看到消息已移动L1182-L1197ListMessageMoveTasks按SourceArn过滤任务并按开始时间倒序返回任务状态包括RUNNING、CANCELLING、CANCELLED、COMPLETED终止态任务保留 1 小时TERMINAL_MOVE_TASK_TTL且每个源队列最多保留 10 条MAX_TERMINAL_MOVE_TASKSL43-L44CancelMessageMoveTask将任务从RUNNING置为CANCELLING并通过CountDownLatch立刻唤醒限速休眠中的 worker最终状态落为CANCELLED并返回已迁移数量L1321-L1339。迁移时每条消息通过copyForRedrive复制保留 ID 与内容接收计数等「本次接收状态」清零重来保证目标队列中的消息开始全新生命周期投递失败时消息会被放回源队列头部保持队列顺序restoreFirstGuardedMessageQueue.java。队列权限与标签AddPermission校验Label非空、AWSAccountId与ActionName必填然后向队列的Policy属性追加一条SidLabel、EffectAllow、Principal.AWS为各账户arn:aws:iam::account:root、Action为SQS:action的语句Label重复返回InvalidParameterValueSqsService.javaRemovePermission按LabelSid删除语句删空后直接移除Policy属性L1465-L1500TagQueue/UntagQueue/ListQueueTags标签作为队列模型字段持久化存储Queue.java对应操作见 SqsService.java。兼容性验证与测试覆盖Floci 仓库对 SQS 的兼容性有多个维度的验证Java 单元/集成测试SqsIntegrationTest.java、SqsServiceTest.java、SqsFifoIntegrationTest.java、SqsJsonProtocolTest.java、SqsInspectionControllerIntegrationTest.java 与 GuardedMessageQueueTest.java覆盖协议分发、FIFO 语义、检查端点与并发安全Node.js SDK 测试sqs.test.ts 使用 AWS SDK v3 走真实协议路径验证端到端行为多语言 SDK 测试矩阵仓库还提供 Go、Java、Python 的 SQS 测试如 sqs_test.go、test_sqs.py确保不同语言 SDK 的序列化差异都能被兼容Terraform/OpenTofu/CDK 兼容测试compat-terraform 与 compat-cdk 目录中包含 SQS 相关的基础设施编排兼容性验证。小结Floci 的 SQS 模拟服务以 SqsService.java 为单一业务核心通过 QueryXML与 JSON 1.0 双协议对外暴露 20 个 AWS SQS Action覆盖标准/FIFO 队列、长轮询、可见性超时、批量操作、DLQ、消息迁移任务、队列权限与标签并提供 LocalStack 兼容的/_aws/sqs/messages检查端点用于非破坏性测试断言。无论是本地开发调试、CI 中的集成测试还是对照 docs/services/sqs.md 查阅协议细节都可以直接使用aws sqsCLI 或任意语言的 AWS SDK 以--endpoint-url http://localhost:4566接入获得与 AWS 高度一致的语义行为。赞分享【免费下载链接】flociLight, fluffy, and always free - The AWS Local Emulator alternative项目地址https://gitcode.com/gh_mirrors/fl/floci点击查看免费下载相关推荐Strapi 数据迁移 WebSocket 协议解析Remote Data Transfer 的 Dispatcher 消息模型与传输生命周期Strapi 数据迁移 WebSocket 协议解析Remote Data Transfer 的 Dispatcher 消息模型与传输生命周期 Strapi后端CMS前端LocalStack SQS本地消息队列服务完全使用指南LocalStack SQS本地消息队列服务完全使用指南 想要在本地开发和测试AWS SQS消息队列服务LocalStack为你提供了完美的解决方案解密convformer_m36.sail_in22kMetaFormer基线模型的42M激活值计算奥秘解密convformer_m36.sail_in22kMetaFormer基线模型的42M激活值计算奥秘 convformer_m36.sail_in22k是上一篇MLflow隐私保护差分隐私与联邦学习的合规性管理下一篇3分钟搞定Filament多环境配置从开发到生产的无缝切换指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
【免费下载链接】flociLight, fluffy, and always free - The AWS Local Emulator alternative项目地址https://gitcode.com/gh_mirrors/fl/floci点击查看免费下载Floci 是一个轻量、免费、开源的 AWS 本地模拟器LocalStack 的替代方案其 SQS 服务在 docs/services/sqs.md 中有着完整的协议、操作与配置说明。本指南以该文档为骨架结合 SqsService.java 等核心源码与集成测试系统讲解 Floci SQS 的端点协议、队列操作、长轮询、可见性超时、FIFO 去重、死信队列DLQ以及消息迁移任务读完你可以直接用aws sqsCLI 在本地上手完整的队列工作流并理解其底层实现行为。协议与端点Query (XML) 与 JSON 1.0 双协议并存与真实 AWS SQS 一致Floci 的 SQS 同时支持两种请求协议Query (XML)经典 AWS 查询协议基于application/x-www-form-urlencoded表单参数响应为 XMLJSON 1.0application/x-amz-json-1.0请求与响应均为 JSON。统一端点为POST http://localhost:4566/协议分发在源码中有清晰体现SqsQueryHandler通过AwsQueryController接收 Query 协议请求并按Action参数做switch分发见 SqsQueryHandler.javaSqsJsonHandler则复用 DynamoDB 控制器的 JSON 1.0 端点为 SQS 目标请求提供相同的一组 Action见 SqsJsonHandler.java。两个处理器最终都调用同一个SqsService因此协议不同不影响业务语义——你可以放心混用两种客户端AWS CLI 走 Query较新的 SDK 走 JSON。支持的 Actions 一览Floci SQS 覆盖了 AWS SQS 的绝大多数常用操作包括标准队列与 FIFO 队列、批量操作、DLQ 与消息迁移任务、队列权限与标签Action说明CreateQueue创建标准队列或 FIFO 队列DeleteQueue删除队列ListQueues列出所有队列GetQueueUrl按名称查找队列 URLGetQueueAttributes获取队列配置属性SendMessage向队列发送消息ReceiveMessage轮询获取消息DeleteMessage确认并删除消息DeleteMessageBatch批量删除多条消息SendMessageBatch单次调用发送最多 10 条消息ChangeMessageVisibility延长或重置消息的可见性超时ChangeMessageVisibilityBatch批量修改可见性超时SetQueueAttributes更新队列配置TagQueue为队列添加标签UntagQueue移除队列标签ListQueueTags列出队列标签PurgeQueue清空队列中的全部消息ListDeadLetterSourceQueues查找将本队列作为 DLQ 的源队列StartMessageMoveTask启动 DLQ 消息迁移redrive任务ListMessageMoveTasks列出 DLQ 迁移任务CancelMessageMoveTask取消正在进行的迁移任务AddPermission向队列策略添加跨账户授权语句RemovePermission从队列策略移除授权语句从源码看SqsService为上述每个 Action 都提供了对应方法例如createQueueSqsService.java、sendMessageL606-L752、receiveMessageL882-L938以及整套 move task 生命周期L1114-L1339。队列 URL 格式Floci 的队列 URL 与 LocalStack / 真实 AWS 形态一致由基础地址、12 位账户 ID 与队列名组成http://localhost:4566/000000000000/queue-name源码中createQueue正是按baseUrl / accountId / queueName拼接队列 URLSqsService.java。值得注意的是存储键与查找逻辑会剥离主机名只保留路径部分extractQueuePathL1583-L1597因此无论客户端使用localhost还是localhost.localstack.cloud等主机名都能命中同一队列同时normalizeQueueUrlL1564-L1573允许调用方直接传裸队列名而不传完整 URL。快速上手完整的队列工作流示例以下示例可直接复制运行默认 Floci 监听localhost:4566export AWS_ENDPOINT_URLhttp://localhost:4566 # 创建标准队列 aws sqs create-queue --queue-name orders --endpoint-url $AWS_ENDPOINT_URL # 创建 FIFO 队列名称必须以 .fifo 结尾 aws sqs create-queue \ --queue-name orders.fifo \ --attributes FifoQueuetrue \ --endpoint-url $AWS_ENDPOINT_URL # 发送一条消息 QUEUE_URL$AWS_ENDPOINT_URL/000000000000/orders aws sqs send-message \ --queue-url $QUEUE_URL \ --message-body {event:order.placed,id:abc123} \ --endpoint-url $AWS_ENDPOINT_URL # 接收消息最多 10 条 aws sqs receive-message \ --queue-url $QUEUE_URL \ --max-number-of-messages 10 \ --endpoint-url $AWS_ENDPOINT_URL # 删除消息将 RECEIPT_HANDLE 替换为 ReceiveMessage 的返回值 aws sqs delete-message \ --queue-url $QUEUE_URL \ --receipt-handle RECEIPT_HANDLE \ --endpoint-url $AWS_ENDPOINT_URL # 配置死信队列先取 DLQ 的 ARN DLQ_ARN$(aws sqs get-queue-attributes \ --queue-url $AWS_ENDPOINT_URL/000000000000/orders-dlq \ --attribute-names QueueArn \ --query Attributes.QueueArn \ --output text \ --endpoint-url $AWS_ENDPOINT_URL) # 为 orders 队列挂上 RedrivePolicy接收 3 次后进入 DLQ aws sqs set-queue-attributes \ --queue-url $QUEUE_URL \ --attributes {\RedrivePolicy\:\{\\\deadLetterTargetArn\\\:\\\$DLQ_ARN\\\,\\\maxReceiveCount\\\:3}\} \ --endpoint-url $AWS_ENDPOINT_URLFIFO 队列方面源码会做双向校验FifoQueuetrue但名称不以.fifo结尾时报InvalidParameterValue反过来名称以.fifo结尾时会自动补上FifoQueuetrue属性SqsService.java。重复create-queue同名队列时如果属性存在冲突会返回QueueAlreadyExists属性一致则幂等返回已有队列L457-L475。本地检查端点不消费消息的 Peek 与一键清空在测试断言与调试场景下直接ReceiveMessage会消耗消息并推进接收计数破坏测试状态。为此 Floci 提供了一个LocalStack 兼容的检查端点MethodPath说明GET/_aws/sqs/messages?QueueUrlurl列出队列中的所有消息非破坏性DELETE/_aws/sqs/messages?QueueUrlurl清空队列中的所有消息GET返回队列中当前存在的每一条消息——包括 in-flight已被接收但未删除的消息且不会改变可见性超时也不会推进ApproximateReceiveCount更不会移除消息。DELETE等价于PurgeQueue会移除全部消息。该端点由 JAX-RS 控制器 SqsInspectionController.java 实现内部委托SqsService.peekMessages非破坏性快照SqsService.java与purgeQueue。响应形状{ messages: [ { MessageId: abc123, MD5OfBody: ..., Body: {\event\:\order.placed\}, ReceiptHandle: null, Attributes: { SentTimestamp: 1714000000000, ApproximateReceiveCount: 0 }, MessageAttributes: {} } ] }字段说明ReceiptHandle对尚未被接收过的消息为null一旦被ReceiveMessage认领则返回对应的接收句柄源码中Message的receiptHandle与visibleAt是瞬态字段见 Message.javaFIFO 消息若设置了对应字段Attributes中会额外包含MessageGroupId、MessageDeduplicationId和SequenceNumberSqsInspectionController.java消息属性MessageAttributes中会展开每个属性的DataType与StringValue/BinaryValue。使用示例QUEUE_URLhttp://localhost:4566/000000000000/orders # 不消费消息直接窥视队列内容包括 in-flight 消息 curl http://localhost:4566/_aws/sqs/messages?QueueUrl$QUEUE_URL # 一键清空队列 curl -X DELETE http://localhost:4566/_aws/sqs/messages?QueueUrl$QUEUE_URL注意QueueUrl查询参数缺失时端点会返回 HTTP 400 与 JSON 错误体SqsInspectionController.java。长轮询ReceiveMessage 的等待语义ReceiveMessage支持长轮询其行为与 AWS 对齐WaitTimeSeconds取值范围0 到 20超出范围返回InvalidParameterValue源码常量MAX_RECEIVE_WAIT_TIME_SECONDS 20SqsService.java请求省略WaitTimeSeconds时采用队列属性ReceiveMessageWaitTimeSeconds默认0即短轮询长轮询期间只要队列中有一条消息到达就立即返回不必等满等待时间。底层实现是receiveMessage内的循环 Object.wait每轮先尝试认领消息没有消息则最多等待 1 秒再重试直到耗尽等待预算SqsService.java。sendMessage写入消息后通过notifyReceivers唤醒正在阻塞的轮询者L855-L862实现「消息到达即刻返回」的低延迟长轮询。另一个细节是DeleteQueue会唤醒挂起的长轮询让它们感知队列已删除并空手返回避免删除后重建同名队列时旧轮询误消费新队列的消息L523-L527。# 为队列的所有消费者启用长轮询等待最多 20 秒 aws sqs set-queue-attributes \ --queue-url $QUEUE_URL \ --attributes ReceiveMessageWaitTimeSeconds20 \ --endpoint-url $AWS_ENDPOINT_URL队列属性详解GetQueueAttributes传--attribute-names All时Floci 返回与 AWS 标准队列一致的属性集合QueueArn、CreatedTimestamp、LastModifiedTimestamp、ApproximateNumberOfMessages、ApproximateNumberOfMessagesNotVisible、ApproximateNumberOfMessagesDelayed、VisibilityTimeout、MaximumMessageSize、MessageRetentionPeriod、DelaySeconds、ReceiveMessageWaitTimeSeconds和SqsManagedSseEnabled。以下几点行为值得注意Policy、RedrivePolicy、KmsMasterKeyId仅在设置后才会出现在返回中FIFO 队列额外报告FifoQueue与ContentBasedDeduplicationApproximateNumberOfMessages*三个计数由GuardedMessageQueue.messageCounts()实时计算可见消息计为 visible已被认领有 receipt handle且不可见计为 in-flight未认领但等待延迟到期的计为 delayedGuardedMessageQueue.java属性过滤只传部分属性名时仅返回请求列表中存在的属性SqsService.java。MaximumMessageSize 的取值边界与语义MaximumMessageSize默认值为1048576字节1 MiB这也是 AWS 自 2025 年 8 月起将默认值与上限同时从262144256 KiB提升后的新值。Floci 的取值规则源码常量 SqsService.javaCreateQueue与SetQueueAttributes对范围10241 KiB到 10485761 MiB之外的值拒绝返回InvalidAttributeValuevalidateMaximumMessageSizeL771-L788通过环境变量FLOCI_SERVICES_SQS_MAX_MESSAGE_SIZE调高该值时接受的上限随之抬高你可以配置更大的默认消息尺寸调低该变量时只改变新建队列得到的默认值接受上限仍保持 AWS 上限 1048576——即仍可显式把队列设置为 1048576。发送路径同样强制执行该上限sendMessage按「UTF-8 消息体字节 每条消息属性名称 类型 值字节」计算线级总大小computeMessageSizeL823-L841超过队列MaximumMessageSize时返回InvalidParameterValueSendMessageBatch则按整批总大小校验超限返回顶层错误BatchRequestTooLongL806-L817。SqsManagedSseEnabled 的派生逻辑SqsManagedSseEnabled的行为与 AWS 对齐未设置KmsMasterKeyId的队列为true设置 KMS 密钥后为false。它是读取时派生而非存储的属性SqsService.java因此清除KmsMasterKeyId后队列会回到true除非你显式设置过SqsManagedSseEnabled此时以你设置的值false为准。需要说明AWS 官方文档并未清晰描述清除 KMS 密钥后的行为因此「清除后回落到默认值」是 Floci 自身的设计选择而非照搬 AWS 的行为。环境变量配置SQS 服务可通过以下环境变量配置对应源码 EmulatorConfig.java 中的SqsServiceConfig变量默认值说明FLOCI_SERVICES_SQS_ENABLEDtrue启用或禁用 SQS 服务FLOCI_SERVICES_SQS_DEFAULT_VISIBILITY_TIMEOUT30默认消息可见性超时秒FLOCI_SERVICES_SQS_MAX_MESSAGE_SIZE1048576最大消息尺寸字节1 MiBFLOCI_SERVICES_SQS_CLEAR_FIFO_DEDUPLICATION_CACHE_ON_PURGEfalse为true时PurgeQueue同时清除该队列及订阅它的 SNS FIFO 主题的 FIFO 去重缓存配置项在SqsService构造时注入defaultVisibilityTimeout用作新建队列的VisibilityTimeout默认值maxMessageSize用作新建队列的MaximumMessageSize默认值clearFifoDeduplicationCacheOnPurge控制purgeQueue是否联动清理去重缓存SqsService.java。启用开关enabled()由服务注册层消费用于决定是否挂载 SQS 相关端点其它 Floci 服务的环境变量约定可参考 docs/configuration/environment-variables.md。FIFO 队列有序性、组锁定与 5 分钟去重窗口FIFO 队列是 Floci SQS 支持最深入的部分之一其实现要点如下强制的MessageGroupId与组内串行向 FIFO 队列发送消息必须携带MessageGroupId否则返回MissingParameter。接收端GuardedMessageQueue.claimFifoGuardedMessageQueue.java实现跨调用的组锁定某个组已有 in-flight 消息时后续ReceiveMessage调用会跳过该组直到消息被删除或可见性超时到期——保证同一组内消息的有序消费。单次调用内可以返回同一组的多条消息保持插入顺序上限为MaxNumberOfMessages。被延迟DelaySeconds等待、从未被认领的消息不会锁定其组。5 分钟去重窗口FIFO 队列维护 5 分钟常量DEDUP_WINDOW_SECONDS 300SqsService.java的去重窗口显式提供MessageDeduplicationId时按该 ID 去重未提供时若队列开启ContentBasedDeduplicationtrue则用消息体的 MD5 作为去重 IDcomputeMd5两者都没有时返回InvalidParameterValue窗口内的重复消息返回原消息的MessageId与SequenceNumber但响应的 MD5 按本次请求的 body 与属性重新计算避免 SDK 客户端的 MD5 校验失败L676-L709支持DeduplicationScopemessageGroup此时去重按MessageGroupId NUL MessageDeduplicationId复合键进行不同组的相同去重 ID 不算重复L680-L684。序列号FIFO 消息的SequenceNumber由进程内AtomicLong单调递增分配L71。FIFO 队列的延迟只能走队列级DelaySecondsSendMessage请求级delaySeconds会被忽略并回落到队列属性L652-L656。FIFO 专属行为在 SqsFifoIntegrationTest.java 与 SqsJsonProtocolTest.java 中有系统性覆盖包括组锁定、去重、内容去重与DeduplicationScope等场景。可见性超时与消息生命周期消息生命周期围绕「可见性」展开核心状态机在GuardedMessageQueue.claimVisibleMessagesGuardedMessageQueue.java每条消息在认领时ReceiveCount 1记录首次接收时间戳生成新的ReceiptHandleUUID并将visibleAt置为当前时间 可见性超时tryClaimL95-L113认领时若未显式传VisibilityTimeout使用队列属性默认来自FLOCI_SERVICES_SQS_DEFAULT_VISIBILITY_TIMEOUT即 30 秒ChangeMessageVisibility/ChangeMessageVisibilityBatch通过ReceiptHandle定位消息并重置visibleAtL170-L181无效句柄返回ReceiptHandleIsInvalidDeleteMessage同样按ReceiptHandle匹配删除找不到句柄返回ReceiptHandleIsInvalidSqsService.java所有复合操作认领、删除、变更可见性、清空都在ReentrantLock保护下原子执行并同步持久化到存储后端persist因此模拟器重启后消息与队列状态可恢复。死信队列DLQ与消息迁移任务DLQ 投递队列设置了RedrivePolicydeadLetterTargetArnmaxReceiveCount后消息被认领的次数超过maxReceiveCount即成为 DLQ 候选由receiveMessage直接从源队列移除并投递到目标 DLQSqsService.java。RedrivePolicy会被解析缓存redrivePolicyCacheL949-L968。ListDeadLetterSourceQueues反向扫描所有队列的RedrivePolicy找出以目标队列为 DLQ 的源队列L1100-L1112。消息迁移任务AWS 的 DLQ redrive 能力完整支持三个操作StartMessageMoveTask要求SourceArn指向一个被其他队列的RedrivePolicy引用的 DLQ同一源队列同一时刻只允许一个活跃任务并发启动会返回InvalidParameterValue。支持可选DestinationArn不传时消息会被送回其originalSourceQueueUrl记录的来源队列该字段在消息进入 DLQ 时记录见 L1001-L1004。任务由后台线程执行MaxNumberOfMessagesPerSecond控制限速——首条消息在请求线程内同步迁移让调用方在StartMessageMoveTask返回后立即轮询目标队列就能看到消息已移动L1182-L1197ListMessageMoveTasks按SourceArn过滤任务并按开始时间倒序返回任务状态包括RUNNING、CANCELLING、CANCELLED、COMPLETED终止态任务保留 1 小时TERMINAL_MOVE_TASK_TTL且每个源队列最多保留 10 条MAX_TERMINAL_MOVE_TASKSL43-L44CancelMessageMoveTask将任务从RUNNING置为CANCELLING并通过CountDownLatch立刻唤醒限速休眠中的 worker最终状态落为CANCELLED并返回已迁移数量L1321-L1339。迁移时每条消息通过copyForRedrive复制保留 ID 与内容接收计数等「本次接收状态」清零重来保证目标队列中的消息开始全新生命周期投递失败时消息会被放回源队列头部保持队列顺序restoreFirstGuardedMessageQueue.java。队列权限与标签AddPermission校验Label非空、AWSAccountId与ActionName必填然后向队列的Policy属性追加一条SidLabel、EffectAllow、Principal.AWS为各账户arn:aws:iam::account:root、Action为SQS:action的语句Label重复返回InvalidParameterValueSqsService.javaRemovePermission按LabelSid删除语句删空后直接移除Policy属性L1465-L1500TagQueue/UntagQueue/ListQueueTags标签作为队列模型字段持久化存储Queue.java对应操作见 SqsService.java。兼容性验证与测试覆盖Floci 仓库对 SQS 的兼容性有多个维度的验证Java 单元/集成测试SqsIntegrationTest.java、SqsServiceTest.java、SqsFifoIntegrationTest.java、SqsJsonProtocolTest.java、SqsInspectionControllerIntegrationTest.java 与 GuardedMessageQueueTest.java覆盖协议分发、FIFO 语义、检查端点与并发安全Node.js SDK 测试sqs.test.ts 使用 AWS SDK v3 走真实协议路径验证端到端行为多语言 SDK 测试矩阵仓库还提供 Go、Java、Python 的 SQS 测试如 sqs_test.go、test_sqs.py确保不同语言 SDK 的序列化差异都能被兼容Terraform/OpenTofu/CDK 兼容测试compat-terraform 与 compat-cdk 目录中包含 SQS 相关的基础设施编排兼容性验证。小结Floci 的 SQS 模拟服务以 SqsService.java 为单一业务核心通过 QueryXML与 JSON 1.0 双协议对外暴露 20 个 AWS SQS Action覆盖标准/FIFO 队列、长轮询、可见性超时、批量操作、DLQ、消息迁移任务、队列权限与标签并提供 LocalStack 兼容的/_aws/sqs/messages检查端点用于非破坏性测试断言。无论是本地开发调试、CI 中的集成测试还是对照 docs/services/sqs.md 查阅协议细节都可以直接使用aws sqsCLI 或任意语言的 AWS SDK 以--endpoint-url http://localhost:4566接入获得与 AWS 高度一致的语义行为。赞分享【免费下载链接】flociLight, fluffy, and always free - The AWS Local Emulator alternative项目地址https://gitcode.com/gh_mirrors/fl/floci点击查看免费下载相关推荐Strapi 数据迁移 WebSocket 协议解析Remote Data Transfer 的 Dispatcher 消息模型与传输生命周期Strapi 数据迁移 WebSocket 协议解析Remote Data Transfer 的 Dispatcher 消息模型与传输生命周期 Strapi后端CMS前端LocalStack SQS本地消息队列服务完全使用指南LocalStack SQS本地消息队列服务完全使用指南 想要在本地开发和测试AWS SQS消息队列服务LocalStack为你提供了完美的解决方案解密convformer_m36.sail_in22kMetaFormer基线模型的42M激活值计算奥秘解密convformer_m36.sail_in22kMetaFormer基线模型的42M激活值计算奥秘 convformer_m36.sail_in22k是上一篇MLflow隐私保护差分隐私与联邦学习的合规性管理下一篇3分钟搞定Filament多环境配置从开发到生产的无缝切换指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
