Code-x

Code-X

License

License

Categories

Categories

Dex General Purpose Libraries Utility
GroupId

GroupId

pub.codex
ArtifactId

ArtifactId

codex-core
Last Version

Last Version

4.2.5
Release Date

Release Date

Type

Type

jar
Description

Description

Code-x
Code-X
Project URL

Project URL

https://github.com/codex-league/codex
Source Code Management

Source Code Management

https://github.com/codex-league/codex

Download codex-core

How to add to project

<!-- https://jarcasting.com/artifacts/pub.codex/codex-core/ -->
<dependency>
    <groupId>pub.codex</groupId>
    <artifactId>codex-core</artifactId>
    <version>4.2.5</version>
</dependency>
// https://jarcasting.com/artifacts/pub.codex/codex-core/
implementation 'pub.codex:codex-core:4.2.5'
// https://jarcasting.com/artifacts/pub.codex/codex-core/
implementation ("pub.codex:codex-core:4.2.5")
'pub.codex:codex-core:jar:4.2.5'
<dependency org="pub.codex" name="codex-core" rev="4.2.5">
  <artifact name="codex-core" type="jar" />
</dependency>
@Grapes(
@Grab(group='pub.codex', module='codex-core', version='4.2.5')
)
libraryDependencies += "pub.codex" % "codex-core" % "4.2.5"
[pub.codex/codex-core "4.2.5"]

Dependencies

compile (3)

Group / Artifact Type Version
pub.codex : codex-common-db jar 4.2.5
pub.codex : codex-common jar 4.2.5
pub.codex : codex-core-template-stream jar 4.2.5

runtime (5)

Group / Artifact Type Version
org.springframework.boot : spring-boot-starter-web jar
org.apache.velocity : velocity-engine-core jar 2.0
org.apache.commons : commons-lang3 jar 3.5
commons-configuration : commons-configuration jar 1.10
commons-io : commons-io jar 2.5

Project Modules

There are no modules declared in this project.

Code-X Reference Guide

欢迎使用Code-X
关注官方网站:【http://www.codex.pub/codex.html】
关注Github:【https://github.com/codex-league/codex】

1 我们能做什么?

Code-X致力解决团队开发中的各种效率问题,目前我们能做的是解决部分重复性工作,比如CRUD工作的重复性,以及restfulAPI文档编写一致性;
从目前看来Code-X希望减少程序员的重复性开发工作,把更多的尽力放在业务实现,或者更有价值的工作当中。

演示地址

http://www.codex.pub/codex.html

使用了Code-X,你的项目将可以看到演示地址中的所有功能

2 环境要求

jdk 1.8 +
mybatis-plus 3.x+ (后续支持其他框架)
MySql (后续支持其他关系型数据库或非关系型数据库)
maven 、gradle
spring boot 2.x+

3 快速开始

3.1 引入依赖

已经发布至maven中央库,阿里云maven均可获取: https://search.maven.org/search?q=pub.codex 当前版本最新 3.2.14

gradle:

    compile 'pub.codex:codex-index:3.x.x'
    compile 'pub.codex:codex-core-template-mybatis-plus:3.x.x'

maven:

<dependency>
  <groupId>pub.codex</groupId>
  <artifactId>codex-index</artifactId>
  <version>3.x.x</version>
</dependency>

<dependency>
  <groupId>pub.codex</groupId>
  <artifactId>codex-core-template-mybatis-plus</artifactId>
  <version>3.x.x</version>
</dependency>
     

3.2 配置信息

在spring boot 引口类增加 @EnableCodexLeague
这么做表示当前项目正式启用Code-X,与此同时Code-X会与当前项目配置信息做绑定

@SpringBootApplication
@EnableCodexLeague // 添加codex启用信息
public class TestApplication { 

    public static void main(String[] args) {
       ……
    }
}

只是这么做还不够,你还需要告诉Code-X一些基础配置信息,下面列出必须的简单配置信息,详细解释见后续

在spring boot application.yml,添加一下信息

codex:
  jdbc:
    url: jdbc:mysql://localhost:3306/test
    username: root
    password: 123456
    driverClassName: com.mysql.jdbc.Driver
  package:
    entity-path: pub.codex.db.entity
    mapper-path: pub.codex.db.mapper
    mapperXML-path: mapper
    service-path: pub.codex.db.service
    serviceImpl-path: pub.codex.db.service.impl
    controller-path: pub.codex.controller
  prefix: t_,tb_,test_
