面向接口开发的前后端跨团队合作方案

1.问题描述

1.1 背景

大中型产品研发中，由于参与人员过多的原因，手机应用程序、后端服务研发通常会拆分开，由不同的团队负责。这即促进了专业领域的聚焦，又减少了团队管理与沟通的复杂度。

1.2 现象

好现象

• 内部沟通效率得到提升：手机应用程序、后端服务研发团队内部讨论、传递的信息都是和绝大数人有关的信息；沟通网络效应造成沟通负担得到遏制。
• 大部分人聚焦内部，少数人做边界沟通，缓解沟通能力的要求。
• 各自内部迭代速度加速。

坏现象

• 组织墙阻隔了团队间集体感。
• 由于缺乏跨组织交流，对合作团队工作认同感降低。
• 前后端联调滞后，导致项目中后期问题激增，团队氛围恶化，项目延期。

1.3 影响

• 产品发布节奏放缓。
• 产品研发成本增加。
• 技术方案倾向于团队折中、妥协，而非基于产品发展。

2.主因分析

核心原因在沟通阻力增加和利益不一致。

原因 1：沟通阻力增加

• 术业有专攻，且缺少天天耳濡目染，对跨组织的工作越来越不理解。
• 因物理和心理两个维度上距离增加，导致小问题得不到及时暴露和解决。如接口的定义、参数的设计、业务逻辑的真正讨论，被延期到集成阶段。
• 工作排期聚焦内部，对于彼此协调、依赖的事项关注不足。

原因 2：利益不一致

• 独立 KPI 考核
• 独立研发计划
• 前端应用面临海量客户的压力，后端面临多个前端应用需求的压力

3.项目治理方案

• 建立持续交付的工作模式，以持续交付用户价值为共同目标。
• 建立跨组织的产品级路线图。
• 建立以产品经理和系统架构师为核心的跨组织领导体系，拥有决策权和评价权。
• 后端服务团队的接口人以虚拟角色形式，参与到前端团队的研发管理，包括日会、技术会。
• 建立面向接口的开发模式。
• 定期组织跨组织的团队建设活动。

4.实施方案

4.1 组建阶段

• 明确授权产品经理、产品级架构师
• 统一研发基础设施，包括接口设计与发布流程
• 统一沟通工具，制定沟通计划
• 统一迭代节奏

4.2 实施阶段

• 保持后端团队代表的有效参与前端团队，需产品经理、架构师监督。
• 保持按节奏持续发布至测试环境，包括前端、后端，让问题在有限时间内得到暴露和解决

4.3 接口开发技术

方案一：基于 Swagger

基于接口设计、描述框架 Swagger （

https://swagger.io/

），构建基于接口的研发流程。

• 后端服务即 API 文档，前端团队清晰了解接口能力，利于持续集成。
• 后端持续发布接口能力，简化 API 文档维护成本。
• 需要前后端团队遵循开发流程，提高项目的整体效率，而非单次沟通效率。

Swagger - Simplify API development for users, teams, and enterprises with the Swagger open source and professional toolset. Find out how Swagger can help you design and document your APIs at scale.

by

（1）接口设计阶段

针对业务需求清晰的接口，即通过规划的接口，启动基于Swagger的接口设计。

• 侧重基于真实服务代码描述接口设计
• 不做功能的有效实现
• 将设计通过的接口，发布到测试环境，供前端团队查阅和开发联调

接口设计规范：OpenAPI Specification

https://swagger.io/resources/open-api/

接口设计工具：Swagger Editor

Design, describe, and document your API on the first open source editor fully dedicated to OpenAPI-based APIs. The Swagger Editor is great for quickly getting started with the OpenAPI (formerly known as the Swagger Specification) specification, with support for Swagger 2.0 and OpenAPI 3.0.

https://editor.swagger.io/

• 使用Yaml语言, 定义好API接口
• 点击 generate server code, 选择需要的语言, 即可下载自动生成的相关接口的初始化项目
• 点击 generate client code, 选择需要的语言, 即可以下载自动生成调用这个接口的客户端代码

