# socketmvc 即时通信框架

**Repository Path**: xueyanjun/socketmvc

## Basic Information

- **Project Name**: socketmvc 即时通信框架
- **Description**: socketmvc 是一款简单易用的即时通信框架
支持tcp ，websocket
单机支持30万+在线
- **Primary Language**: Java
- **License**: BSD-3-Clause
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2022-04-06
- **Last Updated**: 2025-09-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

---

## 🚀 SocketMVC

SocketMVC 是一个基于 Java 的高性能网络通信框架，专注于为 WebSocket 和 TCP/UDP 协议下的实时消息交互提供一套优雅、高效的解决方案。其设计理念深受 **Spring MVC** 启发 —— 正如 Spring MVC 简化了 HTTP 接口开发，SocketMVC 则致力于简化 WebSocket 与 TCP 协议下的消息处理流程。

> **SocketMVC = WebSocket/TCP + Spring MVC 风格开发体验**

你可以像写 Web 接口一样来编写 WebSocket 或 TCP 消息处理器，享受注解驱动、参数自动解析、命令路由等便利特性。

---

## 📌 为什么叫 SocketMVC？

SocketMVC 的命名源自我个人对经典架构模式的致敬：

- **Spring MVC** 解决了 HTTP 请求的路由、参数解析和控制器处理问题；
- 而 **SocketMVC** 将这一思想带入到 WebSocket 和 TCP 通信领域中，通过命令路由（Command Mapping）机制，将指令字符串与业务处理器绑定，支持类似 Spring MVC 的注解驱动开发风格。
- 使用 @SocketControl 注解实现类级别的路由
- 通过 @SocketCommand 实现方法级别的指令映射
- 支持类似 SpringMVC 的参数解析机制（@SocketParam）
- 提供过滤器链等扩展机制

例如，你可以这样定义一个消息处理器：

```java
@SocketControl("/chat")
public class DemoProcessor {

    @SocketCommand("/p1")
    public int p1(@SocketParam("age") Integer age, @SocketParam("name") String name, SocketChannel context) {
        return age;
    }
}
```

不仅如此，SocketMVC 还支持参数自动解析、过滤器链、心跳机制等高级特性，让开发者在编写实时通信逻辑时更加得心应手。

---

## 🧩 模块说明

SocketMVC 采用模块化设计，结构清晰，易于扩展：

| 模块名称 | 功能说明 |
|----------|----------|
| `socketmvc-client` | 提供客户端功能，支持连接建立、消息发送与接收、协议编解码 |
| `socketmvc-core` | 核心功能模块，包含消息处理、协议定义、异常管理以及通用工具类 |
| `socketmvc-server` | 服务端实现模块，支持 TCP、WebSocket 通信，具备连接管理、消息路由能力 |
| `socketmvc-spring-support` | 提供与 Spring 框架的深度集成，支持自动配置、处理器注册及上下文管理 |

---

## ✨ 主要特性

- **多协议支持**：支持 JSON、GZIP、Base64、HEX（16进制）等多种数据格式编解码。
- **消息处理机制**：内置消息处理器，支持命令路由、参数解析、过滤链、心跳检测等。
- **高性能异步通信**：底层基于 TIO 高性能网络框架，支持大规模并发连接。
- **文件传输能力**：支持二进制文件及多文件的传输。
- **Spring 集成友好**：提供与 Spring Boot 的无缝集成，简化配置和启动流程。
- **过滤器链（Filter Chain）支持**：灵感来源于 Servlet Filter，允许开发者插入自定义逻辑（如身份认证、日志记录、权限控制等）。

---

## 🧱 过滤器链（Filter Chain）支持

SocketMVC 提供了强大的 **过滤器链机制（Filter Chain）**，灵感来源于 Java Web 中的 Servlet Filter 设计，允许开发者在消息到达业务处理器之前或之后插入自定义逻辑，从而实现诸如身份验证、权限控制、日志记录、请求拦截等全局处理逻辑。

### 🔧 自定义 Filter 示例

```java
// 身份认证过滤器
public class AuthenticationFilter extends AbstractFilter {

    private final Logger logger = LoggerFactory.getLogger(AuthenticationFilter.class);

    @Override
    public void doFilter(IContext context, Object other, IFilterChain filterChain) {
        IPacket packet = context.getPacket();

        // 身份认证逻辑（这里简单假设某个属性不为空就认为验证通过，实际不应该这么写）
        if (context.getAttr("u-token") != null) {
            filterChain.doFilter(context, other);
            return;
        }
        // 身份验证未通过，关闭连接
        context.close();
    }

    @Override
    public String path() {
        return "/*"; // 表示匹配所有命令路径
    }

    @Override
    public short order() {
        return 0; // 排序优先级，值越小越早执行
    }
}
```

