钉钉API请求中JSON参数格式错误导致400报错，常见原因有哪些？

Question

钉钉API请求返回400错误，常因JSON参数格式不合规所致。常见原因包括：① JSON语法错误（如末尾多余逗号、单引号替代双引号、中文标点、缺少引号包裹字符串）；② 必填字段缺失或字段名拼写错误（如`userid`误写为`userId`，钉钉严格区分大小写与命名规范）；③ 数据类型不匹配（如`isPrivate`传字符串`"true"`而非布尔值`true`，或`deptIdList`传单个数字而非整型数组）；④ 字段嵌套结构错误（如应传`{ "userIds": ["u1","u2"] }`却错传为`{ "userIds": "u1,u2" }`）；⑤ UTF-8 BOM头或不可见控制字符污染JSON体。建议使用标准JSON校验工具预检，并开启钉钉API的`debug`模式或查看响应体中的`error_message`获取精准提示。生产环境务必通过`JSON.stringify()`序列化对象，避免手动拼接。

Answer 1

```html

一、现象层：400 Bad Request 的表征与初判

当调用钉钉开放平台 API（如 /v1.0/im/chat/scenes/groups 创建群、/v1.0/contact/users/batchGet 批量获取用户）时，HTTP 状态码返回 400，且响应体中无业务数据，仅含 {"errcode":400,"errmsg":"invalid request"} 或类似泛化提示——这是典型的「客户端请求格式非法」信号。该错误不涉及鉴权（401）、权限（403）或服务不可用（5xx），而是钉钉网关在反序列化 JSON 请求体阶段即终止处理，说明问题根植于请求载荷（Request Body）本身。

二、语法层：JSON 文本的「形式正确性」陷阱

• ❌ 末尾逗号残留：{"userid":"zhangsan",} —— RFC 8259 明确禁止对象/数组末尾逗号；
• ❌ 引号误用：单引号 {'userid':'zhangsan'} 或中文全角引号 ｛“userid”：“zhangsan”｝；
• ❌ 字符串未加引号：{userid: "zhangsan"}（key 必须双引号包裹）；
• ❌ 控制字符污染：UTF-8 BOM（EF BB BF）、零宽空格（U+200B）、段落分隔符（U+2029）等不可见字符混入 JSON 字符串。

✅ 推荐校验工具链：JSONLint（在线）、VS Code 插件 JSON Tools、或 Node.js 中使用 JSON.parse() 预检（捕获 SyntaxError）。

三、契约层：钉钉 OpenAPI Schema 的强约束解析

字段名	类型	是否必填	常见错误示例	钉钉规范要求
userid	string	✓	userId, USERID	严格小驼峰，全小写，无下划线
isPrivate	boolean	✓	"true", 1	必须为原始布尔值 true/false
deptIdList	array of integer	✓	101, ["101","102"]	必须为整型数组：[101,102]

⚠️ 注意：钉钉文档中所有字段名均为精确大小写匹配，userid ≠ userId ≠ UserID；Swagger UI 文档与实际接口契约一致，建议以 官方 OpenAPI Spec（YAML/JSON） 为唯一信源。

四、结构层：嵌套对象与数组的语义合规性

以下为典型结构误用对比：

// ✅ 正确：userIds 是字符串数组
{
  "chatName": "技术攻坚组",
  "userIds": ["u_123", "u_456"],
  "isPrivate": true
}

// ❌ 错误：userIds 被扁平化为字符串（违反 schema）
{
  "chatName": "技术攻坚组",
  "userIds": "u_123,u_456",
  "isPrivate": true
}

// ❌ 错误：多层嵌套缺失（如创建群需传 groupOwner + ownerUserId）
{
  "chatName": "测试群",
  "ownerUserId": "zhangsan" // 缺少外层 groupOwner 对象
}

五、工程层：生产环境安全序列化的最佳实践

graph TD
  A[原始 JS 对象] -->|1. 严格类型校验| B{字段存在性检查}
  B -->|缺失必填字段| C[抛出 Error：Missing required field 'userid']
  B -->|存在| D[数据类型转换]
  D -->|isPrivate| E[强制 Boolean conversion]
  D -->|deptIdList| F[map(Number) → integer array]
  E & F --> G[JSON.stringify]
  G --> H[发送至钉钉 API]
  H --> I{响应状态码}
  I -->|400| J[提取 error_message 并 log]
  I -->|200| K[正常业务处理]

六、诊断层：从 debug 到精准归因的闭环路径

1. 启用钉钉 SDK 的 debug: true 模式（如 @dd-sdk/node）输出完整请求/响应日志；
2. 捕获 400 响应体，优先解析 error_message 字段（例："errmsg":"invalid json: missing required field 'userid'"）；
3. 使用 curl -v 或 Postman 复现请求，比对原始 payload 与 wire-level 字节流（Hex View）；
4. 在 Node.js 中打印 Buffer.from(JSON.stringify(payload)).toString('hex') 检查 BOM；
5. 对前端请求，禁用浏览器插件干扰，检查 Fetch API 是否意外添加了 Content-Type: text/plain。

💡 高阶技巧：在 Express/Koa 中增加中间件，对所有 application/json 请求做 JSON.parse(req.body) 预校验并记录原始字节长度，可提前拦截 90% 的语法类 400。

```