engineering-senior-developer

高级开发指南

概述

本指南介绍如何在 Web、后端、移动端和平台开发中，通过工作流、标准和模式交付生产级软件。在规划实现、权衡架构方案、提升代码质量或安全发布时，请参考本指南。

交付工作流

1. 理解问题

• 明确目标、约束、成功指标、截止日期和非目标。若缺少其中任何一项，请先询问，再编写代码——绝不要自行假设。
• 找出未知项：如果未知项超过 2 个，请先添加一个探索任务（最长 2 小时，并规定具体交付物），再承诺预估工期。
• 优先提出最小可行技术方案。如果该方案需要超过 5 天的工作，请寻找更简单的替代方案或拆分为多个阶段。
• 在实现前定义验收标准。每项标准都必须可验证——“运行正常”不算标准；“返回包含 user_id 声明的 JWT，状态码为 200”才算。

2. 规划实现

• 将工作拆分为小型、可测试的里程碑。每个里程碑都必须能独立合并——如果里程碑 B 必须依赖里程碑 A 才能发布，则它们属于同一个里程碑。
• 如果变更涉及超过 5 个文件，请在开始前编写一段计划。如果超过 15 个文件，请编写设计文档（参见 references/design-docs.md）。
• 规划回滚方案：每次数据库迁移都必须可逆。如果迁移要删除某个列，请先部署停止读取该列的代码，然后在下一次发布中删除该列。
• 对于任何新的外部依赖（API、服务、数据库），请定义：超时时间（默认 5s）、重试策略（尝试 3 次，采用指数退避）、熔断器阈值（60s 内失败 5 次）以及回退行为。

3. 实现并验证

• 函数超过 40 行时应拆分。文件超过 300 行时应拆分。函数参数超过 4 个时，应引入配置/选项对象。
• 在合适的层级进行测试：纯逻辑 = 单元测试。API 端点 = 集成测试。关键用户流程 = E2E 测试（每个功能最多 5 个 E2E 测试——这类测试运行缓慢且不稳定）。
• 每个新增的 API 端点都必须具备：输入验证（Zod/Pydantic/class-validator）、错误响应架构、速率限制，以及至少一个集成测试。
• 对包含超过 10k 行数据的表进行的每个数据库查询都必须有索引。运行 EXPLAIN ANALYZE，并拒绝大型表上的顺序扫描。
• 绝不要捕获错误后悄悄忽略。请记录包含上下文的日志（操作、输入、关联 ID），或重新抛出错误。仅捕获能够处理的错误。
• 向后兼容：如果要更改共享类型或 API 响应结构，请使用 grep 搜索所有使用方。如果有使用方依赖旧结构，请采用扩展-迁移-收缩方案（添加新字段、迁移使用方、删除旧字段）。

4. 发布并稳定

• 合并前：在本地运行完整测试套件，确认没有 lint/类型错误，并在适用时检查打包体积/二进制文件大小。
• 部署时确保可观测性：每次部署都必须在 5 分钟内体现在指标中。如果无法通过仪表板判断部署是否健康，请先添加检测，再进行部署。
• 部署后：监控错误率和 p95 延迟 30 分钟。如果错误率上升超过 2 倍，或 p95 延迟翻倍，请立即回滚——不要先在生产环境中排查。
• 发现技术债后 48 小时内记录下来。每项债务都必须包含：描述、影响（延迟/可靠性/开发效率）、预估工作量和负责人。没有负责人的债务不会得到修复。

工程标准

• 每个 API 端点都必须说明：请求／响应架构、错误代码及其含义、身份验证要求和速率限制。缺少这些内容的端点尚未达到评审要求。
• 每次数据库迁移在合并前，都必须在生产数据副本（或真实的种子数据）上测试回滚。若迁移在生产规模的数据上耗时超过 30 秒，则必须作为后台作业运行，不得阻塞部署。
• 每条关键路径（身份验证、支付、核心 CRUD）都必须具备：延迟直方图、错误率计数器，以及在 p95 超过基线的 2 倍或错误率超过 1% 时触发的告警。
• 安全不是后续任务。身份验证检查、输入验证和 CSRF 防护都属于初始实现的一部分。如果 PR 添加了不带身份验证的端点，就尚未达到评审要求。
• 性能预算：读取 API 响应的 p95 <200ms，写入 API 响应的 p95 <500ms。如果新功能超出这些指标，必须在合并前优化，而不是合并后再处理。

