一行代码将文件存储到本地、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

随着微服务架构的盛行，很多公司都把系统按照业务边界拆分成多个微服务节点。在排查问题查看日志时，由于业务链路贯穿多个微服务节点，**定位某个请求的完整日志链** 变得极其困难。传统的分布式追踪系统如 SkyWalking、Pinpoint 等虽然功能强大，但 **搭建和维护成本较高**，对于中小型项目来说过于沉重。

正是在这样的背景下，TLog 应运而生。它是一款轻量级的分布式日志标记追踪神器，通过对日志自动打标签完成微服务链路追踪，几乎零性能损耗，10分钟即可快速接入。

## TLog

TLog 提供了一种最简单的方式来解决日志追踪问题，它不收集日志，也不需要另外的存储空间，只是自动地对你的日志进行打标签，生成 `TraceId` 贯穿微服务的一整条链路，并提供上下游节点信息。适合中小型企业以及想快速解决日志追踪问题的公司项目使用。

**核心特性**

* 无侵入式设计：对业务代码零侵入，使用简单，10分钟即可接入
* 多日志框架支持：支持log4j、log4j2、logback三大日志框架，自动检测适配
* 多RPC框架支持：支持dubbo、dubbox、springcloud三大RPC框架
* 灵活的接入方式：提供javaagent完全无侵入接入、字节码一行代码接入、基于配置文件的接入三种方式
* 异步线程追踪：支持线程池、多级异步线程等复杂场景的追踪
* 自定义标签模板：支持配置自定义日志标签模板，提供多个系统级埋点标签
* 高性能：几乎无性能损耗，快速稳定

## 快速接入指南

TLog提供三种接入方式，满足不同场景的需求。

### Javaagent 接入方式

这种方式完全不侵入项目，利用 Javaagent 在启动时加入jar包，整个过程1分钟就能搞定。

**使用步骤：**

下载 tlog-agent.jar，可以在官方发布页面下载。在Java启动参数中加入：

```
text

-javaagent:/path/to/tlog-agent.jar
```

只需要这一步，就可以把springboot项目快速接入。

### 字节码注入方式

这种方式适合springboot项目，需要项目依赖 tlog-all-spring-boot-starter 包。

依赖配置：

```
xml

<dependency>
    <groupId>com.yomahub</groupId>
    <artifactId>tlog-all-spring-boot-starter</artifactId>
    <version>1.5.2</version>
</dependency>
```

在启动类中加入一行代码：

```
java

@SpringBootApplication
public class Application {

    static {AspectLogEnhance.enhance();}//进行日志增强，自动判断日志框架

    public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}
```

警告

这种方式和javaagent接入差不多，虽然简单，但是不支持MDC和异步日志。而且只支持springboot项目。

### 日志框架适配器方式（官方推荐）

TLog 对 springboot 和 spring native 提供了2种不同的依赖，此种方式只需依赖一个包，必须的包会传递依赖进来

springboot 全量依赖

```
xml

<dependency>
  <groupId>com.yomahub</groupId>
  <artifactId>tlog-all-spring-boot-starter</artifactId>
  <version>1.5.2</version>
</dependency>
```

spring native 依赖

```
xml

<dependency>
  <groupId>com.yomahub</groupId>
  <artifactId>tlog-all</artifactId>
  <version>1.5.2</version>
</dependency>
```

或者根据模块部分依赖配置：

```
xml

<dependency>
    <groupId>com.yomahub</groupId>
        <artifactId>tlog-xxx-spring-boot-starter</artifactId>
    <version>1.5.2</version>
</dependency>
```

具体模块和描述如下表

| 模块名 | 描述 |
| --- | --- |
| tlog-dubbo-spring-boot-starter | 适用于apache dubbo的项目 |
| tlog-dubbox-spring-boot-starter | 适用于当当的dubbox的项目 |
| tlog-feign-spring-boot-starter | 适用于spring cloud中open feign的项目 |
| tlog-gateway-spring-boot-starter | 适用于spring cloud中的gateway网关服务 |
| tlog-soul-spring-boot-starter | 适用于soul网关服务 |
| tlog-web-spring-boot-starter | 适用于有spring web的项目 |
| tlog-xxljob-spring-boot-starter | 适用于xxl-job的项目 |

SpringBoot 中默认的日志框架是 Logback，我们以 Logback 配置示例：

```
xml

<appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
    
    <encoder class="com.yomahub.tlog.core.enhance.logback.AspectLogbackEncoder">
        <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50} - %msg%n</pattern>
    </encoder>
</appender>
```

以上为同步日志的处理，如果是异步日志，可以通过以下配置：

