框架基础 on Macula

Macula Boot Starter Web

Mon, 01 Jan 0001 00:00:00 +0000

概览

该模块为web开发所需的基本依赖包。是对spring-boot-starter-web模块的扩展，并且使用undertow替换了tomcat作为WEB服务器。有兴趣可以阅读优雅的写Controller。

组件坐标

<dependency>
 <groupId>dev.macula.boot</groupId>
 <artifactId>macula-boot-starter-web</artifactId>
 <version>${macula.version}</version>
</dependency>

使用配置

macula:
	jackson:
		null-to-empty: true # 默认为false。设置为true时，json序列化默认将null转为-1或者空串，空对象转为{}，空数组转为[]。
		long-to-string: false # 默认为true。设置为true时，BigDecimal/BigInteger/Long类型会序列化为字符串，设置为false时，超出JS最大最小值范围才处理为字符串，其他按照数字处理。
		local-date-time-format: 'yyyy/MM/dd HH:mm:ss a' # 设置LocalDateTime的全局格式
 local-date-format: 'dd/MM/yyyy'									 # 设置LocalDate的全局格式
 local-time-format: 'HH:mm:ss a'									 # 设置LocalTime的全局格式
 web:
 exception-advie: true # 统一异常处理器，默认true
 response-advice: true # 统一响应处理器，默认true

核心功能

全局异常处理

如果在Controller每个方法都catch异常，非常不方便，所以默认通过ControllerExceptionAdvice类处理，包括：

BindException（使用form data方式调用接口，校验异常抛出 BindException）
ConstraintViolationException（单个参数校验异常抛出ConstraintViolationException）
MethodArgumentNotValidException (使用 json 请求体调用接口，校验异常抛出 MethodArgumentNotValidException)
BizException（业务异常，一般业务可以继承这个异常类）
BizCheckException（这个异常主要是业务检查类异常，一般告警系统无需关注，主要是提示给前端用户的输入不正确，返回510状态码）
NullPointerException
Exception（兜底）

统一按照如下结构返回，HTTP Status返回是500：

Macula Boot Starter MapStruct

Mon, 01 Jan 0001 00:00:00 +0000

概览

开发JAVA应用程序时会进行逻辑分层，各层之间为了解耦，通常会定义不同的对象进行数据传递（如XXXVO、XXXDTO、XXXPO、XXXBO）。当在不同层之间进行数据传递时，需要将这些对象进行相互转换。通常有两种处理方式：一是直接使用Setter和Getter方法转换，二是使用一些工具类进行转换（如BeanUtil.copyProperties）。第一种方式如果对象属性比较多时，要写很多的Getter/Setter代码，很繁琐；第二种方式虽然比第一种方式要简单很多，但是因为使用了反射，性能不佳。故在此推荐，统一使用MapStruct（MapStructPlus），代码简洁且不存在性能问题。

组件坐标

<dependency>
 <groupId>dev.macula.boot</groupId>
 <artifactId>macula-boot-starter-mapstruct</artifactId>
 <version>${macula.version}</version>
</dependency>

使用配置

该组件在编译期生成转换代码，无独立运行时 YAML 配置。继承 Macula Boot 父 POM 的注解处理配置，并在 IDE 启用注解处理；具体写法见“核心功能”。

核心功能

基于MapStruct

MapStruct是一个类型转换工具，通过定义类型转换接口（如下所示），然后在编译的时候自动生成实现类来工作。

@Mapper
public interface SourceTargetMapper {

 SourceTargetMapper MAPPER = Mappers.getMapper( SourceTargetMapper.class );

 @Mapping( source = "username", target = "user" )
 TargetDto toTarget( SourceDto s );
}

另外，使用mapstruct前，需要在你的父工程的Maven项目的pom中定义以下build插件：

