接口和数据模型是后端协作里的“公共语言”。这一步如果没讲清楚，AI 帮你写得再快，后面联调、测试和文档都会跟着出偏差。所以这一课的重点不是“让 AI 自动生成 DTO”，而是学会用 AI 更快暴露边界、比较方案、补齐异常和字段语义。
真实研发场景
大多数接口问题不是编码时出现，而是在契约阶段埋下
一个功能刚进入设计时，经常会出现这种对话：“先把接口写出来，细节后面再补。”结果是 DTO 很快有了，字段名也不少，看起来一切都在推进。但等前端开始联调、测试开始造样例、文档开始补说明时，问题一批批冒出来：字段到底是必填还是可选、错误码怎么分类、列表接口要不要分页、时间字段用什么格式、这个响应对象到底是不是应该带状态字段。
如果这时让 AI 直接“生成一版完整接口”，模型往往会非常积极地把你没说清楚的地方补齐。危险就在这里：它补齐得越像样，团队越容易误以为契约已经定了。
本课真正要建立的是“先讲场景，再讲字段”
一个稳定的接口设计流程，应该先回答使用场景、调用方、状态变化、异常语义，再去写字段和类定义。AI 的价值就在于帮助你把这些信息组织成字段矩阵、错误表和方案对比，而不是一开始就产出最终 Java 类。
传统做法的痛点
契约一旦模糊，所有协作方都会被迫猜
| 协作方 | 看似拿到了什么 | 实际还缺什么 |
|---|---|---|
| 前端 | 一组字段名 | 字段何时出现、何时为空、何时报错 |
| 测试 | 一个示例 JSON | 边界值、异常码、状态流转 |
| 文档维护者 | 一个接口草稿 | 语义说明、版本策略、兼容性 |
| 后端自己 | 一份 DTO | DTO 与领域对象、配置对象的边界 |
这也是为什么“接口已经有了”不代表“接口已经设计完了”。
AI 参与建模时最容易放大的三个问题
- 字段过量：模型会倾向于补出“可能用得上”的字段，导致响应体越来越胖
- 边界混杂：把传输模型、领域模型、配置模型写成一团
- 命名失真：字段名语义看起来专业，但和真实业务动作不一致
这些问题不一定会马上炸，但会在联调和维护时持续制造摩擦。
AI 能提效到哪一步
最值得让 AI 起草的是这些内容
- 字段矩阵：字段名、类型、是否必填、来源、默认值
- 错误场景表：什么条件下返回什么错误码或状态
- 请求响应示例：帮助团队快速对齐调用形状
- 契约对比：同步接口 vs 异步任务、精简响应 vs 富响应
必须由工程师拍板的内容
| 内容 | 为什么不能直接让 AI 决定 |
|---|---|
| 版本兼容策略 | 影响历史调用方和升级成本 |
| 字段是否公开 | 涉及隐私、权限和职责边界 |
| DTO 与领域模型边界 | 影响后续维护和重构成本 |
| 错误码体系 | 影响前后端协作与可观测性 |
一个简单判断是：凡是会影响多个调用方长期协作的地方，都不该只靠模型自动补全。
推荐工作流
先给 AI 的不应该是类定义，而是场景约束
推荐先准备这些输入：
- 这个接口服务谁
- 调用时机和业务动作是什么
- 成功和失败各有哪些状态
- 哪些字段来自已有代码或配置
- 哪些约束已经定了，哪些还没定
用四步把契约从“猜字段”变成“对齐语义”
| 步骤 | AI 产出 | 人工要做什么 | 验证方式 |
|---|---|---|---|
| 1. 讲场景 | 调用方、目标、状态清单 | 删除不真实的业务假设 | 是否能不用写类就讲清行为 |
| 2. 生字段矩阵 | 字段表、必填性、示例值 | 砍掉冗余字段，统一命名 | 字段是否都能解释来源与语义 |
| 3. 补错误表 | 错误码、异常条件、边界场景 | 确认哪些错误需要暴露 | 测试是否能据此补样例 |
| 4. 回写代码 | DTO 草稿、配置对象草稿 | 审核分层与兼容性 | JSON 示例、测试或接口评审 |
一个实用输入模板
业务动作：
调用方：
成功结果：
失败结果：
已有字段或配置来源：
请输出：
1. 请求/响应字段矩阵
2. 错误场景表
3. 两种可选契约方案及取舍
与仓库代码和模板的映射
- 最小请求响应对象：
../demo/src/main/java/com/example/ainative/chat/api/ChatRequest.java、../demo/src/main/java/com/example/ainative/chat/api/ChatResponse.java适合观察简单同步接口的最小契约形状。 - 带引用信息的响应：
../demo/src/main/java/com/example/ainative/knowledge/rag/api/RagAnswerResponse.java适合讨论“业务结果”和“支撑信息”怎么一起返回。 - 上传结果对象：
../demo/src/main/java/com/example/ainative/knowledge/document/api/UploadDocumentResponse.java适合思考任务状态和结果摘要如何表达。 - 配置建模：
../demo/src/main/java/com/example/ainative/bootstrap/config/InfraProperties.java、../demo/src/main/resources/application.yml适合说明“配置对象”也是一种建模，不该和接口 DTO 混在一起。 - 对应练习：
../课后练习/第2课/练习.md
常见误用与风险
误用一：让 AI 直接生成“完整 DTO”，却没先讲调用场景
模型会默认替你补齐很多字段，这些字段未必真的有业务语义。
误用二：把传输对象和领域对象混为一谈
这会让后续重构、校验和兼容性处理都变得更难。
误用三：只有 happy path，没有异常表
没有错误表的接口设计几乎一定会在联调阶段返工。
误用四：看到字段很多就以为设计很完整
字段数量不等于契约质量，关键是每个字段是否有明确语义、来源和边界。
课后练习
建议直接在 ../课后练习/第2课/练习.md 中完成本课练习，并使用 ../课后练习/通用提交模板.md 保留 AI 输入、人工删改和验证结果。
如果你只做最小版交付，也至少保留四样东西：结构化输入、AI 产出摘要、人工判断记录、最终验证结果。
基础题
选一个你熟悉的接口场景，先不要写 Java 类，只写请求/响应字段矩阵。
进阶题
补一份错误场景表，覆盖参数错误、权限错误和业务失败三类情况。
挑战题
对照 demo/ 中的一个响应对象，给出两种可选契约方案，并说明你会选择哪一种以及原因。