JSON Schema 最佳实践 - 规范设计与性能优化

1
// ✅ 好的设计：简洁明了
2
{
3
  "type": "object",
4
  "properties": {
5
    "name": { "type": "string" },
6
    "age": { "type": "integer" }
7
  },
8
  "required": ["name", "age"]
9
}
10

11
// ❌ 坏的设计：过度复杂
12
{
13
  "type": "object",
14
  "properties": {
15
    "name": {
16
      "type": "string",
17
      "minLength": 1,
18
      "maxLength": 100,
19
      "pattern": "^[a-zA-Z\\s]+$",
20
      "description": "The full name of the person",
21
      "examples": ["John Doe"]
22
    },
23
    "age": {
24
      "type": "integer",
25
      "minimum": 0,
26
      "maximum": 150,
27
      "description": "Age in years"
28
    }
29
  }
30
  // 过度验证，除非必要
31
}

1
// ✅ 好的设计：清晰的标题和描述
2
{
3
  "$schema": "http://json-schema.org/draft-07/schema#",
4
  "title": "用户账户信息",
5
  "description": "描述平台用户的基本账户信息结构",
6
  "type": "object",
7
  "properties": {
8
    "username": {
9
      "type": "string",
10
      "title": "用户名",
11
      "description": "用户的唯一标识名称，3-20 个字符"
12
    }
13
  }
14
}
15

16
// ❌ 坏的设计：缺少描述
17
{
18
  "type": "object",
19
  "properties": {
20
    "username": { "type": "string" }
21
  }
22
}

1
// ✅ 好的设计：明确必填字段
2
{
3
  "type": "object",
4
  "properties": {
5
    "id": { "type": "integer" },
6
    "name": { "type": "string" },
7
    "email": { "type": "string", "format": "email" },
8
    "phone": { "type": "string" },
9
    "address": { "type": "string" }
10
  },
11
  "required": ["id", "name", "email"],
12
  "additionalProperties": true
13
}
14

15
// ❌ 坏的设计：未指定必填字段
16
{
17
  "type": "object",
18
  "properties": {
19
    "id": { "type": "integer" },
20
    "name": { "type": "string" },
21
    "email": { "type": "string" }
22
  }
23
  // 哪些是必填的？不明确
24
}

1
// ✅ 好的设计：合理范围
2
{
3
  "age": {
4
    "type": "integer",
5
    "minimum": 0,
6
    "maximum": 150
7
  },
8
  "username": {
9
    "type": "string",
10
    "minLength": 3,
11
    "maxLength": 30
12
  },
13
  "email": {
14
    "type": "string",
15
    "format": "email"
16
  }
17
}
18

19
// ❌ 坏的设计：过于严格或宽松
20
{
21
  "age": {
22
    "type": "integer",
23
    "minimum": 1,
24
    "maximum": 1000  // 不合理
25
  },
26
  "username": {
27
    "type": "string",
28
    "minLength": 1,
29
    "maxLength": 1000  // 太长
30
  }
31
}

1
// ✅ 好的设计：复用通用结构
2
{
3
  "$schema": "http://json-schema.org/draft-07/schema#",
4
  "definitions": {
5
    "address": {
6
      "type": "object",
7
      "properties": {
8
        "street": { "type": "string" },
9
        "city": { "type": "string" },
10
        "state": { "type": "string" },
11
        "zip": { "type": "string" },
12
        "country": { "type": "string" }
13
      },
14
      "required": ["street", "city", "zip", "country"]
15
    },
16
    "email": {
17
      "type": "string",
18
      "format": "email"
19
    },
20
    "dateCreated": {
21
      "type": "string",
22
      "format": "date-time"
23
    }
24
  },
25
  "type": "object",
26
  "properties": {
27
    "billingAddress": { "$ref": "#/definitions/address" },
28
    "shippingAddress": { "$ref": "#/definitions/address" },
29
    "contactEmail": { "$ref": "#/definitions/email" },
30
    "createdAt": { "$ref": "#/definitions/dateCreated" }
31
  }
32
}

1
// 主 Schema
2
{
3
  "$schema": "http://json-schema.org/draft-07/schema#",
4
  "type": "object",
5
  "properties": {
6
    "user": { "$ref": "user.schema.json" },
7
    "address": { "$ref": "address.schema.json" },
8
    "product": { "$ref": "https://example.com/schemas/product.schema.json" }
9
  }
10
}
11

