HTML不能作为接口契约，因其仅是渲染结果而非数据契约；真正起作用的是OpenAPI 3.0、YAPI/Apifox平台和JSON Schema三类机器可读、可版本化、可自动生成Mock与SDK的契约载体。
HTML 在前后端分离架构中 **不承担接口契约职责**，也不用于定义接口模板——它只是前端渲染层的输出结果，不是契约载体。
为什么 HTML 不能作为接口契约
契约的核心是「数据结构 + 交互规则」，而 HTML 是最终呈现层的标记语言，不具备描述能力：
-
HTML不声明字段类型、必填性、嵌套关系或错误码含义；它只反映某次请求后的一次性渲染快照 - 后端返回
JSON，前端用 JS 解析并生成HTML；若把HTML当契约，等于让后端为每种 UI 状态写一套模板，违背「前后端解耦」原则 - 同一接口可能被 Web、App、小程序共用，但它们根本不需要、也无法复用同一份
HTML
真正起契约作用的是什么
接口契约必须可机器读取、可版本化、可生成 Mock 和 SDK。实际落地靠这三类东西：
-
OpenAPI 3.0（即 Swagger YAML/JSON）：明确定义paths、schemas、requestBody、responses，支持自动生成文档、Mock 服务、TypeScript 类型定义 -
YAPI或Apifox这类协作平台：提供可视化编辑 + 权限管理 + 变更通知，让前端能直接基于契约写fetch调用和interface类型 -
JSON Schema文件：单独存于代码仓库，被 CI 流程校验，确保后端返回体结构与契约一致（例如用ajv在测试中做响应校验）
HTML 模板在分离架构里该放哪、怎么用
如果项目仍需服务端渲染（如 SEO 敏感页面），HTML 模板应由前端编写、交付给后端集成，而非由后端维护：
立即学习“前端免费学习笔记（深入）”；
- 前端用
Vue SFC或React Server Components写组件，构建时产出静态HTML片段或 SSR bundle - 后端只负责注入数据（通过
JSON接口获取）、调用渲染函数，不修改模板逻辑 - 禁止在模板里写
if user.role == 'admin'这类业务判断——权限控制、字段过滤必须在 API 层完成，前端只做展示映射
容易被忽略的是：契约一旦定稿，HTML 渲染层的任何字段名变更（比如把 user_name 改成 nickname）必须同步更新 OpenAPI 定义，否则 Mock 和类型推导会立刻失效。契约不是文档附件，它是代码的源头约束。
