命名规范
选择一种规范并坚持使用：
// ✅ camelCase（JavaScript 规范，最常见）
{
"firstName": "张三",
"lastName": "李四",
"createdAt": "2026-07-22T10:00:00Z"
}
// ✅ snake_case（Python 规范，也很常见）
{
"first_name": "张三",
"last_name": "李四",
"created_at": "2026-07-22T10:00:00Z"
}
// ❌ 避免混合规范
{
"firstName": "张三",
"last_name": "李四", // 不一致！
"createdAt": "2026-07-22T10:00:00Z"
}建议：JavaScript/TypeScript API 使用 camelCase，Python/Ruby API 使用 snake_case。记录你的选择。
数据类型最佳实践
数字
// ✅ 数值使用数字类型
{ "price": 19.99, "quantity": 42 }
// ❌ 不要用字符串表示数字
{ "price": "19.99", "quantity": "42" }
// ✅ 大整数使用字符串（精度问题）
{ "id": "9007199254740993" }
// ✅ 缺失的数字用 null
{ "discount": null }日期和时间
// ✅ ISO 8601 格式（推荐）
{ "createdAt": "2026-07-22T10:30:00Z" }
{ "date": "2026-07-22" }
{ "time": "10:30:00" }
// ❌ 避免歧义格式
{ "date": "07/22/2026" } // MM/DD/YYYY 还是 DD/MM/YYYY？
{ "timestamp": 1690000000 } // Unix 时间戳 - 可读性差布尔值
// ✅ 使用真正的布尔值
{ "isActive": true, "isDeleted": false }
// ❌ 不要用字符串或数字
{ "isActive": "true" }
{ "isActive": 1 }null vs 缺失
// ✅ "明确为空" 使用 null
{ "middleName": null }
// ✅ "不适用" 或 "默认值" 省略字段
{ "firstName": "张三", "lastName": "李四" }
// middleName 省略 - 不适用
// ❌ 不要用空字符串表示缺失
{ "middleName": "" } // 这是故意为空还是缺失？安全最佳实践
永远不要信任用户输入
// ✅ 安全解析
function safeParse(json) {
try {
const data = JSON.parse(json);
// 验证 schema
if (!validate(data)) {
throw new Error('数据验证失败');
}
return data;
} catch (e) {
throw new Error('JSON 解析失败: ' + e.message);
}
}防止原型污染
// ✅ 安全解析，递归清理
function safeParse(json) {
const data = JSON.parse(json, (key, value) => {
if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
return undefined;
}
return value;
});
return data;
}大小限制
const MAX_JSON_SIZE = 1024 * 1024; // 1MB
function safeParseWithLimit(json) {
if (Buffer.byteLength(json, 'utf8') > MAX_JSON_SIZE) {
throw new Error('JSON 数据过大');
}
return JSON.parse(json);
}性能优化
最小化载荷
// ❌ 冗长
{
"userIdentifier": "12345",
"userFullName": "张三",
"userEmailAddress": "zhangsan@example.com"
}
// ✅ 简洁（配合文档）
{
"id": "12345",
"name": "张三",
"email": "zhangsan@example.com"
}大集合使用分页
// ✅ 分页响应
{
"data": [...],
"pagination": {
"page": 1,
"perPage": 20,
"total": 150,
"totalPages": 8
}
}常见陷阱
尾随逗号
// ❌ 无效的 JSON
{ "name": "张三", "age": 30, }
// ✅ 有效的 JSON
{ "name": "张三", "age": 30 }注释
// ❌ 无效的 JSON（使用 JSONC 或 JSON5 支持注释）
{
// 这是注释
"name": "张三"
}单引号
// ❌ 无效的 JSON
{ 'name': '张三' }
// ✅ 有效的 JSON
{ "name": "张三" }API 设计模式
统一信封格式
// ✅ 成功响应
{
"success": true,
"data": { ... },
"meta": { "requestId": "abc123" }
}
// ✅ 错误响应
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "输入无效",
"details": [...]
}
}相关资源
- JSON Schema 完全指南 — 验证你的 JSON 结构
- JSON 安全最佳实践 — 防范常见漏洞
- JSON 格式化工具 — 在线格式化和验证 JSON
- JSON 压缩工具 — 压缩 JSON 减小体积
- JSON Diff 工具 — 比较 JSON 差异