12
// user.schema.json
13
{
14
  "$id": "user.schema.json",
15
  "type": "object",
16
  "properties": {
17
    "id": { "type": "integer" },
18
    "name": { "type": "string" }
19
  }
20
}

1
// ✅ 好的设计：组合复用
2
{
3
  "definitions": {
4
    "baseEntity": {
5
      "type": "object",
6
      "properties": {
7
        "id": { "type": "integer" },
8
        "createdAt": { "type": "string", "format": "date-time" },
9
        "updatedAt": { "type": "string", "format": "date-time" }
10
      },
11
      "required": ["id", "createdAt"]
12
    },
13
    "auditable": {
14
      "type": "object",
15
      "properties": {
16
        "createdBy": { "type": "string" },
17
        "updatedBy": { "type": "string" }
18
      }
19
    }
20
  },
21
  "type": "object",
22
  "allOf": [
23
    { "$ref": "#/definitions/baseEntity" },
24
    { "$ref": "#/definitions/auditable" },
25
    {
26
      "properties": {
27
        "name": { "type": "string" },
28
        "description": { "type": "string" }
29
      },
30
      "required": ["name"]
31
    }
32
  ]
33
}

1
// ✅ 好的设计：扁平结构
2
{
3
  "type": "object",
4
  "properties": {
5
    "userId": { "type": "integer" },
6
    "userName": { "type": "string" },
7
    "userEmail": { "type": "string" }
8
  }
9
}
10

11
// ❌ 坏的设计：过度嵌套（影响性能）
12
{
13
  "type": "object",
14
  "properties": {
15
    "user": {
16
      "type": "object",
17
      "properties": {
18
        "profile": {
19
          "type": "object",
20
          "properties": {
21
            "info": {
22
              "type": "object",
23
              "properties": {
24
                "name": { "type": "string" }
25
              }
26
            }
27
          }
28
        }
29
      }
30
    }
31
  }
32
}

1
// ✅ 好的设计：明确控制
2
{
3
  "type": "object",
4
  "properties": {
5
    "name": { "type": "string" },
6
    "age": { "type": "integer" }
7
  },
8
  "required": ["name", "age"],
9
  "additionalProperties": false
10
}
11

12
// 或允许特定额外属性
13
{
14
  "type": "object",
15
  "properties": {
16
    "name": { "type": "string" }
17
  },
18
  "additionalProperties": {
19
    "type": "string"
20
  }
21
}
22

23
// ❌ 坏的设计：不限制（可能导致问题）
24
{
25
  "type": "object",
26
  "properties": {
27
    "name": { "type": "string" }
28
  }
29
  // additionalProperties 默认为 true
30
}

1
// ✅ 好的设计：简单 pattern
2
{
3
  "username": {
4
    "type": "string",
5
    "pattern": "^[a-zA-Z][a-zA-Z0-9_]{2,19}$"
6
  }
7
}
8

9
// ❌ 坏的设计：复杂的 allOf 组合
10
{
11
  "username": {
12
    "allOf": [
13
      { "type": "string", "minLength": 3, "maxLength": 20 },
14
      { "not": { "pattern": "^[^a-zA-Z]" } },
15
      { "not": { "pattern": ".*[^a-zA-Z0-9_].*" } }
16
    ]
17
  }
18
}

1
// ✅ 好的设计：高效正则
2
{
3
  "email": {
4
    "type": "string",
5
    "format": "email"
6
  },
7
  "simple_pattern": {
8
    "type": "string",
9
    "pattern": "^[a-z]+$"
10
  }
11
}
12

13
// ❌ 坏的设计：低效正则（可能导致 ReDoS）
14
{
15
  "bad_pattern": {
16
    "type": "string",
17
    "pattern": "^(a+)+$"  // 指数级回溯
18
  }
19
}

1
// ✅ 好的设计：自定义错误消息
2
const Ajv = require('ajv');
3
const ajv = new Ajv({ allErrors: true, messages: true });
4

5
const schema = {
6
  type: 'object',
7
  properties: {
8
    username: {
9
      type: 'string',
10
      minLength: 3,
11
      maxLength: 20,
12
      pattern: '^[a-zA-Z0-9_]+$'
13
    },
14
    email: {
15
      type: 'string',
16
      format: 'email'
17
    }
18
  },
19
  required: ['username', 'email']
20
};
21

