maven常用依赖

常用依赖

    <!-- ========== SpringCloud Alibaba微服务核心依赖 ========== -->
    <!-- SpringCloud Alibaba Nacos 服务注册与发现依赖
    作用：1. 整合Nacos注册中心，当前微服务启动后自动注册到Nacos服务端；
         2. 基于SpringCloud Discovery规范，支持@EnableDiscoveryClient注解，实现服务提供者注册、内置负载均衡,消费者通过服务名远程调用（Feign/Nacos负载均衡）；
         3. 替代Eureka、Consul，完成微服务集群的服务列表管理、健康检测、自动上下线剔除故障实例；
    配套：必须配置spring.cloud.nacos.discovery.server-addr=Nacos地址，开启注册中心连接
    -->
    <dependency>
        <groupId>com.alibaba.cloud</groupId>
        <artifactId>spring-cloud-starter-alibaba-nacos-discovery</artifactId>
    </dependency>

    <!-- SpringCloud Alibaba Nacos Config 分布式配置中心依赖
    作用：1. 接入Nacos配置中心，项目yml/properties配置文件托管在Nacos服务端，无需打包修改配置；
         2. 支持配置动态刷新：Nacos后台改配置，项目无需重启实时生效(@RefreshScope)；
         3. 支持环境隔离（dev/test/prod）、多环境配置共享、配置灰度发布；
    注意：
      配置优先级（从高 → 低）
      │
      ├─ 1. JVM 启动参数(xxx)
      ├─ 2. OS 系统环境变量
      ├─ 3. Nacos 远程配置（@RefreshScope 动态刷新）
      │   ├─ {app}-{profile}.yml > {app}-{profile}.properties
      │   ├─ {app}.yml > {app}.properties
      │   ├─ ext-config[]        ← 数组越靠后优先级越高
      │   └─ shared-config[]      ← 数组越靠后优先级越高
      ├─ 4. 本地 bootstrap 系列（bootstrap context 先加载）
      │   ├─ bootstrap-{profile}.yml > bootstrap-{profile}.properties
      │   ├─ bootstrap.yml >  bootstrap.properties
      └─ 5. 本地 application 系列（application context 后加载，子上下文）
          ├─ application-{profile}.yml > application-{profile}.properties
          ├─ application.yml > application.properties
    -->
    <dependency>
        <groupId>com.alibaba.cloud</groupId>
        <artifactId>spring-cloud-starter-alibaba-nacos-config</artifactId>
    </dependency>

    <!-- SpringCloud Alibaba Sentinel 流量防卫组件依赖（熔断、限流、降级、系统保护）
    作用：1. 微服务容错：接口突发流量过大时限流，下游服务故障时熔断降级，避免雪崩效应；
         2. 支持代码注解(@SentinelResource)、Nacos动态配置流控规则、Sentinel可视化控制台管控；
         3. 替代Hystrix，阿里官方SpringCloud默认容错组件，适配Alibaba生态；
    配套：配置spring.cloud.sentinel.transport.dashboard=Sentinel控制台地址，可视化查看监控与配置规则 
    -->
    <dependency>
        <groupId>com.alibaba.cloud</groupId>
        <artifactId>spring-cloud-starter-alibaba-sentinel</artifactId>
    </dependency>

    <!-- ========== SpringBoot内置监控、接口文档、数据库相关依赖 ========== -->
    <!-- SpringBoot Actuator 项目健康监控依赖
    作用：1. 暴露内置监控端点(/actuator/health、/actuator/info、/actuator/metrics等)，监控服务运行状态、内存、线程、磁盘、数据库连接；
         2. Nacos注册中心依赖Actuator健康检查，根据health端点状态判断服务是否在线；
         3. 配合Prometheus/Grafana做运维监控告警，Sentinel、SpringAdmin均依赖该组件采集服务指标；
    配置：默认只开放health端点，生产按需开启env、beans等端点 
    -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-actuator</artifactId>
    </dependency>

    <!-- Swagger UI 前端页面依赖（API在线文档可视化页面）
    作用：1. 提供swagger前端访问页面，展示后端Controller接口入参、出参、注解说明0；
         2. 支持在线调试接口，直接在页面发起GET/POST请求测试；
         3.地址：
         		Knife4j 地址（官方默认）：http://192.168.110.1:9203/doc.html
            SpringDoc 新版 swagger 路径：http://192.168.110.1:9203/swagger-ui/index.html
            原生 springfox 老地址：/swagger-ui.html（仅老版本生效）
    -->
    <dependency>
        <groupId>io.springfox</groupId>
        <artifactId>springfox-swagger-ui</artifactId>
        <version>${swagger.fox.version}</version>
    </dependency>

    <!-- Mysql Connector-Java MySQL8/5.x驱动包
    作用：JDBC标准驱动，Java程序和MySQL数据库建立连接必备依赖；
    备注：mysql8.0+推荐使用com.mysql.cj.jdbc.Driver驱动类，5.x使用com.mysql.jdbc.Driver；
          被ruoyi数据源框架自动加载，配合yml的spring.datasource配置实现数据库连接 -->
    <dependency>
        <groupId>mysql</groupId>
        <artifactId>mysql-connector-java</artifactId>
    </dependency>

    <!-- PostgreSQL数据库驱动（注释状态，启用即适配PG数据库）
    作用：PostgreSQL关系型数据库JDBC驱动，切换数据库时打开注释即可 -->