```
xml


<appender name="ASYNC_FILE" class="com.yomahub.tlog.core.enhance.logback.async.AspectLogbackAsyncAppender">
    <discardingThreshold>0</discardingThreshold>
    <queueSize>2048</queueSize>
    <includeCallerData>true</includeCallerData>
    <appender-ref ref="FILE"/>
</appender>
```

提示

TLog 提供了针对每一种日志框架适配的方式，需要你去修改日志的配置文件，替换相应的类 ，配置方式也很简单，下面给出了每一种场景的示例

这种方式支持了全特性，为官方推荐方式

## 高级功能

### 自定义日志标签模板

在 application.properties 中自定义日志标签的生成样式：

```
properties

tlog.pattern=[$tlogTraceId][$tlogSpanId][$currIp][$tl]
```

支持的变量有：

* tlogTraceId：链路ID
* tlogSpanId：链路spanId
* currIp：当前服务IP
* preIvkApp：上游微服务节点名称
* preIvkHost：上游微服务的Host Name
* preIp：上游微服务的IP地址
* NONE：自定义
* tl：MDC标识,包含业务标签数据
* exchange: 交换

### 业务自定义标签

TLog支持方法级别的自定义业务标签，在方法上添加@TLogAspect注解：

```
java

@TLogAspect({"id","name"})
public String test(String id, String name) {
    logger.info("这是测试方法");
    return "success";
}
```

假设id的值为'NO1234'，name为'jenny'，日志输出：

```
text

<0><7161457983341056> id:NO1234,name:jenny 这是测试方法
```

### 自定义TraceId

可以通过 `tlog.id-generator` 自定义 TraceId 生成器

```
yaml

tlog:
    id-generator: com.yomahub.tlog.example.id.TestIdGenerator
```

继承 TLogIdGenerator 接口即可，其默认实现类 TLogDefaultIdGenerator

```
java

public class TLogDefaultIdGenerator extends TLogIdGenerator{
    @Override
    public String generateTraceId() {
        return UniqueIdGenerator.generateStringId();
    }
}
```

### MDC 模式下logback的配置

TLog 中 logback 的 MDC 占位符为 `%X{tl}`，想要 MDC 生效，需要添加 `TLogLogbackTTLMdcListener` 监听器

```
xml

<?xml version="1.0" encoding="UTF-8"?>
<configuration debug="false">
    
    
    <contextListener class="com.yomahub.tlog.core.enhance.logback.TLogLogbackTTLMdcListener"/>
    
    
    
    <property name="LOG_HOME" value="./logs" />
    
    <appender name="Console" class="ch.qos.logback.core.ConsoleAppender">
        <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} %X{tl} [%thread] %-5level %logger{50} - %msg%n</pattern>
        </encoder>
    </appender>
</configuration>
```

其中 `%X{tl}` 输出格式为 `<0><f9fd5b91-41e8-410c-aaf4-9837a74b5073> [name:"123"]`

### Logback框架适配器

添加上此 `AspectLogbackEncoder` 适配器，即可无需配置 MDC 的属性 `%X{tl}`

```
xml

<?xml version="1.0" encoding="UTF-8"?>
<configuration debug="false">
    <property name="APP_NAME" value="logtest"/>
    <property name="LOG_HOME" value="./logs" />
    <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
        
		<encoder class="com.yomahub.tlog.core.enhance.logback.AspectLogbackEncoder">
			  <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] %-5level %logger{50} - %msg%n</pattern>
		</encoder>
    </appender>
 
</configuration>
```

输出格式为 `<0><f9fd5b91-41e8-410c-aaf4-9837a74b5073> [name:"123"] 这是输出日志`

提示

`%X{tl}` 此格式会出现在自定义好的日志位置中

`AspectLogbackEncoder` 则会自动匹配到输出的日志内容之前

### 异步线程支持

#### 一般异步线程

直接通过new Thread创建异步线程，TLog天然支持携带traceId：

```
java

new Thread(() -> {
    logger.info("异步执行");
}).start();
```

#### 线程池支持

对于线程池，需要使用TLogInheritableTask包装任务：

```
java

ThreadPoolExecutor pool = new ThreadPoolExecutor(1, 2, 1, TimeUnit.SECONDS, new LinkedBlockingQueue<>(10));
pool.execute(new TLogInheritableTask() {
    @Override
    public void runTask() {
        logger.info("异步执行");
    }
});
```

也可以自定义线程池简化操作：

```
java

ThreadPoolExecutor pool = new TLogThreadPoolExecutor(1, 2, 1, TimeUnit.SECONDS, new LinkedBlockingQueue<>(10));
pool.execute(() -> logger.info("异步执行"));
```

## 任务框架的支持

### JDK TIMER 任务

从1.3.0版本开始，TLog对JDK Timer的定时任务作了支持。

只要把TimerTask替换成TLogTimerTask就可以了

