语之溪
竞赛平台的接口工作，很多时候不是把数据保存下来就结束了。一个接口是否能正常返回，还要看当前数据是不是完整、操作是否满足条件，以及前后几个功能之间能不能接得上。
在 2023 年 7 月参与三期开发时，我开始比较集中地遇到这类问题。比如任务列表中的总分为空时，接口不能直接把它当成 0 返回；前台进入比赛时，需要判断战队是否处于延迟状态；修改页面上的内容时，也要重新检查公共接口和编辑、删除接口的条件。
这些问题看起来分散在不同功能里，实际都和“当前状态是否允许继续操作”有关。
空值不是零
任务总分为空时直接返回空，是一个很容易被忽略的细节。空值和 0 在业务上可能代表不同含义：前者说明还没有设置，后者可能表示明确设置成了零。
如果接口把空值统一转换成 0，前端就很难区分这两种情况。页面可能显示出一个看似正常的数字，但用户无法判断这个任务到底没有设置分数，还是分数确实为零。
处理这类问题时，我开始注意到，接口返回值不能只看类型是否正确，还要看这个值在业务中的含义。数据库可以接受空值，接口也应该根据实际情况保留这种区别。
操作前要确认状态
另一个问题出现在前台进入比赛的流程中。获取题目信息时，需要先判断战队是否处于延迟状态。
这说明接口调用不是一串互相独立的请求。前一个状态会影响后一个操作是否可以继续，接口应该在合适的位置做检查，而不是等到后续步骤出现异常后再处理。
我现在对“状态流转”的理解还不完整，但已经能感受到一个基本关系：
当前状态 -> 条件校验 -> 允许操作或返回提示这不是项目中完整的状态机定义，而是我在修改问题时形成的工作认识。对于比赛、试卷和任务这类关联较多的功能，先确认状态，再执行操作，通常比只关注当前页面更可靠。
删除也有数据关系
试卷设置中还遇到过删除红蓝对抗试卷后关联信息没有删除的问题。表面上看是一个删除接口，实际影响的不只是当前试卷记录，还包括和它关联的其他数据。
类似的问题在训练平台中也出现过：删除岗位或职业时，相关联表数据没有完全删除；删除课程、章节或方向时，对应的图片文件也需要处理。这些记录让我逐渐意识到，删除操作不能只检查主表是否已经没有数据，还要确认关联内容是否仍然残留。
出于项目脱敏和公开边界，本文不展开具体表结构和删除策略。但从这些问题可以确认，接口修改需要同时考虑数据关系和后续页面表现。
响应实体与接口边界
现在是 10 月，三期接口正在进行新一轮整理。试题中心增加了独立响应实体类，相关接口也在同步修改；试题中心和试卷中心的多种模式接口继续更新。
独立响应实体的意义，可以先从接口边界来理解：接口不一定要直接把内部数据结构原样暴露出去。将返回内容整理成面向接口的响应对象，有助于让前端得到更稳定、清晰的结果。
这里不展开具体类名和代码，一方面是出于项目脱敏要求，另一方面也避免把内部实现直接带到公开文章中。对现在的我来说，更重要的是开始关注接口返回对象本身，而不是只关注查询能不能执行成功。
进度也有状态
截至昨天，周报记录试题中心完成，试卷中心进度约为 40%。接下来还要继续完成试卷中心内容、接口文档以及前后端对接测试。
这也是项目工作中的一种状态流转：功能并不是只有“完成”和“未完成”两个结果。接口可能已经完成一部分，文档可能还需要更新，前端对接可能还没有结束。记录进度时，如果把这些状态压缩成一个“已完成”，后续就很难判断真正还剩下什么。
对我来说，接口、校验和状态流转逐渐变成了同一个问题的不同侧面：
- 接口负责让功能之间能够交换数据；
- 校验负责判断当前操作是否成立；
- 状态记录负责说明功能现在走到了哪一步。
在竞赛平台这种关联较多的系统里，接口不是孤立存在的。一个空值是否保留、一次删除是否完整、一次进入比赛是否满足条件，都可能影响后续功能。现在我还在继续熟悉项目代码，也越来越清楚，修改一个接口之前，应该先把它连接到的业务关系和状态变化看清楚。
