koatty_router

Koatty路由组件，支持HTTP1/2、WebSocket、gRPC和GraphQL协议的统一路由管理。

特性

- 🚀 多协议支持 - HTTP、HTTPS、HTTP/2、HTTP/3、WebSocket、gRPC、GraphQL
- 🏭 工厂模式 - 灵活的路由器创建和管理
- 🔧 中间件管理器 - 统一的中间件注册、组合和条件执行
- 📝 参数验证 - 强大的输入验证和DTO支持
- 🎯 装饰器支持 - 简洁的路由定义和参数注入
- ⚡ 高性能 - 优化的payload解析和路由匹配
- 🌊 gRPC流处理 - 完整支持四种gRPC流类型，包括自动检测、背压控制和并发管理

安装

``bash
npm install koatty_router
`

快速开始

$3

`typescript
import { NewRouter } from "koatty_router";
import { Koatty } from "koatty_core";

const app = new Koatty();

// 创建HTTP路由器
const httpRouter = NewRouter(app, {
protocol: "http",
prefix: "/api"
});

// 创建WebSocket路由器
const wsRouter = NewRouter(app, {
protocol: "ws",
prefix: "/ws",
ext: {
maxFrameSize: 1024 * 1024,
heartbeatInterval: 15000,
maxConnections: 1000
}
});

// 创建gRPC路由器
const grpcRouter = NewRouter(app, {
protocol: "grpc",
prefix: "/grpc",
ext: {
protoFile: "./proto/service.proto",
poolSize: 10,
streamConfig: {
maxConcurrentStreams: 50,
streamTimeout: 60000
}
}
});
`

$3

`typescript
import { Get, Post, Controller } from "koatty_router";

@Controller("/user")
export class UserController {

@Get("/profile")
async getProfile(@Get("id") id: string) {
return { id, name: "用户" };
}

@Post("/create")
async createUser(@Post() userData: UserDTO) {
return { success: true };
}
}
`

路由器工厂模式

`typescript
import { RouterFactory, RegisterRouter } from "koatty_router";

const factory = RouterFactory.getInstance();

// 获取支持的协议
console.log(factory.getSupportedProtocols());
// ['http', 'https', 'ws', 'wss', 'grpc', 'graphql']

// 创建路由器
const router = factory.create("http", app, { prefix: "/api" });

// 注册自定义路由器
@RegisterRouter("mqtt")
class MqttRouter implements KoattyRouter {
// 自定义路由器实现
}
`

中间件管理

RouterMiddlewareManager 专注于路由级别的中间件注册、组合和条件执行，支持基于路由的独立配置。

$3

- 🎯 路由级别隔离 - 每个路由的中间件实例独立配置
- 🔧 智能实例管理 - 使用 ${middlewareName}@${route}#${method} 格式的唯一标识
- ⚡ 预组合优化 - 注册时组合中间件，提升运行时性能
- 🔄 异步中间件类 - 完整支持异步 run 方法

$3

`typescript
import { Middleware } from "koatty_router";

@Middleware()
export class AuthMiddleware {
async run(config: any, app: Application) {
return async (ctx: KoattyContext, next: KoattyNext) => {
console.log('Auth middleware executed');
ctx.authChecked = true;
await next();
};
}
}
`

$3

#### 1. 基础中间件配置

`typescript
// 控制器级别中间件
@Controller('/api', [AuthMiddleware])
export class UserController {

@GetMapping('/users')
getUsers() {
return 'users list';
}

// 方法级别中间件
@GetMapping('/admin', {
middleware: [RateLimitMiddleware]
})
adminAction() {
return 'admin action';
}
}
`

#### 2. 高级中间件配置

使用 withMiddleware 函数配置优先级、条件、元数据等高级特性：

`typescript
import { withMiddleware } from 'koatty_router';

