接口契约必须用机器可读的OpenAPI 3.0格式定义，而非Word或Excel等人工文档，确保路径、参数、响应、状态码等全声明且可自动化校验；后端通过springdoc-openapi或swagger-jsdoc生成，前端用openapi-typescript-codegen生成类型与请求函数，CI中集成openapi-diff拦截破坏性变更，契约文件须与代码同仓库同提交并参与构建流程。
接口契约必须用机器可读格式定义，别只靠 Word 或 Excel
人工维护的文档在迭代中极易过期，前端调用 GET /api/users 时后端已改成 GET /v2/users，但没人更新表格。契约必须是代码的一部分，能被自动化校验。
推荐直接用 OpenAPI 3.0（即 Swagger YAML/JSON）定义：路径、参数、响应结构、状态码、示例值全写死。不是“描述接口”，而是“声明接口行为”。
- 后端生成：Spring Boot 用
springdoc-openapi，Node.js 用swagger-jsdoc，自动生成并内嵌到服务中（如/v3/api-docs） - 前端消费：用
openapi-typescript-codegen一键生成 TypeScript 接口类型和请求函数，避免手写interface UserResponse出错 - CI 拦截：提交 PR 前跑
openapi-diff，检测是否无意修改了已有字段类型（比如把id: string改成id: number），直接失败构建
模板规范要约束 HTML 片段的边界与数据契约，而非视觉样式
前后端分离后，后端不再渲染完整页面，但常需返回可嵌入的 HTML 片段（如评论列表、商品卡片）。这时模版不是“怎么好看”，而是“怎么安全、可预测、可测试”。
关键约束点：
立即学习“前端免费学习笔记（深入）”；
- 所有变量插值必须显式声明：禁止
{{ content }}这类裸模板语法；统一用${data.title}+ 严格类型检查（TypeScript interface + JSDoc @template） - 禁止在模版里做逻辑判断或循环：
if、for全部移到 JS 层处理，模版只负责“把已计算好的数组映射成字符串” - 输出必须带语义化容器：每个片段包裹在唯一
data-component="product-card"属性的元素内，方便前端用document.querySelector('[data-component="product-card"]')精确挂载 - 默认转义所有动态内容，仅对明确标记为
html的字段（如富文本）开放非转义输出——且后端必须做过滤（如 DOMPurify）
404/500 等错误响应也要进契约，否则前端永远在猜
后端返回 500 Internal Server Error 时，如果响应体是空的、或格式不统一（有时 JSON，有时 HTML），前端就只能弹“服务器出错了”，没法做针对性提示或降级。
契约里必须明确定义错误形态：
- 统一错误结构：
{ "code": "USER_NOT_FOUND", "message": "用户不存在", "trace_id": "xxx" }，所有接口共用同一ErrorResponseschema - 每个 HTTP 状态码对应哪些业务错误码：比如
404只允许USER_NOT_FOUND和ORDER_NOT_FOUND，不能出现PERMISSION_DENIED - 前端 SDK 封装请求时，自动根据
code值触发不同行为：遇到TOKEN_EXPIRED自动跳登录页，遇到THROTTLED显示倒计时重试
本地联调时，契约文件必须和代码一起 commit，不能靠“我刚发你邮箱了”
开发机上跑着 mock 服务，但契约文件没随代码提交，导致新成员 clone 仓库后运行 yarn start 报错：“找不到 openapi.yaml”。协作失效往往始于这种“小遗漏”。
实操底线：
-
openapi.yaml必须放在项目根目录或src/api/下，和源码同仓库、同分支、同 commit - 后端启动时校验该文件是否存在且合法（可用
swagger-parserCLI 预检），否则拒绝启动 - 前端构建脚本里加一步：
npx openapi-typescript src/api/openapi.yaml -o src/api/generated.ts，确保每次 build 都基于最新契约
契约不是交付物，是活代码。它变，两端都得跟着编译、测试、上线。漏掉任何一环，跨团队协作就退化成人肉对线。
