【山竹记账-全栈】3.前端与后端合作的流程


大纲链接 §

[toc]


1. 接口协定的制定原则 ⇧

  • 核心原则:谁更有经验,谁就负责制定接口协定
    • 接口的定义过程高度依赖开发经验,容易出错,因此需要资深人员把控
  • 场景示例:
    • 若前端为新手(< 1年),后端为资深开发者(3年+)- 由后端制定
    • 若前端为资深开发者(3年+),后端为新手 - 由前端制定

接口联调 ⇧

  • [定义]:指通过前端发送请求到后端,并接收后端返回结果(成功或失败)的整个过程
  • [大公司术语]:通常被称为“前后端联调”,本质上是在联合进行接口的调试工作
  • [核心任务]:后端开发者在联调过程中,会不断地调试其后台程序,以确保接口能正确响应前端的请求

2. 如何向后端索要接口 ⇧

2.1 召开功能评审会议 ⇧

  • 参会人员:
    • 必须在场:前端、后端
    • 可选人员:产品经理、设计师、项目经理
  • 会议核心内容:
    • 逐一过一遍界面上的所有功能(例如:登录、查询 items、查询 pads 等)
    • [核心目标]:前后端共同确认功能的逻辑及实现方式

2.2 功能可行性评估 ⇧

  • 前端视角:确认界面功能是否可以实现
  • 后端视角:
    • 评估复杂功能是否需要后端配合
    • [核心关注点]:确认数据库中是否存在足够的数据来支撑前端的功能需求

2.3 确定接口风格与文档要求 ⇧

  • [性能考量]:后端在评估功能时,需考虑数据查询的耗时(例如查询 10 年的数据量可能无法在短时间内完成)
  • 接口风格的选择:
    • 常见的风格包括:
    • REST
    • RPC
    • GraphQL
    • 随意风格:常见于缺乏规范的小公司,前后端没有统一章法,接口随用随改
  • 接口文档的要求
    • 文档是前后端沟通的桥梁,严禁直接让前端去阅读后端源代码来理解接口
    • 核心标准:
      • 全面:覆盖所有调用细节
      • 及时:代码实现后应同步更新文档
      • 可用:文档应能指导实际调用

2.4 接口文档的具体要求 ⇧

  • 全面
    • 所有的 API 必须都包含在文档中
  • 实时
    • 接口一旦修改,文档必须同步更新
    • [风险]:过时的文档与 Bug 无异
    • 例如:后端将参数名从 code 改为 smscode,但文档未更新,会导致调用时报“缺少参数”的错误
    • [应对策略]:如果后端无法做到实时更新文档,前端需要通过“轮询”的方式确认
    • 每天询问后端:“今天更新文档了吗?”
    • 确认文档已更新后再开始开发,避免盲目开发导致错误
  • 可测、可用
    • 确保后端提供的接口在测试用例中是通过可用的
    • 确保后端提供的接口在实际调用中是真实可用的
  • 成熟方案:使用 knife4j 或者 swagger2 等代码实时生成api文档,各框架都存在相关库

参考

2.5 接口文档的可用性挑战 ⇧

  • [核心痛点]:后端开发者有时仅满足于“代码编译通过”,认为接口即可使用
    • 实际上,接口可能在逻辑上存在缺陷,导致前端调用时频繁报错
    • 常见问题:未处理空值(null)或边界情况(edge case)
  • [沟通效率问题]:前后端过度分家会导致沟通成本激增
    • 分家后,接口变更或逻辑不一致需要通过大量会议和文档来同步,效率低下
    • 如果前后端职责过于割裂,前端在调用接口时会面临极大的不确定性
  • [痛点] 联调不顺畅通常源于后端问题,而非前端问题
    • 前端只需负责调用,理论上只要一次调用成功,后续逻辑应能跑通
    • 后端接口可能存在文档不全面、不及时或不可用的问题,导致联调效率低下

[全栈开发的优势] 减少沟通成本

  • 前后端分离会导致沟通效率下降
  • 全栈工程师可以实现后端变更与前端逻辑的同步更新,无需反复确认接口细节

2.6 接口联调的现状 ⇧

  • [现状总结]:接口文档的三个要求(全面、实时、可用)在实际开发中都很难完全达到
  • [协作建议]:为了提高联调效率,应尽可能减少沟通隔阂,保持对接口变更的高度敏感

