基于springboot的配置化接口开发工具包的设计及使用

        此工具包用于辅助后端开发人员快速提供接口及接口文档。

        项目地址： capi-server: 基于springboot的配置化接口开发工具 

        以maven模块的方式集成springboot项目中，提供一套配置化的接口开发方式，不影响原有的接口开发方式，也不影响原有接口的使用。前端人员使用时与使用正常开发的接口无差别。    

        此工具包内涵接口配置页面，用于配置接口。内涵在线接口文档，基于swagger改造而来，可在线调试接口。

        以在线配置的方式定义接口，设置接口访问url，请求参数，返回参数及要操作的数据表。支持在线设置子查询，关联查询，各种组合的查询条件，参数必填验证，返回结果字段控制，分页，排序，id初始化，操作人设置，操作时间设置，默认值设置，时间格式自定义等等。若配置项无法满足复杂的业务逻辑，支持前置处理bean和后置处理bean配置，开发人员只需实现数据的处理逻辑即可。

        对于一般的增删查改接口，可以在不停机的情况下只需几分钟就完成接口的开发，并能直接调试，且包含完整的接口文档。

        对于包含复杂逻辑的接口，可以在几分钟之内完成接口配置，生成接口文档供前端使用，然后在实现数据的处理逻辑。

1 设计原理

       大多数的后端接口，都需要操作表数据，操作表的sql，通常会放在xml配置文件里，也有的放在代码中。这个其实可以放在数据库里，加载在缓存中，使用的时候取出来。

       Springboot的接口定义支持如下的方式

        /{project}/capipost/{module}/{urlName}

        或

        /{project}/capiget/{module}/{urlName}

    用这种方式定义一个通用的大接口。通过 {project}.{module}.{urlName}组合为key可以找到已提前配置好的sql，但光有sql不够，还得有操作类型（查询，新增，修改或删除），请求参数信息和结果参数信息，同时为了控制查询条件及返回字段，sql需要能根据配置动态组装。

     这里设计了接口定义表，接口请求参数表，接口结果参数表，三张表来存储这些信息。

    接口调用时，根据操作类型调用不同的服务方法，根据配置对请求参数进行预处理，然后组装sql语句，执行，然后根据配置对结果处理后返回。

    为了方便配置，提供配置页面，配置页面可下拉联想出数据库中存在的表和表字段

    为了能快速配置，提供默认的初始化配置功能，可以初始化标准的增删查改接口。

    为了方便与前端对接和调试，对swagger进行改造，将根据配置信息来生成接口文档。

    为了支持完成复杂的业务逻辑，定义了前置处理接口和后置处理接口，根据业务逻辑是放在执行sql前还是执行后，来实现对应的bean，在配置中指定bean名称，即可完成调用。

    对于需要连续操作多个表的情况，支持在配置中指定其他的配置key，可以一个请求连续执行多套配置。

   

2 应用方式

目前仅支持pg库，其他类型数据库需要稍作改动

前面分享的项目地址中，项目分两个模块 starter 和 capi， starter只是一个简单的springboot的启动器，挂载capi模块启动。capi为核心功能模块，可集成到其他的springboot项目中。

若需要使用，初始化sql脚本，然后将capi模块集成到自己的springboot项目中，注意需要统一 dao文件的扫描路径，也需要开放接口文档的访问路径，参照 starter中 WebMvcConfig 配置类即可。

3 使用说明

正常集成启动后，会有两个页面可以访问

       配置接口访问：http://localhost:8080/capiConfig.html

       接口文档访问:  http://localhost:8080/capiDoc.html

接口文档的使用方式与swagger文档的使用方法无差别，下面重点说明接口配置的使用：

3.1 初始化基本配置

访问 http://localhost:8080/capiConfig.html 会进入如下界面

点击初始化后，需要等待一段时间，会初始化出基本接口

 访问接口文档：http://localhost:8080/capiDoc.html 可以查看到初始化的接口

 此时，如果没有其他要求，这套接口已经可以提供给前端人员使用了。不过一般都会有其他的设置，比如组合的查询条件，时间格式，序列的生成，新增修改保存时的操作人操作时间设置等。此时，可对接口，接口参数，结果参数进行编辑调整。

3.2 接口编辑

      

配置项说明：

项目：根据schema 生成，不允许修改

模块（表）： 表名称的驼峰写法，当未配置基础sql时，会将此值转换为表名进行操作

模块名称：表的注释，在接口文档中用于分菜单展示

服务： 服务方法名，生成的访问url的最后一段

服务名：用于接口文档中看到的接口名称

请求类型：目前仅支持 post

服务类型：列表查询（query），会查询所有数据；

                 分页查询（queryPage），默认支持page，rows参数，进行分页返回

                详情查询（queryInfo），详情查询，返回查询结果的第一条

                新增（insert）,新增

                修改（update），修改

                保存（save），会判断指定字段是否有值，有着修改，无则新增，需要在扩展json中指定字段，例 {“updateid”:”id”} ,表示根据id存在就执行更新。

        自定义（custom），需要直接在基础sql中配置要执行的完整sql语句，sql中支持mybaits的标签，调用时会自动设置值执行。

基础sql:  配置执行的sql，仅需配置 from 和 where 之间的部分
               如要查询 select t.area_name from area t where t.id =1 仅需配置 area t
               即可，其他段会根据参数组装。如果有表连接查询，写成 （table t1 join table                t2 on t1.id=t2.id）t 注意，查询类型的配置，最后需要指定表别名，且值固定是t
               为空时，会根据模块（表）配置的值生成表名，进行操作
               值写为 “null”, 表示不需要执行sql。
               值为json格式时，调用接口直接返回配置的json。
