软件工程两小时入门：从页面到可靠交付

深挖一：一个按钮点击以后，前端到底发生了什么？

0. 本节先认词 / 先认变量

1. 先把页面理解成“状态 → 界面”的函数

现在再看下面这句：

View = render(props, state)

逐个翻译：

• View：用户现在看到的界面。
• render：根据数据生成界面的过程。
• props：外部传给组件的数据。
• state：组件当前自己保存的状态。

所以整句不是让你算数学题，而是在说：“页面现在长什么样，由外部输入和当前状态共同决定。”

例如教练正在编辑一周计划，至少同时存在三类状态：

• 界面状态：周三是否选中、动作 Drawer 是否打开、筛选器是什么。
• 请求状态：保存请求当前是 idle（还没发）、loading（正在等）、success（服务器确认成功）、error（失败）。
• 业务状态：这份计划究竟是 draft、published、archived，或者服务器里已经变成了新版本。

最关键的边界是：业务状态不能只听前端自己的。 前端可以临时显示“正在发布”，但最终“是否真的发布成功”要以服务端权威状态为准。

下面按具体值读图。图是教学示例，不是生产系统运行记录。

2. 路由、布局、滚动是三个不同问题

Routing 回答“在哪个页面”；Layout 回答“页面内部怎么排”；Scroll Ownership 回答“内容超出以后到底哪一层滚动”。

fill 和 content 是项目语义，不是 CSS 官方关键字。你真正要问的是：这个页面是在“读一份会自然增长的内容”，还是在“操作一个需要占满视口的工作台”？

3. 点击“发布”之后发生了什么

先认下面链路里的三个新词：Reverse Proxy（反向代理）是服务端前门；Authentication（身份认证）回答“你是谁”；Authorization（授权）回答“你能不能做这件事”。后面第三章会细讲，这里只看它们在流程中的位置。

用户点击
→ 前端读取 state
→ 构造 HTTP Request
→ 浏览器发送请求
→ Reverse Proxy / API Gateway
→ 后端 Route
→ Authentication
→ Authorization
→ Business Rule
→ Database Transaction
→ HTTP Response
→ 前端更新 request state
→ 显示权威业务状态

4. HTTP Request 里每个变量是什么意思

常见状态码也先翻译成人话：200 大体成功；400 输入本身有问题；401 没有有效身份；403 有身份但没权限；409 当前状态/版本冲突；500 服务端内部出错。

5. 错误提示真正解决的是“用户下一步做什么”

答案：因为客户端只知道“没收到 Response”，不知道服务端是否已经执行。如果第一次其实已经写库并发通知，第二次可能重复产生副作用。后面支付章节会进一步解释“幂等”如何解决这类问题。

深挖二：数据库不是仓库，而是“守住事实”的机器

0. 本节先认词 / 先认变量

1. CRUD 只是最表层

CRUD 是 Create（创建）、Read（读取）、Update（更新）、Delete（删除）。它告诉你数据库能做哪四类基础动作，但没有回答“哪些数据可以更新、什么时候能删、两个人一起更新怎么办”。

以训练 SaaS 为例，可以把三个对象分开：

• plans：计划这个业务对象的“当前入口”。
• plan_versions：每次发布/修订后形成的历史版本。
• training_logs：运动员真实执行后产生的记录。

这里 plans、plan_versions、training_logs 只是示例表名。重点是：“计划本身”“计划的版本”“实际执行记录”不是同一个对象。

2. 不变量：真正要守的是规则，而不只是字段

Invariant（不变量）可以理解为：无论系统经历多少合法操作，都必须一直成立的条件。

• 已经发布的历史版本不能被偷偷改写。
• 训练记录必须知道自己执行的是哪个计划版本。
• 同一个支付事件不能生成两条有效账本。
• 一个机构的数据不能被另一个机构的普通账号读到。

这些规则如果只写在前端 if 里，很脆弱；越关键的不变量，越应该由数据库约束、唯一索引、事务和服务端规则一起兜底。

3. Transaction 为什么解决“一半成功”

先认代码里的两个关键词：BEGIN 表示“事务开始”，COMMIT 表示“确认提交”。

BEGIN
INSERT usage_event ...
INSERT ledger_entry ...
UPDATE quota ...
UPDATE invoice ...
COMMIT

逐行翻译：

• usage_event：记录这次到底用了多少服务。
• ledger_entry：账本里新增一条金额/额度变化记录。
• quota：用户剩余额度。
• invoice：账单。

如果这四件事在业务上是一体的，就不希望只做完前两件服务器就挂掉。Transaction 的作用就是尽量让它们表现为“整体成功”或“整体失败”。