示例：

```
java

Timer timer = new Timer();
timer.scheduleAtFixedRate(new TLogTimerTask() {
    @Override
    public void runTask() {
        log.info("hello,world");
    }
}, 100, 1000);
```

### Quartz 框架的支持

从1.3.0版本开始，TLog对Spring Quartz框架作了支持，只需要把QuartzJobBean替换成TLogQuartzJobBean就可以了。

示例：

```
java

public class DateTimeJob extends TLogQuartzJobBean {

    private Logger log = LoggerFactory.getLogger(this.getClass());

    @Override
    public void executeTask(JobExecutionContext jobExecutionContext) throws JobExecutionException {
        //获取JobDetail中关联的数据
        String msg = (String) jobExecutionContext.getJobDetail().getJobDataMap().get("msg");
        log.info("current time :"+new SimpleDateFormat("yyyy-MM-dd HH:mm:ss").format(new Date()) + "---" + msg);
    }
}
```

### spring-scheduled 的支持

从1.3.4版本开始，TLog对Spring中的@Scheduled作了支持。

在springboot环境下，你无需作任何改动。只需引入依赖包即可生效。

而在spring native下，你需要额外配置一行

```
xml

<bean class="com.yomahub.tlog.task.spring.SpringScheduledTaskAop"/>
```

### XXL-JOB 框架的支持

从1.3.0版本开始，TLog对开源框架XXL-JOB作了支持。

在springboot环境下，你无需作任何改动。只需引入依赖包即可生效。

而在spring native环境下，你需要额外配置一行

```
xml

<bean class="com.yomahub.tlog.xxljob.aop.TLogXxlJobAop"/>
```

## 实战演示

### 基础使用

spring cloud openfeign 同时需要 tlog-feign-spring-boot-starter 和 tlog-web-spring-boot-starter 包

```
xml

<dependency>
    <groupId>com.yomahub</groupId>
    <artifactId>tlog-feign-spring-boot-starter</artifactId>
    <version>1.5.2</version>
</dependency>

<dependency>
    <groupId>com.yomahub</groupId>
    <artifactId>tlog-web-spring-boot-starter</artifactId>
    <version>1.5.2</version>
</dependency>
```

日志配置文件

```
xml

<?xml version="1.0" encoding="UTF-8"?>

<configuration>
    
    <contextListener class="com.yomahub.tlog.core.enhance.logback.TLogLogbackTTLMdcListener"/>

    
    <property name="log.path" value="logs"/>
    <property name="log.maxHistory" value="15"/>
    <property name="log.colorPattern" value="%magenta(%d{yyyy-MM-dd HH:mm:ss}) %highlight(%-5level) %boldCyan(%X{tl})  %yellow(%thread) %green(%logger{50}) %msg%n"/>
    <property name="log.pattern" value="%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level %boldCyan(%X{tl}) %thread %logger{50} %msg%n"/>

    
    <springProfile name="dev">
        
        <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
            <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
                <level>DEBUG</level>
            </filter>
            <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
                <FileNamePattern>${log.path}/info.%d{yyyy-MM-dd}.log</FileNamePattern>
            </rollingPolicy>
            <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
                <pattern>${log.colorPattern}</pattern>
            </encoder>
        </appender>

        
        <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
            <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
                <level>DEBUG</level>
            </filter>
            <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
                <pattern>${log.colorPattern}</pattern>
            </encoder>
        </appender>

        
        <logger name="liu" level="DEBUG" additivity="false">
            <appender-ref ref="STDOUT"/>
            <appender-ref ref="FILE"/>
        </logger>

        
        <root level="INFO">
            <appender-ref ref="STDOUT"/>
            <appender-ref ref="FILE"/>
        </root>
    </springProfile>

    <springProfile name="prod">
        
        <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
            <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
                <level>DEBUG</level>
            </filter>
            <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
                <FileNamePattern>${log.path}/info.%d{yyyy-MM-dd}.log</FileNamePattern>
            </rollingPolicy>
            <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
                <pattern>${log.colorPattern}</pattern>
            </encoder>
        </appender>

        
        <appender name="STDOUT" class="ch.qos.logback.core.ConsoleAppender">
            <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
                <level>DEBUG</level>
            </filter>
            <encoder class="ch.qos.logback.classic.encoder.PatternLayoutEncoder">
                <pattern>${log.colorPattern}</pattern>
            </encoder>
        </appender>

        
        <logger name="liu" level="DEBUG" additivity="false">
            <appender-ref ref="STDOUT"/>
            <appender-ref ref="FILE"/>
        </logger>

        
        <root level="INFO">
            <appender-ref ref="STDOUT"/>
            <appender-ref ref="FILE"/>
        </root>
    </springProfile>
</configuration>
```

