· 全部指南
从 JSON 样例快速生成 Schema
使用 towalles.com/json-schema-from-sample 工具，只需粘贴任意 JSON 数据，即可自动推断字段类型、必填项和嵌套结构。例如电商 API 的订单数据，工具能智能识别价格应为 number 类型而非字符串，避免手动编写时的常见错误。所有处理在浏览器本地完成，敏感数据不会上传至服务器。
进阶技巧：通过「严格模式」强制枚举值校验，比如将订单状态限定为 ['pending', 'shipped', 'delivered']。对于动态字段，可使用 patternProperties 定义正则匹配规则，如用户自定义元数据 meta_* 字段的通用处理方案。
校验 LLM 结构化输出实战
通过 structured-output-validator 工具，将生成的 Schema 作为质量检查关卡。当 LLM 返回的 JSON 缺少必填字段或类型不匹配时，系统会立即抛出可读性错误，比如「contact.email 应为字符串但收到 null」。支持批量校验历史对话数据，帮助优化提示词工程。
特殊场景处理：针对 LLM 可能返回的 Markdown 代码块包裹的 JSON，工具内置自动提取逻辑。对于非标准格式如「Yes/No」布尔值，可配置自定义转换器将其规范化为 true/false。
Function Calling 设计最佳实践
在 function-schema-builder 中设计 AI 函数时，务必添加清晰的 description 字段。例如参数「location」应说明「使用城市名而非邮政编码，如 'Beijing'」。工具生成的 Schema 可直接用于 OpenAI 等平台的 function calling 配置，实现全流程可视化编辑。
推荐采用「宽松输入+严格输出」原则：输入参数接受字符串或数字等多种类型，但函数返回值必须符合精确的 Schema 定义。通过添加 examples 数组展示典型用例，显著降低 AI 的理解偏差。
隐私优先的本地化处理方案
所有 Towalles 工具均采用浏览器本地计算架构，Schema 生成和校验过程不会将您的 API 数据或业务逻辑外传。对于医疗、金融等敏感行业，配合「离线模式」使用可完全隔绝网络请求，符合 GDPR 等严格合规要求。
开发者可导出标准 JSON Schema 文件（Draft-07 兼容）到自有系统集成。结合 CI/CD 流程，自动校验生产环境 API 的响应格式，或在测试阶段捕捉 LLM 输出的结构性错误。
Schema 即真相来源
把 JSON Schema（或 OpenAPI components）与产出载荷的服务放在一起。生成客户端与契约测试应消费人类在 PR 里阅读的同一文件。
演进规则
新增可选字段通常安全；重命名或改类型需要升版本。为弃用字段写明删除日期。仅在威胁模型要求时拒绝未知字段。
校验位置
对不信任输入在边缘校验；存在多写者时落库前再校验。返回可操作的错误路径——不要只说「JSON 无效」。
本地闭环
用 json-formatter 美化样例，再在 CI 对照 schema fixture 校验。把失败载荷（已脱敏）留作回归测试。
JSON Schema 治理
动生产前先写操作程序：输入、期望输出、负责人与回滚。Towalles 上的工具便于本地检查样例，不能替代变更控制。
前置条件
- 有代表失败案例的脱敏 fixture。
- 清楚谁是真相来源（应用、网关、CMS 或网络设备）。
- 能在非生产环境或用合成数据复现问题。
步骤
- 用 fixture 复现，记录精确命令或 UI 路径。
- 按需用格式化、哈希或解析工具与已知正确样例对照。
- 做最小修复；同一变更里避免顺手重构。
- 补充回归测试或清单项，避免下一任 on-call 重复踩坑。
- 更新 runbook：症状 → 检查 → 修复。
善后
观察 24–72 小时错误率与支持工单。若做过一次性数据修复，安排后续防止复发。工单里保留截图与哈希，不要留真实密钥。
反模式
- 把生产密钥贴到公开页面「只是看一下」。
- 上线却不写回滚说明。
- 把本地绿色演示当成多区域生产的证明。