某神秘公司 RESTful、共用接口、前后端分离、接口约定的实践

作者: 良月柒 | 来源:发表于2019-02-14 10:14 被阅读25次

阅读本文大概需要 4.6 分钟。

本文来自

https://juejin.im/post/59eafab36fb9a045076eccc3

前言

随着互联网高速发展，公司对项目开发周期不断缩短，我们面对各种需求，使用原有对接方式，各端已经很难快速应对各种需求，更难以提高效率。于是，我们不得不重新制定对接规范、开发逻辑以便快速上线项目。

我们的目标

尽可能的缩小沟通的成本，开最少的会，确定大部分的事。

花最少的时间写文档，保证90%的开发人员看懂所有内容。

哪怕不看文档，也能知道各种接口逻辑。

不重复写代码

尽可能的写高可读性的代码

我们做了哪些事

完成了前后端分离

Android、ios、web共用一套接口

统一接口规范（post、put、get、patch、delete）

统一了调试工具

统一了接口文档

之前的我们

接口是这样子的：

接口地址含义请求方式

…/A项目/模块1/getProducts获得产品GET

…/A项目/模块1/addProduct添加产品POST

…/A项目/模块1/getProductDetail获得产品详情GET

…/A项目/模块1/editProduct修改产品POST

客户端请求是这样的：

…/A项目/模块1/getProducts?id=1&a=2&b=3&c=4&d=5…………

A页面=====》B页面（携带n个变量）====》C页面（携带m个变量，包含i个A页面的变量） -------经常n>4

大部分请求是POST，至于put、patch、delete是什么鬼，关我屁事。

关于接口入参使用json，那完全是看开发心情。

出参是这样的：

{"message":"success","code":0,"data":具体内容}

其中data里包含数组可能是

[{"a":"1","b":"1"},{"a":"1","b":"1"},{"a":"1","b":"1"},{"a":"1","b":"1"}]

即使下一个页面用到也不会使用id，而是把所有字段都传进去。

A接口中，返回产品用product；B接口中使用good，多个接口很可能不统一。

客户端对接是这样子的：

安卓、ios一套;部分接口各自用一套；html5端一套。

客户端和后台是不停交流的

接口文档是这样的

img

swagger

阿里的rap

Word文档

其它

当然了，我觉得swagger和rap神器都是非常强大的，能够实现各种功能逻辑，但是考虑到开发人员掌握程度不通，复杂度较高，难以提高效率，我决定初期并不使用这两样神器。

后端是这样的

…/A项目/模块1/getProducts ----接口

…/A项目/模块1/Products.html ----页面

…/A项目/模块1/Products.js ----静态资源

接口和静态资源缠在一块，毕竟很多页面可能是一位开发人员同时开发前端、后端，这里的弊端是，只需要自己清楚逻辑，很多做法临时应付，方案并不优雅，别人也很难看懂。一旦这位同事离职，很多说不清的逻辑就留给后人采坑了。

等等…………

重构

下面步入正题，面对以上众多问题聊聊我是如何重新制定流程的

数据库约定

约定数据库里所有表必须包含名为id主键字段。

可能有人会说，正常来说不是每张表里都应该有id主键吗？但是，我们项目中由于之前开发不严谨，部分表没有id主键，或者不为id的主键。这里我们采用分布式的全球唯一码来作为id。

api出参约定

约定所有出参里含list，且其他请求会用到这组list，则list里所有对象必须含id唯一标识。

入参约定

约定token身份认证统一传入参数模式，后端采用aop切面编程识别用户身份。其他参数一律为json。

resultfull接口约定

首先我们选择一个名词复数，比如产品

post方法

新增一条XXX

比如 ……/products 则代表新增一条产品

入参json如下：

{ "name":"我是一款新产品", "price":100, "kind":"我的分类", "pic":[一组图片], 等等还有很多}

java 代码control层

@ResponseBody @RequestMapping(value = "/A项目/B模块/products", method = {RequestMethod.POST}) public ResultObject getProducts() { //具体逻辑。 }

put方法

新增某条XXX记录

比如 ……/products/1111111111

入参json如下：

{ "name":"我是一款新产品", "price":100, "kind":"我的分类", "pic":[一组图片], 等等还有很多}

表示增加一条1111111111id的记录

java代码control层

@ResponseBody @RequestMapping(value = "/A项目/B模块/products/{id}", method = {RequestMethod.PUT}) public ResultObject putProducts(@PathVariable(value = "id") String id) { //具体逻辑。 }

get方法

获得所有XXX

……/products 则代表获取所有产品

因为有分页，所以我们后面加了?page=1&pageSize=50

我们约定了所有名词复数，都会返回list，且list每个对象都有字段为id的唯一id。

比如

{ "data":{"list":[{"id":"唯一id","其他很多字段":""},{"id":"唯一id","其他很多字段":""}],"page":1,其他字段}, "code":0, "message":"成功"}

……/products/{id} 获取某个具体产品（一定比列表更详细）

比如某个具体产品里还包含一个list，如该产品推荐列表，则：

……/products/{id}/recommendations

假设它包含的不是一个list，而是对象，比如产品佣金信息，则：

……/products/{id}/Commission

这里我们以是否名词复数来判断是对象还是list.

java代码control层

@ResponseBody @RequestMapping(value = "/A项目/B模块/products/{id}", method = {RequestMethod.GET}) public ResultObject putProducts(@PathVariable(value = "id") String id) { //具体逻辑。 }

patch 方法

更新局部XXX产品YYY信息

入参是post方法时入参的子集，所有支持更新的参数会说明，并不是支持所有变量

……/products/{id}

{ "name":"我是一款新产品", "price":100, 部分变量}

java代码control层

@ResponseBody @RequestMapping(value = "/A项目/B模块/products/{id}", method = {RequestMethod.PATCH}) public ResultObject putProducts(@PathVariable(value = "id") String id) { //具体逻辑。 }

delete方法

删除XXX记录

……/products/11111

删除11111产品。

java代码control层

@ResponseBody @RequestMapping(value = "/A项目/B模块/products/{id}", method = {RequestMethod.DELETE}) public ResultObject putProducts(@PathVariable(value = "id") String id) { //具体逻辑。 }

其他说明

我们尽可能少的使用动词，但有一些行为需要使用动词，比如登录等。

关于版本号，我们打算在模块后增加/v1/等标识。

权限约定

服务端要对用户角色进行判断，是否有权限执行某个逻辑。

前后端分离约定

后端以开发接口为主，不再参与页面开发，或者混合式jsp页面开发，统一以接口形式返回，前端通过js渲染数据以及处理逻辑。

共用接口

web、Android、ios使用统一接口，不在因为哪方特殊要求额外开放接口。

使用统一dao层生成工具

基于mybatis-generator改造成适合我们项目的dao层以及部分service层，内部共同维护共同使用。

使用postman最为接口文档、调试工具