龙岩网站建设推广,wordpress添加自定义链接,家乡网站建设策划书,创新的企业网站开发团队内部RestAPI开发采用设计驱动开发的模式#xff0c;即使用API设计文档解耦前端和后端的开发过程#xff0c;双方只在联调与测试时耦合。在实际开发和与前端合作的过程中#xff0c;受限于众多因素的影响#xff0c;开发效率还有进一步提高的空间。本文的目的是优化工具… 团队内部RestAPI开发采用设计驱动开发的模式即使用API设计文档解耦前端和后端的开发过程双方只在联调与测试时耦合。在实际开发和与前端合作的过程中受限于众多因素的影响开发效率还有进一步提高的空间。本文的目的是优化工具链支持减少一部分重复和枯燥的劳动。 现状梳理 前后端工作流 需求理解前后端先理解产品思路、需求的详细内容 敲定接口后端出API设计文档初稿与前端面对面或者在线讨论修正接着后端有时是前端把API描述记录到公司内部的API文档库在线markdown编辑器提供分级目录的存储功能对如何描述API没有一定的标准因此描述格式不统一因人而异1。接着根据双方工作的安排约定联调时间 独立开发双方独立开发也有可能非完全独立开发如需要对方的环境配合等或者存在返工如API设计发生变更等 系统联调测试API基本功能和双方系统的连通性测试回归开发或者QA编写测试用例并测试业务流程可优化方向 1. 减少文档编写时间 根据个人的开发经验后端编写API设计文档时常见的情况有如果是简单的需求API数量较少后端直接通过内部即时通信软件和前端沟通如果是复杂的需求API数量较多后端会先把API描述写到本地临时文档纯文本、markdown、evernote等或者内网内部个人Wiki、git仓库中然后把链接发给前端review或者直接面对面沟通。这样的方式灵活但存在一些问题比如 描述格式没有标准。对于简单的描述文档格式比较随意双方基于约定和经验理解和开发1完备的描述编写文档所需时间较长并且细节复杂需要考虑不同的HTTP请求类型、HTTP头部信息、HTTP请求内容等高质量地创建这份文档本身就是件非常吃力的事下游的抱怨声不绝于耳。当然在合作开发中文档越完备双方的理解偏差就越少、开发产生的bug就越少后期也更容易维护代码、适应人员变更但是编写完备的文档所需要的额外时间也不容忽视没有代码产出的设计文档可能不得已让位于现实中整体开发时间的紧张。 以开发“获得管理员账户下可用商户”为例。如果是简单的描述后端告知前端url为{host}/ajax/shop返回的结构是[{shopId:int,shopName:string}]有经验的前端会自动判断出Method为GetContent-type为application/jsonrequest不需要附带参数不需要对错误值做特殊处理而如果是复杂的描述后端一般会列出API名称、功能描述、调用方式、请求参数、请求示例、返回值、成功的返回结果示例、失败的返回结果示例中的几项填充到已有的API模板中2。 输入效率不高。由于开发的API模板缺乏固定的标准因此只能在例如Wiki、纯文本编辑器、markdown编辑器中编写无法得到现代IDE中语法高亮、自动补全、错误提示等特性的支持整体感觉就像是在记事本中写Java。 设计文档中会规定API输出的数据结构一般为json数组或者json对象如果数据结构较为复杂比如包含有几十个字段的POJO要在设计文档中书写可读性良好的数据结构需要更多的时间如果数据结构中字段缺失或者可读性差则会影响前端的文档理解和代码开发。如果后端能提供样例数据自然是最好的因为后端最熟悉业务逻辑产生的样例数据比前端自己Mock的数据更好。但是复杂数据结构的样例数据的编写同样很花时间。 举例需求要求开发一个新增优惠券API其样例数据只能由开发手动生成。如果是修改已有的API要补充新的样例数据开发一般会登录商户平台打开优惠券页面在Chrome中实际操作一遍抓包得到request的bodyjson格式在json格式化网站如[json.cn](json.cn)美化后复制到API设计文档中。 重复录入。因为文档库功能羸弱使用不便所以开发一般先按自己的格式写一份文档但是如果不直接把API录入到公司文档库则开发需要对一份API出两份设计文档。开发一般会开两个窗口左边是API设计文档的完成件右边是公司API文档库编辑页面然后把左边格式各异的API描述文本转换到右边统一的markdown格式。 例如想象一下从Wiki文档的表格中一个个复制粘贴再编辑成markdown格式文本是典型的成本大于收益的工作。 文档维护成本大。由于文档和代码分开存放由于需要手动操作因此文档与代码同步成本较高。随着时间推移不断修改接口实现的时候都必须同步修改接口文档而文档与代码又处于两个不同的媒介除非有严格的管理机制不然很容易导致不一致现象并在业务整体交接、开发成员替换时使后来人付出较大的时间成本。 不同的存放形式的优缺点见仁见智类似于Spring也有XML和JavaConfig两种配置方式。 2. 减少联调时间 缺少样例数据。由于团队内部前端一般不会全面的了解业务后端提供的样例数据往往比前端自己生成的Mock数据对业务需求的把握更准确。如果后端能在API设计文档中提供样例数据一是如果前端没有自动Mock工具的话能节约前端生成Mock数据的时间二是能在联调前为前端提前发现一些低级错误比如具有业务特征的一些默认值处理、空值处理、字段缺失等场景。 3. 减少部署时间 beta环境绑定了唯一的beta域名因此在多分支并行开发时是稀缺资源较大的项目在beta环境编译和部署往往消耗很多等待和解决冲突的时间。如果在联调中发现的问题较多就需要多次部署beta环境时间成本十分可观。 如何减少部署时间另外行文 寻找技术候选 总结起来上面列出的问题大部分是由于API描述标准不统一引起的因此要用标准化的工厂代替散乱的手工生产。虽然平时开发的API具有Rest风格、对外网开放只被企业自己的应用调用不过普遍的WebAPI开发流程还是适用的。我在网上搜索一些功能较为符合的RestAPI设计工具将其大致分为3类讨论。 第一类Swagger、Apiary、RAML 人和机器可读的API描述标准围绕该语言有完善的工具链一般有设计、编译即Codegen、测试有MockServer、自动Mock、本地直连等形式、文档包括静态文档如html和pdf还有可交互文档htmljs、合作多人多角色合作开发这几个模块各个标准都差不多。 较为学术性的表述虽然Web API的实现正变得越来越普及但在工具方面还缺乏一些被广泛接受的标准用以描述、发现并且理解大量基于API的服务的意义。Web API之“元语言”有三个关键领域API描述、API发现以及API档案。所谓的API描述指的是以一种让人类与机器都可读的形式对API进行描述包括API的实现细节例如资源与URL、表述格式HTML、XML、JSON等等、状态码以及输入参数。Swagger、Apiary、RAML的格式各自采取了一种略有不同的设计方式但在本质上都提供了相同的基本特性以多种不同级别的细节对Web API进行描述。 以Swagger23为例分为5个部分示例图来自于RAML不过功能都差不多。 Design其标准为OpenAPI前身是Swagger API Spec提供强大的在线编辑功能包括语法高亮、错误提示、自动完成、实时预览4并且支持用户以Json、Yaml格式撰写5、导入、导出、转换文档。 Build设计文档可以编译成客户端和服务端支持的语言包括Java、NodeJS、C等主流语言。其中Java服务器端使用流行的Spring Boot构建生成的代码包括定义的API接口、空实现方法的样板代码、业务POJO、配套的Swagger注解。值得注意的是由自动生成的Swagger注解可以反向生成最初的API设计文档 Test可在本地服务器运行时使用本地测试功能用户也可以使用SwaggerHub中提供收费的在线测试功能主要有MockServerAuto Mocking、问题跟踪Issue Tracking Document可以在线或离线包括代码编译时和运行时地生成静态html、pdf等文档SwaggerHub可以配合API版本自动同步相应文档的版本 ShareSwaggerHub提供团队管理、联调开发、文档标注等多人合作开发的支持再提一下Apiary和RAML。Apiary6使用API Blueprint标准Apiary网站提供了在线编辑、实时预览、Mock、可交互文档、团队合作、Github同步、流量追踪等包含整个API生命周期的所有服务当然这是收费产品而且价格不菲另外用户也可以通过开源的命令行工具进行离线的API设计、文档生成、发布过程并将其集成到自己的工作流中这也是它的一大特点。RAML使用RAML1.0标准没有自己的可视化在线开发平台而是用官方或第三方的离线工具如API Workbench系列来代替因此它也存在一些缺点比如工具更新不及时某些Tool不支持最新的RAML1.0。 第二类Apidocjs 类似于Intellij Idea的生成JavaDoc功能是一种注释解析器从C、Java、Python代码注释中基于特定的关键字如param、return生成API静态文档。由于更像是先代码实现后生成API文档所以不能算作是设计驱动的开发另外apidocjs也缺乏IDE支持。 第三类Rap、eolinker 没有公开的API设计语言提供在线或离线、闭源或开源的可视化、一体化API开发平台。这里选择中文的Rap、eolinker作为代表。Rap是阿里的开源作品也提供线上服务核心功能是文档编辑和自动Mock服务。eolinker是综合的接口管理平台除了常见的功能还提供接口商店、数据字典等适合创业团队快速开发API的特性。在此不做进一步介绍。 如何选型 选型逻辑 社区活跃、功能完善应用成熟。学习成本低、上手时间短。作为业务开发缺少时间熟悉学习曲线陡峭的知识和工具。功能较多地契合上述优化方向。能补充现有工作流的不足不做大范围的代替。要考虑测试环境处于内网造成的障碍。初步分析 rap、eolinker、swaggerHub、apiary提供了一整套API开发环境取代了现有工作流。放弃。apidocjs缺乏现代IDE特性支持输入效率较低。放弃。进一步分析 Swagger2API BlueprintRAMLDesign在线编辑、IntelliJ Idea插件在线编辑、命令行、Sublime/Atom/Vim插件API Workbench、Sublime/VS插件Design文档格式yaml、jsonmarkdownyamlBuild支持在线Build、IntelliJ Idea插件/Maven插件Codegen服务端框架Spring Boot/JAX—RSTest运行时手动Mock、第三方工具官方和第三方工具生成MockServer/Client第三方工具和在线服务DocumentMaven插件生成静态文档、在线或运行时生成可交互文档支持SpringMVC注解形式第三方工具第三方工具Share在线、收费在线、收费离线、第三方工具综合考虑最后选择Swagger2。因为Swagger对现有的工作流侵入较少工具较为完整与团队使用的Spring MVC技术栈无缝集成可以减轻文档工作量。Swagger2也有一些缺点如使用注解方式对代码有侵入性。 用Swagger2优化现有工作流 减少文档的编写时间 如果后端先编写独立的API设计文档可利用Swagger在线编辑器或IDE插件的自动完成等特性yaml格式统一、简单易懂、表达能力强较markdown冗余字符更少。通过模仿官方Example很容易学习OpenAPI规定的关键字。另外后端也可以把API设计文档直接通过注解的形式标注在Controller类和相关方法上以Spring MVC和Spring Boot为例即可以通过Java反射在Maven Complie或运行时生成API设计文档。Swagger有Intellij Idea的插件支持Swagger注解则能利用现代Java IDE的特性提高输入效率另外完善的注解也方便其他开发人员进行后期维护不需要在设计文档和代码实现中来回切换查看。此种方式相当于面向规约的开发模式即先规定接口再填充实现。 减少文档的转换时间利用第三方工具实现从Swagger、API Blueprint、RAML格式的互相转换或者直接输出为html静态文档方便整合到现在的工作流中。比如API Blueprint的markdown格式可以存储到公司的API文档库html静态文档可以存储到内部Wiki。减少可能的开发时间如果已有独立的API设计文档在Swagger Editor中生成基于Maven Spring Boot的服务端代码不过生成的POJO和Controller类的命名可能不太理想需要自己调整。减少联调时间后端可以在设计文档或注解中指定API或者POJO的Example数据节约前端手动编写Mock数据的时间。附录1流程实例演示脚手架为Spring MVC 1. 标注相应的Swagger注解作为API设计文档 先建立RestController类、相应的API空方法、POJO作为骨架。对应的API设计文档见文末的Reference节。 Api(Users)
RestController
RequestMapping(value /users)
public class UserController {ApiOperation(value 创建用户, notes 根据User对象创建用户)PostMappingpublic String postUser(RequestBody User user) {return null;}ApiOperation(value 获取用户详细信息, notes 根据url的id来获取用户详细信息)GetMapping(/{id})public User getUser(PathVariable Long id) {return null;}
}
class User{private Long id;private String name;private String age;//getter,setter
} 2. 生成API设计文档 生成的具体方式按照耗时长短排列为Maven Complie、Test Case、Server Runtime。可在Swagger Editor中预览相应的可交互文档。根据前端的反馈修改Swagger注解并把新的文档存储到内部Wiki或者API文档库如果改动量大的话利用Diff工具提高效率。 3. 在Swagger-UI提供的可视化页面中完成自测 开发完成后启动ServerSwagger-UI的访问地址为http://localhost:8080/swagger-ui.html 4. 与前端联调 为了减少beta环境的冲突、加快部署速度最好在本地开发环境联调。 附录2Swagger配置与使用 【5分钟指南】Swagger2环境配置与使用 附录3YAML格式的API描述文档示例 swagger: 2.0
info:description: Click Link Below for Helpversion: v1title: demo13termsOfService: http://www.github.com/kongchen/swagger-maven-plugin
host: HOST
basePath: /s
tags:- name: Users
schemes:- http
paths:/users:post:tags:- Userssummary: 创建用户description: 根据User对象创建用户operationId: postUserparameters:- in: bodyname: bodyrequired: falseschema:$ref: #/definitions/Userresponses:200:description: successful operationschema:type: string/users/{id}:get:tags:- Userssummary: 获取用户详细信息description: 根据url的id来获取用户详细信息operationId: getUserparameters:- name: idin: pathrequired: truetype: integerformat: int64responses:200:description: successful operationschema:$ref: #/definitions/User
definitions:User:type: objectproperties:id:type: integerformat: int64name:type: stringage:type: stringReference SwaggerRest API的描述语言RAML vs. Swagger vs. API BlueprintSpringfox Reference DocumentationSwagger使用swagger-maven-plugin通过Swagger进行API设计与Tony Tam的一次对话API 设计: RAML、Swagger、Blueprint三者的比较API描述、发现与档案入门Spring Boot中使用Swagger2构建强大的RESTful API文档API Design And DocumentationSwagger与其他API文档编写工具对比 以“云打印机设置”中的一个API为例简单描述的典型。 ↩ 自定义API模板。 ↩ swagger的Design-Build-Document流程 ↩ 实时预览。 ↩ Swagger支持YAML格式。↩ Apiary的Design-Use-Implement流程。 ↩
