devlab-contract-web-serverlisted

# 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/缺省/空值语义已约定。 - [ ] 时间/时区/数字精度格式已约定。 - [ ] 错误码结构统一，前端按码分支。 - [ ] 敏感配置未进前端；环境变量前缀正确。