XXL-RPC 框架使用手册

---

🚀 XXL-RPC 框架使用手册

📖 项目概述

XXL-RPC 是一个高性能、分布式的RPC服务开发框架，提供稳定高效的RPC功能。支持"高性能、分布式、服务注册、负载均衡、服务治理"等特性，是一个开箱即用的企业级RPC框架。
XXL-RPC Logo

---

🎯 核心特性

✨ 亮点功能

•🏃 高性能 ：基于Netty通信框架，支持TCP/HTTP协议•🌐 分布式 ：支持服务注册与发现，负载均衡•🔧 易集成 ：支持Spring Boot、原生Java等多种集成方式•📊 服务治理 ：提供服务监控、熔断、限流等功能•🔌 多协议 ：支持TCP、HTTP、RESTful等多种调用方式•📦 多序列化：支持JSONB、Hessian、KRYO、PROTOSTUFF等序列化方案

🏗️ 架构组件

组件	说明
Provider	服务提供者，负责RPC服务的暴露和调用处理
Invoker	服务调用者，负责RPC服务的远程调用
Serializer	序列化组件，支持多种序列化方案
Remoting	通信组件，支持Netty/TCP、Netty/HTTP、Jetty、Mina等
Registry	注册中心，支持XXL-RPC Admin、ZooKeeper、Local等

---

🛠️ 快速开始

环境要求

•JDK ：1.8+•Maven ：3+•XXL-CONF：1.9.0+（服务注册中心）

第一步：启动XXL-CONF配置中心

# 拉取XXL-CONF镜像docker pull xuxueli/xxl-conf-admin# 启动配置中心docker run -p 8080:8080-v /tmp/data:/applogs --name xxl-conf-admin -d xuxueli/xxl-conf-admin# 访问管理界面# http://localhost:8080/xxl-conf-admin

第二步：Maven依赖配置

<dependency><groupId>com.xuxueli</groupId><artifactId>xxl-rpc-core</artifactId><version>${version}</version></dependency>

第三步：服务提供者配置

application.properties

# XXL-CONF 配置中心地址xxl.conf.admin.address=http://localhost:8080/xxl-conf-adminxxl.conf.admin.accesstoken=defaultaccesstoken# XXL-RPC 基础配置xxl.rpc.base.env=testxxl.rpc.base.appname=xxl-rpc-sample-springboot-serverxxl.rpc.invoker.enable=false# XXL-RPC Provider 配置xxl.rpc.provider.enable=truexxl.rpc.provider.server=com.xxl.rpc.core.remoting.impl.netty.server.NettyServerxxl.rpc.provider.serializer=com.xxl.rpc.core.serializer.impl.JsonbSerializerxxl.rpc.provider.port=7080

第四步：服务接口定义

// 1. 定义服务接口publicinterfaceDemoService{UserDTO load(String name);}// 2. 实现服务接口@XxlRpcService@ServicepublicclassDemoServiceImplimplementsDemoService{@OverridepublicUserDTO load(String name){returnnewUserDTO(name,"hello world");}}

第五步：服务消费者配置

application.properties

# XXL-RPC Consumer 配置xxl.rpc.base.env=testxxl.rpc.base.appname=xxl-rpc-sample-springboot-clientxxl.rpc.provider.enable=falsexxl.rpc.invoker.enable=truexxl.rpc.invoker.client=com.xxl.rpc.core.remoting.impl.netty.client.NettyClientxxl.rpc.invoker.serializer=com.xxl.rpc.core.serializer.impl.JsonbSerializer

// 服务引用@XxlRpcReference(appname ="xxl-rpc-sample-springboot-server")privateDemoService demoService;// 调用服务UserDTO user = demoService.sayHi("jack");

---

🎮 高级功能

🔧 调用方式

调用方式	特点	适用场景
SYNC	同步调用，阻塞等待结果	普通业务场景
FUTURE	异步调用，返回Future对象	需要异步处理的场景
CALLBACK	回调调用，结果通过回调返回	事件驱动的场景
ONEWAY	单向调用，不等待结果	日志记录、消息通知等

🌐 通用服务调用

// 通用服务调用示例XxlRpcGenericService genericService =...;String result = genericService.$invoke("com.xxl.rpc.sample.server.service.generic.DemoService",,"addUser",newString[]{"com.xxl.rpc.sample.server.service.generic.UserDTO"},newObject[]{Map.of("name","jack2","word","[SYNC]jack - Generic2")});

📊 性能监控

XXL-RPC提供了完整的性能监控功能：

•QPS监控 ：实时监控服务调用量•响应时间 ：统计接口响应时间分布•成功率 ：监控服务调用成功率•错误统计：详细记录错误信息和堆栈

---

🚨 最佳实践

✅ 推荐配置

生产环境配置建议：

# 线程池配置xxl.rpc.provider.corePoolSize=60xxl.rpc.provider.maxPoolSize=300xxl.rpc.provider.queueCapacity=1000# 超时配置xxl.rpc.invoker.timeout=3000xxl.rpc.provider.readTimeout=5000# 重试配置xxl.rpc.invoker.retryCount=2

序列化选择建议：

•JSONB ：兼容性好，性能中等，推荐用于接口调试•Hessian ：性能优秀，推荐用于生产环境•PROTOSTUFF：性能最佳，推荐用于对性能要求极高的场景

⚠️ 注意事项

1.服务版本管理 ：建议使用版本号管理服务接口变更2.超时设置 ：合理设置超时时间，避免雪崩效应3.熔断降级 ：配置熔断策略，提高系统稳定性4.监控告警 ：配置关键指标监控，及时发现问题5.日志记录：合理配置日志级别，便于问题排查

---

🆘 故障排查

常见问题

Q1：服务注册失败

解决方案：1.检查XXL-CONF配置中心是否正常启动2.验证网络连接和防火墙设置3.确认access_token配置正确

Q2：调用超时

解决方案：1.检查网络延迟和服务器负载2.调整超时配置参数3.优化服务端处理逻辑

Q3：序列化异常

解决方案：1.确认客户端和服务端序列化方式一致2.检查依赖版本兼容性3.验证对象序列化兼容性

---

📈 性能基准

测试环境：

•服务器：4核8G，SSD硬盘•网络：千兆局域网•并发：100连接持续10秒

测试结果：

•QPS ：3万+•平均响应时间 ：0.1ms•99.9%响应时间 ：0.5ms•成功率：99.99%

---

🔄 版本迭代

版本	发布时间	主要特性
v2.2.1	2025-01-09	最新稳定版，性能优化
v2.2.0	2024-12-21	框架重构，架构升级
v2.1.0	2024-11-24	支持Spring Boot 3.x
v1.8.0	2023-12-24	添加服务治理功能

---

🤝 社区支持

•GitHub ：https://github.com/xuxueli/xxl-rpc•**Gitee** ：https://gitee.com/xuxueli0323/xxl-rpc•**官方文档** ：https://www.xuxueli.com/xxl-rpc/•**社区交流**：https://www.xuxueli.com/page/community.html

---

📄 开源协议

本项目基于 Apache License 2.0 协议开源，欢迎社区贡献和反馈。

---

💡 温馨提示：XXL-RPC经过多年生产环境验证，在多个大型企业得到广泛应用。如果您在使用过程中遇到问题，欢迎通过GitHub Issues反馈，我们将及时为您解答。

---

希望这份使用手册能帮助您快速上手XXL-RPC框架！🎉