2.7 开发流程的衔接 ⇧

  • [理想状态]:功能评审 - 接口文档到位 - 前端直接开始开发
  • [实际操作]:使用 Mock 数据

    • [定义]:在后端真实接口尚未完成时,前端使用模拟的(假)数据进行开发
    • [目的]:为了让前端可以先行完成界面逻辑和功能的搭建,而不必等待后端数据
    • [要求]:Mock 数据的结构应尽可能与后端真实接口文档定义的格式保持一致
    • [优势]:一旦后端真实接口就绪,前端只需将请求地址从 Mock 地址切换为真实地址,界面即可直接投入使用

      1
      2
      3
      4
      
      flowchart 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
      8
      
      flowchart TD
      A[后端完成开发] --> B{是否仅通过编译?}
      B -- 是 --> C[认为接口可用]
      B -- 否 --> D[修复逻辑错误]
      C --> E[交付前端]
      E --> F{前端调用测试}
      F -- "报错 (如 Edge Case 未处理)" --> G[反馈给后端重构]
      F -- 成功 --> H[正常联调]

4. 后续学习路径 ⇧

全栈:确保充分的接口单元测试,覆盖边际情况

  1. 后端开发阶段:从第一个 API 开始,完成全部后端逻辑并输出完整的接口文档。
  2. 前端 Mock 阶段:前端根据文档构建模拟数据,先行完成界面和业务逻辑的搭建。
  3. 真实 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)的处理。
  • [常见的沟通误区]:
    • “看源码”陷阱:在缺乏规范的小公司,部分后端可能会以“太忙”为由,要求前端直接阅读源代码来理解接口逻辑。这在实际协作中是不可行的,因为前后端并不一定使用同一种“语言”或思维逻辑,必须依赖标准化的文档进行沟通。
    • 职责割裂风险:如果前后端分工过于僵化且缺乏有效的文档支撑,会导致沟通成本激增,前端在调用接口时会面临极大的不确定性。

联调中的常见报错场景 ⇧

  • [逻辑缺陷 vs 编译通过]:
    • 在 Java 等编译型语言环境下,后端开发者容易陷入“代码编译通过即代表接口可用”的误区。
    • 实际后果:前端在联调时可能遭遇连续的请求失败(例如:连续多次请求均无法获得 200 OK 状态码,而是一直报错)
    • 这通常是因为接口在逻辑层面(如参数校验、空值处理)存在缺陷,而非语法错误。
  • [文档滞后引发的参数错误]:
    • 典型案例:后端将参数名从 code 修改为 smscode 但未同步更新文档。
    • 报错表现:前端按旧文档调用时,会因“缺少参数”而导致请求失败。
    • [应对策略]:由于现实中许多公司难以做到文档的实时自动化更新,前端应采取“轮询”策略,在开发前主动询问后端:“文档更新了吗?”以确保基于最新规范进行开发。

全栈视角下的协作优势 ⇧

  • [沟通效率对比]:
    • 前后端分家模式:沟通高度依赖文档和会议,存在信息滞后和理解偏差的风险,导致联调过程可能非常不流畅。
    • 全栈开发模式:由于后端逻辑的变更可以即时同步给前端(因为是同一个人),能够实现逻辑的快速响应与同步,极大地降低了沟通成本。
  • [前端开发节奏]:
    • 在理想的协作流程中,前端在完成功能评审后即可进入开发阶段。即使后端 API 尚未就绪,也可以通过 Mock 数据先行完成界面和业务逻辑的搭建,从而实现开发进度的并行。

接口联调的本质 ⇧

  • [核心定义]:联调(调试)不仅仅是前端发送请求并接收响应的过程,其本质是前后端联合进行接口的调试工作。
  • [后端的角色]:在联调过程中,后端开发者需要不断地调试其后台程序,以确保接口逻辑能够正确响应前端的各种请求。
  • [阶段目标]:通过联调确保程序逻辑的正确性,从而完成第一版功能的交付,为后续的上线测试打下基础。

后续开发计划 ⇧

  • 阶段 1:后端 API 开发
    • 从第一个 API 开始,完成所有后端逻辑实现
    • 核心产出:输出完整的接口文档
  • 阶段 2:前端 Mock 开发
    • 前端根据后端提供的文档构建模拟数据
    • 完成界面布局与业务逻辑的搭建
  • 阶段 3:真实 API 联调
    • 将前端请求的 Mock 地址替换为真实的 API 地址
    • [重要前提]:如果接口文档足够健全,此过程应当是“无痛”的;若文档不健全,替换过程会非常痛苦

·未完待续·

参考文章

  • 无

相关文章


  • 作者: Joel
  • 文章链接:
  • 版权声明
  • 非自由转载-非商用-非衍生-保持署名