05. 开发、部署与快速上站 · 资料陈述 · 教学步骤 3

用结构化模板搭骨架

把主题和区块变成结构化数据，可减少重复改代码和漏字段。

原知识点：快速上站的首个部件是复用自己的模板，并用 JSON 结构化描述主题、标题、段落、关键词和区块。

执行步骤

  1. 列出页面渲染真正需要的字段，并为每个字段规定类型、是否必填、长度/格式和说明。
  2. 建立JSON Schema，写明$schema、type、properties、required和additionalProperties策略。
  3. 分别准备一个完整有效样例，以及缺必填、类型错误和多余字段等无效样例。
  4. 在构建或提交检查中运行验证器，使错误指出字段路径并阻止不合格内容发布。
  5. 为Schema增加版本号和迁移说明；模板相同不意味着正文可以同质复制。

可复制工作表

复制为schema.json并替换__：
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://__/page.schema.json",
  "title": "__页面类型__",
  "type": "object",
  "properties": {
    "__field__": {"type": "string", "minLength": 1}
  },
  "required": ["__field__"],
  "additionalProperties": false
}
复制为valid.json并替换__：{"__field__":"__value__"}
复制为invalid-missing.json：{}
再分别增加类型错误和多余字段无效样例：__
实际验证命令：npx --yes ajv-cli@5 validate --spec=draft2020 -s schema.json -d valid.json
无效样例命令：npx --yes ajv-cli@5 validate --spec=draft2020 -s schema.json -d "invalid-*.json"
预期：有效样例退出码0；每个无效样例退出码非0并指出字段路径。
Schema版本/迁移说明：从__到__需要__
CI失败后动作：阻止构建并退回__

完整示例

【完整可运行示例；字段和约束只服务本页面类型，不是通用阈值】schema.json：
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://example.com/page.schema.json",
"title": "ToolPage",
"type": "object",
"properties": {
"slug": {"type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*{{INITIAL_CONTENT}}quot;},
"title": {"type": "string", "minLength": 1},
"sections": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"properties": {
"type": {"type": "string"},
"heading": {"type": "string", "minLength": 1}
},
"required": ["type", "heading"],
"additionalProperties": false
}
}
},
"required": ["slug", "title", "sections"],
"additionalProperties": false
}
valid.json：
{"slug":"audio-to-text","title":"Audio to Text","sections":[{"type":"hero","heading":"Transcribe audio"}]}
invalid-missing.json：
{"slug":"audio-to-text","sections":[{"type":"hero","heading":"Transcribe audio"}]}
invalid-type.json：
{"slug":"audio-to-text","title":"Audio to Text","sections":"hero"}
invalid-extra.json：
{"slug":"audio-to-text","title":"Audio to Text","sections":[{"type":"hero","heading":"Transcribe audio"}],"unknown":true}
执行：npx --yes ajv-cli@5 validate --spec=draft2020 -s schema.json -d valid.json；应返回valid。再执行npx --yes ajv-cli@5 validate --spec=draft2020 -s schema.json -d "invalid-*.json"；三个无效实例都应失败并指出缺title、sections类型错误或不允许unknown。将这两类命令接入构建门禁。

完成清单

  • Schema声明版本、对象类型、字段类型、必填项和额外字段策略。
  • 至少一个有效样例通过，三类无效样例被拒绝并指出路径。
  • 验证已接入构建或提交门禁，而非只靠人工记忆。
  • 模板内容字段允许页面独有证据，不会迫使跨页复制同文。

当前官方依据

平台规则会变化，行动前以打开后的当前官方页面为准。

适用条件

schema 要版本化并做必填、类型和长度校验。

来源：Blank：以 AITDK 为例聊如何基于需求开发产品