作品集验收、文档与面试证据
面试中，比起列十个框架名，更有说服力的是讲清一次真实设计：为什么这样做，遇到什么失败，怎样确认修复。这里把项目材料整理成别人能运行、能追问、能核对的说明。
高质量作品集展示决策、正确性、测试、性能和运营证据，而不是只列框架名和截图。
1. 本文覆盖范围
- README 与架构记录
- 测试和质量证据
- 性能与故障报告
- 演示、复盘和面试表达
2. 核心知识详解
1. 可复现 README
README 写出问题、架构、版本、前置条件、一条命令启动、配置、测试、演示账号、限制和许可证。
- 锁定工具版本。
- 提供架构图、ER 图和关键序列图。
- 敏感配置使用模板。
这里容易混淆的是： 只有 API 列表而没有业务目标和运行步骤，评审者难以验证能力。
2. ADR 与权衡
Architecture Decision Record 记录背景、选项、选择、后果和复审条件，例如数据库、消息、缓存和一致性方案。
- 保留被拒方案及理由。
- 结论关联基准/文档/实验。
- 过期决策由新 ADR supersede。
这里容易混淆的是： 事后把现状包装成唯一正确方案，不是有效架构决策记录。
3. 证据包
CI 报告、覆盖的风险清单、执行计划、JFR/压测、SLO、故障时间线、恢复演练和安全扫描形成可核验材料。
- 数据脱敏。
- 报告含环境和版本。
- 失败和改进同样保留。
这里容易混淆的是： 单张“QPS 很高”截图缺少负载、正确性和资源信息，结论不可复现。
4. 表达方法
用“问题—约束—选项—决策—验证—结果—后续”讲项目；被追问时能下钻到协议、事务、线程和 SQL。
- 准备一次 5 分钟演示和一次 30 分钟深挖。
- 明确自己负责部分。
- 诚实说明边界和未完成项。
这里容易混淆的是： 背诵术语而讲不出失败模式、指标和代码位置，难以证明掌握。
3. 工程链路
flowchart LR
A["业务问题"] --> B["约束/选项"]
B --> C["ADR 决策"]
C --> D["代码/测试"]
D --> E["性能/故障/安全证据"]
E --> F["可复现演示"]
F --> G["复盘与下一步"]
4. 实践示例：写一份别人能复查的结果
假设你做的是订单服务，先挑一个具体承诺：“同一个幂等键重复提交不会重复扣库存”。用下表组织证据，表中的结果需要你实际运行后填写，不能当作已经测试通过。
| 要说明什么 | 要保留什么 | 怎么复查 |
|---|---|---|
| 正常下单 | 请求样例、脱敏响应、订单记录 | 从干净测试数据创建一次订单 |
| 重复提交 | 两次相同键请求及数据库结果 | 订单数与扣减次数都应为 1 |
| 冲突提交 | 相同键、不同请求体 | 返回明确冲突，不能复用另一笔订单 |
| 中途失败 | 故障注入位置、事务与事件记录 | 不留下半扣库存、半创建订单 |
| 性能 | 版本、机器、并发、持续时间、错误率和延迟 | 用相同负载重跑，再比较差异 |
例如，README 不要只写“实现高并发幂等”。写出唯一约束在哪里、事务覆盖哪些表、网络超时后客户端如何查询状态，并链接到对应测试。再把“我们尚未覆盖跨地域故障”这样的限制写明，读者才知道结论适用到哪里。
准备一次演示：正常下单、重复发送、查看数据库、注入失败、展示恢复结果。每一步都说明预期与实际；如果演示只能依赖已有截图，就还缺少可复现入口。
5. 实践与验证
- 为项目写一份完整 README 和两份 ADR。
- 整理可匿名复现的测试、性能和故障证据包。
- 录制 5 分钟部署与故障恢复演示并按清单复盘。
6. 掌握检查
- 他人能独立启动。
- 决策有证据。
- 质量和性能可复现。
- 能清晰表达边界与改进。