fagongzi/manba项目JavaScript插件开发指南

fagongzi/manba项目JavaScript插件开发指南

manba HTTP API Gateway 项目地址: https://gitcode.com/gh_mirrors/ma/manba

概述

fagongzi/manba是一个功能强大的网关系统，它提供了JavaScript插件开发能力，允许开发者通过编写JavaScript代码来动态扩展网关功能。这种设计理念类似于Serverless架构，为网关提供了极高的灵活性和可扩展性。

插件基础结构

JavaScript插件的基本结构如下：

function NewPlugin(cfg) {
    // 导入内置模块
    var JSON = require("json")
    var HTTP = require("http")
    var REDIS = require("redis")
    var LOG = require("log")

    // 初始化插件
    return {
        // 前置过滤器方法
        "pre": function(ctx) {
            // 业务逻辑代码
            return {
                "code": 200,
                "error": "error",
            }
        },
        // 后置过滤器方法
        "post": function(ctx) {
            // 业务逻辑代码
            return {
                "code": 200,
                "error": "error",
            }
        },
        // 错误处理方法
        "postErr": function(ctx) {
            // 错误处理逻辑
        }
    }
}

上下文对象详解

插件执行时会获得一个上下文对象ctx，它提供了丰富的API来操作请求和响应：

核心方法

• OriginRequest(): 获取原始请求对象
• ForwardRequest(): 获取转发到后端的请求对象
• Response(): 获取后端响应对象
• SetAttr(key, value): 在上下文中存储属性
• HasAttr(key): 检查属性是否存在
• GetAttr(key): 获取存储的属性

HTTPRequest对象

提供完整的HTTP请求操作能力：

• 头部操作：Header(), SetHeader(), RemoveHeader()
• Cookie操作：Cookie(), SetCookie(), RemoveCookie()
• 查询参数：Query()
• 请求体：Body(), SetBody()

HTTPResponse对象

提供HTTP响应操作能力：

• 头部和Cookie操作
• 响应体操作：Body(), SetBody()
• 状态码设置：SetStatusCode()
• 特殊方法：Delegate()用于在pre方法中直接返回响应

内置模块详解

JSON模块

提供JSON编解码功能：

• Stringify(): 将对象序列化为JSON字符串
• Parse(): 将JSON字符串解析为对象

LOG模块

提供日志记录功能，支持多种级别：

• 信息级：Info(), Infof()
• 调试级：Debug(), Debugf()
• 警告级：Warn(), Warnf()
• 错误级：Error(), Errorf()
• 致命级：Fatal(), Fatalf()（会导致网关进程退出）

HTTP模块

提供HTTP客户端功能，支持同步请求：

• 基础方法：Get(), Post(), Put(), Delete()
• JSON专用方法：PostJSON(), PutJSON(), DeleteJSON()
• 响应处理：通过HTTPResult对象提供完整的响应信息

Redis模块

提供Redis客户端功能：

• 创建连接：RedisModule(config)
• 执行命令：Do(command, args...)
• 结果处理：通过CmdResp对象提供多种格式的结果转换

插件方法详解

pre方法

在请求转发到后端前执行，典型应用场景：

1. 请求鉴权
2. 请求参数校验
3. 请求改写

特殊控制：

• 返回BreakFilterChainCode可中断后续插件执行
• 设置UsingResponse属性可直接返回响应

示例代码：

"pre": function(ctx) {
    // 检查认证头
    if(!ctx.OriginRequest().Header("Authorization")) {
        return {
            "code": 403,
            "error": "Authentication required"
        }
    }
    // 正常通过
    return {"code": 200}
}

post方法

在收到后端响应后执行，典型应用场景：

1. 响应改写
2. 添加额外头信息
3. 响应数据转换

示例代码：

"post": function(ctx) {
    // 添加响应头
    ctx.Response().SetHeader("X-Custom-Header", "value")
    return {"code": 200}
}

postErr方法

在后端请求失败时执行，典型应用场景：

1. 错误日志记录
2. 错误响应格式化
3. 失败重试逻辑

最佳实践

1. 性能优化：避免在插件中进行耗时操作，如复杂计算或大量网络请求
2. 错误处理：始终检查Redis和HTTP操作的结果是否有错误
3. 日志记录：合理使用日志级别，避免过度记录
4. 资源共享：对于Redis连接等资源，考虑在插件初始化时创建并复用
5. 状态管理：使用上下文属性在插件方法间传递数据

总结

fagongzi/manba的JavaScript插件系统提供了强大的扩展能力，通过本文介绍的核心概念和API，开发者可以轻松实现各种网关扩展功能。无论是简单的请求改写，还是复杂的业务逻辑集成，都能通过JavaScript插件优雅地实现。

manba HTTP API Gateway 项目地址: https://gitcode.com/gh_mirrors/ma/manba