【山竹记账-全栈】3.前端与后端合作的流程
大纲链接 §
[toc]
1. 接口协定的制定原则 ⇧
- 核心原则:谁更有经验,谁就负责制定接口协定
- 接口的定义过程高度依赖开发经验,容易出错,因此需要资深人员把控
- 场景示例:
- 若前端为新手(< 1年),后端为资深开发者(3年+)- 由后端制定
- 若前端为资深开发者(3年+),后端为新手 - 由前端制定
接口联调 ⇧
- [定义]:指通过前端发送请求到后端,并接收后端返回结果(成功或失败)的整个过程
- [大公司术语]:通常被称为“前后端联调”,本质上是在联合进行接口的调试工作
- [核心任务]:后端开发者在联调过程中,会不断地调试其后台程序,以确保接口能正确响应前端的请求
2. 如何向后端索要接口 ⇧
2.1 召开功能评审会议 ⇧
- 参会人员:
- 必须在场:前端、后端
- 可选人员:产品经理、设计师、项目经理
- 会议核心内容:
- 逐一过一遍界面上的所有功能(例如:登录、查询 items、查询 pads 等)
- [核心目标]:前后端共同确认功能的逻辑及实现方式
2.2 功能可行性评估 ⇧
- 前端视角:确认界面功能是否可以实现
- 后端视角:
- 评估复杂功能是否需要后端配合
- [核心关注点]:确认数据库中是否存在足够的数据来支撑前端的功能需求
2.3 确定接口风格与文档要求 ⇧
- [性能考量]:后端在评估功能时,需考虑数据查询的耗时(例如查询 10 年的数据量可能无法在短时间内完成)
- 接口风格的选择:
- 常见的风格包括:
RESTRPCGraphQL- 随意风格:常见于缺乏规范的小公司,前后端没有统一章法,接口随用随改
- 接口文档的要求
- 文档是前后端沟通的桥梁,严禁直接让前端去阅读后端源代码来理解接口
- 核心标准:
- 全面:覆盖所有调用细节
- 及时:代码实现后应同步更新文档
- 可用:文档应能指导实际调用
2.4 接口文档的具体要求 ⇧
- 全面
- 所有的 API 必须都包含在文档中
- 实时
- 接口一旦修改,文档必须同步更新
- [风险]:过时的文档与 Bug 无异
- 例如:后端将参数名从
code改为smscode,但文档未更新,会导致调用时报“缺少参数”的错误 - [应对策略]:如果后端无法做到实时更新文档,前端需要通过“轮询”的方式确认
- 每天询问后端:“今天更新文档了吗?”
- 确认文档已更新后再开始开发,避免盲目开发导致错误
- 可测、可用
- 确保后端提供的接口在测试用例中是通过可用的
- 确保后端提供的接口在实际调用中是真实可用的
- 成熟方案:使用
knife4j或者swagger2等代码实时生成api文档,各框架都存在相关库
参考
2.5 接口文档的可用性挑战 ⇧
- [核心痛点]:后端开发者有时仅满足于“代码编译通过”,认为接口即可使用
- 实际上,接口可能在逻辑上存在缺陷,导致前端调用时频繁报错
- 常见问题:未处理空值(null)或边界情况(edge case)
- [沟通效率问题]:前后端过度分家会导致沟通成本激增
- 分家后,接口变更或逻辑不一致需要通过大量会议和文档来同步,效率低下
- 如果前后端职责过于割裂,前端在调用接口时会面临极大的不确定性
- [痛点] 联调不顺畅通常源于后端问题,而非前端问题
- 前端只需负责调用,理论上只要一次调用成功,后续逻辑应能跑通
- 后端接口可能存在文档不全面、不及时或不可用的问题,导致联调效率低下
[全栈开发的优势] 减少沟通成本
- 前后端分离会导致沟通效率下降
- 全栈工程师可以实现后端变更与前端逻辑的同步更新,无需反复确认接口细节
2.6 接口联调的现状 ⇧
- [现状总结]:接口文档的三个要求(全面、实时、可用)在实际开发中都很难完全达到
- [协作建议]:为了提高联调效率,应尽可能减少沟通隔阂,保持对接口变更的高度敏感
2.7 开发流程的衔接 ⇧
- [理想状态]:功能评审 - 接口文档到位 - 前端直接开始开发
[实际操作]:使用 Mock 数据
- [定义]:在后端真实接口尚未完成时,前端使用模拟的(假)数据进行开发
- [目的]:为了让前端可以先行完成界面逻辑和功能的搭建,而不必等待后端数据
- [要求]:Mock 数据的结构应尽可能与后端真实接口文档定义的格式保持一致
[优势]:一旦后端真实接口就绪,前端只需将请求地址从 Mock 地址切换为真实地址,界面即可直接投入使用
1 2 3 4flowchart LR A[Mock Data] --> B[API Documentation] B --> C[Real API] C --> D[UI Detail Refinement]
前端并行开发:Mock 技术 ⇧
- [场景] 当后端接口尚未开发完成,但前端界面已经设计好时
- [方法] 使用 Mock(模拟数据)
- 开发者可以根据预先确定的接口文档,构造“假数据”来模拟真实的接口返回
- [目的] 允许前端在等待真实数据期间先行完成界面逻辑开发
- [衔接] 当后端真实接口上线后,只需将 Mock 数据替换为真实接口调用即可
前后端联调 (Integration & Debugging) ⇧
- [定义] 调用接口
- 前端通过发送请求到后端,并接收后端返回成功或失败结果的过程
- [核心本质] 联调即调试
- 在大公司中,前后端联调(Integration)的过程实际上是在进行“调试”工作
- [重点] 后端需要不断地调试后台程序,直到接口能够稳定、正确地响应前端请求
- [流程]
- 联调通过 -> 解决所有接口报错 -> 产出第一版功能 -> 上线测试
3. 开发流程规划 ⇧
- [理想流程]:
- 1. 召开会议,通过功能评审
- 2. 后端开发 API 并输出文档
- 3. 前端根据文档进行 Mock 开发
- 4. 将 Mock 数据替换为真实的 API 进行联调
- [核心逻辑]:
- 无痛切换的前提:接口文档必须足够健全
- 如果文档定义清晰,Mock 数据与真实 API 的格式一致,那么从 Mock 切换到真实 API 的过程应该是“无痛”的。
- 文档不健全的后果:如果文档不完善,替换过程会非常痛苦,需要反复修改前端逻辑以适配真实的接口返回。
[协作路径] 从后端实现到最终发布的一般流程:
- 第一阶段:后端开发
- 后端实现 API 并输出接口文档
- 第二阶段:前端 Mock
- 前端根据文档进行 Mock 开发
- 第三阶段:真实对接
- 将 Mock 数据替换为真实的 API 调用
- [关键点] 若接口文档足够健全,此过程应是“无痛”的;若文档不完善,切换过程会非常痛苦
- 第四阶段:细节完善
- 所有 API 调通后,前端开始完善 UI 细节
- 后端同步完善其业务逻辑细节
- 第五阶段:发布
将功能正式上线
1 2 3 4 5 6 7 8flowchart TD A[后端完成开发] --> B{是否仅通过编译?} B -- 是 --> C[认为接口可用] B -- 否 --> D[修复逻辑错误] C --> E[交付前端] E --> F{前端调用测试} F -- "报错 (如 Edge Case 未处理)" --> G[反馈给后端重构] F -- 成功 --> H[正常联调]
4. 后续学习路径 ⇧
全栈:确保充分的接口单元测试,覆盖边际情况
- 后端开发阶段:从第一个 API 开始,完成全部后端逻辑并输出完整的接口文档。
- 前端 Mock 阶段:前端根据文档构建模拟数据,先行完成界面和业务逻辑的搭建。
- 真实 API 联调阶段:将请求地址从 Mock 地址切换为真实的 API 地址,进行最终的联调测试。
5. 发布策略与风险控制 ⇧
- 发布流程:
- 在完成接口联调并完善 UI 及后端细节后,进入发布阶段
- AB Test (实验测试)
- 定义:不一次性向所有用户发布新版本,而是将用户分组进行对比测试
- 实现方式示例:
- 用户 ID 分组:例如只向用户 ID 尾号为 1 的用户发布新功能,其余用户维持原状
- 特征分组:例如根据用户 ID 的奇偶数(基数/偶数)提供不同的版本
- 预发布 (Pre-release)
- 策略:在正式向大众发布前,先在受控的小范围内进行测试
- 示例:先向公司内部员工(如腾讯员工)发布,确认无误后再向全网用户推广
- 灰度发布 (Canary Release / 阶梯发布)
- 定义:一种逐步放量、阶梯式增加用户比例的发布方式,用于平滑过渡并观察系统稳定性
发布策略补充说明 ⇧
- [AB 测试的实现逻辑]
- 分组方式可以非常多样化,例如通过用户 ID 的奇偶性(基数与偶数)来分配不同的版本,从而进行对比测试。
- [预发布的规模效应]
- 在像腾讯这样规模的公司,利用公司内部 IP 进行预发布可以瞬间获得数万名员工的测试反馈,这为正式面向公众发布提供了极高的安全保障。
- [灰度发布的风险规避]
- [核心逻辑] 灰度发布(接替发布)本质上是在进行流量压力测试。通过 10% -> 30% -> 40% -> 20% 的阶梯式放量,可以有效防止因瞬时用户量过大而导致服务器宕机,从而避免因系统崩溃导致的严重事故(KPI 失败)。
灰度发布的实施细节 ⇧
阶梯式放量策略:
- 并非一次性对全量用户开放,而是按照比例逐步增加
- 示例流程:
- 先发布给 10% 的用户
- 逐步扩大至 30% 的用户
- 再扩大至 40% 的用户
- 最后发布剩余的 20% 用户
[核心目的]:风险控制
- 防止因一次性发布新功能导致用户量激增,从而压垮服务器机器(把机器搞崩了)
- 这种策略在大公司中非常常见,通过分阶段观察系统的稳定性来确保平滑过渡
发布系统的实现:
- 不同的发布策略(如 AB Test、灰度发布等)通常需要专门的发布系统来支撑
- 发布系统是经过开发并具备特定功能的自动化工具,用于精确控制流量的分发
发布系统的实现差异 ⇧
- [现实情况] 复杂的发布策略(如 AB 测试、灰度发布)需要专门的发布系统支撑
- 这些系统通常是企业内部开发的,并非现成的通用工具
- 需要投入人力和资源去搭建和维护这些系统
- [演示项目实践] 直接发布
- 对于功能较少、用户量较小的项目,直接发布即可
- 不需要为了演示而构建复杂的发布基础设施
6. 接口制定原则总结 ⇧
- 决策逻辑:谁更有经验,谁就负责制定接口协定
- 接口定义需要兼顾易记性、便捷性与准确性,这些都高度依赖开发经验
- 后端开发重点:
- 在后端深入了解如何科学地确定
RESTful接口风格
- 在后端深入了解如何科学地确定
功能评审的深度产出 ⇧
- [核心产出]:会议结束后,前后端应对功能实现逻辑达成初步共识,并明确后续的接口风格走向。
- [后端评估重点]:除了数据是否存在,后端还需在评审阶段预判复杂逻辑对系统性能的影响,确保功能在预期的响应时间内可交付。
接口文档的质量标准与沟通陷阱 ⇧
- [核心标准]:
- 全面性:所有 API 必须完整记录。此外,除了
REST和RPC,GraphQL也是一种需要被纳入文档规范的常见风格。 - 实时性:接口变更必须立即同步至文档。若后端无法做到自动化同步,前端应通过主动询问(如“今天更新文档了吗?”)来确认,避免因文档滞后导致开发错误。
- 可用性:确保接口在逻辑层面而非仅仅在编译层面是正确的,需特别注意空值(null)和边界情况(edge case)的处理。
- 全面性:所有 API 必须完整记录。此外,除了
- [常见的沟通误区]:
- “看源码”陷阱:在缺乏规范的小公司,部分后端可能会以“太忙”为由,要求前端直接阅读源代码来理解接口逻辑。这在实际协作中是不可行的,因为前后端并不一定使用同一种“语言”或思维逻辑,必须依赖标准化的文档进行沟通。
- 职责割裂风险:如果前后端分工过于僵化且缺乏有效的文档支撑,会导致沟通成本激增,前端在调用接口时会面临极大的不确定性。
联调中的常见报错场景 ⇧
- [逻辑缺陷 vs 编译通过]:
- 在 Java 等编译型语言环境下,后端开发者容易陷入“代码编译通过即代表接口可用”的误区。
- 实际后果:前端在联调时可能遭遇连续的请求失败(例如:连续多次请求均无法获得
200 OK状态码,而是一直报错) - 这通常是因为接口在逻辑层面(如参数校验、空值处理)存在缺陷,而非语法错误。
- [文档滞后引发的参数错误]:
- 典型案例:后端将参数名从
code修改为smscode但未同步更新文档。 - 报错表现:前端按旧文档调用时,会因“缺少参数”而导致请求失败。
- [应对策略]:由于现实中许多公司难以做到文档的实时自动化更新,前端应采取“轮询”策略,在开发前主动询问后端:“文档更新了吗?”以确保基于最新规范进行开发。
- 典型案例:后端将参数名从
全栈视角下的协作优势 ⇧
- [沟通效率对比]:
- 前后端分家模式:沟通高度依赖文档和会议,存在信息滞后和理解偏差的风险,导致联调过程可能非常不流畅。
- 全栈开发模式:由于后端逻辑的变更可以即时同步给前端(因为是同一个人),能够实现逻辑的快速响应与同步,极大地降低了沟通成本。
- [前端开发节奏]:
- 在理想的协作流程中,前端在完成功能评审后即可进入开发阶段。即使后端 API 尚未就绪,也可以通过 Mock 数据先行完成界面和业务逻辑的搭建,从而实现开发进度的并行。
接口联调的本质 ⇧
- [核心定义]:联调(调试)不仅仅是前端发送请求并接收响应的过程,其本质是前后端联合进行接口的调试工作。
- [后端的角色]:在联调过程中,后端开发者需要不断地调试其后台程序,以确保接口逻辑能够正确响应前端的各种请求。
- [阶段目标]:通过联调确保程序逻辑的正确性,从而完成第一版功能的交付,为后续的上线测试打下基础。
后续开发计划 ⇧
- 阶段 1:后端 API 开发
- 从第一个 API 开始,完成所有后端逻辑实现
- 核心产出:输出完整的接口文档
- 阶段 2:前端 Mock 开发
- 前端根据后端提供的文档构建模拟数据
- 完成界面布局与业务逻辑的搭建
- 阶段 3:真实 API 联调
- 将前端请求的 Mock 地址替换为真实的 API 地址
- [重要前提]:如果接口文档足够健全,此过程应当是“无痛”的;若文档不健全,替换过程会非常痛苦
·未完待续·
参考文章
- 无
相关文章
- 作者: Joel
- 文章链接:
- 版权声明
- 非自由转载-非商用-非衍生-保持署名