项目作者: codex-league

项目描述 :
Code-X致力解决团队开发中的各种效率问题,目前我们能做的是解决部分重复性工作,比如CRUD工作的重复性,以及restfulAPI文档编写一致性; 从目前看来Code-X希望减少程序员的重复性开发工作,把更多的尽力放在业务实现,或者更有价值的工作当中。
高级语言: Java
项目地址: git://github.com/codex-league/codex.git
创建时间: 2018-11-21T05:08:27Z
项目社区:https://github.com/codex-league/codex

开源协议:Apache License 2.0

下载


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:

  1. compile 'pub.codex:codex-index:5.x.x'
  2. 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
  1. ### 3.2 配置信息
  2. >在spring boot 引口类增加 `@EnableCodexLeague`
  3. 这么做表示当前项目正式启用`Code-X`,与此同时`Code-X`会与当前项目配置信息做绑定
  4. ```java
  5. @SpringBootApplication
  6. @EnableCodexLeague // 添加codex启用信息
  7. public class TestApplication {
  8. public static void main(String[] args) {
  9. ……
  10. }
  11. }

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

在spring boot application.yml,添加一下信息
```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

  1. >完成以上配置后,你可以你的启动项目,如果见到下列图标,恭喜你成功了
  1. _ ___ ___
  2. ______ | | \ \ / /

. / | | _ \ \ / /
/\ | ‘ /
\ / ` | / \ __ \ / \ \ \ \
( ( )| | | | | || | | || /__\
, (__) / \ \ \ \ \
\/ | .__ | || || || || |__ / / \ \ ) ) ) )
‘ __‘ _/ \, | __/ // _\ / / / /
=======================================================/
///

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

  1. >你可以访问工具地址 http://{IP}:{port}/codex.html
  2. 例如:http://localhost:8080/codex.html
  3. IP: 是你的项目地址
  4. port: 是你项目的端口
  5. ## 4 CRUD生成
  6. >利用`Code-X`可实现CRUD重复性工作快速生成
  7. 我们再来看一下配置文件:
  8. - jdbc:设置你的的数据库信息
  9. - package.entity-path: 设置你的entity的位置
  10. - package.mapper-path: 设置你的mapper的位置
  11. - package.service-path: 设置你的service的位置
  12. - package.serviceImpl-path: 设置你的service实现的位置
  13. - package.mapperXML-path: 设置你的mapper.xml的位置
  14. - package.controller-path: 设置你的controller的位置
  15. - prefix: 忽略表的前缀(可添加多个 按逗号分割)
  16. ```yml
  17. codex:
  18. jdbc:
  19. url: jdbc:mysql://localhost:3306/test
  20. username: root
  21. password: 123456
  22. driverClassName: com.mysql.jdbc.Driver
  23. package:
  24. entity-path: pub.codex.db.entity
  25. mapper-path: pub.codex.db.mapper
  26. mapperXML-path: mapper
  27. service-path: pub.codex.db.service
  28. serviceImpl-path: pub.codex.db.service.impl
  29. controller-path: pub.codex.controller
  30. prefix: t_,tb_,test_

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

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

5 api文档工具

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

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

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

5.1 原理

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

  1. @Api("演示API管理接口描述") // 只描述Controller 信息
  2. @RestController
  3. public class DemoApix {
  4. @ApiOperation(value = "演示接口描述") // 只描述API信息
  5. @PostMapping("index")
  6. private Person index(@RequestBody Person person,
  7. @RequestParam String name) {
  8. return person;
  9. }
  10. }

上面是一个简单接口描述信息,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搭配使用
  1. 注解(ElementType)有:
  2. 1.FIELD:用于描述域
  3. 2.METHOD:用于描述方法
  4. 3.PARAMETER:用于描述参数
  5. 4.TYPE:用于描述类、接口(包括注解类型) enum声明

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

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

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

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

5.2 注解

5.2.1 @ApiParam@RequestParam

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

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

5.2.2 @Valid@RequestBody

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

接口:

  1. @ApiOperation(value = "演示接口")
  2. @PostMapping("index")
  3. private Person index(@Valid @RequestBody Person person) {
  4. …………
  5. return person;
  6. }

参数对象

  1. public class Person {
  2. @NotNull
  3. Integer id;
  4. @ApiModelProperty(describe = "姓名")
  5. @NotBlank
  6. private String name;
  7. @ApiModelProperty
  8. private String age;
  9. String sex;
  10. …………
  11. }

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

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

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

5.2.3 @Validate@RequestBody

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

接口:

  1. @RestController
  2. public class DemoApix {
  3. @ApiOperation(value = "演示接口1")
  4. @PostMapping("add")
  5. private Person index1(@Validated(VG.Add.class) @RequestBody Person person) {
  6. return person;
  7. }
  8. @ApiOperation(value = "演示接口2")
  9. @PostMapping("del")
  10. private Person index2(@Validated(VG.Delete.class) @RequestBody Person person) {
  11. return person;
  12. }
  13. }

参数对象

  1. public class Person {
  2. @NotBlank(groups = VG.Delete.class)
  3. String id;
  4. @ApiModelProperty(describe = "姓名")
  5. @NotBlank(groups = VG.Add.class)
  6. private String name;
  7. @ApiModelProperty(groups = VG.Add.class)
  8. private String age;
  9. …………
  10. }

这里只阐述@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)生效

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

5.2.4 规则

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

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

规定

  1. example:
  2. 1@Valid
  3. ApiModelProperty (选填)
  4. Notnull(必填)
  5. 2@Validate(g1)
  6. ApiModelProperty/ApiModelProperty(g1)/(空)/ApiModelProperty(g2),Notnull(g1)(必填)
  7. ApiModelProperty(g1),Notnull/ Notnull(g2)/(空)(选填)
  8. 3@ApiGroup(g1)
  9. ApiModelProperty(g1),NotNull/(空) (选填)
  10. 4@Validate(g1) ,@ApiGroup(g1):
  11. ApiModelProperty/(空)/ApiModelProperty(g2),Notnull(g1)(必填)
  12. ApiModelProperty(g1),Notnull/(空)/ Notnull(g2)(选填)
  13. 5@Validate(g1) ,@ApiGroup(g2):
  14. ApiModelProperty(g1)(选填)
  15. ApiModelProperty(g2)(选填)
  16. Notnull(g1)(必填)
  17. ApiModelPropertyNotnull(g1)(必填)
  18. ApiModelProperty(g1),Notnull(选填)
  19. ApiModelProperty(g2),Notnull(选填)
  20. ApiModelProperty(g1),Notnull(g1) (必填)
  21. ApiModelProperty(g2),Notnull(g2) (选填)
  22. ApiModelProperty(g1),Notnull(g2) (选填)
  23. ApiModelProperty(g2),Notnull(g1) (必填)

todo

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