@Controller('/api')
export class UserController {

@GetMapping('/users', {
middleware: [
withMiddleware(AuthMiddleware, {
priority: 100,
metadata: { role: 'admin' }
}),
withMiddleware(RateLimitMiddleware, {
priority: 90,
conditions: [
{ type: 'header', value: 'x-api-key', operator: 'contains' }
]
})
]
})
getUsers() {
return 'users list';
}

// 条件中间件
@PostMapping('/admin', {
middleware: [
withMiddleware(AuthMiddleware, {
priority: 100,
conditions: [
{ type: 'header', value: 'x-admin-token', operator: 'contains' }
]
})
]
})
adminAction() {
return 'admin action';
}
}
`

#### 3. 中间件元数据配置

通过 metadata 为中间件传递配置参数：

`typescript
@GetMapping('/rate-limited', {
middleware: [
withMiddleware(RateLimitMiddleware, {
priority: 100,
metadata: {
limit: 100, // 每分钟最大请求数
window: 60000, // 时间窗口（毫秒）
keyGenerator: 'ip' // 限流键生成策略
}
})
]
})
rateLimitedEndpoint() {
return 'rate limited endpoint';
}
`

中间件类接收配置：

`typescript
class RateLimitMiddleware {
async run(config: any, app: any) {
const {
limit = 60,
window = 60000,
keyGenerator = 'ip'
} = config;

return async (ctx: KoattyContext, next: KoattyNext) => {
const key = keyGenerator === 'ip' ? ctx.ip : ctx.user?.id;

if (await this.isRateLimited(key, limit, window)) {
ctx.status = 429;
ctx.body = { error: 'Rate limit exceeded' };
return;
}

await next();
};
}
}
`

#### 4. 中间件禁用和添加功能

通过 enabled: false 配置可以禁用中间件的执行：

控制器级别禁用：控制器下所有路由都不执行该中间件
方法级别禁用：只有该方法不执行指定的中间件（仅限控制器已声明的中间件）
方法级别添加：可以添加控制器未声明的中间件，仅在该方法中生效

`typescript
@Controller('/api', [
AuthMiddleware,
withMiddleware(RateLimitMiddleware, { enabled: false }), // 控制器级别禁用
LoggingMiddleware
])
export class UserController {

@Get('/users')
async getUsers() {
// 执行 AuthMiddleware 和 LoggingMiddleware
}

@Post('/users', [
withMiddleware(AuthMiddleware, { enabled: false }), // 方法级别禁用
ValidationMiddleware // 方法级别添加
])
async createUser() {
// 执行 LoggingMiddleware 和 ValidationMiddleware
}

@Put('/users/:id', [
withMiddleware(AuthMiddleware, { enabled: false }), // 禁用认证
withMiddleware(AdminAuthMiddleware, { priority: 80 }) // 添加管理员认证
])
async updateUser() {
// 只执行 AdminAuthMiddleware
}
}
`

优先级规划建议：
- 100+: 认证和授权中间件
- 90-99: 限流和安全中间件
- 80-89: 验证和数据处理中间件
- 70-79: 日志和监控中间件
- 50-69: 业务逻辑中间件

参数验证和注入

$3

`typescript
import { Get, Post, Header, PathVariable, File } from "koatty_router";

@Controller("/api")
export class ApiController {

@Get("/user/:id")
async getUser(
@PathVariable("id") id: string,
@Get("include") include?: string,
@Header("authorization") token?: string
) {
return { id, include, token };
}

@Post("/upload")
async upload(
@File("file") file: any,
@Post() metadata: any
) {
return { filename: file.name, metadata };
}
}
`

$3

`typescript
import { IsString, IsNumber, IsEmail } from "koatty_validation";

export class UserDTO {
@IsString()
name: string;

@IsNumber()
age: number;

@IsEmail()
email: string;
}