apix:
  controllerPackage: pub.codex.controller

完成以上配置后,你可以你的启动项目,如果见到下列图标,恭喜你成功了


                           _                 ___     ___
      ______              | |                \  \   /  /
   . /  ____'  ____    ___| |  ____           \  \ /  / __ _ _
 /\\ | '      / __ \  / __` | / __ \   ______  \  _  /  \ \ \ \
( ( )| |     | |  | || |  | || /__\_, (______) /     \   \ \ \ \
 \\/ | .____ | |__| || |__| || |____          /  / \  \   ) ) ) )
  '  \______' \____/  \___, | \____/         /__/   \__\ / / / /
 =======================================================/_/_/_/


本项目使用Code-x
关注官方网站:【http://www.codex.pub】
关注Github:【https://github.com/codex-league/codex】

你可以访问工具地址 http://{IP}:{port}/codex.html
例如:http://localhost:8080/codex.html

IP: 是你的项目地址  
port: 是你项目的端口

4 CRUD生成

利用Code-X可实现CRUD重复性工作快速生成
我们再来看一下配置文件:

  • jdbc:设置你的的数据库信息
  • package.entity-path: 设置你的entity的位置
  • package.mapper-path: 设置你的mapper的位置
  • package.service-path: 设置你的service的位置
  • package.serviceImpl-path: 设置你的service实现的位置
  • package.mapperXML-path: 设置你的mapper.xml的位置
  • package.controller-path: 设置你的controller的位置
  • prefix: 忽略表的前缀(可添加多个 按逗号分割)
codex:
  jdbc:
    url: jdbc:mysql://localhost:3306/test
    username: root
    password: 123456
    driverClassName: com.mysql.jdbc.Driver
  package:
    entity-path: pub.codex.db.entity
    mapper-path: pub.codex.db.mapper
    mapperXML-path: mapper
    service-path: pub.codex.db.service
    serviceImpl-path: pub.codex.db.service.impl
    controller-path: pub.codex.controller
  prefix: t_,tb_,test_

配置好上面的信息,就可以完全使用 CRUD生成的功能了

如果你只是单独配置了code-core,你可以访问http://localhost:8080/codex-core.html

5 api文档工具

api文档工具,可以使你快捷的生成文档信息
你只需要你在的Spring boot 配置文件中增加下列配置:

  • controllerPackage: 描述你的resetful接口的包路径,这样codex可以根据你指定的范围进行搜索API,并生成文档信息
apix:
  controllerPackage: pub.codex.controller

如果你只是单独配置了Apix,你可以访问http://localhost:8080/codex-apix.html

5.1 原理

codex运行时会去根据用户提供的controllerPackage包路径来进行restful api扫描,扫描的接口信息必须是String boot 的RequestHandler信息

@Api("演示API管理接口描述")  // 只描述Controller 信息
@RestController
public class DemoApix {

   
    @ApiOperation(value = "演示接口描述") // 只描述API信息
    @PostMapping("index")
    private Person index(@RequestBody Person person, 
            @RequestParam String name) {

        return person;
    }

}

上面是一个简单接口描述信息,Apix会根据 @RequestBody@RequestParam 来确定参数的详细内容

如果你想为你的api文档丰富起来,你可以使用更多的注解

注解 类型(ElementType) 描述
@Api ElementType.TYPE 描述你的Controller信息
@ApiOperation ElementType.METHOD 描述你的接口信息
@ApiParam ElementType.PARAMETER 描述你 @RequestParam的参数信息
@ApiModelProperty ElementType.FIELD 描述你的@RequestBody的对象字段信息
@ApiGroup ElementType.PARAMETER 描述你的@RequestBody对象字段信息分组
@Valid ElementType.PARAMETER 设置你的@RequestBody的对象字段信息全部必填
@Validated ElementType.PARAMETER 设置你的@RequestBody的对象字段信息的组来设置必填
@NotBlank、@NotNull.. ElementType.FIELD 设置的验证方式 与@Validated搭配使用
注解(ElementType)有:
    1.FIELD:用于描述域
    2.METHOD:用于描述方法
    3.PARAMETER:用于描述参数
    4.TYPE:用于描述类、接口(包括注解类型) 或enum声明