4. ACID 四个字母先翻译成人话

5. 状态机不是“有个 status 字段”

DRAFT
  ↓ publish
PUBLISHED
  ↓ execute
IN_EXECUTION
  ↓ complete
COMPLETED
  ↓ review
REVIEWED

这里 publish、execute、complete、review 是“触发状态变化的动作”。状态机真正规定的是：哪些动作在当前状态下合法。

所以“已发布以后为了方便继续改，直接把 status 改回 DRAFT”通常很危险。更合理的是保留已发布的 v7，再创建新的 draft v8。

6. 并发更新为什么会把别人改动覆盖掉

先定义：v7 就是版本 7，v8 是版本 8。A、B 两位教练同时看到 v7。A 先保存，服务器变成 v8。B 还拿着旧 v7 保存，如果服务器不检查版本，就可能把 A 的修改覆盖掉。这叫 Lost Update（丢失更新）。

下面按具体值读图。图是教学示例，不是生产系统运行记录。

Optimistic Locking（乐观锁）的一种写法：

UPDATE plans
SET content = ?, version = 8
WHERE id = 123 AND version = 7;

逐个解释：content 是计划内容；? 是稍后传入真实内容的参数占位符；id=123 指具体计划；version=7 表示“只有服务器仍然是我看到的旧版本 7 时，才允许这次更新”。如果服务器已经是 v8，这次 UPDATE 会匹配不到记录，应返回冲突。

7. Migration：数据库结构自己也有版本

例如现在要给 plans 增加 coach_note。不能只改代码，因为旧数据库没有这个字段。常见安全思路是：

expand → backfill → switch → contract

翻译：先新增兼容结构（expand）→ 给旧数据补值（backfill）→ 新代码切过去（switch）→ 确认旧逻辑不用后再删旧结构（contract）。

答案：因为这会让历史事实倒退。已经收到或执行 v7 的运动员仍需要一个稳定的 v7。正确思路通常是保留 v7，再创建 v8 draft。

深挖三：鉴权真正难的不是登录，而是“谁能对哪条数据做什么”

0. 本节先认词 / 先认变量

1. Session、Cookie、Token、JWT 都只是“维持身份”的手段

Session 可以理解为服务端保存的登录会话；Cookie 是浏览器保存并自动携带的小段数据；Token 是客户端主动携带的身份凭证；JWT 是 JSON Web Token，一种带签名的 Token 格式。

它们解决的是“服务端如何知道这个请求来自谁”。但即使 Token 里写着 role=coach，也不能因此允许他编辑所有机构的所有计划。

2. 真实授权往往是多个条件的 AND

先解释下面变量：authenticated 表示身份是否有效；same_tenant 表示用户和资源是否属于同一租户；role_allows(action) 表示角色是否允许这个动作；has_relation 表示用户和资源是否有业务关系；state_allows 表示资源当前状态是否允许这个动作。

allow = authenticated
        AND same_tenant
        AND role_allows(action)
        AND has_relation(user, resource)
        AND state_allows(action)

AND 的意思是“并且”：所有条件都成立，allow 才是真。

例如教练发布训练计划，需要同时满足：账号有效；属于这个机构；角色允许 publish；确实管理这个训练组；计划当前仍处于可发布状态。

3. 为什么 RBAC 一个人通常不够

RBAC 擅长回答“这个角色大体能干什么”，但不能单独回答“能不能操作这一条具体数据”。例如两个用户都是 coach，一个管理短跑一组，一个管理跳远组。只判断角色会让二者都拥有同样的资源范围。

所以真实 SaaS 常常是：Role + Tenant + Resource Relation + Resource State 一起判断。

4. 多租户最怕“改个 ID 就看到别人数据”

假设页面从来不展示机构 B 的计划，但用户手工调用：

GET /api/plans/98765

这里 98765 只是某份计划的 resource_id。如果后端只按这个 ID 查数据库然后返回，就可能出现对象级越权。

正确思路通常是：查询和授权都带上当前 tenant_id，再校验用户和资源的 relation。前端隐藏按钮只是体验优化，不是安全边界。

5. Audit Log 和普通 Debug Log 不一样

Audit Log（审计日志）记录高价值业务动作，用于回答“谁、什么时候、对哪个对象、做了什么”。典型字段包括 user_id、tenant_id、resource_id、action、version、request_id。

request_id 是一次请求的追踪编号，方便把前端报错、后端日志和审计事件串起来。

答案：浏览器完全可以被用户控制。用户可以自己构造 HTTP 请求。真正的安全条件必须由服务端针对当前 user、tenant、resource、action 再做一次授权判断。

深挖四：异步、Webhook、幂等与支付，为什么会成为生产级难点