接入TLog后，代码中无需任何改动，直接使用日志API：

```
java

@Slf4j
@RestController
public class DemoController {
    @Resource
    private AsyncAnnoDomain asyncAnnoDomain;

    @TLogAspect("name")
    @RequestMapping("/hi")
    public String sayHello(@RequestParam String name){
        log.info("invoke method sayHello,name={}",name);
        asyncAnnoDomain.testAnnotationAsync();
        new AsynDomain().start();
        return "hello";
    }
}

@Component
public class AsyncAnnoDomain {
    private Logger log = LoggerFactory.getLogger(this.getClass());
    @Async
    public void testAnnotationAsync(){
        log.info("这是异步标签日志");
    }
}

public class AsynDomain extends Thread{
    private Logger log = LoggerFactory.getLogger(this.getClass());
    @Override
    public void run() {
        log.info("这是异步方法哦");
        log.info("异步方法开始");
        log.info("异步方法结束");
    }
}
```

结果输出

```
text

2024-11-05 17:48:33 INFO  <0><b0fdba05-6e3b-48ea-b334-784a4f3b0b0c> [name:"123"]  http-nio-8051-exec-1 c.y.t.e.RunnerApplication$$EnhancerBySpringCGLIB$$3cbc6fa2 invoke method sayHello,name=123
2024-11-05 17:48:33 INFO  <0><b0fdba05-6e3b-48ea-b334-784a4f3b0b0c> [name:"123"]  Thread-3 com.yomahub.tlog.example.AsynDomain 这是异步方法哦
2024-11-05 17:48:33 INFO  <0><b0fdba05-6e3b-48ea-b334-784a4f3b0b0c> [name:"123"]  Thread-3 com.yomahub.tlog.example.AsynDomain 异步方法开始
2024-11-05 17:48:33 INFO  <0><b0fdba05-6e3b-48ea-b334-784a4f3b0b0c> [name:"123"]  Thread-3 com.yomahub.tlog.example.AsynDomain 异步方法结束
2024-11-05 17:48:33 INFO  <0><b0fdba05-6e3b-48ea-b334-784a4f3b0b0c> [name:"123"]  task-1 com.yomahub.tlog.example.AsyncAnnoDomain 这是异步标签日志```
```

## 性能分析

TLog在设计上充分考虑了性能因素，具有以下优势：

轻量级设计：不收集日志，只对日志进行标签增强，网络开销极小

异步处理：关键的耗时操作采用异步方式，不影响主业务流程

智能采样：支持采样率配置，在高并发场景下可控制日志输出量

本地变量：基于ThreadLocal的实现，上下文传递效率极高

在实际压测中，TLog的性能损耗通常低于1%，完全满足生产环境要求。

## 最佳实践

推荐选择 **日志框架适配** 接入方式，最稳定，功能完整，可扩展性高

虽然TLog本身不收集日志，但在微服务体系中，官方推荐使用TLog+ELK/EFK方案：

* TLog负责生成和传递traceId
* ELK负责日志的收集、存储和展示
* 通过traceId在Kibana中快速检索整个调用链路

**注意事项**

* TraceId生成：默认使用Snowflake算法生成，可通过SPI扩展其他算法
* 传递失败处理：当traceId传递中断时，有完善的恢复机制
* ID长度控制：支持traceId长度定制，避免日志膨胀

## 总结

TLog作为一款轻量级的分布式日志标记追踪工具，在易用性、功能性和性能之间取得了很好的平衡：

* 简单易用：10分钟快速接入，学习成本低
* 功能完善：支持多种日志框架、RPC框架和复杂场景
* 性能优异：几乎零性能损耗，适合高并发场景
* 灵活扩展：支持多种接入方式和自定义扩展

对于尚未搭建完整分布式追踪系统的中小型项目，或者希望以最小成本解决日志追踪问题的团队，TLog无疑是一个极具性价比的选择。

Java 工具包 - 轻量级的分布式日志 TLog

Java作为一种解释型语言，其字节码具有较高的抽象级别，这使得它很容易被反编译。任何一个简单的反编译工具，如JD-GUI，都可以将class文件还原成可读性很高的源代码。这对于投入大量研发成本的企业来说，意味着核心算法、业务逻辑等知识产权面临泄露风险。

想象一下：你辛苦开发的核心算法，竞争对手只需一个反编译工具就能一览无遗——这种场景绝不是危言耸听！

## 保护知识产权，从代码加密开始

我们先了解几种常见的 Java 代码保护技术：

1. 代码混淆：对Class文件进行重新组织和处理，使得处理后的代码完成相同的功能，但反编译后难以理解。包括符号混淆、数据混淆、控制混淆等。
2. Class文件加密：将关键Class文件进行加密，使用时通过自定义ClassLoader解密并加载到JVM中。
3. 转换成本地代码：将关键模块转换成本地代码，通过JNI技术调用。这种方法牺牲了Java的跨平台特性。
4. 隔离Java程序：将关键Java Class放在服务器端，客户端通过接口获得服务。

在以上方案中，代码混淆因其在安全性和维护成本上的平衡，成为最常用的保护方案

## ClassFinal ：基于字节码加密的Java保护神

ClassFinal是一款基于字节码加密的Java保护工具，它能够保护Spring Boot项目或其他Java项目中的源代码和配置文件不被非法获取或篡改。

**核心特性**

* 无需修改源代码：通过Maven插件集成，对开发透明
* 强大的加密能力：对字节码进行加密，而非简单混淆
* 灵活的配置：可指定加密的包、排除的包等
* 运行时动态解密：通过Java Agent机制，在运行时动态解密类文件

**工作原理**

ClassFinal-maven-plugin 插件通过调用 Java Native Interface（JNI）实现对Java字节码的加密。具体来说，它会在编译阶段对类文件进行混淆和加密，然后在运行时动态解密这些类文件。

## 实战：使用 ClassFinal 保护 Spring Boot 项目

### 环境准备

* JDK 8+
* Maven 3.5+
* Spring Boot项目

### 步骤1：添加 Maven 插件配置

在项目的 pom.xml 文件中添加 ClassFinal 插件配置：

```
xml

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
        <plugin>
            
            <groupId>net.roseboy</groupId>
            <artifactId>classfinal-maven-plugin</artifactId>
            <version>1.2.1</version>
            <configuration>
                <password>#</password>
                <excludes>org.spring</excludes>
                <packages>${groupId}</packages>
                <cfgfiles>application.yml,application-dev.yml</cfgfiles>
                <libjars>hutool-all.jar</libjars> 
                <code>xxxx</code> 
            </configuration>
            <executions>
                <execution>
                    <phase>package</phase>
                    <goals>
                        <goal>classFinal</goal>
                    </goals>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>