看了上面的那么多注解,应该已经晕了,由于注解组合较多,关系比较复杂,下面为你娓娓道来

上述注解总体可以分两大类,一类是Apix的自有注解,例如:@Api、@ApiOperation、@ApiParam、@ApiModelProperty、@ApiGroup
另一类是外部支持注解,例如:@Valid、@Validated、@NotBlank、@NotNull

自有注解主要作为工作描述接口的描述信息;
而外部支持注解主要工作是设置接口强验证,Apix利用外部支持注解来为文档提供必填信息

关于外部支持,可以参考
http://hibernate.org/validator/  
详细了解@Valid、@Validated、@NotBlank、@NotNull..  本文档不在详细描述他们的功能

5.2 注解

5.2.1 @ApiParam 和 @RequestParam

@ApiOperation(value = "演示接口") 
@PostMapping("index")
private String index( @ApiParam("姓名") @RequestParam(required = false) String name) { 
    …………
    }

Apix可以获取被@RequestParam标注的参数(必须是基本类型或String),你可以配合@ApiParam给前述参数添加一个新的描述信息,另外Apix根据你的给定的@RequestParam行为,决定他是否必填

5.2.2 @Valid 和 @RequestBody

Apix可以获取被@RequestBody标注的对象参数(必须是对象,不能是基本数据类型和String),你可以配合@Valid来描述对象中必填的字段信息

接口:

@ApiOperation(value = "演示接口")
@PostMapping("index")
private Person index(@Valid @RequestBody Person person) { 

            …………
        return person;
        }

参数对象

public class Person {

    @NotNull
    Integer id;

    @ApiModelProperty(describe = "姓名")
    @NotBlank
    private String name;

    @ApiModelProperty
    private String age;

    
    String sex;

      …………
}

在被@Valid和@RequestBody标注的Person对象,内部使用了 @NotNull、@NotBlank,这种注解属于验证注解,在你请求接口的时候,被标注的字段必须不能为空;但在这里,仅为了获取其信息,使用这类注解告诉@Apix其字段是否必填。

按照上面的例子,使用了@Valid和@RequestBody标注的Person对象,他的id和name字段在@Apix生成文档时显示必填
如果你需要为字段提供丰富的描述信息,你可以像上述代码一样,为字段增加ApiModelProperty(describe = "姓名"),它可以告诉Apix这个字段的描述信息

上述只描述了如何让Apix必填显示,如果需要选填,只需要像 age 字段一样,增加@ApiModelProperty

5.2.3 @Validate 和 @RequestBody

@Validate 和 @RequestBody的业务其实与@Valid 和 @RequestBody一样,只是增加了一个分组的概念@ApiGroup,@ApiGroup的主要目的是为了在多个接口同时使用同一对象下的情况下,区分不同业务,不同验证规则

接口:

@RestController
public class DemoApix {

    @ApiOperation(value = "演示接口1")
    @PostMapping("add")
    private Person index1(@Validated(VG.Add.class) @RequestBody Person person) {


        return person;
    }

    @ApiOperation(value = "演示接口2")
    @PostMapping("del")
    private Person index2(@Validated(VG.Delete.class) @RequestBody Person person) {


        return person;
    }

}

参数对象

public class Person {

    @NotBlank(groups = VG.Delete.class)
    String id;

    @ApiModelProperty(describe = "姓名")
    @NotBlank(groups = VG.Add.class)
    private String name;

    @ApiModelProperty(groups = VG.Add.class)
    private String age;

      …………
}

这里只阐述@ApiGroup,因为其他内容与@Vaild无异
首先看上述接口代码,其两个接口使用了相同的 Person 对象,但是两个接口的业务不一样,一个是添加,一个是删除,为了区分接口业务,我们使用了@Validated(VG.Delete.class)和@Validated(VG.Add.class)来表示,他的主要目的是告诉Apix这两个接口的业务不同,对Person 对象处理的业务逻辑也不一样
现在再来看Person对象内部,@NotBlank(groups = VG.Delete.class)@NotBlank(groups = VG.Add.class),分别表示接口被@Validated(VG.Delete.class)标注时,@NotBlank(groups = VG.Delete.class)生效 / @NotBlank(groups = VG.Add.class)标注时,@NotBlank(groups = VG.Add.class)生效

