欢迎来到 秦皇岛市某某自控阀门培训中心
全国咨询热线:020-123456789
联系我们

地址:联系地址联系地址联系地址

电话:020-123456789

传真:020-123456789

邮箱:admin@aa.com

新闻中心
最佳实践之接口规范性检查插件
  来源:秦皇岛市某某自控阀门培训中心  更新时间:2024-04-29 11:31:28

最佳实践之接口规范性检查插件

前言

本文是最佳之接针对微服务架构下各服务之间交互接口契约定义与声明规范性在实际生产中的一个最佳实践 。在经历无数次组件间和项目间的实践扯皮、修改再修改的口规过程中,总结的范性一套契约规范,并辅之以有效的检查自动化检测手段即本文提及的检查插件,通过上述规范和工具统一各项目服务间的插件接口的理解,降低出错返工概率,最佳之接最终提高开发效率 ,实践节省开发成本 。口规

一、范性Maven插件是检查什么

Maven本质上是一个插件框架 ,它的插件核心并不执行任何具体的构建任务 ,所有这些任务都交给插件来完成 ,最佳之接例如编译源代码是实践由maven- compiler-plugin完成的 。进一步说 ,口规每个任务对应了一个插件目标(goal)  ,每个插件会有一个或者多个目标,例如maven- compiler-plugin的compile目标用来编译位于src/main/java/目录下的主源码 ,testCompile目标用来编译位于src/test/java/目录下的测试源码。

用户可以通过两种方式调用Maven插件目标 。第一种方式是将插件目标与生命周期阶段(lifecycle phase)绑定  ,这样用户在命令行只是输入生命周期阶段而已 ,例如Maven默认将maven-compiler-plugin的compile目标与 compile生命周期阶段绑定,因此命令mvn compile实际上是先定位到compile这一生命周期阶段,然后再根据绑定关系调用maven-compiler-plugin的compile目标。第二种方式是直接在命令行指定要执行的插件目标,例如mvn archetype:generate 就表示调用maven-archetype-plugin的generate目标 ,这种带冒号的调用方式与生命周期无关。
目前已经积累了大量有用的插件 ,参考:

  1. http://maven.apache.org/plugins/index.html
  2. http://mojo.codehaus.org/plugins.html

二、接口定义(Yaml)

为避免从代码生成yaml再到yaml编出的代码 ,两者间产生不一致和歧义,如下某Rest接口返回的对象模型 :

