如果你需要一个体积小、依赖少、能够直接运行在 JDK NIO 之上的 Java Web 框架，wastnet MVC 提供了一条值得尝试的路径。它不是把现成容器、HTTP 服务器和一堆第三方组件拼接在一起，而是从 Reactor 多路复用模型出发，自主实现网络层，并在此基础上提供注解驱动的 MVC 和轻量 IoC 能力。
这篇文章围绕一个简单的用户接口服务，说明如何组织 Controller、Endpoint、参数处理和 HTTP 调用。由于 wastnet 的具体 API 可能随版本变化，示例中的启动类和方法签名应以项目实际版本为准；Controller 结构和调用方式可以直接作为改造起点。
从网络层到 MVC 层
wastnet 的底层核心基于 JDK 原生 NIO 和 Reactor 多路复用模型。连接接入、读写事件和请求处理可以在较少线程的情况下完成，这种设计适合轻量 API、内部服务和对部署依赖敏感的场景。
它还自主实现了 HTTP/2 相关能力，包括 HPACK、Huffman 编码和 ALPN 协商。对业务开发者而言，这些细节通常被隐藏在服务器层，但它们决定了框架能否在不依赖成熟 HTTP 容器的情况下处理现代 Web 协议。
wastnet-mvc 则把底层能力转换成更熟悉的开发模型：
@Controller标记控制器组件。@Endpoint暴露 HTTP 接口。- 轻量 IoC 负责发现并管理控制器实例。
- 请求参数和响应对象由 MVC 层完成绑定与转换。
这种分层方式很重要。业务代码不应该直接操作 NIO 的 Selector、字节缓冲区或 HTTP/2 帧；网络层负责连接和协议，MVC 层负责路由与参数，Controller 负责业务决策。
设计一个最小接口
下面是一个可以按实际 wastnet MVC 版本调整的控制器示例。假设项目支持 @Controller 和 @Endpoint，并允许通过方法参数接收查询参数：
package example.web;
import java.util.Map;
@Controller
public class UserController {
@Endpoint("GET /api/users/{id}")
public Map<String, Object> findUser(String id) {
return Map.of(
"id", id,
"name", "Ada",
"active", true
);
}
}
不同版本可能把路径、HTTP 方法和参数绑定拆分成多个注解，例如使用 @Endpoint(path = "/api/users/{id}", method = "GET")，或者通过单独的路径参数注解声明 id。遇到这种差异时，优先查看 wastnet-mvc 的注解定义和示例工程，不要在 Controller 中自行解析原始 URI。
如果你要先验证接口链路，可以把响应先保持为简单的 Map 或 DTO，再逐步加入服务层。接口稳定后，再将数据访问代码从 Controller 中移出：
package example.service;
public class UserService {
public User findById(String id) {
return new User(id, "Ada", true);
}
public record User(String id, String name, boolean active) {
}
}
Controller 的职责应该是接收请求、调用服务、返回结果，而不是同时负责 SQL、业务校验、日志拼接和错误格式化。轻量框架并不意味着所有代码都应该集中在一个类里。
启动服务与验证请求
wastnet 的启动 API 需要以当前版本提供的入口类为准。可以采用下面这种启动结构作为改造模板：
package example;
public final class Application {
public static void main(String[] args) {
// 按 wastnet 版本替换为实际的 MVC 应用启动器。
// 启动时需要指定 Controller 扫描包和监听端口。
WastnetMvc.start(
WastnetMvc.builder()
.scan("example.web")
.port(8080)
.build()
);
}
}
如果当前版本不是 Builder 风格，而是通过配置对象或静态启动方法创建应用，调整启动部分即可，Controller 仍然保持相同的边界。启动成功后，可以使用 curl 检查路由：
curl --request GET \
--url http://127.0.0.1:8080/api/users/42 \
--header 'Accept: application/json'
预期响应可以是：
{
"id": "42",
"name": "Ada",
"active": true
}
如果返回 404，排查顺序应当是：Controller 是否位于扫描包内、类是否被 @Controller 标记、Endpoint 的 HTTP 方法和路径是否匹配，以及应用是否真的监听了预期端口。不要一开始就怀疑 NIO 或 HTTP/2；大多数首次接入问题发生在组件扫描和路由声明上。
把接口做成可维护的服务
参数校验要靠近入口
路径参数、查询参数和 JSON 请求体都属于外部输入。即便 MVC 层已经完成类型转换，业务仍然需要检查空值、格式和范围。例如用户 ID 应该在进入服务层前完成基本校验：
@Endpoint("GET /api/users/{id}")
public Map<String, Object> findUser(String id) {
if (id == null || id.isBlank()) {
throw new IllegalArgumentException("id must not be blank");
}
return userService.findView(id);
}
真实项目中建议建立统一异常处理策略，把参数错误转换成稳定的 HTTP 状态码和 JSON 错误结构。不要让异常堆栈直接泄漏给客户端，也不要让每个 Endpoint 手写一套错误响应。
先确认线程模型，再决定阻塞操作
Reactor 事件循环适合处理网络事件，但数据库查询、文件读写和远程 HTTP 调用可能是阻塞操作。不要因为框架底层使用 NIO，就默认所有业务代码都可以安全地在事件循环线程中执行。
落地时应确认以下问题：
- Endpoint 方法由哪个线程执行。
- 是否提供业务线程池或异步调度机制。
- 阻塞数据库驱动是否需要切换执行器。
- 超时、取消和连接关闭如何传播。
如果框架没有内置业务线程池，可以在边界处显式封装执行器，但要控制队列长度和拒绝策略，避免请求积压最终拖垮整个事件循环。
HTTP/2 不是免费性能
wastnet 自主实现 HTTP/2 协议栈是一项底层能力，但是否启用 HTTP/2，应由客户端兼容性、TLS、代理链路和监控能力共同决定。接口服务上线前，至少应验证：
- ALPN 协商是否符合部署环境。
- 反向代理是否透传或终止 HTTP/2。
- HPACK 动态表和请求头大小限制是否合理。
- HTTP/1.1 客户端是否仍有兼容路径。
不要只因为协议版本更高就直接切换生产流量。先用小流量或测试环境验证连接复用、错误日志和压测结果。
一份接入检查清单
- 确认 wastnet 核心版本与 wastnet-mvc 版本匹配。
- 明确 Controller 扫描包，避免组件没有被发现。
- 为每个 Endpoint 明确 HTTP 方法、路径和输入类型。
- 将业务逻辑放进 Service，不让 Controller 变成巨型类。
- 为异常建立统一的 HTTP 状态码和响应格式。
- 检查阻塞操作是否运行在合适的线程池中。
- 使用
curl或集成测试覆盖 2xx、4xx 和 5xx 场景。 - 在启用 HTTP/2 前验证 ALPN、代理和客户端兼容性。
wastnet MVC 的价值在于把一个自研 NIO 网络核心收敛成可使用的接口开发模型。它适合希望减少依赖、理解网络层边界，或者需要轻量部署形态的团队。采用时要接受相应的工程成本：生态和资料可能不如成熟框架丰富，版本 API 也需要通过源码和示例确认。稳妥的路径是先用一个小型只读接口验证扫描、路由、参数绑定和线程模型，再逐步接入数据库、鉴权和生产流量。