输入校验、错误处理与接口契约
接口不能假设输入总是正确。校验负责拒绝不合格数据，错误契约让前端知道发生了什么以及怎样提示用户。
- 新增任务接口对正常、缺字段和格式错误三类输入给出稳定且可区分的响应。
- 类型、必填字段、长度与业务规则校验
- 检查输入校验、错误处理与接口契约后，应当新增任务接口对正常、缺字段和格式错误三类输入给出稳定且可区分的响应，并保留状态码、响应结构、进程输出和前后端同一次请求作为可重复检查的依据。
- 完成 5.3「写出第一个后端接口」
FOUNDATION
必须理解
接口契约让前后端对字段和错误达成一致；输入校验保护业务边界；错误处理把失败变成可理解、可恢复的信息。三者共同决定联调是否稳定。
本课依次讲清类型、必填字段、长度与业务规则校验、400、401、403、404、409、500 的职责和稳定错误结构、日志和用户提示的差异，最后通过“逐一调用五种场景并比较契约与实际响应”检查学习结果。
快递面单规定姓名、地址和电话格式；缺字段时工作人员不会把包裹随便寄出，而会指出哪项有问题。内部传送带故障也不会把机器细节写给顾客。
创建任务要求 title 为 1 到 80 个字符，成功返回 Task，校验失败返回字段错误，服务器异常返回通用信息并在日志保留细节。
类型、必填字段、长度与业务规则校验
校验会检查类型、长度、格式和业务规则。去掉标题首尾空格通常没问题，但不要在用户不知情时把内容改成另一种意思。
基础概念
输入校验是把外部数据与明确规则比较，包括类型、必填、长度、格式、取值范围和业务条件。只有全部满足后，数据才能进入核心逻辑。
进一步理解
类型与格式回答“长得对不对”，业务规则回答“在当前状态下允不允许”。例如标题是字符串仍可能过长，日期格式正确仍可能早于项目开始。
规范化可去除无意义差异，如首尾空格；但不能悄悄改变用户真实含义。校验错误应指向具体字段与可修复原因。
创建任务先确认 body 是对象、title 是 1 到 80 个字符，再确认同一项目没有违反唯一规则，最后才写数据库。
校验不是清洗一切输入，也不是安全的全部。权限、参数化查询和输出编码仍属于其他防线。
这一小节记住：在可信逻辑开始前，把数据形状与业务边界明确检查一遍。
400、401、403、404、409、500 的职责
接口契约就是前后端共同遵守的约定：用什么方法、发哪些字段、成功和失败分别长什么样。字段一改，两边都要知道。
基础概念
HTTP 400 表示请求无效，401 表示尚未认证，403 表示身份已知但无权操作，404 表示资源不存在，409 表示状态冲突，500 表示服务端意外失败。
进一步理解
状态码让调用方先判断失败类别，错误正文再给稳定代码、用户消息和可选字段细节。不同错误应保持语义一致，不能全部返回 200。
有时出于安全考虑，服务端会用 404 隐藏资源是否存在；这是明确策略，不是随意混用。500 响应给用户通用信息，内部日志保留请求标识与详细原因。
未登录创建任务返回 401；登录但编辑他人任务返回 403 或策略化 404；重复唯一标题返回 409；数据库异常返回 500。
401 不等于“权限不够”，403 也不等于“没登录”。状态码选择影响前端是引导登录、提示无权还是允许重试。
这一小节记住：用状态码表达失败类别，用稳定正文帮助调用方采取下一步。
稳定错误结构、日志和用户提示的差异
400 多半是请求本身有问题，401 和 403 与身份权限有关，404 是没找到资源，409 是冲突，500 则是服务端意外。给用户的错误要稳定，也别把堆栈和秘密直接吐出去。
基础概念
错误结构是程序之间的稳定契约，日志是维护者调查内部过程的证据，用户提示是面向当前任务的可理解说明。三者受众不同，信息量也不同。
进一步理解
响应可包含 `code`、`message`、`fieldErrors` 和 `requestId`；日志则记录异常类型、操作上下文和堆栈，但要脱敏。界面根据 code 决定聚焦字段或展示重试。
不要把原始数据库错误直接交给用户，也不要只在界面写“失败”。前者泄露内部，后者让用户无法恢复。请求 ID 可以安全地连接两类信息。
标题过长时响应指出 title 限制，界面把提示放到输入框旁；数据库故障只显示“暂时无法保存”，日志用 requestId 记录根因。
错误 message 适合人看，code 适合程序判断；把界面逻辑绑定完整中文句子会让文案调整破坏行为。
这一小节记住：同一次失败，为调用方、用户和维护者提供各自需要的信息。
AI COLLABORATION
AI 如何参与
在输入校验、错误处理与接口契约这一课，AI 负责根据真实材料解释类型、必填字段、长度与业务规则校验并指出遗漏，学习者负责控制范围、执行修改和核对状态码、响应结构、进程输出和前后端同一次请求。
推荐协作顺序
- 1
把字段限制和错误结构告诉 AI，让它先列完整场景表。
- 2
逐条检查状态码、错误 code 和用户提示是否一致。
- 3
用边界输入实际调用，确认实现没有只照顾示例数据。
这是接口输入模型和现有响应。请先列出可验证规则，再设计最小错误结构。错误信息不得包含堆栈、SQL、路径或秘密。为每条规则给正常与失败请求，并说明前端如何展示。
前端可以依据状态码和稳定错误 code 呈现反馈，服务端异常不暴露内部路径或堆栈；输入校验、错误处理与接口契约的人工验收必须回到真实页面、请求、终端、测试或数据结果，不能用 AI 的文字说明代替。
人工检查清单
- 确认校验发生在服务端，客户端校验只是体验优化；状态码与含义一致。
- 要求 AI 为正常、缺失、越界、冲突、未授权和内部失败分别给出输入与预期响应。
- 亲自发送每类请求，确认状态码、错误结构、界面提示和日志内容相互对应且已脱敏。
COMMON TRAPS
常见误区
下面三类问题会让任务看似完成，却经不起刷新、错误输入或真实环境检查。先看现象，再找原因和修正方法。
只在前端校验
- 你会看到
- 绕过页面即可提交错误数据
- 为什么发生
- 调用者可以绕过页面直接发请求，服务端仍会收到未经检查的数据。
- 怎样纠正
- 服务端再次执行权威校验
所有错误都返回 200
- 你会看到
- 前端难以区分成功与失败
- 为什么发生
- 状态码失去语义后，客户端、监控和缓存都难以区分成功与失败。
- 怎样纠正
- 使用合适状态并保持正文结构
把堆栈返回给用户
- 你会看到
- 内部路径和实现细节暴露
- 为什么发生
- 堆栈含有文件路径和内部实现，既难帮助用户，也扩大信息暴露。
- 怎样纠正
- 详细信息写日志，响应保持安全
HANDS-ON
动手任务
新增任务接口对正常、缺字段和格式错误三类输入给出稳定且可区分的响应。
- 完成 5.3「写出第一个后端接口」
跟着做
- 01
为任务创建写出字段表和限制。
- 02
定义统一成功与错误 JSON。
- 03
在 Route Handler 中实现类型、空值与长度校验。
- 04
前端根据 field 显示输入框错误。
- 05
逐一调用五种场景并比较契约与实际响应。
新增任务接口对正常、缺字段和格式错误三类输入给出稳定且可区分的响应。
加入幂等或冲突场景：相同请求重复提交时，决定产品应该创建两条还是返回冲突。
离开本课前，自问四件事
- 类型、格式和业务规则校验有什么不同？
- 400、401、403、404、409、500 各自表达什么？
- 稳定错误结构、用户提示和内部日志为何不能使用同一内容？
- 怎样让一条错误既能被前端处理，又能被维护者追踪？
确认完成后，会同步更新学习中心的课程学习进度。