<!--    <dependency>-->
<!--        <groupId>org.postgresql</groupId>-->
<!--        <artifactId>postgresql</artifactId>-->
<!--    </dependency>-->

 

 
 

    <!-- ========== 第三方工具类、业务组件依赖 ========== -->
    <!-- Hutool-all 国产全能Java工具类库(5.6.3版本)
    作用：封装常用工具方法，避免重复造轮子：
          字符串、日期、加密、IO、文件、验证码、URL、反射、集合、缓存等工具；
          RuoYi框架大量使用Hutool简化代码开发 
    -->
    <dependency>
        <groupId>cn.hutool</groupId>
        <artifactId>hutool-all</artifactId>
        <version>5.6.3</version>
    </dependency>

    <!-- ZXing Core 谷歌开源二维码生成解析核心包
    作用：1. 二维码、条形码生成与图片解析；
         2. 业务场景：系统登录二维码、单据条码生成；仅核心算法，无图片渲染，配合IO工具生成图片 
    -->
    <dependency>
        <groupId>com.google.zxing</groupId>
        <artifactId>core</artifactId>
        <version>3.3.3</version>
    </dependency>

    <!-- Activiti7 SpringBoot启动器：工作流引擎核心依赖（流程审批引擎）
    作用：1. BPMN工作流引擎，支持流程图定义、流程发起、审批流转、任务节点管理；
         2. 内置自动建表（activiti_*系列数据表），整合Spring事务；
    排除说明：exclusion剔除原生mybatis，避免和RuoYi自带Mybatis-Plus冲突，防止包版本冲突报错 -->
    <dependency>
        <groupId>org.activiti</groupId>
        <artifactId>activiti-spring-boot-starter</artifactId>
        <version>7.0.0.GA</version>
        <exclusions>
            <exclusion>
                <artifactId>mybatis</artifactId>
                <groupId>org.mybatis</groupId>
            </exclusion>
        </exclusions>
    </dependency>

    <!-- Activiti流程图生成工具包：BPMN流程图高清图片生成
    作用：根据数据库中流程定义数据，动态生成PNG流程图（审批页面查看流程进度图）；
    排除说明：剔除冲突的bpmn-model依赖，和上方activiti7依赖包版本冲突，防止类重复加载异常；
    注意：版本5.22.0和activiti7主包版本不一致是官方常规搭配，专门用于流程图渲染 -->
    <dependency>
        <groupId>org.activiti</groupId>
        <artifactId>activiti-image-generator</artifactId>
        <version>5.22.0</version>
        <exclusions>
            <exclusion>
                <artifactId>activiti-bpmn-model</artifactId>
                <groupId>org.activiti</groupId>
            </exclusion>
        </exclusions>
    </dependency>

    <!-- 
    SpringBoot单元测试依赖 scope=test：仅测试环境生效，打包不打入生产包
    作用：提供JUnit5、MockMvc、Mockito等单元测试能力，编写Controller、Service单元测试、集成测试；
    scope=test：编译、测试阶段有效，项目打包部署时不会被引入依赖
    -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
    
    
    <!-- lombok：代码简化插件
       @Data 自动生成：getter()、setter()、toString()、equals()、hashCode()
       @NoArgsConstructor 生成无参构造函数；Mybatis 反射实例化实体必须有无参构造，RuoYi 数据库实体必备。
       @AllArgsConstructor 生成全参构造函数；用于对象快速赋值，构造注入使用。	
       @Builder 建造者模式，链式赋值：User.builder().name("xxx").age(18).build()；多用于 VO 组装、参数构建。
    -->
    <dependency>
        <groupId>org.projectlombok</groupId>
        <artifactId>lombok</artifactId>
    </dependency>

Swagger

常用注解

Swagger2 全套常用注解详细教程（文章版、带完整代码实例）

本文适配 Ruoyi 框架（SpringBoot2 + Knife4j/Swagger2），按类注解、方法注解、参数注解、实体注解分类讲解，所有注解均附带属性说明、使用场景和可直接运行的代码示例，是项目开发中最实用的 Swagger 注解手册。

一、Controller 类级别注解

1. @Api

作用：标记整个控制器类，用于在接口文档中对当前模块进行分组命名，文档左侧菜单栏会展示该名称，统一归类当前类下所有接口。

核心属性：tags，用于填写模块中文名称，必填。

代码实例：

@RestController
@RequestMapping("/system/user")
@Api(tags = "用户管理模块")
public class SysUserController {
    // 当前类下所有接口都会归到【用户管理模块】分组中
}

2. @ApiIgnore