### ✅ Filter 的关键能力：

- **路径匹配**：支持类似 `/*`、`/chat/*` 等通配符路径配置。
- **顺序控制**：通过 `order()` 方法定义执行顺序，确保多个 Filter 按照预期顺序执行。
- **可插拔设计**：新增 Filter 不需要修改已有逻辑，符合开闭原则，便于系统扩展。

### 🧩 典型应用场景：

- **身份认证**：在请求到达处理器前校验用户身份令牌。
- **日志记录**：记录每次请求的命令、参数、耗时等信息。
- **权限控制**：根据角色限制某些命令的访问权限。
- **请求拦截**：对特定命令进行预处理或拒绝非法请求。
- **性能监控**：统计每个命令的调用次数与执行时间。

---

## 🚀 使用场景

SocketMVC 特别适合以下类型的项目：

- 实时聊天系统
- 即时通讯应用
- 在线游戏服务器
- 需要长连接和实时数据推送的物联网（IoT）系统
- 需要自定义 TCP/UDP 协议交互的企业级系统

---

## ⚙️ 安装与配置

### 前置条件

- Java 1.8 或以上版本
- Maven 3.0 或以上版本
- 若需集成 Spring，建议使用 Spring Boot

### 构建项目

```bash
mvn clean package
```

---

## 🧪 快速开始

### 启动服务端

```java
public class Bootstrap {
    public static void main(String[] args) throws Exception {
        // 配置并启动服务
        SocketServerStarter serverStarter = new SocketServerStarter(new MySocketMvcConfig());
        serverStarter.start();
    }
}
```

### 启动客户端

```java
SocketMvcConfig mvcConfig = new DefMvcConfig();
WsClient wsClient = new WsClient(mvcConfig);
wsClient.connect();
```

---

## 📦 示例代码

### 消息处理器示例

```java
@SocketControl("/chat")
public class DemoProcessor {

    @SocketCommand("/p1")
    public int p1(@SocketParam("age") Integer age, @SocketParam("name") String name, SocketChannel context) {
        // 处理消息
        return age;
    }

    @SocketCommand("/p2")
    public int p2(@SocketParam("age") Integer age, SocketChannel context) {
        return age * 2;
    }
}
```

---

## 🧨 异常体系

SocketMVC 提供完善的异常处理机制：

- `SocketNotConnectedException`：当客户端未连接时抛出。
- `ResponseException`：响应消息异常时抛出。
- `ProcessorExecException`：执行处理器方法时发生错误时抛出。
- `AmbiguousProcessorMethodCommandException`：处理器存在模糊方法命令异常。
- `SockFileIOException`：处理器解析参数为FILE时异常。
...更多
---

## 🛠 开发者支持

- **日志系统**：支持标准 Logger 记录调试与运行日志。
- **编解码器**：提供多种编解码实现，如 `JsonGzipTextContentCodec`。
- **上下文管理**：提供线程安全的上下文管理类 `ThreadSocketChannelHandler`。

---

## 🤝 贡献代码

欢迎贡献代码和提交 Issues！请遵守开源协议，提交 Pull Request 前确保代码通过测试并符合编码规范。

---

## 📜 协议

本项目使用 [BSD-3-Clause License](LICENSE)，请查看 LICENSE 文件了解更多细节。

---

## 📬 联系方式 & 社区支持

如果你有任何疑问或建议，欢迎通过以下方式联系作者交流：
- [GitHub](https://github.com/xueyanjun1992/socketmvc)/[Gitee](https://gitee.com/xueyanjun/socketmvc) Issues
- 邮箱：15024702174@163.com

---

> SocketMVC 是一个轻量、高效、可扩展的实时通信框架，适用于各类需要长连接和即时消息交互的场景。无论你是构建企业级通信系统还是个人学习项目，SocketMVC 都将是你的理想选择。

--- 

再次强调一下这个项目的亮点：

> **SocketMVC = WebSocket/TCP + Spring MVC 风格开发体验**  
> 如果你熟悉 Spring MVC 的编程模型，那么你会觉得 SocketMVC 的使用几乎零学习成本。

---