0. 本节先认词 / 先认变量

1. 为什么要异步

发布计划时，真正必须同步确认的通常只有核心事实：“这份计划版本是否成功发布”。给 300 个运动员发通知、调用 AI 生成摘要、生成报表，可以放到后台。

HTTP Request
→ 核心事务
→ 写入 Queue
→ Response 返回给用户
              ↓
            Worker
              ↓
     Push / AI / Email

这里 HTTP Request 是用户发来的请求；核心事务 是必须当场确认的数据库变化；Queue 保存待处理任务；Worker 在后台执行。

2. 为什么 Retry 会逼出幂等问题

系统很难保证每个消息“恰好只送一次”。现实里更常见的是：宁愿重复，也别无声丢失。这类语义常被称为 at-least-once delivery，中文可以理解为“至少送达一次，因此可能送达多次”。

于是业务必须能安全处理重复，这就是幂等。

3. 先定义 business key，再谈去重

假设手机离线上传训练记录。先定义两个变量：

• athlete_id：哪位运动员。
• local_log_uuid：手机在本地生成的这条训练记录的唯一编号。

business_key = athlete_id + local_log_uuid

这句话读成：“一条训练记录的业务身份，由运动员身份 + 本地唯一记录号共同决定。” 手机重试 5 次都复用同一个 local_log_uuid，数据库对这个业务键做唯一约束，就能避免生成 5 条重复记录。

4. Webhook 为什么不能假设只来一次

先验签并核对支付交易、金额、币种，再处理业务。验签确认通知来自可信平台；下面的数据库事务把唯一业务占位、账本分录、余额变化一起提交。不能先单独写“已处理”，随后才尝试入账。

接收并验证通知
→ 在同一事务内判定是否已提交该业务效果
→ 首次：唯一占位 + 写账本 + 改余额一起提交
→ 重复且已提交：不再入账
→ 提交成功后返回结果

提交前故障不能吞掉重试；提交后响应丢失不能重复记账。真实异步系统还需区分“已持久接收”和“业务已完成”；这里仅展示一个受控的同步事务例子。

下面按具体值读图。图是教学示例，不是生产系统运行记录。

5. “先 SELECT 再 if”为什么仍然会多加钱

请求 A: SELECT processed = false
请求 B: SELECT processed = false
A: balance += 100
B: balance += 100

先解释：processed=false 表示“数据库暂时认为这个事件还没处理”；balance += 100 表示“在原余额基础上再加 100”。

两个并发请求都可能在任何一个写入之前读到 false，于是两个 if 都通过。真正防重不能只靠应用层查询，而要用数据库 UNIQUE、事务、锁等原子机制。

6. Order、Payment、Ledger、Refund 是不同对象

7. Timeout 不是 Failure

Timeout 只表示“规定时间内没收到 Response”。第一次充值请求可能已经成功，只是响应没回来。所以创建支付/订单这类有副作用的动作，要让重试复用同一个 idempotency_key。

答案：一次明确业务意图生成一个 idempotency key；网络重试复用这个 key。用户明确重新发起一次新购买，则生成新的 key。服务端按 key 唯一，而不是简单按“用户+金额”去重。

深挖五：小程序和手机 App，真正多出来的是“平台与现实世界”

0. 本节先认词 / 先认变量

1. 小程序登录为什么比普通 Web 多一层

先定义：code 是微信临时给客户端的一次性登录凭证；openid 可以理解为某个用户在某个小程序里的平台身份标识；user_id 是你自己业务数据库里的用户 ID。

wx.login()
→ 得到临时 code
→ code 发给你的后端
→ 后端向微信验证
→ 得到平台身份 openid
→ 映射到你自己的 user_id
→ 建立业务 Session / Token

这里最重要的边界是：openid 不是你的完整业务用户模型。 同一个微信用户可能在机构 A 是教练，在机构 B 是运动员。

2. 平台能力意味着平台规则

小程序除了你的代码，还受宿主平台约束：合法请求域名、支付 API、隐私接口、审核、WebView 业务域名等。于是“代码逻辑正确”不等于“平台允许这样运行”。

3. App Lifecycle：程序可能突然不再运行

先解释几个状态：Foreground 是 App 正在屏幕前台；Background 是离开当前屏幕但进程可能还在；Suspended 是系统暂时停止它继续执行；Cold Start 是完全没运行时重新启动。

Cold Start
→ Foreground
→ Background
→ Suspended
→ OS 回收进程
→ 用户重新打开
→ 从本地恢复
→ 再和服务器同步

所以关键输入不能只存在内存变量里。否则用户锁屏或系统回收进程后，刚填的训练记录可能直接消失。

