{"record":{"id":"dd22e5676316504e","repo":"YunaiV/ruoyi-vue-pro","slug":"error-dd22e5","errorCode":null,"errorMessage":"二进制消息编码失败: {}","messagePattern":"二进制消息编码失败: (.+?)","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"yudao-module-iot/yudao-module-iot-gateway/src/main/java/cn/iocoder/yudao/module/iot/gateway/serialize/binary/IotBinarySerializer.java","lineNumber":89,"sourceCode":"    @Override\n    public IotSerializeTypeEnum getType() {\n        return IotSerializeTypeEnum.BINARY;\n    }\n\n    @Override\n    public byte[] serialize(IotDeviceMessage message) {\n        Assert.notNull(message, \"消息不能为空\");\n        Assert.notBlank(message.getMethod(), \"消息方法不能为空\");\n        try {\n            // 1. 确定消息类型\n            byte messageType = determineMessageType(message);\n            // 2. 构建消息体\n            byte[] bodyData = buildMessageBody(message, messageType);\n            // 3. 构建完整消息\n            return buildCompleteMessage(message, messageType, bodyData);\n        } catch (Exception e) {\n            log.error(\"[encode][二进制消息编码失败，消息: {}]\", message, e);\n            throw new RuntimeException(\"二进制消息编码失败: \" + e.getMessage(), e);\n        }\n    }\n\n    @Override\n    public IotDeviceMessage deserialize(byte[] bytes) {\n        Assert.notNull(bytes, \"待解码数据不能为空\");\n        Assert.isTrue(bytes.length >= MIN_MESSAGE_LENGTH, \"数据包长度不足\");\n        try {\n            Buffer buffer = Buffer.buffer(bytes);\n            int index = 0;\n\n            // 1. 验证魔术字\n            byte magic = buffer.getByte(index++);\n            Assert.isTrue(magic == MAGIC_NUMBER, \"无效的协议魔术字: \" + magic);\n\n            // 2. 验证版本号\n            byte version = buffer.getByte(index++);\n            Assert.isTrue(version == PROTOCOL_VERSION, \"不支持的协议版本: \" + version);","sourceCodeStart":71,"sourceCodeEnd":107,"githubUrl":"https://github.com/YunaiV/ruoyi-vue-pro/blob/0418084e222612af2fc1141f566af454f9236ab1/yudao-module-iot/yudao-module-iot-gateway/src/main/java/cn/iocoder/yudao/module/iot/gateway/serialize/binary/IotBinarySerializer.java#L71-L107","documentation":"IotBinarySerializer.serialize wraps any Exception thrown while building a binary frame — determineMessageType, buildMessageBody, or buildCompleteMessage — and rethrows it as a RuntimeException whose message and cause carry the root failure. The method first asserts the message and its method field are non-null/non-blank (those throw IllegalArgumentException directly, NOT via this wrapper). So this specific wrapped error means the message passed preconditions but the binary encoding logic itself broke.","triggerScenarios":"Passing an IotDeviceMessage whose method is present but whose data/type cannot be mapped by determineMessageType; a payload field exceeding the fixed-width binary layout limits; an IotDeviceMessage subclass unrecognized by buildMessageBody; numeric/length overflow while writing the Buffer.","commonSituations":"Introducing a new IotDeviceMessage subclass without extending determineMessageType/buildMessageBody; sending a message with fields that violate the binary protocol contract; encoding a method name longer than the wire format allows.","solutions":["Read the logged cause (log.error \"[encode][二进制消息编码失败\" prints the full exception) — the wrapped Throwable identifies the real failing step.","Ensure the IotDeviceMessage subclass you serialize is one the binary protocol knows how to encode (check determineMessageType covers it).","Prefer IotSerializeTypeEnum.JSON for message types the binary serializer does not yet support.","Add the missing message-type branch in buildMessageBody/determineMessageType and a round-trip serialize+deserialize unit test."],"exampleFix":"// before\nbyte[] bytes = binarySerializer.serialize(message); // RuntimeException on encode\n\n// after\nbyte[] bytes;\ntry {\n    bytes = binarySerializer.serialize(message);\n} catch (RuntimeException e) {\n    log.error(\"[encode][failed for method {}]\", message.getMethod(), e);\n    bytes = jsonSerializer.serialize(message); // graceful fallback to JSON\n}","handlingStrategy":"try-catch","validationCode":"// Validate the message is one the binary protocol claims to support before serializing\nif (message == null || StrUtil.isBlank(message.getMethod())) {\n    throw new IllegalArgumentException(\"message/method required\");\n}\n// If you have a known set of supported message types, check membership here:\n// if (!SUPPORTED_BINARY_MESSAGE_TYPES.contains(message.getClass())) use JSON instead.","typeGuard":null,"tryCatchPattern":"byte[] bytes;\ntry {\n    bytes = binarySerializer.serialize(message);\n} catch (RuntimeException e) {\n    // e.getCause() holds the real encode failure (determineMessageType/buildMessageBody)\n    log.error(\"[encode][binary serialize failed for {}]\", message.getMethod(), e);\n    bytes = jsonSerializer.serialize(message); // optional JSON fallback\n}","preventionTips":["Always log and inspect the wrapped cause — the outer RuntimeException hides it.","Keep determineMessageType/buildMessageBody coverage in sync with IotDeviceMessage subclasses.","Round-trip test (serialize then deserialize) every message type you add.","Route message types the binary protocol does not support through JSON instead."],"tags":["iot","serialization","binary-protocol","encoding"],"backgroundTag":null,"analyzedSha":"0418084e222612af2fc1141f566af454f9236ab1","analyzedAt":"2026-08-14T00:56:18.412Z","schemaVersion":2},"datasetVersion":"2026-08-14T05:17:29.042Z"}