关于 API 文档驱动研发模式的探索与实践
陈子煜
得物商家前端负责人
自我介绍
- 2015毕业于Rutgers University
- 曾就职 Epic、字节跳动、蚂蚁集团
- 得物商家前端负责人， Mooncake平台项目PM
迭代中的效能瓶颈分析
前端迭代流程
沟通成本: 信息互换、变更触达
- 需求确认、技术方案设计需要反复沟通确认
- 研发过程中，方案的变更需要及时沟通
依赖: 数据依赖
- 前端应用数据驱动，据”来渲染页面依赖服务端返回的“数
- 测试过程中依赖“造数工具”复现场景进行回归
流程痛点
前端位于链路的最上游，因此需要付出最多的协作成本
- 数据依赖服务端，在所有下游服务开发完成后，才能获取到数据
- 开发过程中，任意下游服务发生变动，都有可能影响到前端应用
- 联调过程中严重依赖服务端、测试造数来进行场景的调试
- 出现问题，测试永远先从前端应用开始排查
- ......
文档驱动流程相关介绍
API Mandate
能不能造个轮子解决协作问题?如果可以，基于什么来造?
Jeff Bezos’ API mandate
- Data and Capabilities must be exposed through APIs
- Team Communications must be through APIs
- There can be no side channels/shortcuts
- Technology choice is secondary
- APIs must be externalizable
API文档驱动
基于API文档在Mooncake平台完成协同，各职能团队独立完成工作
- 生产端: 通过idea插件、cli等工具快速生成API文档
- 消费端: 基于API文档完成文档驱动研发流程
- 生态: 向内部其他平台、工具提供接口文档信息
API文档信息
基于文档完成协作，需要解决哪些问题?
- 信息互换
- 变更触达
- 数据依赖
API文档信息 为什么写
- 该接口本次迭代相关的如PRD链接等 需求信息
- 从研发协同平台同步和该需求相关的 研发人员信息，接口发生变更时能够 及时触达相关人
API文档信息 写什么
接口的基础信息字段，包含但不限于:
- 出入参数
- 字段备注
- 文档备注
- 文档评论
- ......
以迭代维度记录接口的历史 版本信息，包括但不限于:
- 变更原因
- 变更时间
- 变更人
- ......
API文档信息 写什么
支持对历史版本diff，快速定位到变更的 字段，主要应用于前后端信息交换的场景
API文档信息 要怎么用
- 基于单测用例即文档的理念，让用例当作文档的一部分。每一条用例即该接口的一个使用场景
- 平台同时也支持用例的执行、结果查看等
用例详情描述了该场景的具体信息， 包含但不限于:
- 用例负责人信息
- 用例的断言信息
- 接口的上下游调用链路信息
- ......
文档驱动下前端的研发流程
前端构成
最终产物 = 前端交互&渲染逻辑(API返回数据)
UI = render(data)
- 前端研发流程
- 文档生态 – API Mock
- 文档生态 – API Mock 数据Mock
- 文档生态 – API Mock Mock场景
- 前端如何文档驱动
- 构建mock场景完成自测
- Mock数据的生产依然依赖于服务端接口定义
- 防腐层(ACL)
- 前端研发流程变化
落地成果
- 不止于前端 – 文档生产 基于IDEA插件快速上传接口
- 不止于前端 – 服务端文档驱动 Mooncake文档代替飞书文档
- 不止于前端 – 服务端文档驱动流程 提供Dubbo/GRPC Mock能力，解决服务端跨团队协作效率问题
- 不止于前端 – 服务端文档驱动流程 服务端、测试协同完成的类TDD流程
- 不止于前端 – 流程融合
后续规划