```

**配置参数说明**

* password：加密密码，#表示启动时不需要密码
* packages：要加密的包名，多个包用逗号分隔
* cfgfiles：需要加密的配置文件
* excludes：排除不加密的包
* libjars：项目依赖的jar包

注意

整合插件只需要在启动类的 pom.xml 文件中添加上述插件即可，需要注意的是，改插件时要放到 `spring-boot-maven-plugin` 插件后面，否则不起作用。

### 步骤2：执行加密打包

运行Maven打包命令：

```
bash

mvn clean package
```

执行完成后，在target目录下会生成两个文件：

* yourproject.jar：原始jar包
* yourproject-encrypted.jar：加密后的jar包

### 步骤3：运行加密后的应用

加密后的 jar 包不能直接运行，需要通过Java Agent方式启动：

```
bash

java -javaagent:yourproject-encrypted.jar -jar yourproject-encrypted.jar
```

如果配置了密码，则需要这样启动：

```
bash

java -javaagent:yourproject-encrypted.jar=-pwd:yourpassword -jar yourproject-encrypted.jar
```

### 效果验证：加密前后对比

加密前：使用JD-GUI等反编译工具可以清晰查看源代码，逻辑一目了然。

加密后：反编译后方法体为空，无法查看实际逻辑，但类名、方法名等元数据仍可查看（可通过配合ProGuard等混淆工具进一步加强保护）

## 高级配置与技巧

### 指定加密范围

通过配置可以精确控制需要加密的包和排除的包：

```
xml

<configuration>
    <packages>com.yourcompany.core,com.yourcompany.service</packages>
    <excludes>org.spring,com.yourcompany.test</excludes>
</configuration>
```

### 加密强度设置

ClassFinal支持设置不同的加密强度：

```
xml

<configuration>
    <strength>strong</strength>
</configuration>
```

可选值包括：weak， medium， strong，强度越高安全性越高但性能影响也越大。

### 多套加密密钥

为提高安全性，可以针对不同机器使用不同加密密钥：

```
xml

<configuration>
    <cfKeys>
        <cfKey>
            <id>machine1</id>
            <key>your-encryption-key-for-machine1</key>
        </cfKey>
        <cfKey>
            <id>machine2</id>
            <key>your-encryption-key-for-machine2</key>
        </cfKey>
    </cfKeys>
</configuration>
```

### 保留自定义注解

可以配置保留特定注解，确保某些功能正常：

```
xml

<configuration>
    <annotations>
        <annotation>com.yourcompany.MyAnnotation</annotation>
    </annotations>