接口定义查看工具：Swagger UI

Swagger UI 可以将项目接口自动生产具有交互的html页面, 是一个前端页面的自动生成项目. Swagger UI的 demo见: 

swagger ui demo

. 

（2）接口实现阶段

按节奏逐渐实现接口的能力。

• 对于已实现的能力，要清晰描述能力
• 对于在在研的能力，要描述清晰状态

后端服务工程引入swagger的依赖

<dependency> 
  <groupId>io.springfox</groupId
  <artifactId>springfox-swagger2</artifactId
  <version>2.7.0</version> 
</dependency> 
<dependency> 
  <groupId>io.springfox</groupId
  <artifactId>springfox-swagger-ui</artifactId
  <version>2.7.0</version> 
</dependency>           

生成API的server stub和client SDK

Swagger Codegen can simplify your build process by generating server stubs and client SDKs for any API, defined with the OpenAPI (formerly known as Swagger) specification, so your team can focus better on your API’s implementation and adoption.

（3）接口设计变更

后端人员无需关注Swagger描述文件和接口文档，有需求变更导致接口变化，直接写代码就好了。把调用层的代码做个修改，然后生成新的描述文件和接口文档后，给到前端即可。

方案二：基于阿里云 API 网关

https://www.aliyun.com/product/apigateway

API 网关（API Gateway），提供API托管服务，涵盖API发布、管理、运维、售卖的全生命周期管理。辅助用户简单、快速、低成本、低风险的实现微服务聚合、前后端分离、系统集成，向合作伙伴、开发者开放功能和数据。

• 提供防攻击、防重放、请求加密、身份认证、权限管理、流量控制等多重手段保证 API 安全，降低 API 开放风险。
• 提供 API 定义、测试、发布、下线等全生命周期管理，并生成 SDK、API 说明文档，提升 API 管理、迭代的效率。
• 提供便捷的监控、报警、分析、API 市场等运维、运营工具，降低 API 运营、维护成本。

API 网关功能

• API 生命周期管理
  • 支持包括 API 发布、API 测试、API 下线等生命周期管理功能。
  • 支持 API 日常管理、API 版本管理、API 快速回滚等维护功能。
• 全面的安全防护
  • 支持多种认证方式，支持 HMAC (SHA-1，SHA-256) 算法签名。
  • 支持 HTTPS 协议，支持 SSL 加密。
  • 防攻击、防注入、请求防重放、请求防篡改。
• 灵活的权限控制
  • 用户以 APP 作为请求 API 的身份，网关支持针对 APP 的权限控制。
  • 只有已经获得授权的 APP 才能请求相应的 API。
  • API 提供者可以将调用某个API 的权限主动授予给某个APP。
  • 若 API上架到 API 市场，购买者可以将已购买的 API 授权给自己的 APP。
• 精准的流量控制
  • 流量控制可以用于管控 API的被访问频率、APP的请求频率、用户的请求频率。
  • 流量控制的时间单位可以是分钟、小时、天。
  • 支持流控例外，允许设置特殊的 APP 或者用户。
• 请求校验
  • 支持参数类型、参数值（范围、枚举、正则）校验，无效校验会被 API 网关直接拒绝，以减少无效请求对后端造成的资源浪费，大幅降低后端服务的处理成本。
• 数据转换：通过配置映射规则，实现前、后端数据翻译。
  • 支持前端请求的数据转换。
  • 支持返回结果的数据转换。
• 监控报警
  • 提供可视化的API实时监控，包括：调用量、流量大小、响应时间、错误率，在陆续增加维度。
  • 支持历史情况查询，以便统筹分析。
  • 可配置预警方式（短信、Email），订阅预警信息，以便实时掌握API运行情况。
• 自动工具
  • 自动生成 API 文档，可供在线查看。
  • API 网关提供多种语言 SDK 的示例。降低 API 的运维成本。
  • 提供可视化的界面调试工具，快速测试，快速上线。