---
name: devlab-contract-web-server
description: 前后端契约规范技能（contract 技能簇首个，定位介于 devlab-srv-* 与 devlab-web-* 之间）。约束大型前后端分离项目的接口/序列化契约、字段类型一致性、错误码与配置分层，提供契约校验与联调防错清单。Triggers on "前后端契约", "接口对不上", "序列化", "字段类型不一致", "contract", "api schema", "联调对齐".
---

# 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/端口/凭据；示例字段不含真实隐私数据。
- 规范要可校验，避免只写文档不落校验。

## 推荐触发方式

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

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