工程基础三件套
从 requirement 推导到可运营、可演进的 change

一项业务诉求不会自动变成可交付的软件。本章沿一条完整链路走：先把 business requirement 推成 functional 与 infrastructure requirements，再把它落实为 REST / JSON / async 合约，最后用 systems life cycle、版本控制、code review 与分阶段 refactoring 守住演进质量。

一、先拆业务句子：目标、约束、验收证据

设想团队要给客服工作台接入一个由 Claude 应用调用的内部 case service。原始需求只有一句：「大促期间把退款案例的中位处理时间从 9 分钟降到 3 分钟，同时不能重复退款，所有决定可追溯。」这句话混着三种不同东西：

推导的第一步不是立刻选数据库或 queue，而是把自然语言变成可观测的结果、不可破坏的不变量、可验收的边界。诸如「系统要快」「架构要 scalable」无法直接验收；把它们改成带 workload、percentile、failure mode 与观察窗口的条件，后续设计才有裁决标准。

二、Functional requirements：描述可见能力，不偷渡实现

Functional requirement 回答「系统对外能做什么」。对上述 case service，可以写成一组可验证的 capability：

1. 接收带稳定 request ID 的退款案例，并返回 case ID；
2. 查询 case 的当前状态、决定与失败原因；
3. 在满足授权条件时提交人工覆盖，并记录操作者与理由；
4. 同一 request ID 与同一 payload 重放时返回同一业务结果；
5. 同一 request ID 搭配不同 payload 时拒绝歧义，而不是执行第二次。

这组写法没有指定 PostgreSQL、Kafka 或某个 framework，因为那些是候选实现。反过来，若业务真的要求「调用方在 300 ms 内拿到最终决定」，同步完成就是功能边界的一部分；若允许稍后查询，那么「提交 + 状态资源」才是合理合约。同步还是异步不是偏好，而是 response-time requirement 推出来的。

三、Infrastructure requirements：从 solution architecture 反推运行条件

Solution architecture 给出组件与数据流，infrastructure requirement 则说明这些组件在目标 workload 下需要什么运行条件。假设架构是「API → durable queue → worker → ledger adapter」，推导链应逐项落地：

这里最容易犯的错是把产品清单当 requirement：写「需要 Kubernetes」只说了工具，没有说负载、故障或恢复目标。更好的写法先声明 throughput、latency、durability、security、observability 与 recovery 约束，再由团队比较 managed service、自托管组件或更简单的进程内方案。

四、REST contract：先建模资源，再选择 method 与 status

REST API 的核心不是把函数名搬进 URL，而是给资源、状态转换与错误语义一个稳定合约。异步 case 可建模成：

POST /refund-cases
Idempotency-Key: req-8f2…

{ "order_id": "o-1842", "amount": "49.90", "currency": "USD" }

202 Accepted
Location: /refund-cases/case-731

{ "id": "case-731", "status": "queued" }

202 Accepted 表示请求已接收、处理尚未完成；调用方随后 GET /refund-cases/case-731 读取状态。若服务器已经同步创建完整资源，201 Created 更贴切。选择 status 的判断轴是此刻已经发生了什么，而不是团队习惯统一返回 200。

五、幂等与重试：把「至少一次到达」变成「一次业务效果」

网络超时只说明客户端没有看到响应，不说明服务器没有执行。若调用方在超时后重试，资金、发信、建单等副作用就可能重复。幂等设计要覆盖完整竞态：

1. 客户端为一个业务意图生成稳定 key，重试沿用它；
2. 服务器把 key、规范化请求摘要、处理状态与最终响应关联起来；
3. 首次执行与幂等记录写入处在能共同成败的一致性边界；
4. 相同 key + 相同请求返回既有结果；相同 key + 不同请求返回冲突；
5. 处理中重入有明确行为：等待、返回 processing，或让调用方稍后查询。

Retry policy 与幂等合约要成对设计。临时网络错误或服务不可用可以采用有上限的 exponential backoff 加 jitter；校验失败、权限不足、schema 不兼容通常需要改请求，机械重试只会制造流量。即便 operation 可幂等，无界重试也会把局部故障放大成 retry storm。

六、JSON schema 演进：缺失、null 与类型是三件事