</configuration>
```

## 与其他工具对比

**ClassFinal vs ProGuard**

| 特性 | ClassFinal | ProGuard |
| --- | --- | --- |
| 保护方式 | 字节码加密 | 代码混淆 |
| 性能影响 | 运行时动态解密有轻微影响 | 优化后可能提升性能 |
| 使用复杂度 | 简单，配置少 | 相对复杂，需细致配置 |
| 保护强度 | 高，反编译后无法查看逻辑 | 中，反编译后代码晦涩难懂 |

**注意事项与最佳实践**

* 环境兼容性：ClassFinal依赖于glibc，主要在Linux环境下使用
* 性能考量：加密强度越高，运行时解密开销越大，需根据场景权衡
* 依赖管理：确保所有依赖项正确配置，避免因缺少依赖导致运行失败
* 版本兼容：注意ClassFinal版本与JDK版本的兼容性
* 测试验证：加密后务必进行全面测试，确保功能正常

使用建议

对于安全性要求极高的场景，可以组合使用 `ProGuard` 和 `ClassFinal`组合：先使用 ProGuard 进行混淆和优化，再使用 ClassFinal 进行加密，实现双重保护。

## 总结

在当今竞争激烈的软件市场中，代码保护不是可选项，而是必选项。ClassFinal作为一个简单易用、效果显著的Java代码保护工具，为开发者提供了一道坚实的安全防线。

通过本文的介绍，你应该已经掌握了：

✅ Java代码面临的安全风险

✅ ClassFinal的工作原理和优势

✅ 如何集成使用ClassFinal插件

✅ 高级配置和最佳实践

**保护你的知识产权，从现在开始！** 不要让辛苦开发的代码成为他人剽窃的对象。

Java 工具包 - ClassFinal 代码安全加密，从此拒绝反编译

作为一名 Java 开发者，我在日常工作中经常需要处理 PDF 文档。无论是生成报告、合同，还是对现有 PDF 进行编辑，一个简单易用的工具能极大提升开发效率。今天给大家介绍一款 Java 语言简化处理 PDF 的框架——x-easypdf，它最近发布了具有 AI 加持的 3.3.0 版本，让我们一起来看看它的强大功能吧。

## x-easypdf 是什么？

x-easypdf 是一个专为简化 PDF 处理而设计的 Java 框架，提供了一套简单易用的 API 接口。它包含两个核心模块：

* fop 模块：专注于 PDF 文档创建，基于 xsl-fo 模板生成 PDF 文档，支持多种数据源进行模板渲染
* pdfbox 模块：专注于 PDF 文档编辑，在标准的 Apache PDFBox 基础上进行扩展，添加了大量实用功能

在 3.3.0 版本中，x-easypdf 更是加入了 AI 能力，可以智能解析文档内容，为 PDF 处理带来了全新可能。

官网地址：<https://x-easypdf.cn/>

项目地址：<https://gitee.com/dromara/x-easypdf>

Mavan仓库：<https://central.sonatype.com/artifact/org.dromara/x-easypdf/overview>

fop 模块与 pdfbox 模块如何选择？

fop 模块基于 xsl-fo 模板生成 pdf 文档，仅适用于文档创建。 pdfbox 模块支持文档的创建、解析、提取与处理，适用范围更广。

## 核心特性

### 简单易用

x-easypdf 的设计理念就是简化 PDF 操作流程，仅需一行代码，便可完成多种 PDF 操作。它通过组件化的形式进行 PDF 构建，极大降低了使用门槛。

### 功能丰富

* 创建 PDF 文档：轻松创建新的 PDF 文档
* 编辑 PDF 文档：添加文本、图像、表格等元素
* 操作 PDF 文档：支持合并、分割、加密和解密 PDF 文档
* 生成 PDF 表单：创建包含可填写字段的 PDF 表单
* 自动换行与分页：当内容超过页面宽度或高度时自动处理
* 内置中文支持：支持华为鸿蒙字体，中文处理更加自然

### AI 加持

3.3.0 版本新增了大模型解析文档的支持，包括：

* 月之暗面（Kimi）AI 解析器
* 讯飞（Spark）AI 解析器
* 腾讯 AI 解析器

这些 AI 功能可以智能解析 PDF 中的文本和图像内容，实现更高级的文档处理能力。

## 安装与配置

### Maven 依赖

根据需求，可以选择引入全功能模块或特定模块：

全功能模块（pdfbox + fop）

```
xml

<dependency>
    <groupId>org.dromara</groupId>
    <artifactId>x-easypdf</artifactId>
    <version>版本号</version>
</dependency>
```

仅 pdfbox 模块

```
xml

<dependency>
    <groupId>org.dromara</groupId>
    <artifactId>x-easypdf-pdfbox</artifactId>
    <version>版本号</version>
</dependency>
```

仅 fop 模块

```
xml

<dependency>
    <groupId>org.dromara</groupId>
    <artifactId>x-easypdf-fop</artifactId>
    <version>版本号</version>