排序/分组规则： 配置 order by 和 group by 语句，会自动拼接在sql最后面
前置处理器： 配置实现了前置处理接口的服务bean名称。2.5 有详细说明
后置处理器：配置实现了后置处理接口的服务bean名称。2.6有详细说明
记录日志和权限控制： 功能暂未实现

3.3 请求参数编辑

       点击请求参数，会弹出接口请求参数的列表。

   可进行批量的删除，启用，禁用，行上的新增表示基于原有的copy一份新的

       点击批量新增参数时，可批量选择参数进行新增：

  添加参数后，对参数进行编辑：

 字段说明：

        参数： 表示参数名称，调用接口时，需要按此值传参

        参数名： 用于接口文档中的参数描述。

       参数类型： 参数的类型。需要注意的是，Date类型时，需要在 格式化配置中，配置时间格式, 例如: yyyy-MM-dd 。 object和list，表示参数分别时对象形式和集合形式，这种配置会单独在 2.3 中说明。

        是否必填: 选择是，调用接口时会对此参数进行必填校验

        查询类型：等于，大于小于等等，其中 in类型时，需要参数传入的是list。自定义时，会自动将查询列中配置的语句作为一个完成的查询条件。

        查询链接符： 为空时，默认为and ，可以配置为 and，or， and_or_1 ，or_and_1等等，其中 and_or_1这种配置，表示会与其他的有相同连接符配置的参数，组成组合查询，相互之间是 or关系，对外是and关系。

        查询列:  指定要查询的表字段名称。

                        为空时，默认将参数驼峰转下划线写法，进行查询

        默认值类型：会根据类型设置参数的默认值。调用接口时未传此参数值，会自动按规则赋值。支持自定义、当前时间、当前登录id、当前机构id、序列等等设置。选择自定义时，会将 默认值配置的值设置给该参数。选择接口时，会调用配置的接口，2.3中有详细说明。选择序列时，需要在 默认值中配置序列名。

        默认值： 配置默认值

        格式化：主要用于date类型的数据，将传入的参数按此格式转为date对象

        校验规则： 待实现。

3.4 结果参数配置

点击行上的结果参数，弹出结果参数列表，只有查询类型的接口才会有结果参数。

 

可进行批量的删除，启用，禁用，行上的新增表示基于原有的copy一份新的

       点击批量新增参数时，可批量选择参数进行新增：

   添加参数后，对参数进行编辑：

 

字段说明：

           参数：返回的字段名，在执行查询sql中，会自动将此值拼接在sql语句中

                       例 : select status_cd “statusCd” .

           参数名： 用于接口文档展示。

           参数类型 : 为date时，需要配置渲染类型和渲染值，用于格式化时间格式。配置object和list时，需要渲染类型配置为接口，具体参考 2.4.

           是否展示:  原定于定义前端是否展示此字段，暂无用。如需要不返回此字段，禁用或删除此参数配置即可。

          渲染类型： 选date时，渲染值得配置时间格式，例 yyyy-MM-dd

                        选子查询时，渲染值得配置子查询语句，别名自动为参数名

                        选接口时， 2.4中有详细说明

3.5 请求参数中配置嵌套配置

     在请求参数中可配置已配置的接口。用于涉及对多个表进行新增修改时，可包装为一个接口。

选择参数类型为 object 或者list , 默认值类型为接口，默认值为接口名。

接口名需要是在接口配置中已配置的接口，按”项目.模块.服务”指定配置。

 例如：“public.area.insert(id=areaId)”

   public 为项目名，area为模块名，insert是服务名。（id=areaId），表示调用此参数中配置的接口时，将参数areaId的值传给此接口的id参数。

       参数中配置的接口，会先执行。

      

3.6结果参数中配置嵌套配置

       在参数接口中可配置接口。用于涉及在一对多的详情查询时，能用一个接口返回。

选择参数类型为 object 或 list，渲染类型为接口，渲染值为 接口名。

接口需要是在接口配置中已配置的接口，按”项目.模块.服务”指定配置。

 例如：“public.area.query(id=areaId)”

   public 为项目名，area为模块名，query是服务名。（id=areaId），表示调用此参数中配置的接口时，将参数areaId的值传给此接口的id参数。

       结果参数中配置的接口，会在接口执行完之后执行，并将查询结果拼接在返回结果中。

3.7 前置处理bean

       在接口配置中可配置前置处理bean，用于在需要代码处理的情况，可以配置代码段进行处理。

要实现的接口：

      

      

3.8 后置处理bean

在接口配置中可配置后置处理bean，用于在需要代码处理接口的情况，可以配置代码段处理。

要实现的接口：

      

4 操作日志与权限控制

       若需记录操作日志，只要在通用接口那进行拦截即可。

       若需进行权限控制，需要查询接口配置信息，根据配置信息的接口访问路径来设置接口权限

5 性能及安全性

       配置信息会提前加载到缓存中，执行性能与正常接口基本无差别。

       安全方面主要是sql注入问题，无此方面问题。

6 后续功能扩展

       集成前端页面，设计可配置性的不同风格的页面，能根据配置信息进行不同数据的展示，达到在不停机的情况下就能提供页面操作功能。