反模式检测

评审或编写代码时，发现以下问题要立即标记并修复：

• N+1 查询： 在循环中每次迭代都发起数据库调用。使用批量查询、JOIN 或 DataLoader 修复。
• 无界查询： 面向用户的端点使用 SELECT * 或未设置 LIMIT 的查询。始终进行分页，并且只选择需要的列。
• 共享可变状态： 多个请求处理程序会修改同一个全局变量。使用请求作用域上下文或依赖注入。
• 字符串强类型不足： 使用原始字符串表示状态、类型或角色值。改用枚举或联合类型。
• 上帝函数： 一个函数同时处理解析、验证、业务逻辑、数据库操作和响应格式化。应拆分为多个层。
• 缺少错误上下文： catch (e) { throw new Error("failed") }。始终包含原始错误和操作上下文。
• 过早抽象： 为只在一处使用的内容创建通用框架。等模式重复出现 3 次后再抽象。
• 将配置写入代码： 硬编码 URL、API 密钥、功能标记或环境专属值。将其移至环境变量或配置服务。

技术选型决策规则

语言选择

• Go：当服务受 I/O 限制且并发量高（>10k 个并发连接）、需要单二进制文件部署，或属于基础设施工具（CLI、代理、sidecar）时选择。快速原型开发或大量使用 ORM 时避免选择。
• Node.js (TypeScript)：当团队使用全栈 JS、服务属于 BFF（前端后端）、实时功能占主导（WebSocket、SSE），或生态中存在适用于该领域的成熟库时选择。避免用于受 CPU 限制的处理任务（图像／视频、ML 推理）。
• Python：当领域涉及数据／ML、团队以 Python 为主，或快速迭代比运行时性能更重要时选择。对延迟敏感的服务（p95 目标 <10ms）应避免选择，除非使用搭配 uvloop 的 FastAPI。
• Java/Kotlin：当组织具备 JVM 专业能力、需要成熟的企业级库（Spring、Hibernate），或需要高吞吐量下的强类型支持时选择。对于 JVM 启动时间（2-5s）超出可接受冷启动时长的小型服务，应避免选择。
• Rust：仅当服务有严格的延迟要求（p99 <1ms）、需要大规模处理不可信输入，或属于性能关键型库时选择。必须有具体、经过测量的需求来证明 2-3 倍开发耗时的合理性。

数据库选型（快速参考）

• PostgreSQL（默认）：用于任何小于 10TB 的关系型数据。支持 JSON、全文搜索和地理空间功能——尽可能避免为此再引入第二个数据库。
• Redis：用于缓存（TTL <24h）、会话存储、速率限制或实时排行榜。绝不能用作主数据存储——重启后数据丢失是预期行为。
• MongoDB：仅在每个文档的架构确实各不相同的情况下使用（CMS、包含多态负载的事件存储）。如果可以预先定义架构，请使用 PostgreSQL。
• SQLite：用于 CLI 工具、移动应用、嵌入式系统或本地优先应用。如果多个进程同时写入，请使用 PostgreSQL。

API 风格选型

• REST：默认选择。用于以 CRUD 为主的 API、公共 API，或需要缓存的场景（HTTP 缓存可原生使用）。
• GraphQL：仅在客户端需要跨越超过 5 种实体类型灵活选择字段，且前端团队控制架构时使用。如果实体类型少于 3 种，REST 更简单。绝不要将 GraphQL 用于服务间通信。
• gRPC：用于内部服务间通信，适用于延迟低于 5ms 很重要、需要流式传输，或需要在超过 3 种语言之间强制执行严格契约的场景。未经网关处理，绝不要将 gRPC 直接暴露给浏览器。
• tRPC：当前端和后端共用一个 TypeScript 单体仓库时使用。它提供端到端类型安全，且无需重复定义架构。不适用于多语言后端。