</dependency>
```

## fop 模块

### 使用步骤

以 freemarker 数据源为例

1. 添加数据源依赖

```
xml

<dependency>
    <groupId>org.freemarker</groupId>
    <artifactId>freemarker</artifactId>
    <version>版本号</version>
</dependency>
```

2. 创建模板对象

```
java

Template template = TemplateHandler.Template.build();
```

3. 设置 fop 配置文件路径

```
java

template.setConfigPath(configPath);
```

4. 设置数据源，并设置 xsl-fo 模板路径与模板数据

```
java

template.setDataSource(
        TemplateHandler.DataSource.Freemarker.build()
                            .setTemplateName("template.fo")
                            .setTemplateData(data)
);
```

5. 执行转换

```
template.transform(outputPath);
```

### 完整示例

以 freemarker 数据源为例

```
java

// 定义fop配置文件路径
String configPath = "E:\\pdf\\template\\fop.xconf";
// 定义xsl-fo模板路径（目录）
String templatePath = "E:\\pdf\\template\\freemarker";
// 定义pdf输出路径
String outputPath = "E:\\pdf\\test\\fo\\Freemarker.pdf";
// 设置模板路径
TemplateHandler.DataSource.Freemarker.setTemplatePath(templatePath);
// 定义数据map
Map<String, Object> data = new HashMap<>();
// 定义数据list
List<String> list = new ArrayList<>(2);
list.add("hello");
list.add("world");
// 设置值
data.put("list", list);
data.put("str", "hello world");
// 转换pdf
TemplateHandler.Template.build().setConfigPath(configPath).setDataSource(
        // 构建数据源
        TemplateHandler.DataSource.Freemarker.build()
            // 设置模板名称（模板路径下的文件名称）
            .setTemplateName("template.fo")
            // 设置模板数据
            .setTemplateData(data)
).transform(outputPath);
```

fop 配置文件

```
xml

<?xml version="1.0"?>

<fop version="1.0">

    
    <base>.</base>

    
    <source-resolution>72</source-resolution>
    
    <target-resolution>72</target-resolution>

    
    <default-page-settings width="21cm" height="29.7cm"/>

    
    <renderers>
        
        <renderer mime="application/pdf">
            
            <filterList>
                
                <value>flate</value>
            </filterList>
            
            <fonts>
                
                <auto-detect/>
            </fonts>
        </renderer>
    </renderers>
</fop>
```

xsl-fo 配置文件

```
xml

<?xml version="1.0" encoding="utf-8"?>

<fo:root xmlns:fo="http://www.w3.org/1999/XSL/Format">
    
    <fo:layout-master-set>
        
        <fo:simple-page-master master-name="A4">
            
            <fo:region-body/>
        </fo:simple-page-master>
    </fo:layout-master-set>
    
    <fo:page-sequence master-reference="A4">
        
        <fo:flow flow-name="xsl-region-body">
            <#list list as data>
                <fo:block>${data}</fo:block>
            </#list>
            <#if str??>
                <fo:block>${str}</fo:block>
            <#else>
                <fo:block font-family="微软雅黑">为空</fo:block>
            </#if>
        </fo:flow>
    </fo:page-sequence>
</fo:root>
```

提示

使用中文时，需设置支持中文的字体名称

## pdfbox 模块

### 使用步骤

#### 创建文档

以添加文本为例

1. 创建文档对象

```
java

Document document = PdfHandler.getDocumentHandler().create();
```

2. 创建页面对象

```
java

Page page = new Page(document);
```

3. 创建组件对象

```
java

Textarea textarea = new Textarea(page);
```

4. 渲染组件

```
java

textarea.render();
```

5. 添加页面

```
java

document.appendPage(page);
```

6. 保存文档

```
java

document.save(outputPath);
```

7. 关闭文档

```
java

document.close();
```

**完整示例**

```
java

// 定义pdf输出路径
String outputPath = "E:\\PDF\\pdfbox\\test.pdf";

// 创建文档
Document document = PdfHandler.getDocumentHandler().create();
// 设置字体
document.setFontName("微软雅黑");

// 创建页面
Page page = new Page(document);

// 创建文本域
Textarea textarea = new Textarea(page);
// 设置文本
textarea.setText("Hello World!");
// 渲染文本
textarea.render();

// 添加页面
document.appendPage(page);
// 保存文档
document.save(outputPath);
// 关闭文档
document.close();
```

#### 编辑文档

以第一页添加文本为例

1. 读取文档

```
java

Document document = PdfHandler.getDocumentHandler().load(sourcePath);
```

2. 获取页面对象

```
java

Page page = document.getPage(0);
```

3. 创建组件对象

```
java