<build>
 <pluginManagement>
 <plugins>
 <plugin>
 <groupId>org.apache.maven.plugins</groupId>
 <artifactId>maven-compiler-plugin</artifactId>
 <version>3.8.1</version>
 <configuration>
 <source>${java.version}</source>
 <target>${java.version}</target>
 <!-- See https://maven.apache.org/plugins/maven-compiler-plugin/compile-mojo.html -->
 <!-- Classpath elements to supply as annotation processor path. If specified, the compiler -->
 <!-- will detect annotation processors only in those classpath elements. If omitted, the -->
 <!-- default classpath is used to detect annotation processors. The detection itself depends -->
 <!-- on the configuration of annotationProcessors. -->
 <!-- -->
 <!-- According to this documentation, the provided dependency processor is not considered! -->
 <annotationProcessorPaths>
 <path>
 <groupId>org.mapstruct</groupId>
 <artifactId>mapstruct-processor</artifactId>
 <version>${mapstruct.version}</version>
 </path>
 <path>
 <groupId>org.projectlombok</groupId>
 <artifactId>lombok</artifactId>
 <version>${lombok.version}</version>
 </path>
 <path>
 <groupId>org.projectlombok</groupId>
 <artifactId>lombok-mapstruct-binding</artifactId>
 <version>0.2.0</version>
 </path>
 </annotationProcessorPaths>
 </configuration>
 </plugin>
 </plugins>
 </pluginManagement>
</build>

MapStruct更多功能可以参考官方文档

Macula Boot Starter JPA

Mon, 01 Jan 0001 00:00:00 +0000

概览

该模块主要使用alibaba druid作为数据源工具，Spring Data JPA和Fenix作为数据库操作框架。 Fenix（菲尼克斯）是一个为了解决复杂动态 SQL (JPQL) 而生的 Spring Data JPA 扩展库，能辅助开发者更方便快捷的书写复杂、动态且易于维护的 SQL，支持 ActiveRecord 模式和多种查询方式。

组件坐标

<dependency>
 <groupId>dev.macula.boot</groupId>
 <artifactId>macula-boot-starter-jpa</artifactId>
 <version>${macula.version}</version>
</dependency>

使用配置

配置上没有太特殊的，主要是数据源配置以及fenix配置。

spring:
 datasource:
 driver-class-name: com.mysql.cj.jdbc.Driver
 url: jdbc:mysql://localhost:3306/xxx?serverTimezone=Asia/Shanghai&characterEncoding=utf-8
 username: xxx
 password: xxx
 jpa:
 show-sql: true 		# 默认false，在日志里显示执行的sql语句
 hibernate:
 	# 指定为update，每次启动项目检测表结构有变化的时候会新增字段，表不存在时会 新建，如果指定create，
 	# 则每次启动项目都会清空数据并删除表，再新建。生产要指定为none
 ddl-auto: update 
 
# Fenix 的几个配置项、默认值及详细说明，通常情况下你不需要填写这些配置信息（下面的配置代码也都可以删掉）.
fenix:
 # v2.4.1 版本新增，表示是否开启 debug 调试模式，默认 false。
 # 当开启之后，对 XML 中的 SQL 会进行实时文件流的读取和解析，不需要重启服务。切记仅在开发环境中开启此功能.
 debug: true
 # 成功加载 Fenix 配置信息后，是否打印启动 banner，默认 true.
 print-banner: true
 # 是否打印 Fenix 生成的 SQL 信息，默认为空.
 # 当该值为空时，会读取 'spring.jpa.show-sql' 的值，为 true 就打印 SQL 信息，否则不打印.
 # 当该值为 true 时，就打印 SQL 信息，否则不打印. 生产环境不建议设置为 true.
 print-sql: true
 # 扫描 Fenix XML 文件的所在位置，默认是 fenix 目录及子目录，可以用 yaml 文件方式配置多个值.
 xml-locations: fenix
 # 扫描你自定义的 XML 标签处理器的位置，默认为空，可以是包路径，也可以是 Java 或 class 文件的全路径名
 # 可以配置多个值，不过一般情况下，你不自定义自己的 XML 标签和处理器的话，不需要配置这个值.
 handler-locations:
 # v2.2.0 新增的配置项，表示自定义的继承自 AbstractPredicateHandler 的子类的全路径名
 # 可以配置多个值，通常情况下，你也不需要配置这个值.
 predicate-handlers:
 # v2.7.0 新增的配置项，表示带前缀下划线转换时要移除的自定义前缀，多个值用英文逗号隔开，通常你不用配置这个值.
 underscore-transformer-prefix:

