工程文章
把交付边界写清楚,比先选框架更重要
从目标、状态、接口到验收证据,讨论怎样让一个软件项目的交付范围可以检查。
“做一个后台”还不是可验收的目标
当需求只有一个页面名字时,每个人脑中的结果可能不同。运营关心批量操作能否节省时间,财务关心金额来源,开发者可能先想到表格和接口。先实现页面,往往只是把分歧推迟到验收时。
更有用的起点,是描述一个人要完成什么任务。例如“有退款权限的运营者,能在订单仍可退款时提交退款申请,并看见接收结果”。这句话可以继续拆出角色、状态、输入和结果,也能暴露尚未决定的问题。
让状态成为共同语言
“已完成”在订单、支付和交付里可能有不同含义。应先写出状态来源、允许的转移,以及谁能触发这些转移。界面、接口和报表都需要沿用相同定义。
可以拿一条典型记录,从创建一直追踪到关闭,再补上取消、失败和恢复。如果流程图只包含成功路径,就还不足以指导实现。历史数据和旧客户端能否继续工作,也属于状态边界。
把接口契约写成可以核对的约定
接口说明不应只有 URL 和字段名字。必填与可选、金额精度、时间范围、分页、鉴权、错误码、重试和幂等都影响调用结果。
对于外部服务,尤其需要区分传输成功与业务成功。请求超时之后,调用方如何知道动作是否已经执行?再次发送会不会重复扣库存或创建任务?这些问题应先有约定,再选择队列或缓存等技术。
验收证据应对应实际结论
单元测试通过,可以证明某个逻辑分支符合测试输入,不能证明浏览器、设备、真实支付渠道或生产部署都正常。静态审查同样不能代替真实接口返回。
交付说明应写清检查环境、操作步骤、观察结果和未覆盖范围。需要外部账号才能完成的验证,应保留为明确的待办,而不是因为界面能打开就认定完成。这样做并不削弱交付,反而让接手的人知道还需要什么。
范围变化也需要有入口
业务讨论中会发现新需求。重要的不是拒绝变化,而是说明变化影响哪些页面、接口、数据和验收条件,再决定进入本期还是下一期。
一个简单的变更记录,可以保留原因、范围、依赖和接受标准。不必为了每次沟通建立复杂制度,但不能让“顺便加一下”在没有评估时改变核心数据模型。
从一个闭环开始
- 选择一个具体角色和一项可以完成的任务。
- 写出正常、拒绝和失败后的表现。
- 确认数据与权限的真实来源。
- 为最容易出错的边界先写测试。
- 展示完整闭环,并记录验证到哪一层。
Commerce Lab 把这些问题放进交易场景中讨论。它是方案演示,不是成功案例证明;阅读时可以将其中的状态和验收问题换成自己的业务。框架选择随后会更具体,因为真正需要解决的问题已经有了边界。