BizWorks接口扫描规范

接口扫描支持通过平台扫描和使用BizWorks Toolkit扫描。本文介绍BizWorks接口扫描操作和规则。

触发接口扫描操作步骤

通过平台扫描接口

  1. 登录BizWorks,在选择平台下拉列表中选中微服务开发平台image.png

  2. 单击页面右上角image.png图标或其文本框区域,在下拉列表中单击目标项目名称后,单击应用页签。在应用列表页面单击目标中心应用名称。image.png

  3. 在目标中心应用左侧导航栏中,选择应用开发 > 接口管理

  4. 应用接口管理页面,单击接口扫描image.png

  5. 代码扫描上报接口信息面板,单击扫描代码分支。在扫描代码分支面板的代码分支下拉列表中选中目标代码分支后,单击提交image.png

使用BizWorks Toolkit扫描接口

说明

BizWorks Toolkit支持接口扫描的前提是您对应功能权限已经开通。在确认拥有API的修改权限后,您需重新登录BizWorks Toolkit刷新用户权限信息,即可进行接口管理。关于如何登录BizWorks Toolkit账号,请参见登录BizWorks Toolkit账号

  1. 打开IDEA,您可以通过以下两种方式进入接口管理页签。

    • 方式一:在顶部导航栏选择view > Tool Windows > BizWorks > 接口管理image

    • 方式二:根据不同版本或主题风格,在左侧边工具栏或底部工具栏单击BizWorks窗口入口后,再单击接口管理页签。image

  2. 可选接口扫描。

    接口管理页签的顶部工具栏,单击image图标,插件将对当前项目下所有Production范围(不包括 test)的,且符合SpringMVC注解配置的接口进行扫描。image

    image

    扫描结果应与SpringMVC运行时接口范围一致。更多信息,请参见接口扫描规则说明

  3. 可选接口上报。单击image图标进行增量或全量接口上报。

    • 增量上报:上报新增的接口,更新平台已存在的接口。

    • 全量上报:以本地接口定义为准,覆盖平台接口信息,将删除不存在的接口。

    image

接口扫描规则说明

接口扫描适应于Java语言实现,且遵循SpringMVC注解规范的HTTP接口。

当前支持的框架和库如下:

类型

名称

注解示例

服务端框架

Spring MVC

@RestController, @GetMapping

校验库

Java Bean Validation

@NotNull

序列化库

• FASTJSON • GSON

@JsonProperty

语言与注释

Java: Javadoc

扫描关系映射示意如下(下图中序列号相同的字段,代表着相应的映射关系):

image

API的扫描目前遵循与SpringMVC运行时结果一致的原则,所以仅在Interface中声明的API不会被扫描,需有具体的@Controlle@RestController实现类。

因为实现类原则上可以实现多个接口,可以覆盖接口中描述的部分信息,故扫描同样从实现类开始,当实现类中缺少对应信息的时候再从超类或接口中寻找。

注释控制

注释控制,指的是通过在类或方法注释中,通过不同的注释tag,控制扫描的行为。示例代码如下:

/**
 * 商品SKU服务
 * @folder 一级目录/二级目录
 */
@RestController("CommoditySkuServiceCON")
public class SkuServiceController implements SkuServiceI {
 ……
}

@folder即为注释的tag,可以改变目录从默认的“商业SKU服务”到“一级目录”/“二级目录” 两级目录下。

当前,所有支持的注释tag如下:

  • folder指定目录。类上有效。可以通过目录文本包含 “/”指定多级目录。

  • ignore忽略指定Controller或方法上的接口扫描。类或方法上有效。

  • registerAPIGateway是否注册网关。方法上有效。可选值如下:

    • true:注册。

    • false:不注册。

    • 默认注册。

  • authPolicy认证策略,是否开启认证。方法上有效。可选值如下:

    • true/on:开启认证。

    • false/off:关闭认证。

    • default或不填:默认策略。