核心功能

阿里druid数据源配置

数据源的配置请参考druid-spring-boot-starter 官方文档

Macula Boot Starter MyBatis Plus

Mon, 01 Jan 0001 00:00:00 +0000

概览

该模块主要使用alibaba druid作为数据源工具，mybatis-plus作为数据库操作框架

组件坐标

<dependency>
 <groupId>dev.macula.boot</groupId>
 <artifactId>macula-boot-starter-mybatis-plus</artifactId>
 <version>${macula.version}</version>
</dependency>

使用配置

默认自动加载MyBatisPlusAutoConfiguration，已经开启了EnableTransactionManagement事务注解可配置属性：

macula:
 mybatis-plus:
 tenant-id: 1L  # 租户ID，默认1L
 tenant-suffixes: xxx  # 默认是tenant,TENANT
 tenant-enable: true												# 默认是true，开启多租户支持
 audit:
 create-by-name: createBy  # 创建人，默认createBy
 create-time-name: createTime  # 创建时间，默认createTime
 last-update-by-name: lastUpdateBy  # 最后更新人，默认lastUpdateBy
 last-update-time-name: lastUpdateTime  # 最后更新时间，默认lastUpdateTime

核心功能

阿里druid数据源配置

数据源的配置请参考druid-spring-boot-starter 官方文档

BaseEntity

默认提供了ID和审计字段，ID默认是自增长模式，如果数据库的默认字段不是标准的，请自行编写基础的Entity。同时记得在配置文件中设置审计字段的名称

@Getter
@Setter
public class BaseEntity implements Serializable {

 private static final long serialVersionUID = 1L;

 @JsonSerialize(using = ToStringSerializer.class)
 @Schema(description = "主键id")
 @TableId(value = "id", type = IdType.AUTO)
 private Long id;

 @Schema(description = "创建人")
 @TableField(fill = FieldFill.INSERT)
 private String createBy;

 @Schema(description = "创建时间")
 @TableField(fill = FieldFill.INSERT)
 private LocalDateTime createTime;

 @Schema(description = "更新人")
 @TableField(fill = FieldFill.INSERT_UPDATE)
 private String lastUpdateBy;

 @Schema(description = "更新时间")
 @TableField(fill = FieldFill.INSERT_UPDATE)
 private LocalDateTime lastUpdateTime;

}

主键策略

@TableId注解用于设置主键字段，通过IdType设置采用的主键策略，具体可以参考官方文档

Macula Boot Starter Redis

Mon, 01 Jan 0001 00:00:00 +0000

概览

该模块提供连接Redis的相关配置，使用了redisson库

组件坐标

<dependency>
 <groupId>dev.macula.boot</groupId>
 <artifactId>macula-boot-starter-redis</artifactId>
 <version>${macula.version}</version>
</dependency>

使用配置

使用时有两种方式配置，一种是spring-boot默认的配置形式，另一种是redisson的配置形式。如下所示：

spring:
 redis:
 database: 
 host:
 port:
 password:
 ssl: 
 timeout:
 cluster:
 nodes:
 sentinel:
 master:
 nodes:

redisson的配置方式如下，包括单点、主从、集群，下面是集群模式：

spring:
 redis:
 redisson: 
 file: classpath:redisson.yaml  # file和config选一个
 config: |
 clusterServersConfig:
 idleConnectionTimeout: 10000
 connectTimeout: 10000
 timeout: 3000
 retryAttempts: 3
 retryInterval: 1500
 failedSlaveReconnectionInterval: 3000
 failedSlaveCheckInterval: 60000
 password: null
 subscriptionsPerConnection: 5
 clientName: null
 loadBalancer: !<org.redisson.connection.balancer.RoundRobinLoadBalancer> {}
 subscriptionConnectionMinimumIdleSize: 1
 subscriptionConnectionPoolSize: 50
 slaveConnectionMinimumIdleSize: 24
 slaveConnectionPoolSize: 64
 masterConnectionMinimumIdleSize: 24
 masterConnectionPoolSize: 64
 readMode: "SLAVE"
 subscriptionMode: "SLAVE"
 nodeAddresses:
 - "redis://127.0.0.1:7004"
 - "redis://127.0.0.1:7001"
 - "redis://127.0.0.1:7000"
 scanInterval: 1000
 pingConnectionInterval: 0
 keepAlive: false
 tcpNoDelay: false
 threads: 16
 nettyThreads: 32
 codec: !<org.redisson.codec.Kryo5Codec> {}
 transportMode: "NIO"

