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 17 +
mybatis-plus 3.x+ (后续支持其他框架)
MySql (后续支持其他关系型数据库或非关系型数据库)
maven 、gradle
spring boot 3.x+

3 快速开始

3.1 引入依赖

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

gradle：
    compile 'pub.codex:codex-index:5.x.x'
    compile 'pub.codex:codex-core-template-mybatis-plus:5.x.x'
maven:
```xml

pub.codex
codex-index
3.x.x

pub.codex
codex-core-template-mybatis-plus
3.x.x


### 3.2 配置信息
>在spring boot 引口类增加 `@EnableCodexLeague`   
这么做表示当前项目正式启用`Code-X`，与此同时`Code-X`会与当前项目配置信息做绑定
```java
@SpringBootApplication
@EnableCodexLeague // 添加codex启用信息
public class TestApplication { 
    public static void main(String[] args) {
       ……
    }
}

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

在spring boot application.yml，添加一下信息
```yml
codex:
jdbc:
url: jdbc//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: 忽略表的前缀(可添加多个 按逗号分割)
```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_

配置好上面的信息，就可以完全使用 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、@Valid ：
    ApiModelProperty (选填)
    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) （必填）

todo

1、codex 对应springBoot 版本
2、validate对应的javax、jakarta