中间件系统

核心特性

中间件是 SDK 框架的核心功能之一，提供了强大的请求/响应拦截机制，让您可以在不修改业务逻辑的情况下，统一处理横切关注点。

中间件概述

中间件（Middleware）是一种设计模式，允许您在请求处理的生命周期中插入自定义逻辑。GMSSH 框架的中间件系统支持：

请求预处理：验证、转换、日志记录
权限控制：身份验证、授权检查
性能监控：耗时统计、性能分析
响应后处理：格式化、缓存、清理

基础用法

中间件接口规范

重要约定

中间件类必须继承 RPCMiddleware 基类
必须实现 process_request 和 process_response 方法
两个方法都必须返回处理后的数据，不能返回 None
通过 app.middleware() 方法注册中间件

方法	参数	返回值	说明
`process_request`	`request, context`	`request`	请求预处理，在路由函数执行前调用
`process_response`	`response, context`	`response`	响应后处理，在路由函数执行后调用

快速开始示例

# main.py - 基础中间件示例
import asyncio
from simplejrpc.app import ServerApplication
from simplejrpc.response import jsonify
from simplejrpc import RPCMiddleware

# 创建应用实例
app = ServerApplication("app.socket")

class BasicMiddleware(RPCMiddleware):
    """基础中间件示例"""
    
    def process_request(self, request, context):
        """请求预处理 - 在业务逻辑执行前调用"""
        print(f"🔍 [请求进入] {request}")
        # 可以在这里添加：参数验证、权限检查、请求日志等
        return request  # 必须返回处理后的 request
    
    def process_response(self, response, context):
        """响应后处理 - 在业务逻辑执行后调用"""
        print(f"📤 [响应返回] {response}")
        # 可以在这里添加：响应格式化、缓存、清理等
        return response  # 必须返回处理后的 response

# 注册中间件（支持注册多个中间件）
app.middleware(BasicMiddleware())

@app.route(name="hello")
async def hello(name: str = "World"):
    """简单的问候接口"""
    return jsonify(
        data=f"Hello, {name}!", 
        msg="请求处理成功"
    )

if __name__ == "__main__":
    asyncio.run(app.run())

最佳实践

设计原则

中间件设计建议

单一职责：每个中间件只负责一个特定功能
无状态设计：避免在中间件中保存全局状态
异常处理：妥善处理可能出现的异常情况
性能考虑：避免在中间件中执行耗时操作
可配置性：通过参数控制中间件行为

常见陷阱与解决方案

❌ 常见问题	✅ 解决方案	💡 说明
忘记返回数据	确保 `process_request` 和 `process_response` 都有返回值	返回 `None` 会导致请求中断
修改原始数据	使用深拷贝或创建新对象	避免影响其他中间件
阻塞操作	使用异步操作或线程池	保持高并发性能
异常未处理	添加 try-catch 块	防止中间件崩溃影响整个应用
顺序依赖	明确文档说明依赖关系	确保正确的注册顺序

总结

中间件是 GMSSH 框架的强大功能，通过合理使用中间件，您可以：

解耦业务逻辑：将横切关注点从业务代码中分离
增强安全性：统一处理身份验证和权限控制
提升可观测性：集中管理日志、监控和性能分析
提高开发效率：复用通用功能，减少重复代码

记住：好的中间件设计应该是轻量、专注、可复用的！

常见应用场景

场景概览

应用场景	功能描述	实现位置	使用示例
日志记录	记录请求响应详情	`process_request` + `process_response`	接口调用统计、错误追踪
身份验证	验证用户身份和权限	`process_request`	JWT 验证、API Key 检查
性能监控	统计接口响应时间	`process_request` + `process_response`	性能分析、慢查询监控
请求转换	统一请求格式	`process_request`	参数标准化、编码转换
响应格式化	统一响应结构	`process_response`	数据包装、错误码映射
缓存控制	实现响应缓存	`process_request` + `process_response`	Redis 缓存、内存缓存
限流控制	防止接口滥用	`process_request`	频率限制、IP 黑名单

实际应用：日志跟踪中间件

# main.py

import asyncio
from simplejrpc.app import ServerApplication
from simplejrpc.response import jsonify
from simplejrpc import RPCMiddleware
from loguru import logger


class LoggingMiddleware(RPCMiddleware):
    def process_request(self, request, context):
        logger.info(f"请求数据：{request}")
        return request

    def process_response(self, response, context):
        logger.info(f"响应数据：{response}")
        return response


app = ServerApplication("app.socket")
app.middleware(LoggingMiddleware())  # 注册日志中间件


@app.route(name="hello")
async def hello():
    return jsonify(data="hello world!", msg="OK")


if __name__ == "__main__":
    asyncio.run(app.run())

日志输出示例：

2025-05-15 10:42:47.527 | INFO     | __main__:process_request:30 - 请求数据：('{"jsonrpc": "2.0", "method": "hello", "id": 1}',)
2025-05-15 10:42:47.528 | INFO     | __main__:process_response:34 - 响应数据：{'jsonrpc': '2.0', 'result': {'code': 200, 'meta': {'endpoint': 'OK', 'close': 1}, 'data': 'hello world!', 'msg': 'None'}, 'id': 1}