核心功能

默认提供的Bean

RedissonClient
RedissonRxClient
RedissonReactiveClient
RedissonConnectionFactory
RedisTemplate
StringRedisTemplate
ReactiveRedisTemplate
ReactiveStringRedisTemplate

多Redis源的配置-Redisson方式

首先需要在配置文件中添加：

Macula Boot Starter Cache

Mon, 01 Jan 0001 00:00:00 +0000

概览

该模块提供两级缓存功能，第一级是本地缓存，使用Caffeine，第二级是Redis缓存，使用Redis。

组件坐标

<dependency>
 <groupId>dev.macula.boot</groupId>
 <artifactId>macula-boot-starter-cache</artifactId>
 <version>${macula.version}</version>
</dependency>

使用配置

spring:
 redis:
 host: localhost
 port: 6379
 cache:
 type: redis  # 必须指定是redis，否则使用系统默认的缓存
 # These properties are custom
 two-level:
 # Redis properties
 default-time-to-live: 86400000 # 所有缓存默认的过期时间，默认是24h
 time-to-live: # 指定某个缓存的过期时间，不配置使用default
 user-service: 86400000
 tag-service: 43200000
 use-key-prefix: true # 默认true，可以不用配置
 key-prefix: "macula:cache:" # 默认是macula:cache:，可以不用配置，建议加上appName
 topic: "macula:cache:two-level:topic" # 默认是macula:cache:two-level:topic，可以不用配置

 # Local Caffeine cache properties
 local:
 max-size: 2000 	 # 本地缓存的最大容量
 expiry-jitter: 50 	 # 本地缓存的过期时间偏移量

 # Resilience4j Circuit Breaker properties for Redis
 open-circuit-breaker: false 		 # 是否开启熔断器，以下都是默认值，可以不配置
 circuit-breaker:
 failure-rate-threshold: 25
 slow-call-rate-threshold: 25
 slow-call-duration-threshold: 250ms
 sliding-window-type: count_based
 permitted-number-of-calls-in-half-open-state: 20
 max-wait-duration-in-half-open-state: 5s
 sliding-window-size: 40
 minimum-number-of-calls: 10
 wait-duration-in-open-state: 2500ms

核心功能

读取缓存时优先从Caffeine读取，如果没有，则从Redis读取，并且将结果写入Caffeine
写入缓存时优先写入Redis，如果写入失败，则写入Caffeine
当写入或者删除缓存时，通过redis的pub/sub发布订阅机制通知其他实例清除本地缓存
默认已经开启了缓存注解功能，可以直接使用@Cacheable、@CacheConfig等注解
引入了CircuitBreaker，当redis访问出现问题的时候可以启用熔断

使用方式可以参考标准的Spring Cache文档

Macula Boot Starter RocketMQ

Mon, 01 Jan 0001 00:00:00 +0000

概览

该模块主要依赖阿里开源的RocketMQ。RocketMQ支持同步、异步发送消息，半事务消息等，具体可以参考官方文档。

组件坐标

<dependency>
 <groupId>dev.macula.boot</groupId>
 <artifactId>macula-boot-starter-rocketmq</artifactId>
 <version>${macula.version}</version>
</dependency>

使用配置

生产者配置建议

rocketmq:
 name-server: localhost:9876
 producer:
 namespace: ${spring.profiles.active} # 建议与环境保持一致${spring.profiles.active}
 group: ${spring.application.name}  # 建议采用${spring.application.name}
 sendMessageTimeout: 300000
 enableMsgTrace: true # 消息轨迹开启，根据需要来决定