4. Offline-first：本地事实和服务器事实怎么合并

假设运动员离线时执行计划 v3，并记录 100m=10.92s。这里 v3 是 plan_version=3。期间教练在服务器发布 v5。

恢复网络后，正确理解不是“手机有 v3，所以把服务器改回 v3”，而是：

• 服务器当前计划仍然是 v5。
• 本次训练记录保存 plan_version=3，说明当时执行的是 v3。
• 这条本地训练记录有稳定 local_uuid，重复上传不会生成多条。
• 如果同一条记录两端都编辑过，再进入 Conflict Resolution（冲突解决）。

5. Last Write Wins 为什么不是万能答案

Last Write Wins（LWW，最后写入者获胜）就是“谁最后保存，谁覆盖前面”。它对昵称、普通草稿可能够用；对计划版本、审批、支付、训练历史等关键事实通常不够，因为你可能需要保留两边来源和历史。

6. Push accepted 不等于用户已接受业务

先区分三个事实：

1. 推送平台 accepted：平台接收了你要发消息的请求。
2. 设备 displayed / received：设备可能已经展示或收到。
3. 业务 accept：用户本人针对某个具体计划版本明确点击“接受”。

这三件事不能混成一个布尔值。

7. Permission 被拒绝本身就是一种正常状态

定位权限可能是“未请求、允许一次、使用时允许、始终允许、拒绝”。产品逻辑要明确：这个能力是核心必要，还是增强功能。

答案：如果核心任务还能通过手动输入完成，就不应把增强能力缺失变成全局阻断。应该说明哪些自动分析会受影响，同时保留手动路径。

深挖六：AI Coding 时代，真正的交付链不是“代码写完 → push”

0. 本节先认词 / 先认变量

1. Git 证明“源码历史”，不证明“线上版本”

Commit 只能证明某一版源码存在。main 指向最新 commit，也不能推出生产服务器已经运行它。

至少要区分三个身份：

• source_commit：源码是哪一版。
• artifact_digest：构建出的产物是哪一份。
• running_version：线上当前到底运行哪一版。

这三个变量最好能互相追溯。

2. 测试分层：每种测试证明的东西不同

所以“Mock API 下 E2E 全绿”只证明：在假后端返回可控数据时，前端链路能工作。它不能单独证明真实鉴权、真实数据库、支付平台和生产配置正确。

3. Release Candidate 为什么必须冻结

先定义下面几个变量：

• source_commit：候选对应的 Git commit。
• artifact_digest：候选构建产物的指纹。
• migration_version：数据库结构迁移到哪一版。
• configuration_version：运行配置是哪一版。
• verification_report：这版已经跑过哪些检查及结果。
• known_risks：已知但仍接受的风险。

release_candidate = {
  source_commit,
  artifact_digest,
  migration_version,
  configuration_version,
  verification_report,
  known_risks
}

这段伪代码只是在表达：验收对象必须是一个有明确身份的组合，而不是“最新代码”这种不断变化的概念。

4. CI/CD 是把重复动作变成机器合同

CI 负责在代码变化后统一执行 build、test、lint、type check 等。Continuous Delivery 的目标是“合格候选随时可发布”；Continuous Deployment 再进一步，把生产发布也自动执行。

高风险系统可以保留人工 Acceptance（验收接受）门，但这不妨碍构建、测试、部署准备都自动化。

5. Deployment Readback：真正去线上看一眼

部署命令返回成功只说明“部署工具认为操作完成”。你还应从真实目标环境读回：

• 页面上是否出现新版本标识。
• API 是否返回预期 build SHA。
• 关键接口是否真的能工作。
• 数据库 migration 是否处于目标版本。

Readback 是把“我执行过发布命令”升级成“我有证据证明目标环境真的变成了这版”。

6. Observability：Logs、Metrics、Traces 分别是什么

• Logs · 日志：某一时刻发生了什么事件。
• Metrics · 指标：错误率、请求量、P95/P99 延迟等连续数值。
• Traces · 链路追踪：把一次请求经过的多个服务串起来。

P95 的意思是“95% 的请求延迟不超过这个值”；P99 类似，只是看更尾部的慢请求。

7. Rollback 为什么也不是万能药

代码版本可以切回去，但已经发生的支付、通知、邮件、数据库不可逆迁移不一定能自动撤销。这类外部副作用可能需要 Compensation · 补偿动作，例如单独发退款，而不是假装旧代码重新上线就把钱退回来了。

答案：还缺明确候选身份、真实后端/目标 Runtime 证据、数据库迁移状态、部署 artifact 身份、线上 readback、关键负向测试，以及有权主体的 Acceptance。