估算决策规则

按任务类型估算

• CRUD 端点（路由 + 验证 + 数据库查询 + 测试）：2-4 小时。如果需要分页、筛选和排序：增加 2 小时。
• 带身份验证 + 速率限制 + 缓存的 CRUD 端点：1 天。
• 第三方 API 集成（OAuth、webhook、SDK）：1-2 天。如果第三方文档质量较差，估算时间一律加倍——估算前先阅读文档进行核实。
• 数据库迁移（添加列、添加索引）：如果表的行数少于 1M，需要 1-2 小时。如果超过 1M 行，为在线迁移工具和测试增加 4 小时。
• 数据库迁移（架构重新设计、数据回填）：包括双写阶段和验证，共需 2-3 天。
• 从零开始的新服务（仓库 + CI/CD + 健康检查 + 首个端点 + 监控）：3-5 天。
• 身份验证系统（注册 + 登录 + 重置密码 + 会话管理）：使用成熟库（NextAuth、Passport、Django auth）时需 3-5 天。自定义构建需 2-3 周——强烈不建议。
• 文件上传/下载（预签名 URL + 验证 + 存储）：1-2 天。
• 实时功能（WebSocket/SSE + 连接管理 + 重新连接）：2-3 天。
• 搜索（跨越超过 3 个字段的全文搜索，并支持筛选）：使用 PostgreSQL tsvector 需 1 天，使用 Elasticsearch 需 2-3 天。

估算乘数

• 首次使用某个库/框架：估算时间乘以 2。
• 没有测试的遗留代码库：乘以 1.5（必须编写测试来验证更改）。
• 多时区或 i18n 要求：乘以 1.3。
• 合规要求（审计日志、加密、访问控制）：乘以 1.5。
• 如果估算时间超过 5 天，请拆分为子任务并分别估算。如果任何子任务超过 3 天，说明它太大了——应继续拆分。

重构决策规则

何时重构

• 圈复杂度 >15（使用 scripts/review_checklist.py 或 ESLint complexity 规则测量）：将分支提取到命名函数中。每个函数的复杂度应 <10。
• 函数在 >5 个调用点中以不同的标志组合调用：用策略模式或独立函数替换布尔标志。processOrder(order, true, false, true) 难以阅读——拆分为 processStandardOrder()、processExpressOrder()。
• 相同代码块出现 3 次以上：提取为共享函数。出现 2 次时，可以容忍重复——过早抽象比重复更糟。
• 模块从其他模块导入 >10 项内容：耦合度高。引入门面或重新划分模块边界，使每个模块最多从 5 个其他模块导入内容。
• 测试需要 >20 行设置代码：被测代码依赖项过多。注入依赖并提供测试替身。如果测试某个函数必须启动数据库，那这个函数做得太多了。
• 修改一项功能需要跨 >2 个目录修改 >5 个文件：这是散弹式修改。将相关逻辑整合到单个模块中，或引入功能模块模式。

何时不重构

• 代码稳定，>6 个月未修改，也没有待开发的功能。不要动它。
• 你重构只是为了符合风格偏好，而不是解决可衡量的问题（复杂度、耦合度、测试难度）。停止。
• 重构需要 >3 天，且没有能从中受益的功能开发。推迟并记录为技术债务。

代码审查决策规则

按检测到的模式

• 新增数据库查询，但没有 EXPLAIN ANALYZE 输出：要求提供。在生产环境级别的数据量下没有执行计划，不得合并查询。
• 新增端点，但没有错误响应测试：阻止合并。每个端点都必须测试：有效输入（200）、缺少身份验证（401）、禁止访问（403）和无效输入（400）。
• 记录日志后继续执行的 catch 块：确认函数确实能够恢复。如果不能，就重新抛出异常。捕获异常后记录日志并继续执行，会掩盖错误，直到问题连锁扩散。
• 嵌套层级 >3 的函数：要求将内层代码块提取到命名函数中。深层嵌套表明逻辑应通过反转条件（提前返回）或拆分来处理。
• 魔法数字/字符串：要求定义命名常量。if (retries > 3) → if (retries > MAX_RETRIES)。例外：0、1 和常见 HTTP 状态码（200、404、500）。
• 没有关联 issue 链接的 TODO/FIXME：阻止合并。每个 TODO 都必须引用一个工单。没有跟踪的 TODO 永远不会被修复，最终会成为遗留问题。
• 只断言 toBeTruthy() 或 not.toThrow() 的测试：断言过弱。要求断言具体值。输出错误也能通过的测试，比没有测试更糟。
• 新增依赖：检查：对包体积的影响（运行 bundlesize 或同类工具）、最后提交日期、下载量、许可证兼容性，以及是否存在标准库方案。如果某项功能能在 <2 小时内实现，但该依赖会使包体积增加 >50KB，则阻止合并。

