工程文章

把交付边界写清楚,比先选框架更重要

从目标、状态、接口到验收证据,讨论怎样让一个软件项目的交付范围可以检查。

  • 交付
  • 接口契约
  • 验收

“做一个后台”还不是可验收的目标

当需求只有一个页面名字时,每个人脑中的结果可能不同。运营关心批量操作能否节省时间,财务关心金额来源,开发者可能先想到表格和接口。先实现页面,往往只是把分歧推迟到验收时。

更有用的起点,是描述一个人要完成什么任务。例如“有退款权限的运营者,能在订单仍可退款时提交退款申请,并看见接收结果”。这句话可以继续拆出角色、状态、输入和结果,也能暴露尚未决定的问题。

让状态成为共同语言

“已完成”在订单、支付和交付里可能有不同含义。应先写出状态来源、允许的转移,以及谁能触发这些转移。界面、接口和报表都需要沿用相同定义。

可以拿一条典型记录,从创建一直追踪到关闭,再补上取消、失败和恢复。如果流程图只包含成功路径,就还不足以指导实现。历史数据和旧客户端能否继续工作,也属于状态边界。

把接口契约写成可以核对的约定

接口说明不应只有 URL 和字段名字。必填与可选、金额精度、时间范围、分页、鉴权、错误码、重试和幂等都影响调用结果。

对于外部服务,尤其需要区分传输成功与业务成功。请求超时之后,调用方如何知道动作是否已经执行?再次发送会不会重复扣库存或创建任务?这些问题应先有约定,再选择队列或缓存等技术。

验收证据应对应实际结论

单元测试通过,可以证明某个逻辑分支符合测试输入,不能证明浏览器、设备、真实支付渠道或生产部署都正常。静态审查同样不能代替真实接口返回。

交付说明应写清检查环境、操作步骤、观察结果和未覆盖范围。需要外部账号才能完成的验证,应保留为明确的待办,而不是因为界面能打开就认定完成。这样做并不削弱交付,反而让接手的人知道还需要什么。

范围变化也需要有入口

业务讨论中会发现新需求。重要的不是拒绝变化,而是说明变化影响哪些页面、接口、数据和验收条件,再决定进入本期还是下一期。

一个简单的变更记录,可以保留原因、范围、依赖和接受标准。不必为了每次沟通建立复杂制度,但不能让“顺便加一下”在没有评估时改变核心数据模型。

从一个闭环开始

  1. 选择一个具体角色和一项可以完成的任务。
  2. 写出正常、拒绝和失败后的表现。
  3. 确认数据与权限的真实来源。
  4. 为最容易出错的边界先写测试。
  5. 展示完整闭环,并记录验证到哪一层。

Commerce Lab 把这些问题放进交易场景中讨论。它是方案演示,不是成功案例证明;阅读时可以将其中的状态和验收问题换成自己的业务。框架选择随后会更具体,因为真正需要解决的问题已经有了边界。