作用：作用于类或方法，被标记的类/接口会被 Swagger 忽略，不会生成在接口文档中，适用于内部接口、测试接口、保密接口。

核心属性：无属性，直接使用即可。

代码实例：

// 该接口不会展示在Swagger文档中
@ApiIgnore
@GetMapping("/inner/queryData")
public AjaxResult queryInnerData() {
    return AjaxResult.success("内部数据");
}

二、接口方法级别注解（核心常用）

1. @ApiOperation

作用：对单个接口方法进行描述，定义接口名称和详细业务说明，是每个接口必备注解。

核心属性：value 为接口简短名称；notes 为接口详细备注、业务场景说明。

代码实例：

@GetMapping("/list")
@ApiOperation(value = "分页查询用户列表", notes = "支持用户名、用户状态、创建时间筛选，默认分页查询")
public AjaxResult list(SysUser user) {
    return AjaxResult.success();
}

2. @ApiImplicitParams + @ApiImplicitParam

作用：专门用于描述 URL 普通参数、路径参数（GET 请求、REST 路径变量），无法用于 JSON 请求体参数。@ApiImplicitParams 为容器注解，用于包裹多个 @ApiImplicitParam。

核心属性：name 为参数名；value 为参数说明；paramType 为传参位置；required 为是否必填；example 为参数示例值。

paramType 常用取值：path（路径参数 /{id}）、query（地址栏 ? 拼接参数）、header（请求头参数）。

代码实例：

@GetMapping("/detail/{userId}")
@ApiOperation("根据用户ID查询用户详情")
@ApiImplicitParams({
    @ApiImplicitParam(name = "userId", value = "用户主键ID", paramType = "path", required = true, example = "1001")
})
public AjaxResult getInfo(@PathVariable Long userId) {
    return AjaxResult.success();
}

3. @ApiResponses + @ApiResponse

作用：自定义接口返回状态码的含义，补充系统默认没有的状态码说明，方便前端对接查看报错场景。

核心属性：code 为 HTTP 状态码；message 为状态码对应的中文描述。

代码实例：

@PostMapping("/add")
@ApiOperation("新增系统用户")
@ApiResponses({
    @ApiResponse(code = 200, message = "操作成功"),
    @ApiResponse(code = 400, message = "参数校验失败"),
    @ApiResponse(code = 500, message = "服务器内部异常")
})
public AjaxResult add(@RequestBody SysUser user) {
    return AjaxResult.success();
}

4. @ApiParam

作用：直接修饰方法入参，主要用于标注 @RequestBody、@RequestParam 接收的参数，简单描述参数用途和必填状态。

核心属性：value 为参数说明；required 为是否必填。

代码实例：

@PostMapping("/edit")
@ApiOperation("修改用户信息")
public AjaxResult edit(@ApiParam(value = "用户表单提交参数", required = true) @RequestBody SysUser user) {
    return AjaxResult.success();
}

三、实体类 & 字段注解（DTO/POJO专用）

1. @ApiModel

作用：作用于实体类、DTO 参数类，用于描述整个实体的用途和名称，在接口文档中展示实体整体说明。

核心属性：value 为实体名称；description 为实体详细用途说明。

2. @ApiModelProperty

作用：作用于实体字段，描述字段含义、是否必填、示例值，用于接口入参和返回参数字段说明，是最常用的实体注解。

核心属性：value 为字段注释；required 为是否必填；example 为字段示例数据。

完整实体代码实例：

@ApiModel(value = "SysUser", description = "系统用户新增/修改入参实体")
public class SysUser {

    @ApiModelProperty(value = "用户主键ID", required = true, example = "1001")
    private Long userId;

    @ApiModelProperty(value = "用户登录账号", required = true, example = "admin")
    private String userName;

    @ApiModelProperty(value = "用户状态：0正常 1禁用", example = "0")
    private String status;

    @ApiModelProperty(value = "用户手机号", example = "13800138000")
    private String phonenumber;
    
    // getter、setter 省略
}

五、完整可直接运行的 Controller 示例（整合所有常用注解）

@RestController
@RequestMapping("/demo/user")
@Api(tags = "测试-用户接口模块")
public class DemoUserController {

    @GetMapping("/{id}")
    @ApiOperation(value = "根据ID查询用户详情", notes = "通过用户主键查询单条完整用户数据")
    @ApiImplicitParams({
            @ApiImplicitParam(name = "id", value = "用户编号", paramType = "path", required = true, example = "1001")
    })
    @ApiResponses({
            @ApiResponse(code = 200, message = "查询成功"),
            @ApiResponse(code = 404, message = "用户信息不存在")
    })
    public AjaxResult getUserDetail(@PathVariable Long id) {
        return AjaxResult.success("查询成功");
    }

    @PostMapping("/save")
    @ApiOperation(value = "新增用户信息", notes = "提交用户表单数据，新增系统用户")
    public AjaxResult saveUser(@ApiParam(value = "用户新增参数", required = true) @RequestBody SysUser user) {
        return AjaxResult.success("新增成功");
    }
}