架构指导

• 如果团队人数 <5，使用单体架构。如果人数为 5-15，使用具有清晰领域模块的模块化单体。如果人数 >15 且有独立的发布周期，可考虑拆分服务。
• 明确划分领域逻辑、数据访问和传输层的边界。如果领域逻辑导入 HTTP 请求类型或数据库客户端类型，就说明边界已被破坏。
• 新增依赖（库、服务或工具）时：检查最后提交日期（若已停更 >12 个月则拒绝）、每周下载量（JS 少于 1k、Python 少于 500 则拒绝）以及未解决的安全公告。
• 对影响 >1000 名用户或涉及新基础设施的变更使用功能标志。按 1% → 10% → 50% → 100% 的比例逐步发布，每个阶段观察 24 小时。
• 针对以下内容记录架构决策（ADR）：新增外部依赖、数据库架构变更、API 契约变更、基础设施变更和技术选型。编写 ADR 若需 >10 分钟，说明内容太长。

自我验证协议

完成任何实现后，在认为任务已完成之前，先运行以下检查清单：

• 运行完整测试套件。失败数必须为零。如果未修改的测试失败，请确认它在 main 上也会失败——如果不会，就是你的更改导致了问题。
• 对于每个新增的 API 端点，发送真实的 HTTP 请求（使用 curl 或集成测试），并逐字段验证响应是否符合文档中的架构。
• 对于每个数据库迁移，在全新数据库和类似生产环境的种子数据上分别执行正向迁移和回滚。两个方向都必须成功。
• 重构后，对比重构前后的测试输出。如果行为有任何非预期变化，说明重构引入了错误——回滚并重新处理。
• 对每个修改过的文件运行 scripts/review_checklist.py。在请求审查前修复所有问题。
• 检查生产代码路径中是否仍有 console.log、print()、debugger 或 TODO 语句。
• 验证每个新依赖都通过健康检查：最近一次提交距今不到 12 个月，下载量超过每周 1k（JS）或每周 500（Python），且没有未修复的严重 CVE。
• 如果更改影响面向用户的流程，请在浏览器／应用中手动完整走查。自动化测试能发现回归问题，手动测试则能发现 UX 问题。

故障恢复

• 更改后构建失败：阅读完整错误信息，而不只是最后一行。如果是类型错误，就修复它。如果是未修改代码中的测试失败，运行 git stash && npm test，确认它在 main 上也会失败。如果会，就是已有问题；否则就是你的更改导致了问题。
• 测试在本地通过、在 CI 中失败：检查环境差异——Node／Python 版本、缺失的环境变量、时区、操作系统的大小写敏感性，或 Docker 与宿主机文件系统的差异。绝不要 skip CI 测试——应修复根本原因。
• 尝试 2 小时后仍未奏效：停下来。写明：（1）尝试了什么，（2）为何失败，（3）哪个假设有误。找出最简单的替代方案。如果没有替代方案，就带上具体的阻塞问题说明升级处理。
• 部署后出现性能回退：先回滚，再调查。使用性能分析在本地复现（参见 references/performance-profiling.md）。用户受到影响时，绝不要在生产环境中排查性能问题。
• 大型 PR 出现合并冲突：如果冲突超过 5 个文件，不要盲目解决。重新阅读冲突双方的所有内容。如果另一个分支修改了同一个函数，解决后要测试两种行为。
• 依赖升级导致问题：固定到可正常工作的版本，附上准确的错误信息提交问题，然后继续推进。不要为第三方回归问题耗费超过 1 小时。
• 不稳定的测试阻碍合并：在本地运行 5 次。如果结果不一致，就存在竞态条件或时序依赖。修复测试（添加适当的等待、模拟时间、移除共享状态）——绝不要反复重试直到通过。

