devlab-contract-web-server

用途

为大型前后端分离项目建立并守护"契约层"：前端与服务端就接口结构、字段类型、序列化形态、错误码、配置边界达成显式契约，避免靠口头约定导致的联调返工与线上事故。

定位：devlab-contract-* 技能簇的首个成员，处于 devlab-srv-*（服务端）与 devlab-web-*（前端）之间的交界地带。

适用场景

• 前后端分离、多人协作、接口频繁演进的中大型项目。
• 联调阶段反复出现"字段对不上/类型不匹配/序列化不一致"。
• 需要把接口从"约定俗成"升级为"可校验契约"。

不适用场景

• 单体、无独立前端的项目。
• 一次性脚本/内部工具（契约成本大于收益）。

输入

• 现有接口清单/文档（OpenAPI、代码里的 DTO/schema 等）。
• 前后端技术栈与序列化方式。
• 已发生的契约类问题（可选）。

输出

• 契约规范文档（字段命名/类型/可空性/枚举/时间格式约定）。
• 契约校验建议（schema 校验、契约测试落点）。
• 联调防错清单。

核心规范

1. 字段类型契约

• 每个字段显式定义：类型、可空性、枚举取值、单位、时间/数字格式。
• 类型一致性：同一字段跨前后端类型必须一致（典型坑：id 服务端 int、前端传 string → 解析失败）。
• 数组元素结构显式声明（典型坑：groupBy 期望字符串数组，前端传对象数组 [{field: x}]）。

2. 序列化契约

• 统一约定 null/空值/缺省字段的语义（省略 vs null vs 空串）。
• 显式约定大整数/精度/日期的序列化（避免 JS number 精度、时区歧义）。
• MIME/编码显式声明（响应体类型不靠猜）。

3. 错误契约

• 统一错误码 + 错误体结构；区分业务错误与系统错误。
• 前端按错误码分支，不靠 message 文本判断。

4. 配置分层与"不过度"

• 配置分层：与某子系统强相关的配置归其命名空间（如 LLM 配置与排序配置分离），避免大杂烩。
• "既不过度也不缺失"：每个真实可变项可配，不为不存在的需求预埋开关。
• 敏感配置（密钥）不进前端，前端只按构建工具约定前缀暴露非敏感变量。

5. 契约校验落点

• 服务端入参用 schema 校验（类型/必填/枚举），错误要可读（不是裸 500）。
• 有条件时用 OpenAPI/JSON Schema 作单一事实源，前后端各自生成/校验。
• 契约变更 → 契约测试先失败 → 双方同步 → 再合入（破坏性变更同步调用侧）。

工作流

Phase 1: 盘点接口与现存契约问题
Phase 2: 定义契约规范（字段/序列化/错误/配置）
Phase 3: 落地校验（schema 校验 + 契约测试落点）
Phase 4: 防错清单 + 变更流程（破坏性变更同步调用侧）

联调防错清单

• 关键字段类型前后端一致（尤其 id/数字/布尔/枚举）。
• 数组元素结构一致（对象数组 vs 标量数组）。
• null/缺省/空值语义已约定。
• 时间/时区/数字精度格式已约定。
• 错误码结构统一，前端按码分支。
• 敏感配置未进前端；环境变量前缀正确。
• 契约变更走"契约测试先行 + 同步调用侧"。

与其他 devlab-* Skill 的关系

Skill	关系	说明
devlab-srv-*	邻接（服务端侧）	服务端接口实现与入参校验
devlab-web-*	邻接（前端侧）	前端接口调用与类型定义
devlab-contract-*（簇）	同簇	未来可扩展 contract-service-service、contract-event 等
devlab-ai-agent-engineering	调用方	AI 应用前后端交互契约引用本技能

约束

• 契约是双方共识，任何一方单改必须走"契约测试先行 + 同步对侧"。
• 不硬编码具体 URL/端口/凭据；示例字段不含真实隐私数据。
• 规范要可校验，避免只写文档不落校验。

推荐触发方式

用 devlab-contract-web-server 帮我把这几个接口的前后端契约固化并加校验

联调老是字段对不上，帮我建一份契约规范 + 防错清单