“下一个空闲时段”并不明确

第 5 讲先给预约服务增加需求:请求时段被占用时,找到下一个空闲时段并直接预约。生成实现每次向后移动一小时,测试全部通过,分支覆盖率也是 100%。

但会议室在 10:15 已空闲时,算法会跳到 11:00;早于营业时间的非法请求,也可能被自动移到 9:00。问题来自没有决定的语义:向哪个方向搜索,保留多长的预约时长,搜索到几点,是直接预约还是只提出建议?

课程先把这些选择写清楚,再生成检查和任务:搜索是纯函数,返回结果必须真的被预约,非法请求不能产生新预约,通知只能发送一次且内容对应实际时段。验证之前需要有设计,任务才能有明确的结束条件。

我们可以把课件中确定的行为列成下面的表,再据此检查实现:

问题本讲选择
从哪里开始搜索从请求时刻向后搜索
搜索到哪里同一天 17:00 为止
是否缩短预约保留请求时长
找到以后做什么实际预约,并返回已经预约的时段

纯搜索函数 nextFreeSlot(existing, request, dayEnd, step) 不读取时钟或仓库,只返回最早可用区间或空结果。测试先固定请求本就空闲、请求被占用、边界相接、空档太短,以及 10:15 已空闲等情况,再连接服务并检查返回时段真的已被占用。课件比较中,最初实现只通过九项检查中的七项,按明确决策生成的版本才通过全部九项。

相应产物也发生变化:除了实现与测试,还留下 SPEC.md、PLAN.md、最初失败的搜索测试,以及记录选择的 ADR。它们让评审者看到行为从何而来,而不只是看到一个最终绿色结果。

设计决定分别转成搜索、服务连接、非法输入与通知检查

赞助商

设计是对系统形状的选择

两个实现都能通过验收,却可能有完全不同的结构。一个使用 Room、Booking、User 表达领域,另一个把关联数据散落在多个平行数组中。外部行为相同,并不能说明它们同样容易理解和修改。

课程把设计分为数据、操作和结构。数据描述系统知道什么,操作描述能够请求它做什么,结构决定数据与操作如何分组、由谁负责。

设计也不同于文件夹布局或一张图。它们是设计的表达方式。判断某个选择是不是重要决策,可以观察逆转成本:循环改成流式写法通常容易;改变 book() 返回值需要检查调用者;把区间改成固定时间槽,还可能需要迁移已存数据。

从领域概念形成数据模型

会议室有名称和容量,用户预约会议室,并能取消自己创建的预约。同一会议室不能存在重叠预约。

需求中的名词提供候选概念,动词提供候选操作,但不能机械照搬。“预约”和“预订”可能是同一动作,数据库和 JSON 则属于实现选择。取消某一个预约的需求,还隐含了预约需要身份标识。

用户、会议室与预约之间的数据关系

实体(Entity)有持续身份,属性变化后仍然是同一个对象;值(Value)由数据本身决定,相等的值可以互换。用户通常是实体,时间区间可以是值。预约是否作为实体,会直接影响取消和追踪的方式。

“不得重复预约”应记录在数据模型的不变量中,让当前和未来操作都继承它。把规则只写在 book() 的注释里,会遗漏导入、管理员操作等入口。具体由服务还是数据库实施约束,是下一层设计选择。

关系图本身也作出了选择。图中的一个预约只属于一个会议室与一个用户,会议室可以存在许多预约。以后若支持一次预约占用多个房间,单个 room 字段及所有已有记录都可能需要迁移,不能只在图上把数字改掉。

引用方向是另一项决定:由 Room 保存预约列表,由 Booking 引用会议室,还是双向引用?双向方便遍历,但需要维持一致;直接改成 Map<Room, List<TimeRange>> 虽然紧凑,又会丢掉独立预约的身份。我们需要结合取消、查询与生命周期选择表示,而不是让存储容器替我们决定领域概念。

操作决定调用者可以依赖什么

book() 返回 void、预约 ID、完整对象或结果类型,会形成不同契约。失败用异常、空值还是明确错误结果,也需要一致约定。操作名称最好对应领域行为,例如取消后重新预约,可能与简单更新一行数据具有不同规则。

课程用作业二 API 展示状态码、令牌和错误顺序。坏令牌、资源不存在和请求体无效同时出现时,契约规定先判断哪一种错误,所有入口才能保持一致。对不承诺格式的标识符保持不透明,以及为扩展预留命名空间,则有助于后续演进。

例如作业二注册接口成功返回 201,并给出新用户与令牌,让客户端能够继续操作;用户名占用返回 409,缺少用户名或密码返回 400。受保护入口还按 401、404、400、409 的既定顺序判断不同错误。另一种顺序未必不合理,但所有实现必须兑现同一契约。

不透明标识符不承诺内部格式,调用者就不应自行拆解。容忍未知字段的读取方、保留给扩展的 x_ 字段与 /api/x/... 路由,则减少后续核心契约与用户扩展的碰撞。这里每一项都在决定哪些变化可以留在边界内部。

操作集合也包含有意不开放的能力。addRoom、book、cancel 和 listBookings 足以表达当前需求时,是否额外允许任意修改预约、绕过冲突检查,需要单独论证。少暴露一个无依据的入口,就少一份未来必须维护的承诺。

边界分配责任,也限制影响

数据确定以后,需要决定谁检查空闲、谁创建预约、谁编排流程。模块通过操作提供承诺,把内部存储与算法藏在边界后面。方法、类、模块和子系统都需要回答同一个问题:负责什么,允许外界看到什么?

代码中的概念越接近问题领域,表示差距(Representational Gap)就越小。Room.isFree(slot) 比 process(data, true, 2) 更容易理解,也更容易让新会话中的 Agent 正确定位修改。

这些表示与职责确定以后,还可以继续比较不同拆分在真实变化中的代价。

比较不同的拆分方式

课件最后要求把存储、领域、API 的分层重新划分。例如按预约功能组织,可以把一次业务变化所需代码放得更近;围绕日历组织,又可能简化空闲查询,但让用户与通知职责更难安放。这里没有唯一答案,要明确哪项操作变容易、哪项变化变困难。

同样,区间模型灵活,却需要认真测试边界与重叠;固定时间槽容易枚举,却限制了可表达的时长。即时计算空闲、缓存空闲、持久化开放时段,则分别在计算成本、读取速度与一致性维护之间取舍。性能、可修改性、可测试性、可靠性与简单性,才是比较方案时可讨论的依据。

Agent 可以先给出数据模型与多个候选拆分,我们再检查它是否凭空增加概念、图中隐藏了哪些责任、什么最难逆转。本讲尤其强调先确定数据模型,因为后续操作、已存数据与调用者都建立在它上面。确定之后,还需要把理由写下来,下一讲继续解决这些决策怎样保存。

参考资料