22
// 验证后获取详细错误
23
const validate = ajv.compile(schema);
24
const valid = validate(data);
25

26
if (!valid) {
27
  validate.errors.forEach(error => {
28
    console.log({
29
      field: error.instancePath,
30
      message: error.message,
31
      keyword: error.keyword
32
    });
33
  });
34
}

1
{
2
  "type": "object",
3
  "properties": {
4
    "username": {
5
      "type": "string",
6
      "minLength": 3,
7
      "maxLength": 20,
8
      "errorMessage": {
9
        "type": "用户名必须是字符串",
10
        "minLength": "用户名至少 3 个字符",
11
        "maxLength": "用户名最多 20 个字符"
12
      }
13
    },
14
    "email": {
15
      "type": "string",
16
      "format": "email",
17
      "errorMessage": {
18
        "format": "请输入有效的邮箱地址"
19
      }
20
    }
21
  }
22
}

1
// ✅ 好的设计：分层验证
2
async function validateUser(data) {
3
  // 第一层：基本结构
4
  const basicSchema = {
5
    type: 'object',
6
    required: ['username', 'email']
7
  };
8

9
  if (!validate(basicSchema, data)) {
10
    throw new Error('数据结构错误');
11
  }
12

13
  // 第二层：详细验证
14
  const detailSchema = {
15
    properties: {
16
      username: { type: 'string', minLength: 3 },
17
      email: { type: 'string', format: 'email' }
18
    }
19
  };
20

21
  if (!validate(detailSchema, data)) {
22
    throw new Error('数据验证失败');
23
  }
24

25
  // 第三层：业务规则
26
  if (await usernameExists(data.username)) {
27
    throw new Error('用户名已存在');
28
  }
29
}

1
// ✅ 好的设计：向后兼容
2
{
3
  "type": "object",
4
  "properties": {
5
    "name": { "type": "string" },
6
    "email": { "type": "string", "format": "email" }
7
  },
8
  "required": ["name", "email"],
9
  "additionalProperties": true  // 允许新增字段
10
}
11

12
// ❌ 坏的设计：破坏性变更
13
{
14
  "type": "object",
15
  "properties": {
16
    "fullName": { "type": "string" }  // 改名了
17
  },
18
  "required": ["fullName"],
19
  "additionalProperties": false  // 不允许旧字段
20
}

1
{
2
  "type": "object",
3
  "properties": {
4
    "username": {
5
      "type": "string",
6
      "description": "用户名（已废弃，请使用 name 字段）",
7
      "deprecated": true
8
    },
9
    "name": {
10
      "type": "string",
11
      "description": "用户姓名"
12
    }
13
  },
14
  "required": ["name"]
15
}

1
// ✅ 好的设计：全面测试
2
const Ajv = require('ajv');
3
const ajv = new Ajv();
4

5
const schema = {
6
  type: 'object',
7
  properties: {
8
    username: { type: 'string', minLength: 3 },
9
    email: { type: 'string', format: 'email' }
10
  },
11
  required: ['username', 'email']
12
};
13

14
const validate = ajv.compile(schema);
15

16
// 测试有效数据
17
test('valid data', () => {
18
  expect(validate({ username: 'john', email: 'john@example.com' })).toBe(true);
19
});
20

21
// 测试无效数据
22
test('missing required field', () => {
23
  expect(validate({ username: 'john' })).toBe(false);
24
});
25

26
test('invalid email', () => {
27
  expect(validate({ username: 'john', email: 'invalid' })).toBe(false);
28
});
29

30
test('short username', () => {
31
  expect(validate({ username: 'jo', email: 'john@example.com' })).toBe(false);
32
});

1
// 边界值测试
2
const testData = [
3
  // 有效边界
4
  { username: 'abc', email: 'a@b.com' },  // 最小长度
5
  { username: 'a'.repeat(20), email: 'a@b.com' },  // 最大长度
6

7
  // 无效边界
8
  { username: 'ab', email: 'a@b.com' },  // 长度不足
9
  { username: 'a'.repeat(21), email: 'a@b.com' },  // 超长
10
  { username: 'john', email: '' },  // 空邮箱
11
  { username: 'john', email: 'not-email' }  // 格式错误
12
];
13

14
testData.forEach((data, index) => {
15
  test(`boundary test ${index}`, () => {
16
    const valid = validate(data);
17
    console.log(`Test ${index}: ${valid ? 'PASS' : 'FAIL'}`);
18
  });
19
});