demo:
 rocketmq:
 stringRequestTopic: stringRequestTopic:tagA

public class Test {
 @Resource
 private RocketMQTemplate rocketMQTemplate;
 @Value("${demo.rocketmq.stringRequestTopic}")
 private String stringRequestTopic; // 按照最佳实践，topic一个应用保持一个topic，topic:tag，通过tag区分业务

 SendResult sendResult = rocketMQTemplate.syncSend(stringRequestTopic, "hello world");
}

消费者配置建议

Push模式

Push的namespace、topic等都是配置在@RocketMQMessageListener注解里面的

Macula Boot Starter Kafka

Mon, 01 Jan 0001 00:00:00 +0000

概览

该模块依赖spring-kafka接入kafka服务。

组件坐标

<dependency>
 <groupId>dev.macula.boot</groupId>
 <artifactId>macula-boot-starter-kafka</artifactId>
 <version>${macula.version}</version>
</dependency>

使用配置

spring:
 kafka:
 bootstrap-servers: 197.168.25.196:9092 				# 指定kafka server的地址，集群配多个，中间，逗号隔开
 producer:
 batch-size: 1000																		# 批量发送的消息数量
 buffer-memory: 33554432															# 32MB的批处理缓冲区
 retries: 3																					# 重试次数 
 consumer:
 group-id: crm-user-service													# 默认消费者组
 auto-offset-reset: earliest													# 最早未被消费的offset
 max-poll-records: 4000															# 批量一次最大拉取数据量
 enable-auto-commit: true														# 是否自动提交
 auto-commit-interval: 1000													# 自动提交时间间隔，单位ms

核心功能

发送数据

@RunWith(SpringRunner.class)
@SpringBootTest
public class KafkaProducerTest {

 @Autowired
 private KafkaTemplate<String, String> kafkaTemplate;

 @Test
 public void testSend(){
 for (int i = 0; i < 5000; i++) {
 Map<String, Object> map = new LinkedHashMap<>();
 map.put("datekey", 20210610);
 map.put("userid", i);
 map.put("salaryAmount", i);
 //向kafka的big_data_topic主题推送数据
 kafkaTemplate.send("big_data_topic", JSONObject.toJSONString(map));
 }
 }
}

消费数据

@Component
public class BigDataTopicListener {

 private static final Logger log = LoggerFactory.getLogger(BigDataTopicListener.class);

 /**
 * 监听kafka数据
 * @param consumerRecords
 * @param ack
 */
 @KafkaListener(topics = {"big_data_topic"})
 public void consumer(ConsumerRecord<?, ?> consumerRecord) {
 log.info("收到bigData推送的数据'{}'", consumerRecord.toString());
 //...
 //db.save(consumerRecord);//插入或者更新数据
 }
}

批量消费模式

增加如下配置：

Macula Boot Starter Crypto

Mon, 01 Jan 0001 00:00:00 +0000

概览

该模块提供数据加解密的能力。

组件坐标

<dependency>
 <groupId>dev.macula.boot</groupId>
 <artifactId>macula-boot-starter-crypto</artifactId>
 <version>${macula.version}</version>
</dependency>

使用配置

macula:
 crypto:
 enabled: true # 默认为true
 algorithm: AES  # BASE64, AES, RSA, SM2, SM4 
 encode: HEX  # BASE64, HEX
 password: xxx  # 对称加密的密钥
 publicKey: xxx  # 非对称加密公钥
 privateKey: xxx # 非对称解密私钥

核心功能

配置文件加密

配置文件加密只支持AES（AES/ECB/PKCS5Padding）方式加密，密钥只能通过命令行的方式设置

在启动的时候加入密钥
--macula.crypto.key=password

注意：配置文件的密文属性需要以 “mpw:” 开头，例如：

test:
 encrypt: mpw:Or0wNwIcctnekUyDfeN8cw==

MyBatis的数据库字段加密

配合以下注解使用