现有代码库概览

接手不熟悉的代码库时，编写任何代码之前，请先完成以下步骤：

1. 阅读 README 和配置文件（5 分钟）——确定语言、框架、构建／测试／部署命令和入口点。
2. 在本地运行应用（10 分钟）——如果运行失败，首先要解决开发环境问题。在应用运行起来之前，其他事情都不重要。
3. 运行测试套件（5 分钟）——记录测试总数、耗时和失败情况。注意：如果主分支上有测试失败，这是一个需要记录的危险信号。
4. 追踪关键路径（15 分钟）——选定核心用户操作，追踪从 HTTP 处理程序 → 业务逻辑 → 数据库 → 响应的完整路径，并记录每一步对应的文件和函数。
5. 梳理架构分层（10 分钟）——列出入口点（路由／控制器）、业务逻辑、数据访问和外部服务。记录边界清晰与交织混乱之处。
6. 检查依赖健康状况（5 分钟）——运行 npm outdated / pip list --outdated。标出落后 2 个以上主版本的依赖。
7. 阅读最近 20 次提交（5 分钟）——了解当前活跃的工作领域和提交约定。
8. 找出测试缺口（5 分钟）——了解现有测试类型（单元／集成／E2E），以及尚未覆盖的领域。

完成这项概览后，再规划要做的更改。投入 1 小时，可以避免破坏那些你还不知道其存在的功能。

脚本

• scripts/review_checklist.py -- 分析源文件中常见的代码审查问题：TODO/FIXME 数量、过长函数、裸 except、硬编码密钥和遗留调试语句。运行时使用 --help 查看选项。

参考资料

• 代码示例 — TypeScript API 处理程序、Python 重试封装器、支持安全迁移的 SQL，以及 CI 质量门禁。
• 设计文档和 ADR — 设计文档模板（附已填写的支付处理示例）、架构决策记录示例，以及轻量级 RFC 模板。
• 生产环境模式 — 按百分比逐步发布的功能标志、优雅关停、扩展－迁移－收缩数据库迁移、带关联 ID 的结构化日志、熔断器，以及指数退避重试。全部使用 TypeScript。
• 代码审查和事件响应 — 代码审查清单、事件响应操作手册、事后复盘模板，以及值班交接模板。
• 性能分析 — 使用 clinic.js 和 Chrome DevTools 分析 Node.js、EXPLAIN ANALYZE 工作流、pg_stat_statements 热门查询、N+1 检测、内存泄漏调查（3 次快照堆差异分析）、使用 worker threads 进行 CPU 分析，以及从“端点响应慢”到修复根因的完整示例。
• 调试策略 — 使用自动化测试脚本进行 Git 二分查找、跨服务结构化日志关联、HTTP 流量捕获与重放、基于种子的可复现测试数据、通过时间戳分析和锁争用查询调试竞态条件、生产环境调试端点、详细日志功能标志、金丝雀部署，以及常见 Bug 模式特征。
• 架构决策 — 提供具体的决策矩阵及评分和阈值，用于选择单体还是微服务、数据库（PostgreSQL 与 MySQL、MongoDB、DynamoDB、Redis 之间）、队列（SQS 与 RabbitMQ、Kafka 之间）、缓存策略（含命中率阈值和防止缓存雪崩）、API 风格（REST、GraphQL、gRPC 之间），以及身份验证策略（会话、JWT、OAuth2 之间），并附安全清单。
• 团队实践模式 — 按 PR 大小划分的 PR 审查周转 SLA、审查意见类别（必须修复／建议／学习／表扬）、按严重程度评分的技术债务登记表、含分诊决策树的值班操作手册模板、使用参考故事进行故事点校准、速度跟踪公式、午餐分享会和决策日志模板、逐步增加结对工作的导师指导框架，以及附 Renovate 配置的依赖升级策略。