必须先 JSON.stringify() 再 send()，因 WebSocket.send() 不接受对象，否则转为 “[object Object]”；后端接收的是原始字节/字符串，须显式 json.Unmarshal() 或 json.loads() 解析。
不能直接 send({})，必须先 JSON.stringify()；后端收到的永远是原始字节或字符串，不是对象。
前端发送前必须序列化成字符串
WebSocket 的 send() 方法只接受 string、ArrayBuffer 或 Blob，传入普通对象会自动调用 toString()，结果是 [object Object]，后端根本无法解析。
- ✅ 正确写法：
socket.send(JSON.stringify({type: "update", data: {x: 1, y: 2}})) - ⚠️ 错误写法：
socket.send({type: "update", data: {x: 1, y: 2}})—— 发出去的是字符串[object Object] - 注意
Date、undefined、循环引用字段：它们会让JSON.stringify()返回undefined或抛错；建议用自定义replacer过滤，例如：JSON.stringify(obj, (k, v) => v instanceof Date ? v.toISOString() : v) - 浮点数精度敏感场景（如金额），别传
number，改用字符串字段：{"price": "99.99"}
后端接收后必须显式反序列化
无论用 Go（gorilla）、Python（FastAPI）、Java（Spring）还是 C#（Fleck），ReadMessage()、receive_text()、onMessage 等接口返回的都是原始数据载体（[]byte、str、string），不是解析好的对象。
dmap-jsapi-skill
下载
DMap GL地图JSAPI（dmapgl）开发指南。用于编写、审查、调试 DMap 地图 API 代码，涵盖地图初始化、覆盖物渲染、图层管理、事件处理、控件交互等任务。当用户提及 dmap、dmapgl、jsapi‑gl 或相关地图开发需求时自动触发。
- Go 示例：
json.Unmarshal(dataBytes, &msg)—— 忘了这步，msg就是零值 - FastAPI 示例：
data = await websocket.receive_text(); msg = json.loads(data)—— 不能跳过json.loads() - 类型不匹配时（比如字段名大小写/下划线不一致），反序列化可能静默失败或填入零值；务必检查结构体 tag（Go）或 model 字段定义（Python）是否与 JSON key 完全对应
- 如果消息含二进制内容（如图片 base64），确保它被包裹在字符串字段里，而不是试图把整个 JSON 当二进制传
嵌套深、字段多时要加结构校验
光能 JSON.parse() 或 json.Unmarshal() 不代表数据可用。字段缺失、类型错（比如 "id": 123 实际需要 string）、额外字段都可能引发后续 panic 或逻辑错误。
- 不要只依赖 try/catch 捕获
SyntaxError，还要做运行时字段检查：typeof data.payload === 'object' && data.payload?.user_id - 推荐轻量 schema 库：前端用
zod（z.object({...}).safeParse()），后端 Go 用go-playground/validator，Python 用pydantic - 统一协议顶层结构（如固定
{"type": "...", "payload": {...}, "seq": 123}）能大幅降低分发和调试成本 - 避免在 payload 里塞超大数组或深层递归结构——WebSocket 帧有默认大小限制（常见 64KB–1MB），超限会被断连或截断
时间、二进制、特殊字符这些容易漏处理
看似合法的 JSON，在跨语言、跨环境传输时，常因细节差异崩掉。
-
Date对象：JS 默认转 ISO 字符串，但 Java 后端可能期望 Unix timestamp，需提前约定并转换 - 控制字符（如
\u0000）无法出现在 JSON 字符串中，若业务数据含 null byte，必须 Base64 编码后再作为字符串字段传 - 中文等 UTF-8 字符没问题，但老旧终端或某些嵌入式服务端可能不支持 BOM 或非 ASCII 路径，建议发送前确认
JSON.stringify()输出确实是纯 UTF-8 字节流 - undefined / function / Symbol 字段不会被
stringify序列化，若后端强依赖这些字段，前端必须显式赋默认值或剔除
真正麻烦的不是“能不能传”，而是“传过去之后对方能不能稳稳接住”。字段命名、空值约定、时间格式、错误响应结构——这些细节没对齐，再标准的 JSON 也会在某次上线后突然开始丢消息。