Textarea textarea = new Textarea(page);
```

4. 渲染组件

```
java

textarea.render();
```

5. 保存文档

```
java

document.save(outputPath);
```

6. 关闭文档

```
java

document.close();
```

**完整示例**

```
java

// 定义pdf源路径
String sourcePath = "E:\\PDF\\pdfbox\\test.pdf";
// 定义pdf输出路径
String outputPath = "E:\\PDF\\pdfbox\\newTest.pdf";

// 读取文档
Document document = PdfHandler.getDocumentHandler().load(sourcePath);

// 获取页面
Page page = document.getPage(0);

// 创建文本域
Textarea textarea = new Textarea(page);
// 设置X轴起始坐标
textarea.setBeginX(100F);
// 设置Y轴起始坐标
textarea.setBeginY(100F);
// 设置文本
textarea.setText("Hello World!");
// 渲染文本
textarea.render();

// 保存文档
document.save(outputPath);
// 关闭文档
document.close();
```

**实战**

1. 基础 PDF 创建

```
java

// 创建文档
Document document = PdfHandler.getDocumentHandler().create();
// 设置使用字体
document.setFontName("微软雅黑");
// 创建页面
Page page = new Page(document);
// 创建文本域
Textarea textarea = new Textarea(page);
// 设置文本
textarea.setText("Hello World!");
// 渲染文本
textarea.render();
// 添加页面
document.appendPage(page);
// 保存文档
/Users/zhangni/liushiGong
// 关闭文档
document.close();
```

2. 多张图片合并为 PDF

```
java

public static File imagesToPdf(List<File> imageFiles, File targetPdfFilePath) {
    if (CollUtil.isNotEmpty(imageFiles) && targetPdfFilePath != null) {
        XEasyPdfDocument document = XEasyPdfHandler.Document.build();
        
        imageFiles.stream().forEachOrdered(imageFile -> {
            XEasyPdfComponent xEasyPdfImage = toEasyPdfImage(imageFile);
            XEasyPdfPage newPage = customNewPageByImage(imageFile);
            newPage.addComponent(xEasyPdfImage);
            document.addPage(newPage);
        });
        
        document.save(new FileOutputStream(targetPdfFilePath)).close();
        return targetPdfFilePath;
    }
    return null;
}
```

## 使用 AI 解析文档内容

3.3.0 版本的 AI 功能为文档解析带来了革命性变化：

```
java

// 解析图像示例
@Test
public void parseImageWithPageTest() {
    String ak = System.getenv("ak");
    String sk = System.getenv("sk");
    Document document = PdfHandler.getDocumentHandler().load("E:\\\\PDF\\\\pdfbox\\\\allTest.pdf");
    TencentAIParser parser = PdfHandler.getDocumentAIParser(document).getTencentAI(ak, sk, false);
    AIParseInfo info = parser.parseImageWithPage(
        "根据'这是一张XXX地点XXX的图片'的格式描述图片展示的内容，说出具体的城市，使用中文回答", 
        0, 1
    );
    log.info("返回内容：\n" + info.getResult());
    document.close();
}

// 解析文本示例
@Test
public void parseTextWithDocumentTest() {
    String ak = System.getenv("ak");
    String sk = System.getenv("sk");
    Document document = PdfHandler.getDocumentHandler().load("E:\\PDF\\pdfbox\\allTest.pdf");
    TencentAIParser parser = PdfHandler.getDocumentAIParser(document).getTencentAI(ak, sk, true);
    AIParseInfo info = parser.parseTextWithDocument("提取表格内容，以json格式返回");
    log.info("返回内容：\n" + info.getResult());
    document.close();
}
```

## 实际应用场景

x-easypdf 在实际应用中能帮助开发人员快速构建和编辑 PDF 文件，特别适用于以下场景：

* 生成大量 PDF 文档：如报表、合同等文档
* 数据分析报告：自动化生成标准化的分析报告
* 运维巡检报告：定期生成系统巡检文档
* 资源统计报告：将资源数据可视化输出
* 性能测试报告：自动化生成测试结果报告

## 总结

x-easypdf 作为一款 高效易用的 PDF 构建工具，通过简化 PDF 操作流程，提供了丰富的 API 接口和功能。3.3.0 版本加入的 AI 能力 更是让其如虎添翼，为 PDF 文档处理开辟了新的可能性。

**主要优势：**

* 简单易用的 API 设计，降低学习成本
* 组件化架构，灵活扩展
* 强大的模板支持，满足多样化需求
* AI 加持，智能解析文档内容
* 活跃的社区和持续的更新

如果你正在寻找一个功能强大、易于使用的 Java PDF 处理方案，x-easypdf 绝对值得一试。无论是简单的文档生成，还是复杂的批量处理，它都能成为你开发工作中的得力助手。