上述只描述了如何让Apix必填显示,如果需要选填,只需要像 age 字段一样,增加@ApiModelProperty(groups = VG.Add.class)

5.2.4 规则

由于@Valid、@Validated和@ApiGroup等注解各种组合较多,不方便一一说明,下面罗列了大部分组合的结果信息,感兴趣的同学可以参考,这样可以更熟练的使用Apix

@Valid、@Validated和@ApiGroup决定作用范围不同,所以会表现出不同的优先级

规定

  • @Valid、@Validated、@ApiModelProperty、@ApiGroup作用被@RequestBody标注的对象;

  • @Valid、@Validated的优先级大于@ApiGroup

  • @NotBlank、@NotNull..等优先级大于@ApiModelProperty

  • @ApiModelProperty包含两种形式,分别是@ApiModelProperty("注释")和@ApiModelProperty("注释",group),以下描述会省略为@ApiModelProperty和@ApiModelProperty(group)

  • 以下描述中(group)表示当前注解有分组信息,注意在进行注解组合时,如若分组信息不匹配,当前注解也会失效

  • 当存在@Valid,所有包含分组的注解失效,所有对象字段中存在@NotBlank、@NotNull..等注解则为必填,存在@ApiModelProperty则为选填,如若两者同时存在则以优先级较高的为准。当@ApiModelProperty不存在或者失效,只存在@NotBlank、@NotNull..等时,则当前字段的注释以该字段名代替。

  • @Validated(group)作用域包括@NotBlank(group)、@NotNull(group)..等和@ApiModelProperty(group),并且先校验@NotBlank(group)、@NotNull(group)..等注解,存在则为必填,其次才会校验和@ApiModelProperty(group),存在则为选填,如若两者同时存在则以优先级较高的为准。当@ApiModelProperty(group)不存在或者失效,只存在@NotBlank(group)、@NotNull(group)..等时,则当前字段的注释以该字段名代替。

  • @ApiGroup(group)作用域为@ApiModelProperty(group),只会校验@ApiModelProperty(group),存在则为选填。

  • 当@Validated(group)和@ApiGroup(group)单独存在时按照以上规则进行注解匹配,如若同时存在,且分组相同时以优先级为准,高优先级会屏蔽低优先级的注解,并且@NotBlank(group)、@NotNull(group)..等注解生效时对于@ApiModelProperty和@ApiModelProperty(group)效果一致;当分组不一致时,也会以高优先级注解首先进行匹配,如果匹配失败才会,以低优先级注解来匹配。

 example:
 
 1@ValidApiModelProperty (选填)
    Notnull(必填)
    
 2@Validate(g1) :
    ApiModelProperty/ApiModelProperty(g1)/(空)/ApiModelProperty(g2),Notnull(g1)(必填)
    ApiModelProperty(g1),Notnull/ Notnull(g2)/(空)(选填)
    
 3@ApiGroup(g1) :
    ApiModelProperty(g1),NotNull/(空) (选填)
    
 4@Validate(g1) ,@ApiGroup(g1):
    ApiModelProperty/(空)/ApiModelProperty(g2),Notnull(g1)(必填)
    ApiModelProperty(g1),Notnull/(空)/ Notnull(g2)(选填)
    
 5@Validate(g1) ,@ApiGroup(g2):
    ApiModelProperty(g1)(选填)
    ApiModelProperty(g2)(选填)
    Notnull(g1)(必填)
    ApiModelProperty,Notnull(g1)(必填)
    ApiModelProperty(g1),Notnull(选填)
    ApiModelProperty(g2),Notnull(选填)
    ApiModelProperty(g1),Notnull(g1) (必填)
    ApiModelProperty(g2),Notnull(g2) (选填)
    ApiModelProperty(g1),Notnull(g2) (选填)
    ApiModelProperty(g2),Notnull(g1) (必填)

Versions

Version
4.2.5
4.2.4
4.2.3
4.2.2
4.2.1
4.2.0
4.1.0
4.0.0
3.2.14
3.2.13
3.2.12
3.2.11
3.2.10
3.2.9
3.2.8
3.2.7
3.2.6
3.2.5
3.2.4
3.2.3
3.2.2
3.2.1
3.2.0
3.1.0
3.0.0.release
3.0.0
2.2.1
2.2.0
2.1.1