JSON 的 object、array、string、number、boolean 与 null 看似简单，跨版本时真正危险的是双方给同一字段赋了不同语义。以退款结果为例：

{
  "status": "needs_review",
  "risk_score": null,
  "reasons": [],
  "schema_version": 2
}

• risk_score 缺失可表示旧 producer 不认识该字段；显式 null 可表示 producer 认识但没有值。若 contract 不区分，两者就不要在 consumer 里擅自赋不同业务含义。
• 空数组表示「集合存在且当前无元素」，不等于字段缺失，也不等于 null。
• JSON 的 number 不替 consumer 保证整数宽度或十进制定点精度；金额等精确值需要双方明确表示法与校验规则。

兼容演进通常优先 additive change：新增 optional 字段、consumer 忽略未知字段、producer 不随意改变既有字段类型或语义。删除 required 字段、收窄可接受值、把 string 改成 number 都可能破坏旧 consumer。若系统承诺 Semantic Versioning，MAJOR.MINOR.PATCH 的含义应与公开 contract 的兼容性绑定，而不是与改动行数绑定。

七、异步编程：并发不是无限并行

async/await 让程序在等待 I/O 时把执行机会交回 scheduler；它不会自动让 CPU-heavy 工作并行，也不会自动限制同时在途的请求。一个看似简洁的实现：

results = await gather(*(process(case) for case in cases))

若 cases 有 50,000 个，这行代码可能同时建立过多 connection、占满 memory，并把下游压垮。生产设计需要把 concurrency 当资源预算：

1. 用 semaphore、worker pool 或 queue 设置 bounded concurrency；
2. 用 timeout 与 cancellation 释放调用方已经放弃的工作；
3. 用 backpressure 让 producer 在 consumer 落后时减速，而不是只扩 backlog；
4. 区分 task 失败策略：fail-fast、收集部分结果、重试单项或送 dead-letter queue；
5. 保留 correlation ID，使并发日志仍能还原单个 case。

选择 concurrency 的依据是下游配额、连接池、单任务内存、CPU/I/O 比与目标 latency。把并发从 20 调到 200 可能提高吞吐，也可能只提高 timeout 与 retry 数；答案要看 bottleneck 的测量结果。

八、Systems life cycle：develop / implement / operate / maintain

Systems life cycle 不是「开发完再交给运维」的流水线。四个阶段各有不同决策证据，并通过反馈闭环连接：

例如「压测通过」只覆盖 develop/implement 的部分风险；它不能替代生产中的 latency、error rate 与 backlog 观测。反过来，operate 发现 queue age 持续增长，应回流到 requirement 与 capacity model，而不是永久把 alert threshold 调高。

九、版本控制与 Code review：让风险按 diff 暴露

版本控制的价值不只是保存文件，而是把 change 的意图、边界与验证证据组织成可审查单元。短生命周期 branch、小而自洽的 commit、可复现的 CI 结果，能让 reviewer 判断「为什么改、改了什么、失败时怎么退」。若一个 commit 同时改 API contract、数据库迁移、UI 文案与格式化，任何回退都会带走无关工作。

Code review 应把注意力放在自动化工具看不懂的风险上：

Review comment 也要区分 blocker 与 preference。会导致数据错误、安全问题、兼容性破坏或无法运维的缺陷应阻断；纯个人风格若已有 formatter 或团队没有约定，不宜掩盖真正风险。

十、小重构与大重构：保持行为，分阶段换结构

Refactoring 的目标是在保持可观察行为的前提下改善内部结构。rename、extract function、消除重复通常可在现有测试保护下做成小 change；跨 service、schema 或数据所有权的大重构，则需要先创造兼容 seam。

以 customer_id 改名为 account_id 为例，直接一次性改 producer、queue schema、数据库与所有 consumer，会把部署顺序变成隐含前提。更稳的 sequence 是：先让 consumer 双读；再让 producer 写新字段并保留旧字段；回填与观测；确认旧字段无读者后再删除。每一步都可部署、可验证、可回退。

把三条主线收在一起：business requirement 给出成功标准，life cycle 给出每阶段证据，software engineering practices 把每次 change 缩成可审查、可运营、可演进的单元。题目问「下一步」时，不要选最终最宏大的架构；选当前证据下最小、完整、能降低主要风险的那一步。

本章题组