java中定时方案各式各样，今天来讲述下 xxl-job 的部署与应用




## 概念

XXL-JOB是一个分布式任务调度平台，其核心设计目标是开发迅速、学习简单、轻量级、易扩展。现已开放源代码并接入多家公司线上产品线，开箱即用。

## 特点

参考网站  https://www.xuxueli.com/xxl-job/

## 部署

### 初始化数据库

请下载项目源码并解压，获取 “调度数据库初始化SQL脚本” 并执行即可。

“调度数据库初始化SQL脚本” 位置为:

```sh
/xxl-job/doc/db/tables_xxl_job.sql
```


![image.png](https://blog.liushigong.cn/static/img/7ff83dff04526dd19c28601d3f64f9a2.image.webp)


调度中心支持集群部署，集群情况下各节点务必连接同一个mysql实例;

如果mysql做主从,调度中心集群节点务必强制走主库;


### 编译源码

解压源码,按照maven格式将源码导入IDE, 使用maven进行编译即可，源码结构如下：

```text
xxl-job-admin：调度中心
xxl-job-core：公共依赖
xxl-job-executor-samples：执行器Sample示例（选择合适的版本执行器，可直接使用，也可以参考其并将现有项目改造成执行器）
   ：xxl-job-executor-sample-springboot：Springboot版本，通过Springboot管理执行器，推荐这种方式；
   ：xxl-job-executor-sample-frameless：无框架版本；
```

### 配置部署“调度中心”

调度中心项目：xxl-job-admin

作用：统一管理任务调度平台上调度任务，负责触发调度执行，并且提供任务管理平台。

调度中心配置文件地址：

 ```sh
 /xxl-job/xxl-job-admin/src/main/resources/application.properties
 ```

 调度中心配置内容说明：

 ```properties
 ### web
 server.port=8080
 server.servlet.context-path=/xxl-job-admin

 ### actuator
 management.server.servlet.context-path=/actuator
 management.health.mail.enabled=false

 ### resources
 spring.mvc.servlet.load-on-startup=0
 spring.mvc.static-path-pattern=/static/**
 spring.resources.static-locations=classpath:/static/

 ### freemarker
 spring.freemarker.templateLoaderPath=classpath:/templates/
 spring.freemarker.suffix=.ftl
 spring.freemarker.charset=UTF-8
 spring.freemarker.request-context-attribute=request
 spring.freemarker.settings.number_format=0.##########

 ### mybatis
 mybatis.mapper-locations=classpath:/mybatis-mapper/*Mapper.xml
 #mybatis.type-aliases-package=com.xxl.job.admin.core.model

 ### xxl-job, datasource
 spring.datasource.url=jdbc:mysql://127.0.0.1:3306/xxl_job?useUnicode=true&characterEncoding=UTF-8&autoReconnect=true&serverTimezone=Asia/Shanghai
 spring.datasource.username=root
 spring.datasource.password=root
 spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver

 ### datasource-pool
 spring.datasource.type=com.zaxxer.hikari.HikariDataSource
 spring.datasource.hikari.minimum-idle=10
 spring.datasource.hikari.maximum-pool-size=30
 spring.datasource.hikari.auto-commit=true
 spring.datasource.hikari.idle-timeout=30000
 spring.datasource.hikari.pool-name=HikariCP
 spring.datasource.hikari.max-lifetime=900000
 spring.datasource.hikari.connection-timeout=10000
 spring.datasource.hikari.connection-test-query=SELECT 1
 spring.datasource.hikari.validation-timeout=1000

 ### xxl-job, email
 spring.mail.host=smtp.qq.com
 spring.mail.port=25
 spring.mail.username=xxx@qq.com
 spring.mail.from=xxx@qq.com
 #授权码
 spring.mail.password=xxx
 spring.mail.properties.mail.smtp.auth=true
 spring.mail.properties.mail.smtp.starttls.enable=true
 spring.mail.properties.mail.smtp.starttls.required=true
 spring.mail.properties.mail.smtp.socketFactory.class=javax.net.ssl.SSLSocketFactory

 ### xxl-job, access token  调度器和执行器通信用的
 xxl.job.accessToken=

 ### xxl-job, i18n (default is zh_CN, and you can choose "zh_CN", "zh_TC" and "en")
 xxl.job.i18n=zh_CN

 ## xxl-job, triggerpool max size
 xxl.job.triggerpool.fast.max=200
 xxl.job.triggerpool.slow.max=100

 ### xxl-job, log retention days
 xxl.job.logretentiondays=30

 ```
 
**部署项目：**

 nohup java -jar  xxl-job-admin-2.3.0.jar &

 如果已经正确进行上述配置，可将项目编译打包部署。

 调度中心访问地址：http://localhost:8080/xxl-job-admin (该地址执行器将会使用到，作为回调地址)

 默认登录账号 “admin/123456”, 登录后运行界面如下图所示。


![image.png](https://blog.liushigong.cn/static/img/63ec1f180eea9ae5ff6d471545099ee2.image.webp)


### 项目整合

引入依赖

```xml
 <dependency>
       <groupId>com.xuxueli</groupId>
       <artifactId>xxl-job-core</artifactId>
       <version>2.2.0</version>
   </dependency>
```

### 增加配置

xxl 属性配置文件

```properties
### xxl-job executor appname
xxl.job.executor.appname=msb-item
### xxl-job executor registry-address: default use address to registry , otherwise use ip:port if address is null
###执行器注册 [选填]：优先使用该配置作为注册地址，为空时使用内嵌服务 ”IP:PORT“ 作为注册地址。从而更灵活的支持容器类型执行器动态IP和动态映射端口问题。
xxl.job.executor.address=
### xxl-job executor server-info
### 执行器IP [选填]：默认为空表示自动获取IP，多网卡时可手动设置指定IP，该IP不会绑定Host仅作为通讯实用；地址信息用于 "执行器注册" 和 "调度中心请求并触发任务"；
xxl.job.executor.ip=
xxl.job.executor.port=9001
### xxl-job executor log-path
xxl.job.executor.logpath=D://logs
### xxl-job executor log-retention-days
xxl.job.executor.logretentiondays=30
```

客户端注入配置

```java
@Configuration
public class XxlJobConfig {
   private Logger logger = LoggerFactory.getLogger(XxlJobConfig.class);

   @Value("${xxl.job.admin.addresses}")
   private String adminAddresses;

   @Value("${xxl.job.executor.appname}")
   private String appname;

   @Value("${xxl.job.executor.address}")
   private String address;

   @Value("${xxl.job.executor.ip}")
   private String ip;

   @Value("${xxl.job.executor.port}")
   private int port;

   @Value("${xxl.job.executor.logpath}")
   private String logPath;

   @Value("${xxl.job.executor.logretentiondays}")
   private int logRetentionDays;


   @Bean
   public XxlJobSpringExecutor xxlJobExecutor() {
       logger.info(">>>>>>>>>>> xxl-job config init.");
       XxlJobSpringExecutor xxlJobSpringExecutor = new XxlJobSpringExecutor();
       xxlJobSpringExecutor.setAdminAddresses(adminAddresses);
       xxlJobSpringExecutor.setAppname(appname);
       xxlJobSpringExecutor.setAddress(address);
       xxlJobSpringExecutor.setIp(ip);
       xxlJobSpringExecutor.setPort(port);
       xxlJobSpringExecutor.setLogPath(logPath);
       xxlJobSpringExecutor.setLogRetentionDays(logRetentionDays);

       return xxlJobSpringExecutor;
   }
}
```

修改代码

```java
@Component
public class ItemScanJobHandler {
   @Autowired
   ItemScanSchedule itemScanSchedule;


   @XxlJob("itemScanJobHandler")
   public ReturnT<String> itemScanJobHandler(String param) throws Exception {
       itemScanSchedule.scanItems();
       return ReturnT.SUCCESS;
   }
}
```

### 创建执行器

![image.png](https://blog.liushigong.cn/static/img/964d905dfac29f74c940e695934f2043.image.webp)


### 新增定时任务

![image.png](https://blog.liushigong.cn/static/img/2f5aa3cefbdf0748830bdd8030fbe6f3.image.webp)

运维工具 - 分布式任务调度平台 XXL-job

今天来讲一款高颜值与硬实力的完美融合的一站式服务器运维解决方案 Orion Visor，让运维管理轻松高效



## 什么是 orion-visor？

orion-visor 是一款高颜值、现代化的自动化运维及轻量堡垒机平台，提供全面的服务器智能运维解决方案。作为 Dromara 开源社区 旗下的成员项目，它致力于为企业提供一体化、安全可靠的运维管理体验，支持资产管理分组、多协议访问、文件管理、批量操作等核心功能。

项目地址：https://gitee.com/dromara/orion-visor

官网地址：https://visor.orionsec.cn/

orion-visor 采用现代化的 UI 设计和简洁的操作流程，不仅吸引技术新手快速上手，更能满足资深运维工程师的专业需求，真正做到 "开箱即用"。

![image.png](/static/img/20e4cbf9977f0a28fcef4182a99509cd.image.webp)

## 核心功能特性

### 全面的资产管理

- 统一管理：支持对资产进行分组，实现对主机、密钥和身份的统一管理和授权

- 灵活授权：权限管理清晰可控，分布式资产尽在掌握

- 多级分组：支持树形结构的资产管理，可按部门、项目、环境等进行多级主机分组

### 多协议在线终端

- orion-visor 提供功能完备的 Web 终端，支持多种访问协议：

- SSH 终端：支持语法高亮与 20+ 主题切换，命令自动补全与历史记录

- RDP 远程桌面：支持 Windows 服务器全屏控制，剪贴板双向同步

- VNC 连接：适用于远程图形化桌面访问

- SFTP 文件管理：拖拽上传/下载文件，在线编辑文本文件

### 高效的批量操作

- 批量命令执行：同时在多台主机上执行命令，并聚合显示结果，效率提升 N 倍（N=服务器数量）

- 多主机文件分发：支持多主机同时传输，断点续传，传输进度实时显示

- 实时结果聚合：直观查看批量操作的执行结果和状态

### 智能的计划任务

基于 cron 表达式 的任务调度系统，支持：

- 可视化任务管理：通过图形化界面配置定时任务

- 执行日志记录：完整记录任务执行过程和结果

- 灵活调度：支持各种复杂的时间调度策略

### 完善的系统监控

- 主机监控：支持对主机 CPU、内存、磁盘、网络等系统指标的监控和告警

- 实时监控：实时掌握系统运行状态和性能指标

- 智能告警：及时发现问题并通知相关人员

### 企业级安全审计

- 操作审计：完整记录所有操作日志，包含时间、用户、主机等信息

- 会话录像：终端会话录像可回放，满足等保合规要求

- 权限控制：实现细粒度的 RBAC 权限控制

- 敏感操作保护：敏感操作支持二次认证

## 快速开始

一键部署步骤

```bash
# 克隆代码仓库
git clone --depth=1 https://gitee.com/dromara/orion-visor

# 进入仓库目录
cd orion-visor

# 拉取远程镜像
docker compose pull
```

创建配置

```bash
# 创建名为 .env 的 .env.example 副本, 将其中的值删除以保持默认或将其修改为合适的的值
cp .env.example .env
```

修改配置

```text
# VOLUME_BASE             你希望数据持久化保存的目录, 如果不提前创建将以 docker 进程宿主身份创建 (通常是 root)

# SERVICE_PORT            你希望服务监听的端口
# SPRING_PROFILES_ACTIVE  后端启动的环境

# DEMO_MODE               演示模式

# API_CORS                是否允许跨域
# API_IP_HEADERS          获取 IP 的请求头
# API_EXPOSE_TOKEN        对外服务 token
# SECRET_KEY              加密密钥

# NGINX_SERVICE_HOST      nginx 服务所在的主机
# NGINX_SERVICE_PORT      nginx 服务监听的端口

# MYSQL_HOST              mysql 服务所在的主机, 如果你没有现有的 MySQL 请保持值为 mysql, 如果你有自部署的请在 docker-compose.yaml 中移除 services.mysql 以节约性能
# MYSQL_PORT              mysql 监听的端口
# MYSQL_DATABASE          mysql 数据库
# MYSQL_USER              mysql 用户名
# MYSQL_PASSWORD          mysql 用户密码
# MYSQL_ROOT_PASSWORD     mysql root 密码

# REDIS_HOST              redis 服务所在的主机, 如果你没有现有的 Redis 请保持值为 redis, 如果你有自部署的请在 docker-compose.yaml 中移除 services.redis 以节约性能
# REDIS_PASSWORD          redis 密码
# REDIS_DATABASE          redis 数据库
# REDIS_DATA_VERSION      redis 数据版本

# GUACD_HOST              guacd 服务所在的主机, 如果你没有现有的 Redis 请保持值为 redis, 如果你有自部署的请在 docker-compose.yaml 中移除 services.guacd 以节约性能
# GUACD_PORT              guacd 端口
# GUACD_DRIVE_PATH        guacd 数据挂载目录

# INFLUXDB_ENABLED        是否启用 influxdb (若不需要监控可以设置为 false)
# INFLUXDB_HOST           influxdb 服务所在的主机, 如果你没有现有的 influxdb 请保持值为 influxdb, 如果你有自部署的请在 docker-compose.yaml 中移除 services.influxdb 以节约性能
# INFLUXDB_PORT           influxdb 端口
# INFLUXDB_ORG            influxdb 组织
# INFLUXDB_BUCKET         influxdb bucket
# INFLUXDB_TOKEN          influxdb token   
# INFLUXDB_ADMIN_USERNAME influxdb 控制台用户名
# INFLUXDB_ADMIN_PASSWORD influxdb 控制台用户名
```

启动服务栈

```bash
docker compose up -d
```

等待服务启动（约2分钟），启动完成后，打开浏览器访问 http://localhost:1081，使用默认账号 admin/admin 登录即可开始使用。

运维工具 - 一站式服务器运维解决方案 Orion Visor

在软件开发过程中，数据库设计是一个至关重要的环节。一个好的数据库设计能够提高系统性能、保证数据一致性，而一个糟糕的设计则可能导致各种问题。今天给大家介绍一款开源免费的数据库设计工具——DrawDB，它将彻底改变你设计数据库的方式。




## 什么是 DrawDB？

DrawDB 是一个基于 Web 的开源数据库设计工具和 SQL 生成器，它通过直观的图形化界面，让用户能够轻松设计、可视化并导出各种数据库的 SQL Schema。

**核心特点：**

- 免费开源：DrawDB 是一个开源项目，用户可以无成本地使用所有功能

- 无需注册：无需创建账户，打开即用，保护用户隐私

- 直观易用：提供直观的拖放式界面，让数据库设计变得简单高效

- 多数据库支持：兼容 MySQL、PostgreSQL、SQLite、MariaDB、SQL Server 等多种数据库系统


## 如何使用 DrawDB

### 在线使用

DrawDB 提供了在线版本，直接访问 [官网](https://www.drawdb.app/) 即可开始使用，无需安装任何软件。

![image.png](/static/img/70b4270290aa050b64ce39dfd4357b64.image.webp)

### 本地部署

如果你担心数据安全或希望自定义功能，DrawDB 也支持本地部署。

使用 Docker 部署：

```bash
docker build -t drawdb .
docker run -p 3000:80 drawdb
```

使用 npm 部署：

```bash
git clone https://github.com/drawdb-io/drawdb
cd drawdb
npm install
npm run dev
```

运行成功后，在浏览器中打开 http://localhost:5173/ 即可访问

### 案例设计

在浏览器中输入在线编辑器地址：https://www.drawdb.app/editor ，选择一个你使用的数据库，例如 MySQL，点击确认进入设计页面。

![image.png](/static/img/29b104e6c63979209b63c9000f7da774.image.webp)


drawDB 界面最上面是项目名称，默认“Untitled Diagram”，可以点击修改。然后是常用的菜单栏，包括“文件”、“编辑”、“视图”、“设置”、“帮助”，以及上一次保存时间。

左侧显示了我们设计的表、关系以及主题区域（相关的一组表），点击添加表就可以开始设计新的数据表。

![111](/static/img/41c400ee0d19aafeed9ab1b5fa127c31.1.gif)

对于数据表，可以设置表名、字段名、字段类型、非空约束、主键、默认值、备注以及索引等信息。

drawDB 支持表的外键关联关系，点击外键字段前的蓝色原点，出现红色虚线，拖拽到对应主键字段即可：

![222](/static/img/2b15aaade6d29f5e6fb900a775f0a739.2.gif)

如果想要基于模板进行设计，可以点击“打开”->“新建”按钮：

![image.png](/static/img/5294408f60c06aa904ceb0c4877ae6a1.image.webp)

选择其中一个模板进行创建，例如博客数据库结构，如果想要分享设计，可以点击界面右上角的 “分享” 按钮

![image.png](/static/img/a9fcc55a9dac18ee35d869189ceeb8b9.image.webp)


如果想要将表结构转换为特定数据库的 DDL 脚本，可以点击“文件：->”导出为SQL源代码“：

![image.png](/static/img/e93fddbf46f01f0e0f0cd47f979cde97.image.webp)

另外，也可以通过”文件“->”导出为“菜单将数据库结构导出为图片、PDF 或者 MarkDown 文件。

![image.png](/static/img/ead8d99d4adae616f9f076fb5dffa523.image.webp)


## 使用技巧与最佳实践

- 命名规范：保持表名和字段名的统一命名风格，如使用下划线分隔的小写字母。

- 合理使用注释：为表和字段添加注释，提高可读性。

- 颜色区分：使用不同颜色对功能模块进行区分，使图表更加清晰。

- 版本控制：将 JSON 导出文件纳入版本控制系统，方便跟踪设计变更。

运维工具 - 数据库设计工具 DrawDB

一行代码将文件存储到本地、FTP、SFTP、WebDAV、阿里云 OSS、华为云 OBS、七牛云 Kodo、腾讯云 COS、百度云 BOS、又拍云 USS、MinIO、 Amazon S3、Amazon S3 V2、GoogleCloud Storage、FastDFS、 Azure Blob Storage、Mongo GridFS、Mongo GridFS、go-fastdfs、 火山引擎 TOS、Cloudflare R2、金山云 KS3、美团云 MSS、京东云 OSS、天翼云 OOS、移动 云EOS、沃云 OSS、 网易数帆 NOS、Ucloud US3、青云 QingStor、平安云 OBS、首云 OSS、IBM COS、其它兼容 S3 协议的存储平台。



## X-File-Storage

X-File-Storage（原名 X Spring File Storage）是一个基于 Java 的开源文件存储中间件，目前已捐赠至 Dromara 开源组织。该项目允许开发者通过一行代码将文件存储到各种存储平台中，极大地简化了文件上传、下载和管理的复杂性。

官方文档：https://x-file-storage.xuyanwu.cn/#/

GIT: https://gitee.com/dromara/x-file-storage


### 核心价值主张

在传统的应用开发中，文件存储往往需要针对不同的存储平台编写不同的代码，当需要更换存储方式时，经常面临大量重构工作。X-File-Storage 通过统一的 API 接口，解决了这一痛点，让开发者能够：

- 使用同一套代码应对不同的存储需求

- 轻松在多种存储平台间切换或迁移

- 专注于业务逻辑，而非文件存储细节

### 支持的存储平台

X-File-Storage 支持几乎所有主流的存储平台，包括但不限于：

- 本地存储：本地磁盘

- 云存储服务：阿里云 OSS、华为云 OBS、七牛云 Kodo、腾讯云 COS、百度云 BOS、又拍云 USS

- 国际云服务：Amazon S3、GoogleCloud Storage、Azure Blob Storage

- 开源存储系统：MinIO、FastDFS

- 其他协议：FTP、SFTP、WebDAV

- 新兴平台：火山引擎 TOS、Cloudflare R2、金山云 KS3 等

特别值得一提的是，通过 WebDAV 连接到 Alist 后，还可以间接使用百度网盘、天翼云盘、阿里云盘、迅雷网盘等常见存储服务，大大扩展了其应用范围。

## 快速入门指南

### 环境准备与依赖配置

X-File-Storage 支持 Spring Boot 环境，也需要 JDK 8+ 。

在 pom.xml 中引入相关依赖，这里以阿里云 OSS 为例：

```xml

<dependency>
    <groupId>org.dromara.x-file-storage</groupId>
    <artifactId>x-file-storage-spring</artifactId>
    <version>2.3.0</version>
</dependency>


<dependency>
    <groupId>com.aliyun.oss</groupId>
    <artifactId>aliyun-sdk-oss</artifactId>
    <version>3.16.1</version>
</dependency>
```

### 基础配置
在 application.yml 配置文件中添加存储平台的配置信息：

```yaml
dromara:
  x-file-storage: #文件存储配置
    default-platform: aliyun-oss-1 #默认使用的存储平台
    aliyun-oss:
      - platform: aliyun-oss-1 # 存储平台标识
        enable-storage: true  # 启用存储
        access-key: ?? # 替换为你的 access-key
        secret-key: ?? # 替换为你的 secret-key
        end-point: ?? # 替换为你的 end-point
        bucket-name: ?? # 替换为你的 bucket-name
        domain: ?? # 访问域名，注意“/”结尾，例如：https://abc.oss-cn-shanghai.aliyuncs.com/
        base-path: test/ # 基础路径
```

### 启用与基础使用

在 Spring Boot 启动类上添加 @EnableFileStorage 注解：

```java
@EnableFileStorage
@SpringBootApplication
public class SpringFileStorageTestApplication {
    public static void main(String[] args) {
        SpringApplication.run(SpringFileStorageTestApplication.class,args);
    }
}
````

在 Controller 中注入并使用 FileStorageService：

```java
@RestController
public class FileDetailController {
    
    @Autowired
    private FileStorageService fileStorageService; 

    /**
     * 上传文件
     */
    @PostMapping("/upload")
    public FileInfo upload(MultipartFile file) {
        // 只需要这一行代码即可上传成功
        return fileStorageService.of(file).setPath(LocalDate.now() + StrUtil.SLASH).upload();
    }
}
```

## 高级功能与实战技巧

### 灵活的上传选项

X-File-Storage 提供了丰富的上传选项，满足各种业务场景需求：

```java
/**
 * 上传文件，成功返回文件 url
 */
@PostMapping("/upload2")
public String upload2(MultipartFile file) {
    FileInfo fileInfo = fileStorageService.of(file)
            .setPath("upload/") // 保存到相对路径下，为了方便管理，不需要可以不写
            .setObjectId("0")   // 关联对象id，为了方便管理，不需要可以不写
            .setObjectType("0") // 关联对象类型，为了方便管理，不需要可以不写
            .putAttr("role","admin") // 保存一些属性，可以在切面、保存上传记录、自定义存储平台等地方获取使用
            .upload();  // 将文件上传到对应地方
    return fileInfo == null ? "上传失败！" : fileInfo.getUrl();
}
```

### 图片处理与缩略图生成

X-File-Storage 内置了图片处理功能，基于 thumbnailator 库，可以轻松处理图片和生成缩略图：

```java
/**
 * 上传图片，成功返回文件信息
 */
@PostMapping("/upload-image")
public FileInfo uploadImage(MultipartFile file) {
    return fileStorageService.of(file)
            .image(img -> img.size(1000,1000))  // 将图片大小调整到 1000*1000
            .thumbnail(th -> th.size(200,200))  // 再生成一张 200*200 的缩略图
            .upload();
}
```

### 指定存储平台上传

如果需要将文件上传到特定的存储平台，可以明确指定平台标识：

```java
/**
 * 上传文件到指定存储平台，成功返回文件信息
 */
@PostMapping("/upload-platform")
public FileInfo uploadPlatform(MultipartFile file) {
    return fileStorageService.of(file)
            .setPlatform("aliyun-oss-1")    // 使用指定的存储平台
            .upload();
}
```

### 高级上传技巧

对于大文件或特殊场景，X-File-Storage 提供了更多高级功能：

```java
/**
 * 直接读取 HttpServletRequest 中的文件进行上传
 * 可以实现文件不落盘，边读取边上传，速度更快
 */
@PostMapping("/upload-request")
public FileInfo uploadRequest(HttpServletRequest request) {
    return fileStorageService.of(request).upload();
}
```

使用此功能需要在配置文件中开启 multipart 懒加载：

```yaml
spring:
  servlet:
    multipart:
      max-file-size: 10MB # 文件大小限制
      max-request-size: 100MB # 请求大小限制
      resolve-lazily: true # 开启懒加载
```

## 文件管理与进阶功能

### 文件操作全套解决方案

X-File-Storage 不仅支持文件上传，还提供了一套完整的文件管理功能：

```java
// 根据 URL 获取文件信息
FileInfo fileInfo = fileStorageService.getFileInfoByUrl("https://abc.def.com/test/aa/image.png");

// 检查文件是否存在
boolean exists = fileStorageService.exists("https://abc.def.com/test/aa/image.png");

// 下载文件
byte[] bytes = fileStorageService.download("https://abc.def.com/test/aa/image.png").bytes();

// 删除文件
fileStorageService.delete("https://abc.def.com/test/aa/image.png");
```

### 保存上传记录

通过实现 FileRecorder 接口，可以将文件信息保存到数据库中，方便后续管理和检索。官方推荐的数据库表结构如下：

```sql
CREATE TABLE `file_detail`
(
    `id`                varchar(32)  NOT NULL COMMENT '文件id',
    `url`               varchar(512) NOT NULL COMMENT '文件访问地址',
    `size`              bigint(20)   DEFAULT NULL COMMENT '文件大小，单位字节',
    `filename`          varchar(256) DEFAULT NULL COMMENT '文件名称',
    `original_filename` varchar(256) DEFAULT NULL COMMENT '原始文件名',
    `base_path`         varchar(256) DEFAULT NULL COMMENT '基础存储路径',
    `path`              varchar(256) DEFAULT NULL COMMENT '存储路径',
    `ext`               varchar(32)  DEFAULT NULL COMMENT '文件扩展名',
    `content_type`      varchar(128) DEFAULT NULL COMMENT 'MIME类型',
    `platform`          varchar(32)  DEFAULT NULL COMMENT '存储平台',
    `th_url`            varchar(512) DEFAULT NULL COMMENT '缩略图访问路径',
    `th_filename`       varchar(256) DEFAULT NULL COMMENT '缩略图名称',
    `th_size`           bigint(20)   DEFAULT NULL COMMENT '缩略图大小，单位字节',
    `th_content_type`   varchar(128) DEFAULT NULL COMMENT '缩略图MIME类型',
    `object_id`         varchar(32)  DEFAULT NULL COMMENT '文件所属对象id',
    -- 其他字段...
)
```

### 跨平台文件迁移

X-File-Storage 支持在不同存储平台之间迁移文件，当业务需要更换存储服务商时，这一功能显得尤为实用。

## 技术架构与设计理念

### 模块化设计

X-File-Storage 采用高度模块化的设计，核心特性包括：

- 多后端支持：支持多种文件存储后端，满足不同场景的需求

- 统一的API：通过标准的接口进行文件操作，方便集成到任何应用中

- 易于扩展：设计为微服务架构，容易添加新的功能或者适配器

### 与框架的整合

除了 Spring Boot，X-File-Storage 还提供了对 Solon 框架的支持，并可以脱离 Spring Boot 单独使用，展现了其良好的框架适应性。

## 应用场景与最佳实践

### 典型应用场景

X-File-Storage 适用于多种业务场景：

- 企业级文件管理系统：对内提供统一的文件上传、下载和分享平台

- 图片/视频托管服务：适用于媒体网站、社交媒体平台等

- 多云策略实施：帮助企业避免供应商锁定，灵活调配存储资源

- 数据迁移与备份：方便在不同存储系统间迁移数据

### 性能与安全性建议

在实际生产环境中，建议考虑以下方面：

- 大文件上传：X-File-Storage 支持大文件自动分片上传，适合处理大体积文件

- 权限控制：通过自定义属性和切面实现精细化的访问控制

- 资源清理：合理管理存储空间，定期清理无用文件

## 总结

X-File-Storage 2.3.0 作为一个功能全面的文件存储中间件，通过简化的 API 设计和广泛存储平台支持，极大地降低了Java开发者在文件存储方面的复杂度。其主要优势包括：

- 极简API：一行代码完成文件上传，降低学习成本

- 平台无关性：支持众多存储平台，避免供应商锁定

- 功能全面：从基础上传下载到高级功能如缩略图生成、跨平台迁移

- 持续进化：紧跟技术发展趋势，定期更新加入新特性

- 良好扩展性：支持自定义存储平台和功能扩展

对于正在寻找文件存储解决方案的Java开发者，X-File-Storage 无疑是一个值得尝试的选择，它能显著提升开发效率，让开发者更专注于核心业务逻辑的实现。

Java 工具包 - 多平台文件存储神器 X-File-Storage

强大的 Java 工具包，让微信开发变得简单高效



## WxJava 简介

WxJava 是一款开源的微信开发 Java SDK，支持包括微信支付、开放平台、公众号、企业微信/企业号、小程序等微信功能的后端开发。该项目基于 chanjarster 的 weixin-java-tools 发展而来，经过多次优化和重构，使得接口更易使用，方便开发者快速集成微信各项功能。

GIT: https://gitee.com/binary/weixin-java-tools


### 主要特性

- 不依赖任何 MVC 框架，也不依赖 Servlet，可轻松嵌入到任何系统里

- 模块化设计，结构清晰，只需引入需要的模块即可

- 仅仅作为工具使用，可轻松嵌入到任何系统里

- 支持企业号、公众号、小程序以及微信支付开发

- 丰富的文档和社区支持，持续更新维护

### 核心模块介绍

WxJava 包含 6 个主要模块，每个模块针对不同的微信开发场景：

| 模块名称	| 功能描述 |
| -- | -- |
| weixin-java-common	| 基础工具类与通用接口（如消息加解密、HTTP请求封装） | 
| weixin-java-mp	| 公众号（订阅号和服务号）SDK | 
| weixin-java-miniapp	| 微信小程序 SDK | 
| weixin-java-pay	| 微信支付 SDK | 
| weixin-java-cp	| 企业号/企业微信 SDK | 
| weixin-java-open	| 微信开放平台（第三方平台）SDK | 


## 环境配置与快速开始

### 依赖配置

对于 Spring Boot 项目，只需添加对应模块的 starter 依赖

```xml

<dependency>
    <groupId>com.github.binarywang</groupId>
    <artifactId>wx-java-mp-spring-boot-starter</artifactId>
    <version>4.7.0</version>
</dependency>
```

对于非 Spring Boot 项目：

```xml
<dependency>
  <groupId>com.github.binarywang</groupId>
  <artifactId>weixin-java-mp</artifactId>
  <version>4.7.0</version>
</dependency>
```


### 基础配置

在 application.yml 或 application.properties 中配置微信公众号参数：

```yaml
# 公众号配置(必填)
wx:
  mp:
    appId: your_app_id
    secret: your_app_secret
    token: your_token
    # 存储配置redis(可选),默认是内存
    config-storage:
      type: redistemplate
      redis:
        host: 127.0.0.1
        port: 6379
```

## 核心功能与使用示例

### 服务接入认证

微信公众号开发首先需要完成服务器验证，以下是一个简单的验证接口实现：

```java
@RestController
public class WxController {

    @Autowired
    private WxMpService wxMpService;

    /**
     * 微信服务验证
     */
    @RequestMapping("/wx")
    public void wx(HttpServletRequest request, HttpServletResponse response) throws IOException {
        String signature = request.getParameter("signature");
        String timestamp = request.getParameter("timestamp");
        String nonce = request.getParameter("nonce");
        String echostr = request.getParameter("echostr");
        log.info("微信服务器的认证消息：signature ：{}，timestamp：{}，nonce：{}，echostr：{}", signature, timestamp, nonce, echostr);
        if (!wxMpService.checkSignature(timestamp, nonce, signature)) {
            log.error("消息不合法");
            return;
        }
        PrintWriter writer = response.getWriter();
        try {
            writer.println(echostr);
            log.info("验证成功，给微信服务返回消息：{}", echostr);
        } finally {
            writer.close();
        }
    }
}
```

### 消息加解密

WxJava 内置了消息加解密功能，确保与微信服务器通信的安全：

```java
public String decryptMsg(String msgSignature, String timestamp,
                        String nonce, String encryptMsg) {
    // 1. 签名校验
    String calSignature = SHA1.gen(..., token, timestamp, nonce);
    if(!msgSignature.equals(calSignature)) throw new Exception;
    
    // 2. AES解密
    byte[] aesKey = Base64.decode(encodingAesKey);
    AES aes = new AES(Mode.CBC, Padding.PKCS7, aesKey, iv);
    return aes.decrypt(encryptMsg);
}
```

### 素材管理

WxJava 提供了简洁的 API 来管理微信公众号的素材：

```java
// 上传临时素材
@GetMapping("/saveTemporaryMaterial")
public String saveTemporaryMaterial() {
    File file = new File("path/to/image.jpg");
    WxMediaUploadResult result = wxService.getMaterialService()
            .mediaUpload(WxConsts.MediaFileType.IMAGE, file);
    return "上传成功，mediaId: " + result.getMediaId();
}

// 上传永久素材
@GetMapping("/savePerpetualMaterial")
public String savePerpetualMaterial() {
    File file = new File("path/to/image.jpg");
    WxMpMaterial wxMpMaterial = new WxMpMaterial();
    wxMpMaterial.setFile(file);
    wxMpMaterial.setName("logo");
    
    WxMpMaterialUploadResult result = wxService.getMaterialService()
            .materialFileUpload(WxConsts.MediaFileType.IMAGE, wxMpMaterial);
    return "上传成功，mediaId: " + result.getMediaId();
}
```

### 网页授权与用户信息

获取用户信息是微信公众号开发的常见需求

```java
// 获取用户信息
WxOAuth2AccessToken wxOAuth2AccessToken = wxMpService.getOAuth2Service().getAccessToken(code);
WxOAuth2UserInfo userInfo = wxMpService.getOAuth2Service().getUserInfo(wxOAuth2AccessToken, null);
```

## 微信授权实战

场景：PC网站上提供二维码，通过微信扫码授权登录，获取微信授权的用户信息

1. 构建授权的URL，给前端返回 base64 的二维码，缓存 state 标识1分钟，设置为待处理
2. 前端循环检查登录状态，如果是过期，则前端重新获取二维码，如果是待处理，则跳过，如果是登录成功，则清除缓存状态，前端跳转到网站页面（可同时返回 Token 登录）
3. 微信服务授权后的回调，根据 code 获取用户信息，同时更新 state 为成功，调整成功的页面

```java
@Slf4j
@RestController
public class WxController {

    @Autowired
    private WxMpService wxMpService;

    @Resource
    private ImUsersService imUsersService;

    /**
     * 获取授权URL，生成二维码并转成 base64
     */
    @GetMapping("/login/qrcode")
    public QrCodeResponse authorizationUrl() {
        // 获取重定向URL
        String oauth2RedirectUrl = wxMpService.getWxMpConfigStorage().getOauth2RedirectUrl();
        // 生成回调的state
        String state = IdUtil.fastUUID();
        // 构建授权URL
        String authorizationUrl = wxMpService.getOAuth2Service().buildAuthorizationUrl(oauth2RedirectUrl, WxConsts.OAuth2Scope.SNSAPI_USERINFO, state);
        log.info("微信服务授权URL：{}", authorizationUrl);

        // 生成二维码
        String qrCode = QrCodeUtil.generateAsBase64(authorizationUrl, new QrConfig(200, 200), ImgUtil.IMAGE_TYPE_JPG);
        // 缓存state，有效期1分钟
        if (!RedisCacheUtil.setIfAbsent(String.format(RedisKeyDefine.LOGIN_STATE, state), LoginStateEnum.PENDING.name(), 1, TimeUnit.MINUTES)) {
            return this.authorizationUrl();
        }
        return new QrCodeResponse(state, qrCode);
    }

    /**
     * 检查登录状态
     */
    @GetMapping("/login/check")
    public LoginStateEnum checkLoginStatus(@RequestParam("state") String state) {
        String value = RedisCacheUtil.get(String.format(RedisKeyDefine.LOGIN_STATE, state));
        if (value == null) {
            return LoginStateEnum.EXPIRED;
        }
        else if (LoginStateEnum.PENDING.name().equals(value)) {
            return LoginStateEnum.PENDING;
        }
        // 登录成功，返回token并清除state
        RedisCacheUtil.delete(String.format(RedisKeyDefine.LOGIN_STATE, state));
        return LoginStateEnum.SUCCESS;
    }

    /**
     * 微信服务授权后的回调
     */
    @GetMapping("/callback")
    public String callback(@RequestParam(name = "code") String code, @RequestParam(name = "state") String state) throws WxErrorException {
        log.info("微信服务回调：code：{}", code);
        // 获取用户信息
        WxOAuth2AccessToken wxOAuth2AccessToken = wxMpService.getOAuth2Service().getAccessToken(code);
        WxOAuth2UserInfo userInfo = wxMpService.getOAuth2Service().getUserInfo(wxOAuth2AccessToken, null);
        log.info("微信服务回调：userInfo：{}", userInfo);

        // 更新state,二维码等回调呢
        RedisCacheUtil.set(String.format(RedisKeyDefine.LOGIN_STATE, state), LoginStateEnum.SUCCESS.name());

        // 初始化账户
        imUsersService.initUser(userInfo);
        // 返回响应成功的页面
        return "/success";
    }

    /**
     * 微信服务验证
     */
    @RequestMapping("/wx")
    public void wx(HttpServletRequest request, HttpServletResponse response) throws IOException {
        String signature = request.getParameter("signature");
        String timestamp = request.getParameter("timestamp");
        String nonce = request.getParameter("nonce");
        String echostr = request.getParameter("echostr");
        log.info("微信服务器的认证消息：signature ：{}，timestamp：{}，nonce：{}，echostr：{}", signature, timestamp, nonce, echostr);
        if (!wxMpService.checkSignature(timestamp, nonce, signature)) {
            log.error("消息不合法");
            return;
        }
        PrintWriter writer = response.getWriter();
        try {
            writer.println(echostr);
            log.info("验证成功，给微信服务返回消息：{}", echostr);
        } finally {
            writer.close();
        }
    }
}
```

配置信息

```java
@Configuration
@EnableConfigurationProperties({WxMpProperties.class, EchoIMProperties.class})
public class WxMpConfiguration {

    @Bean
    public WxMpService wxMpService(WxMpConfigStorage configStorage) {
        WxMpService wxMpService = new WxMpServiceImpl();
        wxMpService.setWxMpConfigStorage(configStorage);
        return wxMpService;
    }

    @Bean
    public WxMpConfigStorage wxMpConfigStorage(WxMpProperties wxMpProperties, EchoIMProperties echoIMProperties) {
        WxMpDefaultConfigImpl configStorage = new WxMpDefaultConfigImpl();
        configStorage.setAppId(wxMpProperties.getAppId());
        configStorage.setSecret(wxMpProperties.getSecret());
        configStorage.setToken(wxMpProperties.getToken());
        configStorage.setAesKey(wxMpProperties.getAesKey());
        // 回调地址
        configStorage.setOauth2RedirectUrl(echoIMProperties.url() + "/callback");
        return configStorage;
    }
}
```

## 高级特性与最佳实践

### 消息路由机制

WxJava 提供了强大的消息路由功能，可以根据消息类型、内容等条件将消息路由到不同的处理器：

```java
// 初始化消息路由器
WxMpMessageRouter router = new WxMpMessageRouter(wxMpService);

// 配置路由规则
router.rule()
    .msgType(WxConsts.XmlMsgType.TEXT)
    .handler(textHandler)
    .end()
    .rule()
    .msgType(WxConsts.XmlMsgType.IMAGE)
    .handler(imageHandler)
    .end();

// 处理微信消息
WxMpXmlMessage message = ...;
WxMpXmlOutMessage response = router.route(message);
```

### 缓存策略优化

为了提高性能，WxJava 支持多种缓存策略，推荐使用 Redis 缓存 access_token 等敏感信息：

```java
// JSAPI ticket 缓存示例
public String getJsapiTicket() {
    String ticket = cache.get("jsapi_ticket");
    if (ticket == null || isExpired(ticket)) {
        ticket = refreshTicket();
        // 预留 5 分钟缓冲时间
        cache.set("jsapi_ticket", ticket, 7200 - 300);
    }
    return ticket;
}
```

### 异常处理

WxJava 使用 WxErrorException 来封装微信接口返回的错误信息，便于统一异常处理：

```java
try {
    // 调用微信 API
    WxMpUser user = wxMpService.getUserService().userInfo(openId, lang);
} catch (WxErrorException e) {
    // 处理微信接口错误
    log.error("微信接口调用失败，错误码：{}，错误信息：{}", 
              e.getError().getErrorCode(), e.getError().getErrorMsg());
    // 根据不同的错误码进行特定处理
}
```

### 开发建议

根据实践经验，以下是使用 WxJava 的几点开发建议：

- 自定义消息处理器应遵循单一职责原则

- 敏感操作建议实现二次验证机制

- 分布式部署时注意 access_token 同步问题

- 定期关注微信官方接口更新，及时升级 SDK 版本

## 总结

WxJava 作为一款功能全面、设计优雅的微信开发 Java SDK，极大地简化了微信生态各类应用的开发工作。其模块化设计、丰富的功能覆盖和活跃的社区支持，使其成为 Java 开发者进行微信开发的首选工具包。

无论是初学者还是经验丰富的开发者，都能通过 WxJava **快速构建稳定、高效的微信应用**。随着微信生态的不断发展，WxJava 也在持续更新迭代，为开发者提供更好的开发体验和更强大的功能支持。

Java 工具包 - 微信开发 SDK WxJava

baidu-site-verification

本人自己的博客，对工作与学习过程中的总结、一些场景设计的实现方案、遇到过的疑难问题与解决、以及面试总结等。