@Documented
@Inherited
@Target({ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface CryptoField {

 /**
 * 加密算法
 */
 AlgorithmType algorithm() default AlgorithmType.DEFAULT;

 /**
 * 秘钥。AES、SM4需要
 */
 String password() default "";

 /**
 * 公钥。RSA、SM2需要
 */
 String publicKey() default "";

 /**
 * 公钥。RSA、SM2需要
 */
 String privateKey() default "";

 /**
 * 编码方式。对加密算法为BASE64的不起作用
 */
 EncodeType encode() default EncodeType.DEFAULT;

}

举个栗子

定义一个java bean, 在 userName 上添加该注解

Macula Boot Starter Security

Mon, 01 Jan 0001 00:00:00 +0000

概览

该模块为安全模块，以资源服务器的角色和网关交互。

资源服务器的安全依赖，支持对JWT的验证，不依赖任何认证服务器
内部REST服务依赖该模块，通过JWT来获取用户信息；
网关或者直接对外的REST服务通过OpaqueToken验证登陆信息
该模块只是验证用户，没有处理权限信息。Token验证后的角色信息是有的。通常情况下，网关使用OpaqueToken，然后获取用户角色，验证是否通过权限校验，生成JWT给后续的微服务识别身份

组件坐标

<dependency>
 <groupId>dev.macula.boot</groupId>
 <artifactId>macula-boot-starter-security</artifactId>
 <version>${macula.version}</version>
</dependency>

使用配置

spring:
	security:
 oauth2:
 resourceserver:
 jwt:
 jwk-set-uri: http://127.0.0.1:9000/oauth2/jwks 			# JWT KEY的URL，这里是网关提供
macula:
 security:
 ignore-urls:																							# 忽略权限的列表
 - /api/token
 - /api/token/**
 - /swagger-ui/index.html
 - /v3/api-docs/swagger-config

核心功能

SecurityUtils

/**
 * {@code SecurityUtils} 安全助手
 *
 * @author rain
 * @since 2022/7/25 15:16
 */
public class SecurityUtils {

 public static String getCurrentUser() {
 if (SecurityContextHolder.getContext() != null && SecurityContextHolder.getContext()
 .getAuthentication() != null && SecurityContextHolder.getContext().getAuthentication().isAuthenticated()) {
 return SecurityContextHolder.getContext().getAuthentication().getName();
 }
 return null;
 }

 /**
 * 获取用户昵称/姓名
 *
 * @return nickname
 */
 public static String getNickname() {
 return Convert.toStr(getTokenAttributes().get(SecurityConstants.JWT_NICKNAME_KEY));
 }

 /**
 * 获取用户角色
 *
 * @return 角色Code集合
 */
 public static Set<String> getRoles() {
 Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
 if (authentication != null && CollectionUtil.isNotEmpty(authentication.getAuthorities())) {
 return authentication.getAuthorities().stream()
 .map(item -> StrUtil.removePrefix(item.getAuthority(), "ROLE_")).collect(Collectors.toSet());
 }
 return Collections.emptySet();
 }

 /**
 * 获取部门ID
 *
 * @return deptId
 */
 public static Long getDeptId() {
 return Convert.toLong(getTokenAttributes().get(SecurityConstants.JWT_DEPTID_KEY));
 }

 /**
 * 获取数据权限
 *
 * @return DataScope
 */
 public static Integer getDataScope() {
 return Convert.toInt(getTokenAttributes().get(SecurityConstants.JWT_DATASCOPE_KEY));
 }

 /**
 * 获取当前租户ID
 *
 * @return 租户ID
 */
 public static Long getTenantId() {
 return Convert.toLong(getTokenAttributes().get(GlobalConstants.TENANT_ID_NAME));
 }

 public static String getTokenId() {
 if (SecurityContextHolder.getContext() != null && SecurityContextHolder.getContext()
 .getAuthentication() instanceof JwtAuthenticationToken) {
 JwtAuthenticationToken token =
 (JwtAuthenticationToken)SecurityContextHolder.getContext().getAuthentication();
 if (token != null && token.getToken() != null) {
 return token.getToken().getId();
 }
 }
 return null;
 }

 /**
 * 判断用户是否为超级管理员
 *
 * @return true/false
 */
 public static boolean isRoot() {
 return getRoles().contains(SecurityConstants.ROOT_ROLE_CODE);
 }

 public static Map<String, Object> getTokenAttributes() {
 Authentication authentication = SecurityContextHolder.getContext().getAuthentication();
 if (authentication != null) {
 if (authentication instanceof AbstractOAuth2TokenAuthenticationToken) {
 AbstractOAuth2TokenAuthenticationToken<?> tokenAuthenticationToken =
 (AbstractOAuth2TokenAuthenticationToken<?>)authentication;
 return tokenAuthenticationToken.getTokenAttributes();
 }
 }
 return Collections.emptyMap();
 }
}

鉴权支持

URL鉴权是在gateway实现的，本模块不支持URL鉴权
方法级别的注解鉴权：默认已经解锁 @PreAuthorize 和 @PostAuthorize 两个注解。

内部接口注解@Inner

默认情况下依赖了本模块的接口都要有token才能访问，对于一些内部接口，比如定时任务调用的接口，没有经过网关，没有token，这个时候你可以在你的Controller上的方法上加上@Inner注解。调用方需要设置请求header为from=Y

Macula Boot Starter SpringDoc

Mon, 01 Jan 0001 00:00:00 +0000

概览

该模块是基于SpringDoc的OpenAPI V3规范的API接口文档生成工具。

组件坐标

<dependency>
 <groupId>dev.macula.boot</groupId>
 <artifactId>macula-boot-starter-springdoc</artifactId>
 <version>${macula.version}</version>
</dependency>

使用配置

springdoc:
 api-docs:
 enabled: true # 默认是true，用于开关API文档
 swagger-ui:
 enabled: false # 默认是true，用于开关API UI

核心功能

示例

/**
 * 部门控制器
 *
 * @author haoxr
 * @since 2020/11/6
 */
@Tag(name = "部门接口", description = "部门接口")
@RestController
@RequestMapping("/api/v1/dept")
@RequiredArgsConstructor
public class SysDeptController {

 private final SysDeptService deptService;

 @Operation(summary = "获取部门列表")
 @GetMapping
 public List<DeptVO> listDepartments(DeptQuery queryParams) {
 List<DeptVO> list = deptService.listDepartments(queryParams);
 return list;
 }

 @Operation(summary = "获取部门下拉选项")
 @GetMapping("/options")
 public List<Option> listDeptOptions() {
 List<Option> list = deptService.listDeptOptions();
 return list;
 }

 @Operation(summary = "获取部门详情")
 @Parameter(name = "部门ID")
 @GetMapping("/{deptId}/form")
 public DeptForm getDeptForm(@PathVariable Long deptId) {
 DeptForm deptForm = deptService.getDeptForm(deptId);
 return deptForm;
 }

 @Operation(summary = "新增部门")
 @AuditLog(title = "新增部门")
 @PostMapping
 public Long saveDept(@Valid @RequestBody DeptForm formData) {
 Long id = deptService.saveDept(formData);
 return id;
 }

 @Operation(summary = "修改部门")
 @AuditLog(title = "修改部门")
 @PutMapping(value = "/{deptId}")
 public Long updateDept(@PathVariable Long deptId, @Valid @RequestBody DeptForm formData) {
 deptId = deptService.updateDept(deptId, formData);
 return deptId;
 }

 @Operation(summary = "删除部门")
 @AuditLog(title = "删除部门")
 @Parameter(name = "部门ID，多个以英文逗号(,)分割")
 @DeleteMapping("/{ids}")
 public boolean deleteDepartments(@PathVariable("ids") String ids) {
 boolean result = deptService.deleteByIds(ids);
 return result;
 }
}


@Schema(description = "部门表单对象")
@Data
public class DeptForm {

 @Schema(description = "部门名称")
 private String name;

 @Schema(description = "父部门ID")
 @NotNull(message = "父部门ID不能为空")
 private Long parentId;

 @Schema(description = "状态")
 private Integer status;

 @Schema(description = "排序")
 private Integer sort;
}

官方文档

Swagger UI： http://xxx/context-path/swagger-ui/index.html
API Docs： http://xxx/context-path/v3/api-docs