@Controller("/user")
export class UserController {
@Post("/create")
@Validated()
async create(@Post() user: UserDTO) {
return user;
}
}
`

协议特定功能

$3

`typescript
@GrpcController()
export class StreamController {

// 服务器流
async serverStream(ctx: any) {
for (let i = 0; i < 10; i++) {
ctx.writeStream({ data: Message ${i} });
await new Promise(resolve => setTimeout(resolve, 100));
}
ctx.endStream();
}

// 双向流
async bidirectionalStream(ctx: any) {
if (ctx.streamMessage) {
const response = processMessage(ctx.streamMessage);
ctx.writeStream(response);
}
}
}
`

gRPC 流特性：
- 🔄 自动流类型检测 - 无需手动指定流类型
- 🚦 背压控制 - 防止内存溢出和性能问题
- ⚡ 并发管理 - 限制同时活跃的流数量

配置选项

$3

`typescript
interface RouterOptions {
prefix: string; // 路由前缀
protocol?: string; // 协议类型
methods?: string[]; // 支持的HTTP方法
sensitive?: boolean; // 大小写敏感
strict?: boolean; // 严格匹配
payload?: PayloadOptions; // 载荷解析选项
ext?: Record; // 协议特定扩展配置
}
`

$3

#### WebSocket 配置
`typescript
ext: {
maxFrameSize?: number; // 最大分帧大小(字节)，默认1MB
heartbeatInterval?: number; // 心跳检测间隔(ms)，默认15秒
heartbeatTimeout?: number; // 心跳超时时间(ms)，默认30秒
maxConnections?: number; // 最大连接数，默认1000
maxBufferSize?: number; // 最大缓冲区大小(字节)，默认10MB
}
`

#### gRPC 配置
`typescript
ext: {
protoFile: string; // Protocol Buffer 文件路径（必需）
poolSize?: number; // 连接池大小，默认10
batchSize?: number; // 批处理大小，默认10
streamConfig?: { // 流配置
maxConcurrentStreams?: number; // 最大并发流数量，默认50
streamTimeout?: number; // 流超时时间(ms)，默认60秒
backpressureThreshold?: number; // 背压阈值(字节)，默认2048
};
enableReflection?: boolean; // 是否启用反射，默认false
}
`

#### GraphQL 配置
`typescript
ext: {
schemaFile: string; // GraphQL Schema 文件路径（必需）
playground?: boolean; // 启用 GraphQL Playground，默认false
introspection?: boolean; // 启用内省查询，默认true
debug?: boolean; // 调试模式，默认false
depthLimit?: number; // 查询深度限制，默认10
complexityLimit?: number; // 查询复杂度限制，默认1000
}
`

最佳实践

$3

`typescript
// 框架级别的全局中间件（由Koatty框架管理）
// - 错误处理、请求日志、CORS处理、安全头设置

// 路由级别的中间件（由RouterMiddlewareManager管理）
const routeMiddlewareOrder = [
"paramValidation", // 100 - 参数验证
"routeAuth", // 90 - 路由认证
"routeCache", // 80 - 路由缓存
"rateLimit" // 70 - 限流控制
];
`

$3

`typescript
const protocolMap = {
"web-api": "http",
"real-time": "ws",
"microservice": "grpc",
"query-api": "graphql"
};
`

$3

在生产环境中，正确处理应用终止信号非常重要，特别是使用 WebSocket 或 gRPC 时。koatty_router 提供了完善的资源清理机制。

#### 自动清理（推荐）

路由器组件会自动注册到 Koatty 框架的 stop 事件，当应用收到 SIGTERM 或 SIGINT 信号时，框架会自动触发清理：

`typescript
import { NewRouter } from "koatty_router";
import { Koatty } from "koatty_core";

const app = new Koatty();

// 创建路由器（自动注册清理处理）
const wsRouter = NewRouter(app, {
protocol: "ws",
prefix: "/ws"
});

const grpcRouter = NewRouter(app, {
protocol: "grpc",
prefix: "/grpc",
ext: { protoFile: "./proto/service.proto" }
});

// 上层框架会在收到终止信号时自动调用清理
// 无需手动处理
`

#### 手动清理

在某些场景下，你可能需要手动控制清理时机：

`typescript
import { RouterFactory } from "koatty_router";

const factory = RouterFactory.getInstance();

// 获取活跃路由器数量
console.log(Active routers: ${factory.getActiveRouterCount()});

// 手动触发所有路由器的清理
await factory.shutdownAll();
`

#### 各协议路由器的清理行为

WebSocket 路由器：
- 清理所有活跃连接的定时器（心跳、超时检测）
- 清理定期维护定时器
- 释放连接缓冲区内存

gRPC 路由器：
- 关闭所有活跃的流
- 刷新批处理队列（处理待处理的请求）
- 清空连接池

HTTP/GraphQL 路由器：
- 无状态协议，无需特殊清理

#### Kubernetes 部署配置

`yaml
apiVersion: v1
kind: Pod
spec:
terminationGracePeriodSeconds: 60 # 给予足够时间清理资源
containers:
- name: app
lifecycle:
preStop:
exec:
# 可选：延迟确保负载均衡器已摘除节点
command: ["/bin/sh", "-c", "sleep 5"]
`

#### Docker Compose 配置

`yaml
version: '3.8'
services:
app:
image: your-app:latest
stop_grace_period: 60s # 设置停止等待时间
`

#### 清理流程

1. 接收信号：上层框架（Koatty）监听 SIGTERM/SIGINT
2. 停止接收新请求：关闭服务器监听端口
3. 触发清理：发出 stop` 事件
4. 路由器清理：按顺序清理所有活跃路由器
5. 完成退出：所有资源释放后正常退出进程

API文档

详细的API文档请参考：API Documentation

许可证

BSD-3-Clause