@Gettern@Settern@NoArgsConstructorn@ToString(callSuper = true)n@EqualsAndHashCode(callSuper = true)n@ApiModel(description = "com.xxxx.node.IpL2Node")npublic class IpL2Node extends IpNode { nn @JsonProperty("admin-ip")n @ApiModelProperty(name = "admin-ip", value = "管理地址")n private String adminIp;

团队约定在编写接口代码里 ,要求遵守下列约定:

模型实体类上必须使用注解@ApiModel,并且description设置为该实体类的全路径名

模型实体类上尽量使用注解@JsonIgnoreProperties(ignoreUnknown = true)

模型实体类上必须使用注解@JsonNaming(PropertyNamingStrategy.KebabCaseStrategy.class) ,同时不允许使用@JsonProperty特殊指定实体类中某字段的序列化字符串

模型实体类中每个字段必须使用注解@ApiModelProperty,并且保证name定义与序列化出的JSON字符串完全一致

Rest接口不允许返回Set集合

接口代码中不允许使用注解@JsonInclud(JsonInclud.Include.NON_NULL)

Rest接口中 ,不要使用JAVA层面的方法重载 ,会导致生成yaml编译代码后,相同方法后会自动加_0参数用于区分,影响接口准确性

通过上述约定  ,基本上保证了代码输出的yaml与再次编出的代码含义一致 ,但不能寄希望于开发人员主观遵守 ,所以需要一种自动化的手段  ,能够在出错或不满足上述约定时,在开发阶段即通知开发人员,因此我们通过开发maven插件方式完成上述功能。

三 、插件实现

具体插件的实现原理也十分简单 ,即配置该插件后 ,在代码的编译阶段 ,通过扫描classPath下所有类文件 ,通过注解或包括Json相关过滤出潜在模型类,然后按上述规则进行校验 ,并给出报错明细信息 。具体代码开发逻辑记录如下:

该插件的工程目录 :

最佳实践之接口规范性检查插件

POM依赖:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"n xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">n <modelVersion>4.0.0</modelVersion>n <groupId>com.zte.sdn.oscp.topology</groupId>n <artifactId>oscp-restapi-check</artifactId>n <packaging>maven-plugin</packaging>n <version>1.0-SNAPSHOT</version>n <name>oscp-restapi-check Maven Mojo</name>n <url>http://maven.apache.org</url>n <dependencies>n <dependency>n <groupId>org.apache.maven</groupId>n <artifactId>maven-plugin-api</artifactId>n <version>2.0</version>n </dependency>n <dependency>n <groupId>junit</groupId>n <artifactId>junit</artifactId>n <version>3.8.1</version>n </dependency>n <dependency>n <groupId>org.apache.maven</groupId>n <artifactId>maven-core</artifactId>n <version>3.3.9</version>n </dependency>n <dependency>n <groupId>org.apache.maven.plugin-tools</groupId>n <artifactId>maven-plugin-annotations</artifactId>n <version>3.4</version>n </dependency>n <dependency>n <groupId>io.swagger</groupId>n <artifactId>swagger-annotations</artifactId>n <version>1.5.3</version>n </dependency>n <dependency>n <groupId>com.fasterxml.jackson.core</groupId>n <artifactId>jackson-core</artifactId>n <version>2.9.6</version>n </dependency>n <dependency>n <groupId>com.fasterxml.jackson.core</groupId>n <artifactId>jackson-databind</artifactId>n <version>2.9.6</version>n </dependency>n </dependencies>n <build>n <plugins>n <plugin>n <groupId>org.apache.maven.plugins</groupId>n <artifactId>maven-compiler-plugin</artifactId>n <version>3.8.0</version>n <configuration>n <source>1.8</source>n <target>1.8</target>n <encoding>UTF-8</encoding>n </configuration>n </plugin>n <plugin>n <groupId>org.apache.maven.plugins</groupId>n <artifactId>maven-plugin-plugin</artifactId>n <version>3.5.2</version>n </plugin>n </plugins>n </build>n</project>

入口类RestFormatCheckMojo.java ,设置该插件的运行在PROCESS_CLASSES生命周期,保证编译完源码后能够进行模型的较验 。

import static org.apache.maven.plugins.annotations.LifecyclePhase.PROCESS_CLASSES;nnimport java.io.File;nimport java.lang.reflect.Field;nimport java.lang.reflect.Modifier;nimport java.util.ArrayList;nimport java.util.Arrays;nimport java.util.List;nimport java.util.Map;nimport java.util.Set;nimport java.util.stream.Collectors;nnimport io.swagger.annotations.ApiModel;nimport io.swagger.annotations.ApiModelProperty;nimport junit.framework.Assert;nimport org.apache.maven.plugin.AbstractMojo;nimport org.apache.maven.plugin.MojoExecutionException;nimport org.apache.maven.plugins.annotations.Mojo;nimport org.apache.maven.plugins.annotations.Parameter;nimport org.apache.maven.plugins.annotations.ResolutionScope;nimport org.apache.maven.project.MavenProject;nnimport com.fasterxml.jackson.annotation.JsonIgnore;nimport com.fasterxml.jackson.annotation.JsonProperty;nimport com.fasterxml.jackson.databind.ObjectMapper;nimport com.fasterxml.jackson.databind.annotation.JsonNaming;nimport com.google.common.collect.Lists;nimport com.zte.sdn.oscp.topology.annotation.IgnoreFormatCheck;nimport com.zte.sdn.oscp.topology.util.JavaClassScanner;nn@Mojo(name = "yang2bean", defaultPhase = PROCESS_CLASSES, requiresDependencyResolution = ResolutionScope.COMPILE)npublic class RestFormatCheckMojo extends AbstractMojo { nn private List<String> notCheckPkg = Lists.newArrayList();nn @Parameter(property = "skipCheckPkg")n private String skipCheckPkg;nn @Parameter(property = "outDirectory", defaultValue = "${ project.build.outputDirectory}")n private File outputDirectory;nn @Parameter(defaultValue = "${ project.basedir}")n private File baseDir;nnn @Parameter(defaultValue = "${ project}", readonly = true)n private MavenProject project;nn @Parameter(defaultValue = "${ project.build.sourceDirectory}")n private File srcDir;nn @Parameter(defaultValue = "${ project.build.outputDirectory}")n private File outDir;n @Parameter(defaultValue = "${ project.compileClasspathElements}", readonly = true, required = true)n private List<String> compilePath;nn @Overriden public void execute() throws MojoExecutionException { n if (skipCheckPkg != null && !"".equals(skipCheckPkg.trim())) { n String[] split = skipCheckPkg.split(",");n notCheckPkg = Arrays.asList(split);n }n JavaClassScanner scanner = new JavaClassScanner(project);n scanner.scan(outDir);n List<Class> clsList = scanner.getClsList();n List<Class> models = filterByCondition(clsList);n try { n check(models);n } catch (Exception e) { n e.printStackTrace();n }n }nn private void check(List<Class> models) throws Exception { n ObjectMapper objectMapper = new ObjectMapper();n for (Class<?> aClass : models) { n Assert.assertTrue("[" + aClass.getName() + "] must annotated with AipModel", aClass.isAnnotationPresent(ApiModel.class));n Assert.assertEquals(aClass.getName().replace("$", "."), ((ApiModel) aClass.getAnnotation(ApiModel.class)).description());n String serialize = objectMapper.writeValueAsString(aClass.newInstance());n if ("[]".equals(serialize)) { n continue;n }n Map jsonPropertyMap = objectMapper.readValue(serialize, new MapTypeReference());n jsonPropertyMap.remove("class");nn List<String> apiModelProperties = new ArrayList<>();n List<Field> allFields = getAllFields(aClass);n for (Field field : allFields) { n if (field.isAnnotationPresent(JsonIgnore.class)) { n continue;n }n if (Modifier.isStatic(field.getModifiers())) { n continue;n }n //严格要求,必须定义ApiModelPropertyn Assert.assertTrue("[" + field.getName() + "] in [" + aClass.getName() + "] must annotated with ApiModelProperty", field.isAnnotationPresent(ApiModelProperty.class));n String name = field.getAnnotation(ApiModelProperty.class).name();n if (name == null || "".equals(name)) { n apiModelProperties.add(field.getName());n } else { n apiModelProperties.add(name);n }n }n Assert.assertEquals(jsonPropertyMap.size(), apiModelProperties.size());n Set set = jsonPropertyMap.keySet();n Assert.assertTrue("[" + aClass.getName() + "] JSON and ApiModelPorperty not same", set.containsAll(apiModelProperties));n Assert.assertTrue("[" + aClass.getName() + "] JSON and ApiModelPorperty not same", apiModelProperties.containsAll(set));n }n }nn private List<Class> filterByCondition(List<Class> clsList) { n List<Class> result = clsList.stream().filter(p -> { n if (p.isInterface()) { n return false;n }n for (String pkg : notCheckPkg) { n if (p.getName().startsWith(pkg)) { n return false;n }n }n if (p.isAnnotationPresent(IgnoreFormatCheck.class)) { n return false;n }n if (p.isAnnotationPresent(ApiModel.class)) { n return true;n }n if (p.isAnnotationPresent(JsonNaming.class)) { n return true;n }n for (Field declaredField : p.getDeclaredFields()) { n if (declaredField.isAnnotationPresent(JsonProperty.class)) { n return true;n }n }n return false;n }).collect(Collectors.toList());n return result;n }nnn private List<Field> getAllFields(Class cls) { n List<Field> fields = new ArrayList<>();n Class current = cls;n while (current != Object.class) { n fields.addAll(Arrays.asList(current.getDeclaredFields()));n current = current.getSuperclass();n }n return fields;n }nnn}

在插件开发中,无法直接使用Class.forName进行类加载,需要通过动态读取目标项目所依赖的classpath并根据这些classpath生成相应的url数组,以这个url数组作为参数得到的类加载器可以实现在maven插件中动态加载目标项目类及第三方引用包的目的  ,具体可以参考:https://www.cnblogs.com/coder-chi/p/11305498.html

Please note that the plugin classloader does neither contain the dependencies of the current project nor its build output. Instead, plugins can query the project’s compile, runtime and test class path from the MavenProject in combination with the mojo annotation requiresDependencyResolution from the Mojo API Specification. For instance, flagging a mojo with @requiresDependencyResolution runtime enables it to query the runtime class path of the current project from which it could create further classloaders.

四 、运行效果

如图所示 :相关不满足规范的定义已经正确拦截

最佳实践之接口规范性检查插件最佳实践之接口规范性检查插件最佳实践之接口规范性检查插件

友情链接万丈高楼平地起,从67.3元下来,最低的时候跌到7.4元,跌幅88%针对用户携号转网,为挽留用户,三大运营商都有哪些举措?成功人士一生中所走的这关键几步经历了86.88%的跌幅,股价只剩6.11元,每股净资产却高达7.91元润和软件与博通集成战略合作,打造OpenHarmony芯片助力行业发展2000-2500元手机看这3款就够了,骁龙8旗舰处理器加持,直降900元让全球永不失联,全靠中国“鸿雁”星座系统iPhone14背后的消费电子供应链,你知道多少?iQOO新机来袭 6000mAh大电池加持关于联想集团的一些思考iQOO z6x发布,这是一款反向升级的产品?处理器是天玑810京东20W+评价 OMUONE德国欧慕尼高速电吹风机 到底值不值得买微软首次发布汽车和移动出行整体解决方案国家互联网信息办公室发布《数据出境安全评估申报指南(第一版)》华为服务器新机安装配置:驱动安装,raid制作,值得收藏年轻人不换手机了?国产手机如何“活下来”微信又更新了,加入聊天记录迁移功能,还有1个新变化微信转完钱就被拉黑了?这招教你追回被骗的钱也是一英寸定制大底?与小米12s Ultra同级,明年OPPO旗舰有看头南极和北极,哪个更冷?网易美股涨超4%记录生活的1分钟短视频受著作权法保护吗?北京知产法院判了小米发布米家无线洗车机:一体便携设计 众筹399元WiFi6 路由器怎么选?2022 年 WiFi6 路由器选购推荐iQOO发力清仓,120W闪充+12GB运存+超声波指纹,从5499跌至3569元「Java」一文认识IO操作流时代变了!丰田纯电动轿车申报:搭载比亚迪刀片电池、电驱我一定是天底下最大的傻瓜,不然怎么会花35万买国产新能源车呢?专精特新 | 聚合云端芯,让智能被听见巴菲特减持比亚迪!新能源车重挫,还能加仓吗?当任正非说“把活下来作为纲领”时,普通打工人该怎么办?截至目前,盘点今年发布的“1.5K”屏手机这样的iPhone 14Pro你期待吗?数学也有黑洞?—神奇的黑洞数下月迎来一波新机潮,三款顶尖旗舰手机即将发布,有你喜欢的吗?软银旗下的Arm起诉高通违反合同 侵犯商标豪鲸科技获百万元天使轮融资,人工智能赋能美好未来美的和华为,我都不担心《网络奇兵3》还开发吗?原开发商:腾讯说了算数字货币能否代替货币,量子技术
联系我们

地址:联系地址联系地址联系地址

电话:020-123456789

传真:020-123456789

邮箱:admin@aa.com

0.2111

Copyright © 2024 Powered by 秦皇岛市某某自控阀门培训中心   sitemap